# Comprehensive Technical Guide: Solana Merkle Airdrop Distributor **A Complete Deep Dive into the Gill + Codama + Anchor Architecture** ## 1. Project Architecture & Overview **What we're building**: An airdrop system that can distribute SOL (Solana's native token) to thousands of people efficiently and cheaply. Instead of storing a massive list of recipients on the blockchain (which would be expensive), we use a Merkle tree to store just a single 32-byte "fingerprint" that represents all recipients. **Why this matters**: Traditional airdrops either require expensive on-chain storage or centralized servers. Our approach gives you the security of blockchain verification with the efficiency of storing almost no data on-chain. ### Technology Stack Integration Think of building this airdrop system like constructing a house — you need different specialists for different parts. We use three key technologies that work together like a well-coordinated construction team: #### **Gill (Modern Solana SDK)** **What it is**: Gill is your "translator" between JavaScript/TypeScript and the Solana blockchain. A type-safe SDK means the code "knows" what kind of data to expect and catches mistakes before they happen (like a spell-checker for code). **Why we need it**: The old Solana JavaScript library was clunky and error-prone. Gill makes blockchain interactions feel as smooth as using any modern web API. - **Purpose**: Replaces the legacy `@solana/web3.js` with a more modern, type-safe SDK - **Key Features**: - Simplified transaction creation with `createTransaction()` - Type-safe address handling with `address()` helper - Streamlined key pair management with `createKeyPairSignerFromBytes()` - Built-in RPC client abstraction ```typescript // Example: Creating a Solana client with Gill const client = createSolanaClient({ urlOrMoniker: 'devnet' // Simplified network configuration }) const { rpc, sendAndConfirmTransaction } = client ``` #### **Codama (Client Generation)** **What it is**: Codama is like having an automatic code writer. When you build your blockchain program, it creates an IDL (Interface Description Language) file — think of it as a "menu" listing all the things your program can do. Codama reads this menu and automatically writes all the TypeScript code you need to talk to your program. **Why we need it**: Without Codama, you'd have to manually write hundreds of lines of boilerplate code every time you change your program. It's like having a personal assistant who updates all your documentation automatically. - **Purpose**: Automatically generates type-safe TypeScript clients from Anchor IDL - **Benefits**: - Eliminates manual client code writing - Ensures type safety between on-chain program and client - Automatic updates when program changes ```typescript // Auto-generated instruction builders import { getInitializeAirdropInstruction } from './generated/clients/ts/instructions/initializeAirdrop' import { getClaimAirdropInstruction } from './generated/clients/ts/instructions/claimAirdrop' ``` #### **Anchor Framework (On-Chain)** **What it is**: Anchor is like Rails for Ruby or Express for Node.js, but for Solana blockchain programs. It's a framework that gives you guardrails and common patterns so you don't have to build everything from scratch. **Why we need it**: Writing raw Solana programs is like building a car engine from individual metal parts. Anchor gives you pre-built, tested components so you can focus on your unique logic instead of reinventing the wheel. - **Purpose**: Provides Rust framework for Solana program development - **Features**: - Automatic account validation and deserialization - Built-in security constraints - IDL generation for client tooling ### Data Flow Architecture **How the pieces fit together**: Imagine the airdrop process like a secure mail delivery system. First, you create a master list of who gets what (recipients list). Then you create a special "fingerprint" of that list (Merkle tree) that can prove anyone's eligibility without revealing the whole list. Finally, people can claim their tokens by showing they're on the original list. ```mermaid graph TD A[Recipients List JSON] --> B[Merkle Tree Generation] B --> C[Merkle Root + Proofs] C --> D[On-Chain Initialization] D --> E[Airdrop State PDA] F[User Claim Request] --> G[Proof Generation] G --> H[On-Chain Verification] H --> I[SOL Transfer] I --> J[Claim Status PDA] E --> H J --> K[Double-Claim Prevention] ``` ### Why This Combination? 1. **Developer Experience**: Gill provides modern JavaScript/TypeScript APIs 2. **Type Safety**: Codama ensures client-program compatibility 3. **Security**: Anchor provides battle-tested on-chain security patterns 4. **Scalability**: Merkle trees enable efficient distribution to thousands of recipients 5. **Cost Efficiency**: Only stores 32-byte root on-chain, not entire recipient list --- ## 2. Merkle Tree Implementation & Cryptography **What's a Merkle tree?** Think of it like a digital fingerprint for a large dataset. Just like your fingerprint uniquely identifies you, a Merkle tree creates a unique 32-byte "fingerprint" that represents thousands of recipients and their amounts. If anyone tries to cheat by claiming they deserve more tokens or that they're eligible when they're not, the fingerprint won't match. **Why use this approach?** Storing 10,000 recipients on Solana would cost thousands of dollars in storage fees. Instead, we store just the 32-byte fingerprint on-chain and let people prove they're in the original list using cryptographic proofs. It's like having a bouncer who can verify you're on the VIP list without needing to see the entire list. **The trade-off**: Users need to generate a "proof" to claim (a bit more complex), but we save massive amounts of money and the system scales to millions of recipients. ### Merkle Tree Creation Process **What this code does**: This is the heart of our fingerprinting system. We take all recipients, turn each one into a hash (like a unique ID card), then pair them up and hash the pairs, continuing until we have just one final hash — our Merkle root. The `GillMerkleTree` class implements a binary Merkle tree optimized for airdrop distribution: ```typescript export class GillMerkleTree { public root: Uint8Array private leaves: Uint8Array[] private tree: Uint8Array[][] constructor(recipients: GillRecipient[]) { // Step 1: Create leaf hashes for each recipient this.leaves = recipients.map((r) => this.createLeaf(r.recipient, r.amount)) // Step 2: Build tree bottom-up this.tree = [this.leaves] let currentLevel = this.leaves // Step 3: Pair and hash until single root while (currentLevel.length > 1) { const nextLevel: Uint8Array[] = [] for (let i = 0; i < currentLevel.length; i += 2) { const left = currentLevel[i] const right = i + 1 < currentLevel.length ? currentLevel[i + 1] : left const parent = this.hashPair(left, right) nextLevel.push(parent) } this.tree.push(nextLevel) currentLevel = nextLevel } this.root = currentLevel[0] } } ``` ### Leaf Creation Algorithm **What this does**: Every recipient gets turned into a "leaf" — a unique hash that represents their wallet address, how much they get, and whether they've claimed yet. This is like creating a tamper-proof ID card for each person. **Why the exact format matters**: The client (JavaScript) and the blockchain program (Rust) must create identical hashes for the same person, or verification will fail. It's like both sides of a security checkpoint needing to use the same ID format. The critical leaf encoding must match exactly between client and on-chain verification: ```typescript private createLeaf(recipient: Address, amount: number): Uint8Array { const recipientBytes = bs58.decode(recipient) // 32 bytes const data = Buffer.concat([ Buffer.from(recipientBytes), // recipient_pubkey(32) Buffer.from(new Uint8Array(new BigUint64Array([BigInt(amount)]).buffer)), // amount(8) Buffer.from([0]), // isClaimed(1) = false ]) return new Uint8Array(keccak_256.arrayBuffer(data)) // Keccak-256 hash } ``` **Critical Details:** - **Recipient**: 32-byte public key (base58 decoded) - **Amount**: 8-byte little-endian unsigned integer - **Claimed Flag**: 1-byte boolean (0 = false, 1 = true) - **Hash Function**: Keccak-256 (NOT SHA-256) ### Why Keccak-256? **What's a hash function?** It's like a digital blender that turns any input into a fixed-size, unpredictable output. Change even one bit of the input, and you get a completely different output. **Why this specific one?** We chose Keccak-256 over other hash functions for several strategic reasons: 1. **Ethereum Compatibility**: Standard in many blockchain applications 2. **Security**: Cryptographically secure with no known vulnerabilities 3. **Performance**: Efficient implementation in both Rust and JavaScript 4. **Solana Support**: Available via `anchor_lang::solana_program::keccak` ### Proof Generation & Verification **What's a proof?** Think of it like showing your route on a map. To prove you belong in the Merkle tree, you need to show the path from your "leaf" (your personal hash) up to the root. The proof contains the "sibling" hashes at each level that let you reconstruct the path. **Why this works**: Anyone can verify you're in the tree by following your path and checking that it leads to the known root, but they don't need to see the entire tree or know about other recipients. #### Client-Side Proof Generation **What this code does**: Starting from a person's position in the tree, we collect all the "sibling" hashes needed to prove they belong. It's like collecting stamps at each checkpoint on your way to the top of a mountain. ```typescript public getProof(leafIndex: number): Uint8Array[] { const proof: Uint8Array[] = [] let index = leafIndex // Traverse from leaf to root, collecting sibling hashes for (let level = 0; level < this.tree.length - 1; level++) { const currentLevel = this.tree[level] const siblingIndex = index % 2 === 0 ? index + 1 : index - 1 if (siblingIndex < currentLevel.length) { proof.push(currentLevel[siblingIndex]) } index = Math.floor(index / 2) // Move to parent level } return proof } ``` #### On-Chain Verification (Rust) **What this code does**: The blockchain program takes someone's proof and "walks" back up the tree, hashing at each level to see if it arrives at the stored root. If it matches, the person is verified as eligible. ```rust fn verify_merkle_proof( leaf: &[u8; 32], proof: &[[u8; 32]], leaf_index: u64, ) -> Result<[u8; 32]> { let mut computed_hash = *leaf; let mut index = leaf_index; for proof_element in proof.iter() { if index % 2 == 0 { // Hash(current computed hash + current element of the proof) let mut hash_input = Vec::new(); hash_input.extend_from_slice(&computed_hash); hash_input.extend_from_slice(proof_element); computed_hash = keccak::hash(&hash_input).to_bytes(); } else { // Hash(current element of the proof + current computed hash) let mut hash_input = Vec::new(); hash_input.extend_from_slice(proof_element); hash_input.extend_from_slice(&computed_hash); computed_hash = keccak::hash(&hash_input).to_bytes(); } index /= 2; } Ok(computed_hash) } ``` **Critical Consistency Requirements:** 1. **Leaf Index**: Must match recipient's position in original array 2. **Proof Order**: Sibling hashes in correct traversal order 3. **Hash Order**: Left/right concatenation must match tree construction 4. **Encoding**: Exact byte representation between client and on-chain --- ## 3. On-Chain Program Deep Dive **What's an on-chain program?** This is the "smart contract" that lives on the Solana blockchain. Think of it as a vending machine that follows strict rules: it will only give out tokens if you can prove you're eligible and haven't claimed before. **Why we need specific account structures**: Solana programs don't have traditional databases. Instead, they store data in "accounts" — think of them as files on the blockchain. We need to carefully design these files to store our airdrop information efficiently and securely. ### Account Structure Analysis #### AirdropState PDA **What's a PDA?** A Program Derived Address is like a safe deposit box that only your program can open. It's an account address that's mathematically derived from specific "seeds" (like keywords), so it's predictable but secure. **What this stores**: This is the "master file" for our airdrop, containing the Merkle root, who's in charge, how much SOL is allocated, and how much has been claimed so far. ```rust #[account] pub struct AirdropState { /// The Merkle root of the airdrop (32 bytes) pub merkle_root: [u8; 32], /// The authority allowed to update the merkle root pub authority: Pubkey, /// Total SOL allocated for this airdrop (in lamports) pub airdrop_amount: u64, /// Total SOL claimed so far (in lamports) pub amount_claimed: u64, /// Bump seed for the PDA pub bump: u8, } ``` **PDA Derivation:** - **Seeds**: `["merkle_tree"]` - **Space**: `8 + 32 + 32 + 8 + 8 + 1 = 89 bytes` (Anchor adds 8-byte discriminator) - **Purpose**: Stores immutable airdrop parameters and tracks distribution progress #### ClaimStatus PDA **What this does**: This is like a "claimed" stamp for each person. We create a tiny account for each person who claims, and its mere existence proves they've already gotten their tokens. **Why this approach**: Instead of maintaining a list of claimed addresses, we use Solana's account system itself as our database. If the account exists, they've claimed. If not, they haven't. ```rust #[account] pub struct ClaimStatus {} ``` **PDA Derivation:** - **Seeds**: `["claim", airdrop_state.key(), recipient.key()]` - **Space**: `8 bytes` (minimal - existence indicates claimed) - **Purpose**: Prevents double-claiming by creating unique account per recipient #### Vault Functionality The airdrop state account itself serves as the vault: - **SOL Storage**: Holds all lamports for distribution - **Access Control**: Only program can move funds via CPI - **Accounting**: Tracks total allocated vs. claimed amounts ### Instruction Breakdown **What are instructions?** In Solana, instructions are like function calls to your program. Each instruction tells the program to do one specific thing, like "set up a new airdrop" or "let this person claim their tokens." #### Initialize Airdrop **What this instruction does**: This is the "setup" function that creates a new airdrop. It stores the Merkle root, sets who's in charge, and transfers all the SOL that will be distributed into the program's vault. ```rust pub fn initialize_airdrop( ctx: Context, merkle_root: [u8; 32], amount: u64, ) -> Result<()> { let airdrop_state = &mut ctx.accounts.airdrop_state; // Set immutable parameters airdrop_state.merkle_root = merkle_root; airdrop_state.authority = ctx.accounts.authority.key(); airdrop_state.airdrop_amount = amount; airdrop_state.amount_claimed = 0; airdrop_state.bump = ctx.bumps.airdrop_state; // Transfer SOL to vault (the airdrop_state account itself) let transfer_ix = anchor_lang::solana_program::system_instruction::transfer( &ctx.accounts.authority.key(), &airdrop_state.key(), amount, ); anchor_lang::solana_program::program::invoke( &transfer_ix, &[ ctx.accounts.authority.to_account_info(), airdrop_state.to_account_info(), ctx.accounts.system_program.to_account_info(), ], )?; Ok(()) } ``` **Account Constraints:** ```rust #[derive(Accounts)] pub struct Initialize<'info> { #[account( init, seeds = [b"merkle_tree"], bump, payer = authority, space = 8 + std::mem::size_of::() )] pub airdrop_state: Account<'info, AirdropState>, #[account(mut)] pub authority: Signer<'info>, pub system_program: Program<'info, System>, } ``` #### Claim Airdrop **What this instruction does**: This is where the magic happens. A user provides their Merkle proof, the program verifies it against the stored root, and if valid, transfers SOL to the user and marks them as claimed. **The verification process**: Like a bouncer checking your ID against a guest list, but using cryptographic proofs instead of a physical list. ```rust pub fn claim_airdrop( ctx: Context, amount: u64, proof: Vec<[u8; 32]>, leaf_index: u64, ) -> Result<()> { let airdrop_state = &mut ctx.accounts.airdrop_state; let signer = &ctx.accounts.signer; // Step 1: Recreate leaf hash let mut leaf_data = Vec::new(); leaf_data.extend_from_slice(&signer.key().to_bytes()); leaf_data.extend_from_slice(&amount.to_le_bytes()); leaf_data.push(0u8); // isClaimed flag (0 = false) let leaf_hash = keccak::hash(&leaf_data).to_bytes(); // Step 2: Verify Merkle proof let computed_root = verify_merkle_proof(&leaf_hash, &proof, leaf_index)?; require!( computed_root == airdrop_state.merkle_root, ErrorCode::InvalidProof ); // Step 3: Transfer SOL **airdrop_state.to_account_info().try_borrow_mut_lamports()? -= amount; **ctx.accounts.signer.to_account_info().try_borrow_mut_lamports()? += amount; // Step 4: Update accounting airdrop_state.amount_claimed = airdrop_state.amount_claimed.saturating_add(amount); Ok(()) } ``` **Account Constraints:** ```rust #[derive(Accounts)] pub struct Claim<'info> { #[account( mut, seeds = [b"merkle_tree"], bump = airdrop_state.bump )] pub airdrop_state: Account<'info, AirdropState>, #[account( init, payer = signer, space = 8, seeds = [b"claim", airdrop_state.key().as_ref(), signer.key().as_ref()], bump )] pub user_claim: Account<'info, ClaimStatus>, #[account(mut)] pub signer: Signer<'info>, pub system_program: Program<'info, System>, } ``` ### Security Mechanisms #### PDA-Based Access Control 1. **Deterministic Addresses**: PDAs prevent address spoofing 2. **Seed-Based Validation**: Specific seeds ensure correct account relationships 3. **Bump Verification**: Canonical bump prevents alternative derivations #### Double-Claim Prevention ```rust #[account( init, // Fails if account already exists payer = signer, space = 8, seeds = [b"claim", airdrop_state.key().as_ref(), signer.key().as_ref()], bump )] pub user_claim: Account<'info, ClaimStatus>, ``` The `init` constraint ensures the claim status account can only be created once per recipient. #### Lamport Accounting ```rust // Saturating arithmetic prevents overflow/underflow airdrop_state.amount_claimed = airdrop_state.amount_claimed.saturating_add(amount); ``` #### Authority Validation ```rust require!( ctx.accounts.authority.key() == airdrop_state.authority, ErrorCode::Unauthorized ); ``` --- ## 4. Participant Verification & Eligibility **The challenge**: How do you fairly decide who gets tokens and prevent people from gaming the system? This section covers how we manage the list of eligible recipients and ensure only legitimate claims succeed. **Why this matters**: Without proper verification, anyone could claim to be eligible or try to claim multiple times. We need a system that's both secure and user-friendly. ### Recipient List Management **What this is**: Before launching the airdrop, we create a master JSON file listing everyone who's eligible and how much they should receive. This file becomes the source of truth for generating the Merkle tree. #### Recipients.json Structure ```typescript interface RecipientsFile { airdropId: string description: string merkleRoot: string // Computed from recipients totalAmount: string // Sum of all amounts network: string // Target network programId: string // Deployed program address recipients: RecipientFromJson[] metadata: { createdAt: string // Generation timestamp version: string // Schema version algorithm: string // "keccak256" leafFormat: string // Encoding specification } } ``` #### Automatic Test Wallet Generation **What this does**: For development and testing, we automatically generate fake wallets with random addresses. This lets you test the entire airdrop flow without needing real user wallets. **Why it's helpful**: You can simulate hundreds of users claiming tokens to make sure everything works before going live. The setup process creates test wallets automatically: ```typescript export async function generateGillTestWallets( rpc: any, count: number ): Promise { const wallets: GillWalletInfo[] = [] for (let i = 1; i <= count; i++) { const signer = await generateKeyPairSigner() const walletInfo: GillWalletInfo = { name: `test-wallet-${i}`, address: signer.address, keypairFile: `./test-wallet-${i}.json`, privateKey: { hex: '0x' + Buffer.from(signer.keyPair.privateKey).toString('hex'), base58: bs58.encode(signer.keyPair.privateKey), array: Array.from(signer.keyPair.privateKey) }, // ... additional fields signer } wallets.push(walletInfo) } return wallets } ``` ### Claim Eligibility Verification #### Client-Side Eligibility Check ```typescript export function generateProofForRecipient(recipientAddress: string): { proof: string[] amount: string leafIndex: number recipient: string } | null { // Find recipient in the data const recipient = RECIPIENTS_DATA.recipients.find( r => r.publicKey === recipientAddress ) if (!recipient) { return null // Not eligible } // Generate Merkle proof const merkleTree = new GillMerkleTree(/* recipients data */) const proofResult = generateGillProof(merkleTree, recipient.index) return { proof: proofResult.proof, amount: recipient.amount, leafIndex: recipient.index, recipient: recipient.publicKey } } ``` #### Balance Requirements ```typescript const minBalanceLamports = AIRDROP_CONFIG.MIN_SOL_BALANCE * 1e9 if (balanceLamports < minBalanceLamports) { throw new Error( `Insufficient SOL balance: ${balanceLamports / 1e9} SOL. ` + `Need at least ${AIRDROP_CONFIG.MIN_SOL_BALANCE} SOL for transaction fees.` ) } ``` ### Metadata Tracking The system tracks comprehensive metadata for audit and debugging: ```typescript metadata: { createdAt: "2025-08-14T13:47:28.327Z", version: "1.0.0", algorithm: "keccak256", leafFormat: "recipient_pubkey(32) + amount(8) + is_claimed(1)" } ``` --- ## 5. Identity & Ownership Verification **The security challenge**: How do we make sure the person claiming tokens actually owns the wallet they claim to own? Anyone can copy a wallet address, but only the true owner has the private key. **Our solution**: Every claim must be digitally signed with the recipient's private key. It's like requiring a handwritten signature that only you can produce. ### Cryptographic Proof of Ownership **How digital signatures work**: When you sign a transaction, you're using your private key to create a unique "signature" that proves you own the wallet. Anyone can verify the signature matches your public address, but only you can create it. #### Solana's Built-in Signature Verification Every transaction requires the recipient to sign with their private key: ```typescript const transaction = createTransaction({ version: 'legacy', feePayer: signer, // Must own private key instructions: [claimInstruction], latestBlockhash, }) // Signing happens automatically in sendAndConfirmTransaction const signature = await sendAndConfirmTransaction(transaction) ``` #### On-Chain Signer Validation ```rust #[account(mut)] pub signer: Signer<'info>, // Anchor validates signature ``` The `Signer<'info>` constraint ensures: 1. Transaction is signed by the specified account 2. Private key ownership is cryptographically proven 3. No one else can claim on behalf of the recipient ### Anti-Fraud Mechanisms #### Unique PDA Generation Each recipient gets a unique claim status PDA: ```rust seeds = [b"claim", airdrop_state.key().as_ref(), signer.key().as_ref()] ``` This prevents: - **Replay Attacks**: Same proof can't be used twice - **Cross-Recipient Claims**: Can't use another's proof - **Program Spoofing**: PDA tied to specific program #### Immutable Merkle Root ```rust airdrop_state.merkle_root = merkle_root; // Set once during initialization ``` Once set, the recipient set cannot be modified, preventing: - **Post-hoc Additions**: No new recipients after initialization - **Eligibility Tampering**: Can't modify amounts or addresses - **Root Manipulation**: Cryptographic integrity maintained #### On-Chain State Tracking ```rust pub amount_claimed: u64, // Cumulative tracking ``` Enables: - **Distribution Monitoring**: Track total claimed vs allocated - **Audit Trail**: On-chain record of all claims - **Completion Detection**: Know when distribution is finished --- ## 6. Tooling & Development Workflow **The developer experience challenge**: Blockchain development traditionally involves lots of manual, error-prone work — writing client code by hand, keeping multiple codebases in sync, and dealing with complex transaction building. **Our modern approach**: We use automated tools that eliminate most manual work and prevent common mistakes. It's like having an assembly line instead of handcrafting each part. ### Codama Integration **What Codama does for you**: Instead of writing hundreds of lines of TypeScript to interact with your Solana program, Codama reads your program's "blueprint" (IDL) and writes all that code automatically. When you change your program, just regenerate and everything stays in sync. #### IDL to Client Generation ```typescript // codama.config.ts import { createFromRoot } from 'codama' import { rootNodeFromAnchor } from '@codama/nodes-from-anchor' import { renderJavaScriptVisitor } from '@codama/renderers' async function generateClients() { // Convert Anchor IDL to Codama tree const codama = createFromRoot(rootNodeFromAnchor(anchorIdl as AnchorIdl)) // Generate TypeScript client await visit(codama.getRoot(), await renderJavaScriptVisitor(outputDir)) } ``` #### Generated Type-Safe Instruction Builders ```typescript // Auto-generated: anchor/generated/clients/ts/instructions/initializeAirdrop.ts export function getInitializeAirdropInstruction(input: { airdropState: Address | TransactionSigner authority: TransactionSigner merkleRoot: Uint8Array amount: bigint }): TransactionInstruction { // Type-safe instruction building // Automatic account ordering // Built-in constraint validation } ``` #### Generated Account Deserializers ```typescript // Auto-generated: anchor/generated/clients/ts/accounts/airdropState.ts export async function fetchAirdropState( rpc: Rpc, address: Address ): Promise | null> { // Automatic deserialization // Type-safe data access // Error handling } ``` ### Gill SDK Usage #### Modern Transaction Creation ```typescript import { createTransaction, createKeyPairSignerFromBytes } from 'gill' const transaction = createTransaction({ version: 'legacy', feePayer: signer, instructions: [initializeInstruction], latestBlockhash, }) ``` **Benefits over Legacy SDK:** - Cleaner API surface - Better TypeScript support - Simplified error handling - Modern async/await patterns #### PDA Derivation ```typescript import { getProgramDerivedAddress } from 'gill' const [airdropStatePda] = await getProgramDerivedAddress({ programAddress, seeds: ['merkle_tree'], }) ``` #### Network Abstraction ```typescript const client = createSolanaClient({ urlOrMoniker: 'devnet' // Simple network selection }) ``` ### Build & Deployment Scripts #### Complete Setup Workflow ```typescript // anchor/scripts/deploy-setup.ts export async function runGillDeploymentSetup() { // 1. Create/import deployment wallet const deployWallet = await setupGillDeployWallet(rl, config) // 2. Generate test wallets const testWallets = await setupGillTestWallets(rl, config) // 3. Deploy program (optional) if (shouldDeploy) { await completeGillSetup({ deployProgram: true, generateNewProgramId: generateNewProgram, // ... }) } // 4. Update configuration files // 5. Generate Merkle tree // 6. Create recipients.json } ``` #### Automatic Program ID Management ```typescript // codama.config.ts async function generateProgramId(): Promise { // Generate new keypair execSync(`solana-keygen new --no-bip39-passphrase --silent --outfile ${keypairPath}`) // Get public key const programId = execSync(`solana-keygen pubkey ${keypairPath}`, { encoding: 'utf8' }).trim() // Update lib.rs libRsContent = libRsContent.replace(/declare_id!$".*"$;/, `declare_id!("${programId}");`) // Update Anchor.toml anchorTomlContent = anchorTomlContent.replace(/solana_distributor = ".*"/, `solana_distributor = "${programId}"`) return programId } ``` #### Client Regeneration ```typescript // Automatic sync after program changes const codamaSynced = await ensureGillCodamaSync({ workingDir }) if (!codamaSynced) { console.log('⚠️ Warning: Could not sync Codama client') } ``` --- ## 7. Frontend Integration & User Experience **The user experience challenge**: Even the most technically perfect airdrop is useless if normal users can't figure out how to claim their tokens. We need to hide the complexity behind a simple, intuitive interface. **Our approach**: We create a React-based frontend that handles all the complex blockchain interactions behind the scenes. Users just click a button and see friendly status messages. ### Claim Flow Implementation **What a good claim flow looks like**: Check eligibility → Verify not already claimed → Generate proof → Submit transaction → Show success. Each step should have clear feedback so users know what's happening. #### React Hook for Airdrop Claims ```typescript // src/hooks/useAirdropClaim.ts export function useAirdropClaim(): UseAirdropClaimResult { const [isLoading, setIsLoading] = useState(false) const [status, setStatus] = useState('') const handleClaimAirdrop = async () => { setIsLoading(true) setStatus('Initializing...') try { // 1. Validate configuration validateConfig() // 2. Check if already claimed setStatus('Checking if airdrop has already been claimed...') const alreadyClaimed = await checkClaimStatus(config, privateKey) if (alreadyClaimed) { setStatus('Already claimed') return } // 3. Execute claim setStatus('Claiming airdrop...') const result = await claimAirdrop(config, privateKey) setStatus('Success!') // Show success UI } catch (error) { setStatus('Error occurred') // Handle error } finally { setIsLoading(false) } } return { isLoading, status, handleClaimAirdrop } } ``` #### Claim Button Component ```typescript // src/components/claim-button.tsx export const ClaimButton = () => { const { isLoading, status, handleClaimAirdrop } = useAirdropClaim() return (

