LostAtom Protocol 🚀

A zero-knowledge privacy protocol for ATOM tokens on Solana, providing anonymous transfers and hidden balances using advanced cryptographic techniques including bulletproofs and Pedersen commitments.

🌟 Features

Zero-Knowledge Transfers: Send ATOM tokens without revealing amounts or balances
Hidden Balances: Account balances are cryptographically hidden using Pedersen commitments
Bulletproof Range Proofs: Ensure transaction amounts are valid without revealing them
Schnorr Signatures: Prove account ownership without exposing private keys
ATOM Token Support: Native support for ATOM tokens with 6 decimal precision
Withdrawal Fees: Configurable withdrawal fees with automatic burning mechanism

🏗️ Architecture

Core Components

Hidden Accounts: Store encrypted balance commitments instead of plain balances
Cryptographic Proofs: Bulletproof range proofs and zero-knowledge ownership proofs
Pedersen Commitments: Cryptographically secure balance hiding
Token Vault: Secure storage for deposited ATOM tokens
Fee System: Automatic fee collection and burning on withdrawals

Security Features

Range Proofs: Prevent negative amounts and overflow attacks
Balance Conservation: Cryptographically enforce input = output + fees
Replay Protection: Nonce-based transaction uniqueness
Ownership Proofs: Zero-knowledge proof of private key knowledge

🚀 Quick Start

Prerequisites

Rust (latest stable)
Solana CLI (v1.18+)
Anchor CLI (v0.31+)
Node.js (v18+)
npm (comes with Node.js)

Installation

# Clone the repository
git clone <repository-url>
cd lostatom-protocol

# Install dependencies
npm install

# Build the program
anchor build

Deployment

Option 1: Automated Deployment (Recommended)

# Deploy program only to devnet
npm run deploy:devnet

# Then setup protocol
npm run setup:devnet

# Or do both in one command
npm run deploy-and-setup:devnet

# The deployment script will:
# 1. Build the program
# 2. Deploy to network  
# 3. Verify deployment
# 4. Show next steps

# For mainnet
npm run deploy:mainnet
npm run setup:mainnet

Option 2: Manual Deployment

# Set Solana cluster
solana config set --url devnet

# Deploy the program
anchor deploy --provider.cluster devnet

# Setup the protocol
npm run setup:devnet

Step-by-Step Deployment Guide

Prepare Your Environment

# Check Solana CLI installation
solana --version

# Check Anchor installation
anchor --version

# Create or use existing wallet
solana-keygen new  # if you don't have a wallet

# Check wallet balance (need ~2 SOL for devnet deployment)
solana balance

Configure Network

# For devnet
solana config set --url devnet

# Request airdrop if needed
solana airdrop 2

Build and Deploy

# Build the program
anchor build

# Deploy to devnet
anchor deploy --provider.cluster devnet

Setup Protocol

# Run automated setup
npm run setup:devnet

# Setup with automatic verification
npm run setup-and-verify:devnet

# This will:
# - Create ATOM token mint
# - Initialize protocol state
# - Create token vaults
# - Save configuration
# - Verify everything is working

Verify Deployment

# Run tests
anchor test

# Test protocol functionality
npm run test-protocol

# Check configuration
cat config/protocol-config.json

🧪 Testing

Run All Tests

# Run Anchor tests
anchor test

# Run protocol integration tests
npm run test-protocol

Verify deployment status

npm run verify:devnet

Create Test Users

# Create a test user with 1000 ATOM
npm run create-user devnet 1000

# Create multiple users for testing transfers
npm run create-user devnet 500
npm run create-user devnet 250

Manual Testing

# Test individual components
npx ts-node scripts/test-protocol.ts devnet

📋 Usage Examples

1. Register a Hidden Account

import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { Lostatom } from "./target/types/lostatom";

// Generate Schnorr signature for registration
const publicKey = Array.from(hiddenAccountKeypair.publicKey.toBytes());
const challenge = generateChallenge(); // Your challenge generation
const response = generateResponse();   // Your response generation

await program.methods
  .register(publicKey, challenge, response)
  .accounts({
    payer: authority.publicKey,
    hiddenAccount: hiddenAccountKeypair.publicKey,
    globalState,
    systemProgram: SystemProgram.programId,
  })
  .signers([hiddenAccountKeypair])
  .rpc();

2. Deposit ATOM Tokens

const depositAmount = new anchor.BN(10_000_000); // 10 ATOM

