Solana

Solana RPC, x402 V2 Verification & Full E2E Testing (Agave v3.x/v4.x)

This skill defines the complete pipeline for testing Solana applications locally without Docker. It covers native validator installation, CLI token provisioning, and a fully functional Rust E2E test simulating an x402 HTTP handshake.

1. Native Installation & Localnet Automation (Bash)

Because Apple Silicon Docker containers panic on AVX instructions during Genesis Block creation, your E2E pipelines (and CI/CD scripts) must install the Agave binaries natively and start the validator in the background.

Important: Always export the Agave binary path before running CLI commands.

Provide the LLM or developer with this automation script (setup_e2e.sh):

#!/bin/bash
set -e

# Export Agave binary path (required for spl-token and solana CLI commands)
export PATH="/Users/$(whoami)/.local/share/solana/install/active_release/bin:$PATH"

echo "1. Installing Agave (Solana v3/v4) Natively..."
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

echo "2. Starting Localnet in Background..."
killall solana-test-validator || true
solana-test-validator --reset > validator.log 2>&1 &
sleep 10 # Wait for Genesis Block creation (increase if your system is slow)

echo "3. Configuring CLI to Localhost..."
solana config set --url http://127.0.0.1:8899
solana config set --commitment confirmed

echo "4. Provisioning E2E Test Environment..."
# Generate test keypairs
solana-keygen new --outfile merchant.json --no-bip39-passphrase --force
solana-keygen new --outfile agent.json --no-bip39-passphrase --force

# Airdrop SOL to all keypairs (including default keypair for transaction fees)
echo "Airdropping SOL..."
solana airdrop 10 $(solana-keygen pubkey agent.json)
solana airdrop 10 $(solana-keygen pubkey merchant.json)
solana airdrop 5 # Airdrop to default keypair for fee payment

# Create Mock USDC token (6 decimals, matching real USDC)
echo "Creating Mock USDC token..."
MOCK_USDC=$(spl-token create-token --decimals 6 | grep "Creating token" | awk '{print $3}')
echo "Mock USDC Mint: $MOCK_USDC"

# Create token accounts for merchant and agent (use default keypair as fee payer)
echo "Creating token accounts..."
spl-token create-account $MOCK_USDC --owner merchant.json
spl-token create-account $MOCK_USDC --owner agent.json

# Mint 100 Mock USDC to agent's token account
echo "Minting tokens to agent..."
AGENT_TOKEN_ACCOUNT=$(spl-token address --token $MOCK_USDC --owner agent.json --verbose | grep "Associated Token Address" | awk '{print $NF}')
spl-token mint $MOCK_USDC 100 $AGENT_TOKEN_ACCOUNT

echo "✅ Environment Ready!"
# Save environment variables for Rust test
echo "MOCK_USDC_MINT=$MOCK_USDC" > .env
echo "MERCHANT_PUBKEY=$(solana-keygen pubkey merchant.json)" >> .env
echo "AGENT_KEYPAIR_PATH=agent.json" >> .env
cat .env

2. Rust Dependencies

Use these latest verified compatible versions (May 2026):

[dependencies]
solana-client = "4.0"
solana-sdk = "4.0"
solana-commitment-config = "3.1"
solana-transaction-status = "3.1"
spl-token = "9.0"
spl-associated-token-account = "3.0"
tokio = { version = "1", features = ["full"] }
dotenv = "0.15"

Note: If you encounter build errors related to spl-pod or solana-program, run cargo update to sync to latest compatible versions.

3. The Full Rust E2E Test Suite

This complete Rust test verifies the full x402 lifecycle: 1. The Agent creates a Solana transaction and transfers Mock USDC to the Merchant. 2. The Server intercepts the PAYMENT-SIGNATURE, queries the local RPC, and verifies the pre/post token balance deltas.

Create src/main.rs (or tests/e2e_tests.rs for integration tests):

