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

1. Hidden Accounts: Store encrypted balance commitments instead of plain balances
2. Cryptographic Proofs: Bulletproof range proofs and zero-knowledge ownership proofs
3. Pedersen Commitments: Cryptographically secure balance hiding
4. Token Vault: Secure storage for deposited ATOM tokens
5. 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

1. 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

2. Configure Network

   # For devnet
   solana config set --url devnet
   
   # Request airdrop if needed
   solana airdrop 2

3. Build and Deploy

   # Build the program
   anchor build
   
   # Deploy to devnet
   anchor deploy --provider.cluster devnet

4. 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

5. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. 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

• Full bulletproof implementation
• Optimized curve operations
• Mobile SDK
• Web interface
• Multi-token support
• Cross-chain bridges
• Formal security audit

---

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