Airdrop Claim

{status && (

{status}

)}

) } ``` ### State Management #### Claim Status Checking ```typescript export async function checkClaimStatus( config: AirdropClaimConfig, privateKey: string ): Promise { const clientInstance = createClientInstance(config.network) const signer = await createKeyPairSignerFromBytes(bs58.decode(privateKey)) // Derive claim status PDA const [userClaimPda] = await getProgramDerivedAddress({ programAddress, seeds: ['claim', bs58.decode(airdropStatePda), bs58.decode(signer.address)], }) try { const accountInfo = await clientInstance.rpc.getAccountInfo(address(userClaimPda)).send() return accountInfo.value !== null // Account exists = claimed } catch { return false } } ``` #### Transaction Execution ```typescript async function sendClaimTransaction(clientInstance, params) { const { signer, programAddress, airdropStatePda, userClaimPda, proof } = params // Serialize instruction data const instructionData = serializeClaimInstructionData({ amount: proof.amount, proof: proof.proof, leafIndex: proof.leafIndex, }) // Create transaction const transaction = createTransaction({ version: 'legacy', feePayer: signer, instructions: [{ programAddress, accounts: [ { address: address(airdropStatePda), role: ACCOUNT_ROLES.WRITABLE }, { address: address(userClaimPda), role: ACCOUNT_ROLES.WRITABLE }, { address: signer.address, role: ACCOUNT_ROLES.WRITABLE_SIGNER }, { address: address(PROGRAM_ADDRESSES.SYSTEM_PROGRAM), role: ACCOUNT_ROLES.READONLY }, ], data: instructionData, }], latestBlockhash, }) return await clientInstance.sendAndConfirmTransaction(transaction) } ``` ### Error Handling & User Feedback #### Comprehensive Error Messages ```typescript if (!proof) { throw new Error(`Address ${signer.address} is not eligible for this airdrop`) } if (balanceLamports < minBalanceLamports) { throw new Error( `Insufficient SOL balance: ${balanceLamports / 1e9} SOL. ` + `Need at least ${AIRDROP_CONFIG.MIN_SOL_BALANCE} SOL for transaction fees.` ) } if (alreadyClaimed) { throw new Error('Airdrop has already been claimed for this address') } ``` #### Real-time Status Updates ```typescript setStatus('Checking if airdrop has already been claimed...') // ... check claim status setStatus('Claiming airdrop...') // ... execute transaction setStatus('Success!') // ... show success message ``` --- ## 8. Testing & Validation Strategy **Why testing is critical**: In traditional software, bugs can be fixed with updates. In blockchain, once your program is deployed, bugs can mean lost funds and broken trust. Comprehensive testing isn't optional — it's survival. **Our testing philosophy**: Test everything, from individual functions to complete user flows. Use automated tests to catch regressions, and simulate real-world conditions to find edge cases. ### Comprehensive Test Coverage **What we test**: End-to-end flows (create airdrop → claim tokens), individual components (Merkle tree generation, proof verification), error conditions (double claims, invalid proofs), and edge cases (empty trees, large recipient sets). #### End-to-End Integration Tests ```typescript // anchor/tests/solana-distributor-comprehensive.test.ts describe('Solana Distributor (Comprehensive Gill + Codama)', () => { let client: ReturnType let authority: TransactionSigner let recipient1: TransactionSigner let recipient2: TransactionSigner let merkleTreeResult: { merkleRoot: string; merkleTree: GillMerkleTree } beforeAll(async () => { // Setup test environment client = createSolanaClient({ urlOrMoniker: 'devnet' }) // Load deployment wallet const walletData = fs.readFileSync('./deploy-wallet.json', 'utf8') authority = await createKeyPairSignerFromBytes(new Uint8Array(JSON.parse(walletData))) // Generate test recipients recipient1 = await generateKeyPairSigner() recipient2 = await generateKeyPairSigner() // Fund test accounts await rpc.requestAirdrop(recipient1.address, lamports(10000000n)).send() await rpc.requestAirdrop(recipient2.address, lamports(10000000n)).send() // Generate Merkle tree merkleTreeResult = generateGillMerkleTree(recipientsData) }) }) ``` #### Unit Tests for Merkle Operations ```typescript test('Initialize airdrop with Merkle tree (Gill + Codama)', async () => { const initializeInstruction = getInitializeAirdropInstruction({ airdropState: airdropStatePda, authority: authority, merkleRoot: new Uint8Array(merkleTreeResult.merkleTree.root), amount: BigInt(totalAmount), }) const transaction = createTransaction({ version: 'legacy', feePayer: authority, instructions: [initializeInstruction], latestBlockhash, }) const signature = await sendAndConfirmTransaction(transaction) // Verify state const airdropState = await fetchAirdropState(rpc, airdropStatePda) expect(airdropState!.data.merkleRoot).toEqual(Array.from(merkleTreeResult.merkleTree.root)) expect(Number(airdropState!.data.airdropAmount)).toBe(totalAmount) }) ``` #### Claim Validation Tests ```typescript test('Claim SOL - Recipient 1 (Gill + Codama)', async () => { // Generate proof const proofResult = generateGillProof(merkleTreeResult.merkleTree, 0) // Check balance before const balanceBefore = await rpc.getBalance(recipient1.address).send() // Execute claim const claimInstruction = getClaimAirdropInstruction({ airdropState: airdropStatePda, userClaim: address(claimStatusPda), signer: recipient1, proof: proofResult.proof.map(p => new Uint8Array(Buffer.from(p.slice(2), 'hex'))), amount: BigInt(recipient1Amount), leafIndex: 0, }) const signature = await sendAndConfirmTransaction(transaction) // Verify balance increase const balanceAfter = await rpc.getBalance(recipient1.address).send() const balanceIncrease = Number(balanceAfter.value) - Number(balanceBefore.value) expect(balanceIncrease).toBeCloseTo(recipient1Amount, -5) // Verify claim status created const claimStatus = await fetchClaimStatus(rpc, address(claimStatusPda)) expect(claimStatus).toBeTruthy() }) ``` #### Error Case Testing ```typescript test('Should fail to claim twice (Gill + Codama)', async () => { const proofResult = generateGillProof(merkleTreeResult.merkleTree, 0) const claimInstruction = getClaimAirdropInstruction({ // ... same parameters as successful claim }) const transaction = createTransaction({ version: 'legacy', feePayer: recipient1, instructions: [claimInstruction], latestBlockhash, }) // Should fail because claim status account already exists await expect(sendAndConfirmTransaction(transaction)).rejects.toThrow() }) ``` ### Validation Strategies #### Merkle Tree Consistency ```typescript // Verify client and on-chain proof verification match function verifyProofConsistency(proof: string[], leaf: string, root: string): boolean { let computedHash = Buffer.from(leaf.replace('0x', ''), 'hex') for (const proofElement of proof) { const proofBuf = Buffer.from(proofElement.replace('0x', ''), 'hex') if (Buffer.compare(computedHash, proofBuf) < 0) { computedHash = Buffer.from(keccak_256.arrayBuffer(Buffer.concat([computedHash, proofBuf]))) } else { computedHash = Buffer.from(keccak_256.arrayBuffer(Buffer.concat([proofBuf, computedHash]))) } } return '0x' + computedHash.toString('hex') === root } ``` #### Account State Verification ```typescript // Verify PDA derivation matches expected seeds const [expectedPda] = await getProgramDerivedAddress({ programAddress: SOLANA_DISTRIBUTOR_PROGRAM_ADDRESS, seeds: ['merkle_tree'], }) expect(airdropStatePda).toBe(expectedPda) ``` --- ## 9. Security Considerations & Best Practices **The stakes**: In blockchain, security isn't just about protecting data — it's about protecting money. A single vulnerability can drain an entire airdrop budget or allow unlimited token generation. **Defense in depth**: We use multiple layers of security: cryptographic proofs, access controls, input validation, and careful state management. If one layer fails, others should catch the attack. ### Common Pitfalls & Solutions **Learning from others' mistakes**: The blockchain space is littered with hacks and exploits. We study common attack patterns and build defenses against them proactively. #### Proof Mismatch Issues **Problem**: Client and on-chain verification disagree **Causes**: 1. Different leaf encoding (byte order, field order) 2. Different hash functions (SHA-256 vs Keccak-256) 3. Incorrect proof order or tree construction **Solution**: ```typescript // Ensure exact matching between client and on-chain const createLeafHash = (recipient: Address, amount: number, isClaimed: boolean = false): string => { const recipientBytes = bs58.decode(recipient) const data = Buffer.concat([ Buffer.from(recipientBytes), // 32 bytes Buffer.from(new Uint8Array(new BigUint64Array([BigInt(amount)]).buffer)), // 8 bytes LE Buffer.from([isClaimed ? 1 : 0]), // 1 byte ]) return '0x' + Buffer.from(keccak_256.arrayBuffer(data)).toString('hex') } ``` #### Program ID Consistency **Problem**: Deployed program ID differs from client expectations **Solution**: Automatic synchronization ```typescript async function ensureGillProgramIdConsistency( newProgramId?: string, config: GillBuildConfig = {} ): Promise { const { workingDir = '.' } = config // Get current program ID from lib.rs const libRsPath = path.join(workingDir, 'programs', 'solana-distributor', 'src', 'lib.rs') const libRsContent = fs.readFileSync(libRsPath, 'utf8') const currentMatch = libRsContent.match(/declare_id!$"(.*)"$;/) // Update if different if (newProgramId && currentMatch && currentMatch[1] !== newProgramId) { // Update lib.rs, Anchor.toml, and regenerate client return await updateProgramIdEverywhere(newProgramId, config) } return true } ``` ### Production Deployment Considerations #### Upgrade Authority Management ```rust // Consider making program immutable for security // anchor upgrade --program-id --buffer --authority ``` **Recommendations**: 1. **Testing Phase**: Keep upgrade authority for bug fixes 2. **Production**: Transfer to multisig or make immutable 3. **Documentation**: Clear upgrade/immutability policy #### Compute Budget Considerations ```typescript // For large recipient sets, monitor compute usage const computeBudgetIx = ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000, // Adjust based on proof depth }) const transaction = createTransaction({ instructions: [computeBudgetIx, claimInstruction], // ... }) ``` **Guidelines**: - **Proof Depth**: ~200 CU per proof element - **Max Recipients**: ~10,000 for single transaction - **Larger Sets**: Consider multiple distributions #### Transaction Size Limits **Solana Limits**: - Max transaction size: 1232 bytes - Max accounts: 64 per transaction - Max instruction data: ~1000 bytes **For Large Proofs**: ```typescript if (proof.length > 15) { throw new Error('Proof too large for single transaction. Consider splitting distribution.') } ``` ### Security Audit Checklist #### Smart Contract Security - [ ] **Integer Overflow**: Use saturating arithmetic - [ ] **Access Control**: Verify authority checks - [ ] **PDA Security**: Correct seed derivation - [ ] **Account Validation**: Proper constraints - [ ] **Reentrancy**: Not applicable (no external calls) #### Cryptographic Security - [ ] **Hash Function**: Keccak-256 consistency - [ ] **Leaf Encoding**: Exact byte-level matching - [ ] **Proof Order**: Consistent tree traversal - [ ] **Root Immutability**: Cannot be changed post-init #### Operational Security - [ ] **Key Management**: Secure authority key storage - [ ] **Network Security**: Proper RPC endpoint validation - [ ] **Environment Variables**: Secure secret handling - [ ] **Monitoring**: Transaction and balance tracking --- ## 10. Operational Procedures **From development to production**: Building the airdrop system is only half the battle. You also need reliable processes for deployment, monitoring, and maintenance. This section covers the operational side — the "how to run this in the real world" part. **Why process matters**: A technically perfect system can still fail due to operational mistakes: wrong network deployment, lost keys, insufficient monitoring, or poor incident response. ### Setup & Initialization Process **The deployment journey**: Getting from "it works on my machine" to "it's live and serving thousands of users" requires careful orchestration of multiple steps, each with its own potential failure points. #### Step-by-Step Deployment ```bash # 1. Clone and install git clone cd gill-jito-airdrop pnpm install # 2. Generate TypeScript clients pnpm codama:generate # 3. Interactive setup (creates wallets, deploys program) pnpm airdrop:setup # 4. Initialize airdrop state on-chain pnpm airdrop:init # 5. Start frontend pnpm dev ``` #### Environment Configuration ```typescript // .env.local (automatically created by setup) NEXT_PUBLIC_PROGRAM_ID=AV6HAHbuAxV5hgjF6qGNaYeAhmYZNWKDhi3pdr6wkDXr NEXT_PUBLIC_SOLANA_NETWORK=devnet USER_PRIVATE_KEY=base58_encoded_private_key ``` #### Key Management Best Practices ```typescript // Development: Use environment variables const privateKey = process.env.USER_PRIVATE_KEY // Production: Use secure key management // - Hardware wallets (Ledger, Trezor) // - Key management services (AWS KMS, HashiCorp Vault) // - Multisig wallets ``` ### Monitoring & Maintenance #### Tracking Claim Progress ```typescript async function getAirdropProgress(): Promise<{ totalAmount: number claimedAmount: number remainingAmount: number percentComplete: number }> { const airdropState = await fetchAirdropState(rpc, airdropStatePda) if (!airdropState) { throw new Error('Airdrop not initialized') } const totalAmount = Number(airdropState.data.airdropAmount) const claimedAmount = Number(airdropState.data.amountClaimed) const remainingAmount = totalAmount - claimedAmount const percentComplete = (claimedAmount / totalAmount) * 100 return { totalAmount, claimedAmount, remainingAmount, percentComplete } } ``` #### Balance Monitoring ```typescript async function monitorVaultBalance(): Promise { const balance = await rpc.getBalance(airdropStatePda).send() const balanceSOL = Number(balance.value) / 1e9 console.log(`Vault Balance: ${balanceSOL} SOL`) if (balanceSOL < 0.1) { console.warn('⚠️ Low vault balance detected!') } } ``` #### Error Handling & Support ```typescript // Common error scenarios and solutions const ERROR_SOLUTIONS = { 'Address not eligible': 'Recipient not in original list', 'Already claimed': 'Double-claim prevention worked', 'Invalid proof': 'Merkle proof verification failed - check tree generation', 'Insufficient funds': 'Vault needs more SOL or recipient needs transaction fees', 'Program ID mismatch': 'Client out of sync - regenerate with pnpm codama:generate' } ``` ### Merkle Root Updates #### Adding New Recipients ```typescript // Note: This requires update_merkle_root instruction async function updateAirdropRecipients( newRecipients: GillRecipient[], additionalSOL: number ): Promise { // 1. Generate new Merkle tree const newMerkleTree = new GillMerkleTree(newRecipients) // 2. Call update instruction const updateInstruction = getUpdateMerkleRootInstruction({ airdropState: airdropStatePda, authority: authoritySigner, newMerkleRoot: new Uint8Array(newMerkleTree.root), additionalAmount: BigInt(additionalSOL * 1e9), }) // 3. Execute transaction const signature = await sendAndConfirmTransaction(transaction) // 4. Update recipients.json file // 5. Regenerate client with new data } ``` **Important**: This invalidates existing unclaimed proofs! ### Production Checklist #### Pre-Launch - [ ] **Security Audit**: Third-party code review - [ ] **Load Testing**: Test with realistic recipient counts - [ ] **Network Testing**: Verify on target network (mainnet/devnet) - [ ] **Key Security**: Secure authority key storage - [ ] **Monitoring**: Set up balance and progress tracking - [ ] **Documentation**: User guides and troubleshooting #### Launch Day - [ ] **Final Testing**: Verify all systems operational - [ ] **Recipient Notification**: Announce airdrop availability - [ ] **Support Preparation**: Ready for user questions - [ ] **Monitoring**: Watch for unusual activity or errors #### Post-Launch - [ ] **Progress Tracking**: Regular balance and claim monitoring - [ ] **User Support**: Handle eligibility and technical questions - [ ] **Security Monitoring**: Watch for suspicious activity - [ ] **Completion Planning**: Handle remaining funds and closure --- ## Conclusion **What we've built together**: We've walked through creating a production-ready airdrop system that can distribute tokens to thousands of people efficiently and securely. More importantly, we've done it using modern tools that make the development process smoother and less error-prone. **Why this approach matters**: Traditional airdrop methods are either expensive (storing everything on-chain) or insecure (relying on centralized systems). Our Merkle tree approach gives you the best of both worlds: blockchain security with minimal on-chain storage costs. This comprehensive guide covers the complete technical implementation of the Solana Merkle Airdrop Distributor using modern tooling. The combination of Gill, Codama, and Anchor provides a robust, secure, and developer-friendly approach to large-scale token distribution. ### Key Takeaways 1. **Merkle Trees**: Enable efficient, scalable airdrops with cryptographic proof 2. **Modern Tooling**: Gill + Codama + Anchor provide excellent developer experience 3. **Security First**: Multiple layers of protection against common attack vectors 4. **Type Safety**: Generated clients ensure consistency between on-chain and off-chain code 5. **Operational Excellence**: Comprehensive testing, monitoring, and maintenance procedures ### Next Steps - Customize recipient lists for your specific use case - Adapt the frontend for your brand and user experience - Consider additional features like vesting or multiple token types - Plan for scaling to larger recipient sets if needed For questions or contributions, refer to the project repository and documentation. --- *This guide represents a complete technical reference for implementing and operating Solana airdrop systems using modern best practices and tooling.*

Solana SOL Merkle Distributor: Gas-Efficient Airdrop Program