#[cfg(test)]
mod e2e_tests {
    use solana_client::nonblocking::rpc_client::RpcClient;
    use solana_client::rpc_config::RpcTransactionConfig;
    use solana_commitment_config::CommitmentConfig;
    use solana_transaction_status::{UiTransactionEncoding, EncodedConfirmedTransactionWithStatusMeta};
    use solana_sdk::{
        signature::{Keypair, Signature, Signer},
        pubkey::Pubkey,
        transaction::Transaction,
    };
    use std::str::FromStr;
    use std::sync::Arc;
    use std::env;

    /// SERVER LOGIC: Verifies the exact payment amount hit the Merchant's account
    async fn verify_x402_payment(
        client: &RpcClient, 
        signature_str: &str, 
        merchant_pubkey: &str, 
        expected_amount_decimals: u64
    ) -> Result<bool, Box<dyn std::error::Error>> {
        let sig = Signature::from_str(signature_str)?;
        let config = RpcTransactionConfig {
            encoding: Some(UiTransactionEncoding::JsonParsed),
            commitment: Some(CommitmentConfig::confirmed()),
            max_supported_transaction_version: Some(1),
        };

        let tx: EncodedConfirmedTransactionWithStatusMeta = client
            .get_transaction_with_config(&sig, config)
            .await?;

        let meta = tx.transaction.meta.unwrap();
        if meta.err.is_some() { 
            return Ok(false); 
        }

        if let (Some(pre_tokens), Some(post_tokens)) = (meta.pre_token_balances, meta.post_token_balances) {
            for post in post_tokens {
                if post.owner == Some(merchant_pubkey.to_string()) {
                    let post_amt: u64 = post.ui_token_amount.amount.parse().unwrap_or(0);
                    let pre_amt: u64 = pre_tokens.iter()
                        .find(|pre| pre.account_index == post.account_index)
                        .map(|pre| pre.ui_token_amount.amount.parse().unwrap_or(0))
                        .unwrap_or(0);

                    if post_amt > pre_amt {
                        let actual_received = post_amt - pre_amt;
                        if actual_received == expected_amount_decimals {
                            return Ok(true);
                        }
                    }
                }
            }
        }
        Ok(false)
    }

    #[tokio::test]
    async fn test_full_x402_flow() {
        dotenv::dotenv().ok();
        
        let rpc_url = "http://127.0.0.1:8899";
        let client = Arc::new(RpcClient::new(rpc_url.to_string()));

        let mint_pubkey = Pubkey::from_str(&env::var("MOCK_USDC_MINT").unwrap()).unwrap();
        let merchant_pubkey = Pubkey::from_str(&env::var("MERCHANT_PUBKEY").unwrap()).unwrap();
        
        let agent_keypair_path = env::var("AGENT_KEYPAIR_PATH").unwrap();
        let agent_wallet = solana_sdk::signature::read_keypair_file(&agent_keypair_path).unwrap();

        let agent_ata = spl_associated_token_account::get_associated_token_address(&agent_wallet.pubkey(), &mint_pubkey);
        let merchant_ata = spl_associated_token_account::get_associated_token_address(&merchant_pubkey, &mint_pubkey);

        let invoice_amount: u64 = 1_000_000; // 1.0 USDC (6 decimals)

        let transfer_ix = spl_token::instruction::transfer(
            &spl_token::id(),
            &agent_ata,
            &merchant_ata,
            &agent_wallet.pubkey(),
            &[&agent_wallet.pubkey()],
            invoice_amount,
        ).unwrap();

        let recent_blockhash = client.get_latest_blockhash().await.unwrap();
        let tx = Transaction::new_signed_with_payer(
            &[transfer_ix],
            Some(&agent_wallet.pubkey()),
            &[&agent_wallet],
            recent_blockhash,
        );

        let signature = client.send_and_confirm_transaction(&tx).await.unwrap();
        println!("🤖 AGENT: Payment Sent! Signature: {}", signature);

        let is_valid = verify_x402_payment(
            &client, 
            &signature.to_string(), 
            &merchant_pubkey.to_string(), 
            invoice_amount
        ).await.unwrap();

        assert!(is_valid, "❌ x402 Server Verification Failed!");
        println!("✅ SERVER: Payment Verified. E2E Test Passed!");
    }
}