await program.methods
  .deposit(depositAmount)
  .accounts({
    user: authority.publicKey,
    hiddenAccount: hiddenAccountKeypair.publicKey,
    userAtomAccount,
    programAtomVault,
    tokenProgram: TOKEN_PROGRAM_ID,
    globalState,
  })
  .rpc();

3. Private Transfer (Requires ZK Proofs)

// Create transfer proof (simplified - requires proper ZK proof generation)
const transferProof = {
  balanceProof: generateBalanceProof(),
  amountCommitment: generateAmountCommitment(),
  randomness: generateRandomness(),
  rangeProof: generateRangeProof(),
  c: challenge,
  s: response,
};

await program.methods
  .privateTransfer(recipientPublicKey, amountCommitment, transferProof)
  .accounts({
    sender: senderKeypair.publicKey,
    senderAccount: senderHiddenAccount.publicKey,
    recipientAccount: recipientHiddenAccount.publicKey,
    globalState,
  })
  .signers([senderKeypair])
  .rpc();

4. Withdraw ATOM Tokens

const withdrawAmount = new anchor.BN(5_000_000); // 5 ATOM

// Create withdrawal proof
const withdrawProof = {
  balanceProof: generateBalanceProof(),
  amountCommitment: generateAmountCommitment(),
  randomness: generateRandomness(),
  rangeProof: generateRangeProof(),
  c: challenge,
  s: response,
};

await program.methods
  .withdraw(withdrawAmount, withdrawProof)
  .accounts({
    user: userKeypair.publicKey,
    hiddenAccount: hiddenAccountKeypair.publicKey,
    userAtomAccount,
    programAtomVault,
    feeBurnAccount,
    vaultAuthority,
    tokenProgram: TOKEN_PROGRAM_ID,
    globalState,
  })
  .signers([userKeypair])
  .rpc();

📁 Project Structure

lostatom-protocol/
├── programs/
│   └── lostatom/
│       ├── src/
│       │   ├── lib.rs              # Main program entry
│       │   ├── state.rs            # Account structures
│       │   ├── crypto.rs           # Cryptographic functions
│       │   ├── bulletproof.rs      # Range proof verification
│       │   ├── utils.rs            # Utility functions
│       │   └── anchor_processor.rs # Instruction handlers
│       └── Cargo.toml
├── scripts/
│   ├── deploy.sh                   # Automated deployment
│   ├── setup-protocol.ts           # Protocol initialization
│   ├── create-user.ts              # Test user creation
│   └── test-protocol.ts            # Integration tests
├── tests/
│   └── lostatom.ts                 # Anchor tests
├── config/                         # Generated configurations
├── Anchor.toml                     # Anchor configuration
└── package.json                    # Node.js dependencies

🔧 Configuration

After deployment, configuration files are saved in the config/ directory:

protocol-config.json: Main protocol configuration
users/: Test user configurations

Protocol Configuration Example

{
  "programId": "11111111111111111111111111111111",
  "atomMint": "...",
  "globalState": "...",
  "vaultAuthority": "...",
  "programAtomVault": "...",
  "feeBurnAccount": "...",
  "withdrawalFeeBps": 100,
  "timestamp": "2024-01-01T00:00:00.000Z",
  "network": "https://api.devnet.solana.com"
}

🔐 Security Considerations

Cryptographic Security

Pedersen Commitments: Computationally hiding and perfectly binding
Bulletproof Range Proofs: Prevent negative amounts and overflow
Schnorr Signatures: Provably secure under discrete log assumption
Fiat-Shamir Heuristic: Non-interactive zero-knowledge proofs

Implementation Security

Stack Safety: All operations designed for Solana's stack constraints
Compute Limits: Optimized for Solana's compute unit limits
Replay Protection: Nonce-based transaction uniqueness
Access Control: Proper account ownership verification

Audit Status

⚠️ This is experimental software. Use at your own risk.

Not yet audited by third parties
Cryptographic implementations are simplified for Solana constraints
Suitable for testing and development, not production use

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🆘 Support

Issues: Report bugs and request features via GitHub Issues
Documentation: Check the /docs directory for detailed documentation
Community: Join our Discord/Telegram for community support

🗺️ Roadmap

⚠️ Disclaimer: This software is experimental and not audited. Use at your own risk. Not suitable for production use with real funds.

Name		Name	Last commit message	Last commit date
Latest commit History 89 Commits
app		app
migrations		migrations
programs/lostatom		programs/lostatom
scripts		scripts
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
Anchor.toml		Anchor.toml
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

freenetcoder/gargantua

Folders and files

Latest commit

History

Repository files navigation