4. Running the Test

1. Run the setup script to provision the local environment:

chmod +x setup_e2e.sh && ./setup_e2e.sh

2. Initialize a Rust project:

cargo init --name solana_e2e_test

3. Copy dependencies to Cargo.toml and test code to src/main.rs

4. Run the test:

export PATH="/Users/$(whoami)/.local/share/solana/install/active_release/bin:$PATH"
cargo test test_full_x402_flow -- --nocapture

5. Troubleshooting

• Validator not starting: Check validator.log for errors
• PATH errors: Always export Agave binary path before CLI commands
• Airdrop failures: Wait a few seconds and retry due to rate limits
• Build errors: Run cargo update to sync dependencies

Known Issues — Solana Skill

Issues discovered through practical compilation testing against actual crate versions (solana-client 3.1.x, solana-sdk 4.0.x).

1. solana_sdk::commitment_config Not Re-Exported in v4.x (BREAKING)

The CommitmentConfig type is no longer in solana_sdk::commitment_config. It is now in a separate crate:

// WRONG (skill's code):
use solana_sdk::commitment_config::CommitmentConfig;

// CORRECT:
// Add to Cargo.toml: solana-commitment-config = "3"
use solana_commitment_config::CommitmentConfig;

2. solana_transaction_status as Separate Crate

The UiTransactionEncoding and EncodedConfirmedTransactionWithStatusMeta types require the solana-transaction-status crate as a separate dependency in v4.x:

[dependencies]
solana-transaction-status = "3"

3. Version Notes

• solana-client = "3.1" — Correct. Solana v4.x is pre-release (4.0.0-beta.7) and has incompatible sub-crate versions (solana-transaction-status-client-types conflicts). Stay on 3.1 for stable.
• spl-token = "4.0" → Updated to `"9.0"`. The latest stable SPL token crate is v9.x, fully backward-compatible with solana-client 3.1.
• solana-sdk = "4.0" — Correct. Latest stable is 4.0.1.

solana-skills

A specialized skill for interacting with Solana/Agave blockchains using solana-client v3.x and solana-sdk v4.x.

Overview

Unlike EVM networks which offer eth_getLogs for sweeping events, Solana requires polling account signatures and parsing transaction metadata to extract Native SOL and SPL Token transfers. Furthermore, modern Web3 protocols (like x402 V2) demand precise cryptographic verification and robust End-to-End (E2E) testing environments.

This skill provides the exact patterns required for fetching and parsing transactions, verifying x402 protocol payment signatures, and automating native Agave localnet E2E testing pipelines (specifically engineered to bypass Apple Silicon Docker panics).

Installation

npx skills add melonask/solana-skills

What This Skill Covers

• Native E2E Localnet Automation: Bash scripts to natively install Agave, spin up solana-test-validator, and provision mock SPL tokens (avoiding Rosetta 2 AVX Docker panics on M-series Macs).
• x402 V2 Protocol Verification: Mathematically verifying exact pre/post SPL token balances for a single PAYMENT-SIGNATURE payload.
• Full Rust E2E Testing: Using #[tokio::test] to simulate both the Client (executing transfers) and the Server (intercepting and verifying transactions via RPC).
• RPC Connections: Utilizing modern asynchronous solana_client::nonblocking::rpc_client::RpcClient.
• Signature Sweeping: Polling get_signatures_for_address_with_config for background ledger synchronization.
• Ledger Mapping: Using account_index as a unique event_idx to prevent double-crediting in SQL databases.

File Structure

solana/
└── SKILL.md                          # Main skill file (Localnet automation, x402 verification, E2E Rust tests, and ledger sweeping)

License

Provided as-is for development with LLM assistants.