ZAN

https://docs.zan.top/docs/
Admin
ZAN is a technology brand from Ant Digital Technologies that provides a comprehensive suite of Web3...
Tokens:75,442
Snippets:765
Trust Score:8.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Zan x402 SDK and Dependencies

Source: https://docs.zan.top/docs/quickstart-guide-x402

Install the core SDK and viem for EVM compatibility. Additional packages are needed for Solana authentication and payments.

```bash
npm install @zan_team/x402 viem
```

```bash
npm install @solana/web3.js @solana/spl-token bs58 tweetnacl
```

--------------------------------

### Install ZAN x402 SDK

Source: https://docs.zan.top/docs/introduction-x402

Installs the necessary packages for using the ZAN x402 SDK with viem.

```bash
# Install
npm install @zan_team/x402 viem
```

--------------------------------

### Install ZAN SDK with yarn

Source: https://docs.zan.top/docs/zan-sdk

Install the ZAN SDK using yarn. This is an alternative package manager for installing the SDK.

```bash
yarn add zan-sdk
```

--------------------------------

### One-Click Installation Script for SmartCogent

Source: https://docs.zan.top/docs/how-to-install-smartcogent

Use this command for a quick, one-click installation of SmartCogent. Ensure curl and bash are installed on your system beforehand.

```shell
curl --retry 3 -o- https://static.zan.top/smartcogent/install.sh | bash
```

--------------------------------

### Run QUIC Client Example

Source: https://docs.zan.top/docs/quic

Executes the QUIC client demo with specified parameters for endpoint, keypair, API key, and RPC URL.

```bash
# cargo run --bin client_quic_demo <QUIC_ENDPOINT> <KEYPAIR_PATH> <API_KEY> <RPC_URL>
cargo run --bin client_quic_demo -- \
  "fra.zan.top:21000" \
  "./client_id.json" \
  "00f7xxxc088" \
  "https://api.zan.top/node/v1/solana/mainnet/00f7xxxc088"
```

--------------------------------

### Complete X402 SDK Example: AI Agent On-Chain Settlement

Source: https://docs.zan.top/docs/quickstart-guide-x402

A full-stack example demonstrating client creation, network discovery, balance check, RPC calls, and fetch usage within an async function.

```typescript
import { createX402Client } from '@zan_team/x402';

async function main() {
  // 1. Create client (EVM)
  const client = await createX402Client({
    gatewayUrl: 'https://x402.zan.top',
    privateKey: process.env.PRIVATE_KEY as `0x${string}`,
    autoPayment: true,
    preAuth: true,
  });

  // 2. Discover available networks
  const { networks } = await client.listNetworks();
  console.log(`✅ Available networks: ${networks.length}`);

  // 3. Check balance
  const { balance } = await client.getBalance();
  console.log(`✅ Current balance: ${balance}`);

  // 4. Call RPC
  const block = await client.call('eth', 'mainnet', 'eth_blockNumber');
  console.log(`✅ Latest block: ${block.result}`);

  // 5. Use fetch call
  const res = await client.fetch('/rpc/eth/mainnet', {
    method: 'POST',
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'eth_getBlockByNumber',
      params: ['latest', false],
    }),
  });
  const blockData = await res.json();
  console.log(`✅ Block details: ${blockData.result.number}`);

  console.log('
🎉 All operations completed!');
}

main().catch(console.error);
```

--------------------------------

### Install ZAN SDK with npm

Source: https://docs.zan.top/docs/zan-sdk

Install the ZAN SDK using npm. This is the first step to begin using the SDK in your project.

```bash
npm install zan-sdk
```

--------------------------------

### QUIC Client Output Example

Source: https://docs.zan.top/docs/quic

Illustrates the expected output when the QUIC client connects and sends a transaction.

```plain
Connecting to Zan QUIC server: fra.zan.top:21000 (keypair: ..., api_key: 00f76627)...
Connected!
Sending transaction via uni stream (123 bytes, mTLS auth)...
Transaction sent successfully! signature: xxx, latency: 45.32 ms
```

--------------------------------

### Example Property Annotation

Source: https://docs.zan.top/docs/formal-verification

Illustrates a concrete example of a property annotation using the 'if_succeeds' type.

```solidity
/// #if_succeeds {:msg "This is an example"} a == 1;
```

--------------------------------

### Example Transaction Instruction with SOL Tip

Source: https://docs.zan.top/docs/integration-guide

This example demonstrates how to add a SOL transfer to ZAN's tip account within your transaction instructions. Ensure you have the necessary Solana SDKs and wallet adapters configured.

```javascript
import { Transaction, SystemProgram, LAMPORTS_PER_SOL } from '@solana/web3.js';

const tipAmountLamports = 0.0003 * LAMPORTS_PER_SOL; // Minimum tip amount
const tipAccount = '7HkiWXe5deJvzn4D6kgMUFCADwX9Z4DMrdjNSSxN6bPp';

// Assuming 'transaction' is an existing Transaction object and 'fromPublicKey' is the sender's PublicKey

transaction.add(SystemProgram.transfer({
  fromPubkey: fromPublicKey,
  toPubkey: tipAccount,
  lamports: tipAmountLamports,
}));

// Proceed to sign and send the transaction
```

--------------------------------

### Initialize X402 Client with viem WalletClient

Source: https://docs.zan.top/docs/quickstart-guide-x402

Initialize the X402 client using an existing viem WalletClient. This allows integration with existing viem setups and provides flexibility in wallet management.

```typescript
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { mainnet } from 'viem/chains';
import { X402Client } from '@zan_team/x402';

const wallet = createWalletClient({
  account: privateKeyToAccount('0xYourPrivateKey'),
  chain: mainnet,
  transport: http(),
});

const client = new X402Client({
  gatewayUrl: 'https://x402.zan.top',
  wallet,
  autoPayment: true,
});
```

--------------------------------

### Environment Variables for Private Keys

Source: https://docs.zan.top/docs/quickstart-guide-x402

Example of setting up environment variables for private keys, including EVM and Solana. Emphasizes not committing sensitive keys to version control.

```bash
# .env file
# EVM private key (do not commit to version control!)
PRIVATE_KEY=0xYourEVMPrivateKeyHere...

# Or Solana private key
# SVM_PRIVATE_KEY=YourSolanaBase58PrivateKeyHere...
```

--------------------------------

### QUIC Client Main Function Setup

Source: https://docs.zan.top/docs/quic

Sets up the main function for a QUIC client, parsing command-line arguments for address, keypair path, API key, and RPC URL. It also reads a keypair and fetches the latest blockhash.

```rust
@tokio::main
async fn main() -> Result<()> {
    let args: Vec<String> = std::env::args().collect();
    let addr = args.get(1).cloned().unwrap_or_else(|| "fra.zan.top:21000".to_string());
    let keypair_path = args.get(2).cloned().unwrap_or_else(|| "client_id.json".to_string());
    let api_key = args.get(3).cloned().unwrap_or_else(|| "00f7xxxc088".to_string());
    let rpc_url = args.get(4).cloned().unwrap_or_else(|| "https://api.zan.top/node/v1/solana/mainnet/00f7xxxc088".to_string());

    // Read real account with SOL from file (for transaction signing)
    let keypair = read_keypair_file(&keypair_path)
        .map_err(|e| anyhow::anyhow!("read keypair: {}", e))?;
    let rpc = RpcClient::new(rpc_url);
    let blockhash = rpc.get_latest_blockhash().context("get blockhash")?;
    let msg = Message::new(
        &[instruction::transfer(
            &keypair.pubkey(),
            &keypair.pubkey(),
            1_000,
        )],
        Some(&keypair.pubkey()),
    );

```

--------------------------------

### SmartCogent Installation Output and Configuration

Source: https://docs.zan.top/docs/how-to-install-smartcogent

This output details the successful installation of SmartCogent, including NVM installation and the configuration settings for Cline MCP. It shows how to add SmartCogent to your Cline MCP settings with environment variables for access key, RPC URL, and public key.

```shell
$ curl -o- https://static.zan.top/smartcogent/install.sh | bash
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                   Dload  Upload   Total   Spent    Left  Speed
  100  2679  100  2679    0     0    120      0  0:00:22  0:00:22 --:--:--   643
  curl is installed at /opt/anaconda3/bin/curl
  NVM is not installed, installing NVM...
    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                   Dload  Upload   Total   Spent    Left  Speed
  100 16631  100 16631    0     0   3578      0  0:00:04  0:00:04 --:--:--  3578

  ...


  Cline MCP settings file location: /Users/<username>/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  Add our tool to your Cline MCP settings:
  {
    "mcpServers": {
      "contract-full-client": {
        "autoApprove": [],
        "disabled": false,
        "timeout": 3600,
        "command": "/Users/web3/node-v22.14.0-darwin-arm64/bin/npx",
        "args": [
          "/Users/web3/node-v22.14.0-darwin-arm64/bin/smartcogent"
        ],
        "env": {
          "ZAN_ACCESS_KEY": "<your_zan_access_key>",
          "RPC_URL": "<your_chain_rpc_url>",
          "PUBLIC_KEY": "<your_chain_account>",
          "HOSTING": "metamask"
        },
        "transportType": "stdio"
      }
    }
  }

```

--------------------------------

### MEV Protection Endpoint Example

Source: https://docs.zan.top/docs/endpoints-regions

Append '?anti-mev=true' to any endpoint to enable MEV protection. This is useful for minimizing front-running and other MEV-related risks.

```http
http://booster-sg.zan.top/node/v1/solana/mainnet/<AK>/tips?anti-mev=true
```

--------------------------------

### Connect to Zan QUIC Client

Source: https://docs.zan.top/docs/quic

Establishes a connection to the Zan QUIC server using the provided endpoint address and API key. This function handles the initial connection setup.

```rust
/// Create Zan QUIC client and connect
/// endpoint_addr: QUIC server address, e.g., "fra.zan.top:21000"
/// api_key: Your API Key
let client = ZanClient::connect(endpoint_addr, api_key).await?;
```

--------------------------------

### Zan QUIC Client Setup and Connection

Source: https://docs.zan.top/docs/quic

This snippet shows how to initialize and connect a Zan QUIC client. It derives a keypair from an API key, generates a self-signed certificate for mTLS, configures QUIC transport settings like keep-alive and idle timeouts, and establishes the initial connection.

```rust
//! Zan-style QUIC Client Example (mTLS + API Key Authentication)
//!
//! Usage: cargo run --bin client_quic_demo -- [BOOSTER_QUIC_ADDR] [KEYPAIR_PATH] [API_KEY] [RPC_URL]
//!
//! Features:
//! - Reads keypair from file for transaction signing (real account with SOL)
//! - Generates mTLS certificate using api_key, CN = api_key for authentication
//! - Supports automatic reconnection

use anyhow::{Context, Result};
use arc_swap::ArcSwap;
use quinn::{
    crypto::rustls::QuicClientConfig,
    ClientConfig, Connection, Endpoint, IdleTimeout,
    TransportConfig,
};
use rustls::pki_types::{CertificateDer, PrivateKeyDer};
use solana_client::rpc_client::RpcClient;
use solana_sdk::{
    message::Message,
    signature::{read_keypair_file, Keypair, Signer},
    transaction::Transaction,
};
use solana_system_interface::instruction;
use solana_perf::packet::PACKET_DATA_SIZE;
use std::{net::SocketAddr, sync::Arc, time::Duration};
use tokio::sync::Mutex;

const ALPN_TPU_PROTOCOL_ID: &[u8] = b"solana-tpu";
const ZAN_SERVER: &str = "zan-node";
const KEEP_ALIVE_INTERVAL: Duration = Duration::from_secs(10);
const MAX_IDLE_TIMEOUT: Duration = Duration::from_secs(30);

/// Zan QUIC client with automatic reconnection.
///
/// Thread-safe: can be shared across tasks via `Arc<ZanClient>`.
pub struct ZanClient {
    endpoint: Endpoint,
    client_config: ClientConfig,
    addr: SocketAddr,
    connection: ArcSwap<Connection>,
    reconnect: Mutex<()>
}

impl ZanClient {
    /// Connect to a Zan endpoint.
    ///
    /// # Arguments
    /// * `endpoint_addr` - Server address (e.g., "fra.zan.top:21000")
    /// * `api_key` - Your Zan API key (e.g., "bs_2294d1eb...")
    pub async fn connect(endpoint_addr: &str, api_key: &str) -> Result<Self> {
        // Derive keypair from API key using SHA256 hash
        use sha2::{Digest, Sha256};
        let mut hasher = Sha256::new();
        hasher.update(api_key.as_bytes());
        let seed: [u8; 32] = hasher.finalize().into();

        // Generate keypair from seed
        let keypair = Keypair::new_from_array(seed);
        let (cert, key) = new_dummy_x509_certificate(&keypair, api_key);

        let mut crypto = rustls::ClientConfig::builder()
            .dangerous()
            .with_custom_certificate_verifier(SkipServerVerification::new())
            .with_client_auth_cert(vec![cert], key)
            .context("failed to configure client certificate")?;

        crypto.alpn_protocols = vec![ALPN_TPU_PROTOCOL_ID.to_vec()];

        let client_crypto = QuicClientConfig::try_from(crypto)
            .context("failed to convert rustls config into quinn crypto config")?;

        let mut client_config = ClientConfig::new(Arc::new(client_crypto));
        let mut transport = TransportConfig::default();
        transport.keep_alive_interval(Some(KEEP_ALIVE_INTERVAL));
        transport.max_idle_timeout(Some(IdleTimeout::try_from(MAX_IDLE_TIMEOUT)?));
        client_config.transport_config(Arc::new(transport));

        let mut endpoint = Endpoint::client("0.0.0.0:0".parse().context("parse bind address")?)?;
        endpoint.set_default_client_config(client_config.clone());

        let addr = resolve(endpoint_addr).await?;
        let connection = endpoint.connect(addr, ZAN_SERVER)?.await?;

        Ok(Self {
            endpoint,
            client_config,
            addr,
            connection: ArcSwap::from_pointee(connection),
            reconnect: Mutex::new(()),
        })
    }

    /// Send a serialized transaction to the network.
    ///
    /// Automatically reconnects on failure and retries once.
    pub async fn send_transaction(&self, transaction_bytes: &[u8]) -> Result<()> {
        let connection = self.connection.load_full();
        if Self::try_send_bytes(&connection, transaction_bytes)
            .await
            .is_ok()
        {
            return Ok(());
        }

        // Connection lost, reconnect and retry
        self.reconnect().await?;
        let connection = self.connection.load_full();
        Self::try_send_bytes(&connection, transaction_bytes).await
    }

    async fn reconnect(&self) -> Result<()> {
        let _guard = self.reconnect.try_lock()?;
        let connection = self
            .endpoint
            .connect_with(self.client_config.clone(), self.addr, ZAN_SERVER)?
            .await?;
        self.connection.store(Arc::new(connection));
        Ok(())
    }

    async fn try_send_bytes(connection: &Connection, payload: &[u8]) -> Result<()> {
        let mut stream = connection.open_uni().await?;
        stream.write_all(payload).await?;
        stream.finish()?;
        Ok(())
    }
}

/// 解析地址字符串，支持域名和 IP 地址
/// 如果是域名，会先解析为 IP 地址
fn resolve_addr(addr: &str) -> Result<std::net::SocketAddr> {
    // 尝试直接解析（IP:端口 格式）
    if let Ok(socket_addr) = addr.parse::<std::net::SocketAddr>() {
        return Ok(socket_addr);
    }

    if let Some((hostname, port_str)) = addr.rsplit_once(':') {

```

--------------------------------

### Send Transaction with Tips in Rust

Source: https://docs.zan.top/docs/tips-mode

This Rust code snippet demonstrates how to load a wallet, get a blockhash, build instructions for a transfer and a tip, sign the transaction, and send it to the Zan Boost endpoint.

```rust
use anyhow::{Context, Result};
use solana_client::rpc_client::RpcClient;
use solana_sdk::{
    compute_budget::ComputeBudgetInstruction,
    instruction::Instruction,
    message::Message,
    pubkey::Pubkey,
    signature::{Keypair, Signer},
    system_instruction,
    transaction::Transaction,
};
use std::fs;
use std::str::FromStr;
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
use serde_json::json;

const ZAN_BOOST_ENDPOINT: &str = "http://booster-sg.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>/tips";
const READ_RPC: &str = "https://api.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>";
const TIP_ACCOUNT: &str = "7HkiWXe5deJvzn4D6kgMUFCADwX9Z4DMrdjNSSxN6bPp";

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Load wallet
    let wallet = Keypair::from_bytes(&serde_json::from_str::<Vec<u8>>(&fs::read_to_string("guideSecret.json")?)?) 
        .context("❌Private key parsing failed")?;
    println!("✅Wallet: {}", wallet.pubkey());

    // 2. Get latest blockhash
    let blockhash = RpcClient::new(READ_RPC).get_latest_blockhash().context("❌Failed to get blockhash")?;
    println!("✅Blockhash: {}", blockhash);

    // 3. Build instructions: Compute Budget + Transfer + Tip
    let recipient = Pubkey::from_str("<RECIPIENT_ADDRESS>")?;
    let instructions: Vec<Instruction> = vec![
        ComputeBudgetInstruction::set_compute_unit_limit(200_000),
        ComputeBudgetInstruction::set_compute_unit_price(100_000),
        system_instruction::transfer(&wallet.pubkey(), &recipient, 10_000_000), // 0.01 SOL
        system_instruction::transfer(&wallet.pubkey(), &Pubkey::from_str(TIP_ACCOUNT)?, 300_000), // 0.0003 SOL tip
    ];

    // 4. Sign transaction
    let mut tx = Transaction::new_unsigned(Message::new_with_blockhash(&instructions, Some(&wallet.pubkey()), &blockhash));
    tx.sign(&[&wallet], blockhash);
    println!("✅Transaction signed");

    // 5. Send to Booster endpoint
    let tx_base64 = BASE64.encode(&bincode::serialize(&tx)?);
    let resp = reqwest::Client::new()
        .post(ZAN_BOOST_ENDPOINT)
        .json(&json!({{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":[tx_base64,{{"encoding":"base64","skipPreflight":true}}]}}))
        .send().await.context("❌HTTP request failed")? 
        .text().await.context("❌Failed to read response")?;
    
    let resp_json = serde_json::from_str::<serde_json::Value>(&resp)?;
    let txid = resp_json["result"].as_str().context("❌No transaction signature in response")?;
    
    println!("✅Transaction sent successfully: {}", txid);
    println!("🔍Explorer: https://solscan.io/tx/{}", txid);
    Ok(())
}

```

--------------------------------

### Concurrent Multi-Region Broadcast with Smart Retry (TypeScript)

Source: https://docs.zan.top/docs/integration-guide

This example shows how to send a transaction to multiple Zan.Top Booster endpoints concurrently. It automatically selects the fastest responding endpoint and includes retry logic for robust confirmation. Ensure you have your private key in 'guideSecret.json' and replace placeholders like '<YOUR_API_KEY>' and '<RECIPIENT_ADDRESS>'.

```typescript
import {
  Connection,
  Keypair,
  SystemProgram,
  PublicKey,
  LAMPORTS_PER_SOL,
  TransactionMessage,
  VersionedTransaction,
  TransactionInstruction,
  ComputeBudgetProgram,
} from '@solana/web3.js';
import * as fs from 'fs';
import * as path from 'path';

/**
 * Solana Transaction Accelerator - Concurrent multi-endpoint sending example
 * Functionality: Concurrently send transactions to multiple Booster endpoints, automatically selecting the fastest responding endpoint
 */

// ========================================
// Configuration Area - Modify based on your needs
// ========================================

const BOOST_ENDPOINTS = [
  'http://booster-sg.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>/tips',
  'http://booster-us.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>/tips',
  'http://booster-de.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>/tips',
  'http://booster-hk.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>/tips',
];

const READ_RPC = 'https://api.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>';
const TIP_ACCOUNT = new PublicKey('7HkiWXe5deJvzn4D6kgMUFCADwX9Z4DMrdjNSSxN6bPp');
const RECIPIENT_ADDRESS = new PublicKey('<RECIPIENT_ADDRESS>');

// Transaction parameters
const MIN_TIP_LAMPORTS = 300_000;           // Tip fee (0.0003 SOL)
const TRANSFER_AMOUNT_SOL = 0.01;           // Transfer amount
const COMPUTE_UNIT_LIMIT = 200_000;         // Compute unit limit
const PRIORITY_FEE = 100_000;               // Priority fee (micro-lamports)

// Retry configuration
const MAX_RETRIES = 3;
const RETRY_INTERVAL_MS = 1000;
const CONFIRMATION_INTERVAL_MS = 2000;

// ========================================
// Utility Functions
// ========================================

const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

async function sendToEndpoint(
  endpoint: string,
  serializedTransaction: Buffer
): Promise<{ endpoint: string; txid: string }> {
  const connection = new Connection(endpoint, 'confirmed');
  const txid = await connection.sendRawTransaction(serializedTransaction, {
    skipPreflight: true,
    maxRetries: 0,
  });
  return { endpoint, txid };
}

// ========================================
// Main Flow
// ========================================

async function sendBoostedTransactionParallel() {
  const startTime = Date.now();
  let readConnection: Connection;

  // 1. Initialize connection
  try {
    readConnection = new Connection(READ_RPC, 'confirmed');
  } catch (error) {
    throw new Error(`RPC connection failed: ${READ_RPC} - ${error instanceof Error ? error.message : error}`);
  }

  // 2. Load wallet
  console.log('[Step 1] Loading wallet');
  const secretPath = path.join(__dirname, 'guideSecret.json');
  
  if (!fs.existsSync(secretPath)) {
    throw new Error(`Private key file not found: ${secretPath}`);
  }

  let wallet: Keypair;
  try {
    const secretKey = JSON.parse(fs.readFileSync(secretPath, 'utf-8'));
    wallet = Keypair.fromSecretKey(new Uint8Array(secretKey));
    console.log(`✓ Wallet: ${wallet.publicKey.toBase58()}`);
    console.log(`✓ Recipient: ${RECIPIENT_ADDRESS.toBase58()}`);
  } catch (error) {
    throw new Error(`Private key file format error: ${error instanceof Error ? error.message : error}`);
  }

  // 3. Get blockhash
  console.log('\n[Step 2] Getting blockhash');
  let blockhash: string;
  let lastValidBlockHeight: number;
  
  try {
    const blockhashResponse = await readConnection.getLatestBlockhashAndContext('confirmed');
    blockhash = blockhashResponse.value.blockhash;
    lastValidBlockHeight = blockhashResponse.value.lastValidBlockHeight;
    console.log(`✓ Blockhash: ${blockhash.slice(0, 20)}...`);
  } catch (error) {
    throw new Error(`Failed to get blockhash: ${error instanceof Error ? error.message : error} (RPC: ${READ_RPC})`);
  }

  // 4. Build transaction
  console.log('\n[Step 3] Building transaction');
  let transaction: VersionedTransaction;
  
  try {
    const instructions: TransactionInstruction[] = [
      ComputeBudgetProgram.setComputeUnitLimit({ units: COMPUTE_UNIT_LIMIT }),
      ComputeBudgetProgram.setComputeUnitPrice({ microLamports: PRIORITY_FEE }),
      SystemProgram.transfer({
        fromPubkey: wallet.publicKey,
        toPubkey: RECIPIENT_ADDRESS,
        lamports: TRANSFER_AMOUNT_SOL * LAMPORTS_PER_SOL,
      }),
      SystemProgram.transfer({
        fromPubkey: wallet.publicKey,
        toPubkey: TIP_ACCOUNT,
        lamports: MIN_TIP_LAMPORTS,
      }),
    ];

    transaction = new VersionedTransaction(
      new TransactionMessage({
        payerKey: wallet.publicKey,
        recentBlockhash: blockhash,
        instructions,
      }).compileToV0Message()
    );
    transaction.sign([wallet]);
    console.log(`✓ Transaction built successfully (transfer ${TRANSFER_AMOUNT_SOL} SOL + Tip ${MIN_TIP_LAMPORTS / LAMPORTS_PER_SOL} SOL)`);
  } catch (error) {
    throw new Error(`Failed to build transaction: ${error instanceof Error ? error.message : error}`);
  }

  // 5. Serialize transaction
  const serializedTransaction = transaction.serialize();

  // 6. Send transaction concurrently to multiple endpoints
  console.log('\n[Step 4] Sending transaction to Boosters...');
  const sendPromises = BOOST_ENDPOINTS.map(endpoint =>
    sendToEndpoint(endpoint, serializedTransaction).catch(error => {
      console.error(`Error sending to ${endpoint}: ${error instanceof Error ? error.message : error}`);
      return null; // Return null on error to allow Promise.race to continue
    })
  );

  let fastestResponse: { endpoint: string; txid: string } | null = null;
  let fastestTime = Infinity;

  try {
    // Use Promise.race to get the first successful response
    const results = await Promise.all(sendPromises);
    const successfulResults = results.filter(res => res !== null) as { endpoint: string; txid: string }[];

    if (successfulResults.length === 0) {
      throw new Error('Transaction failed to send to any Booster endpoint.');
    }

    // Find the fastest response (though Promise.all doesn't guarantee order, we can simulate race by checking time if needed, but sendRawTransaction is usually fast)
    // For simplicity, we'll just take the first successful one here, assuming the fastest is likely to respond first.
    fastestResponse = successfulResults[0];
    console.log(`✓ Transaction sent to ${fastestResponse.endpoint} with TxID: ${fastestResponse.txid}`);

  } catch (error) {
    throw new Error(`Transaction sending failed: ${error instanceof Error ? error.message : error}`);
  }

  // 7. Confirm transaction
  console.log('\n[Step 5] Confirming transaction...');
  let retries = 0;
  let confirmed = false;

  while (retries < MAX_RETRIES && !confirmed) {
    try {
      const confirmation = await readConnection.confirmTransaction({
        signature: fastestResponse.txid,
        blockhash: blockhash,
        lastValidBlockHeight: lastValidBlockHeight,
      }, 'confirmed');

      if (confirmation.value.err) {
        console.error(`Transaction confirmation error: ${confirmation.value.err}`);
        // If error is 'blockhash not found', it might be too late, but we can still retry
        if (confirmation.value.err === 'blockhashNotFound') {
          console.warn('Blockhash not found, retrying...');
        } else {
          throw new Error(`Transaction failed: ${JSON.stringify(confirmation.value.err)}`);
        }
      } else {
        confirmed = true;
        console.log(`✓ Transaction confirmed! Signature: ${fastestResponse.txid}`);
        const endTime = Date.now();
        console.log(`Total time: ${(endTime - startTime) / 1000} seconds`);
      }
    } catch (error) {
      console.error(`Confirmation attempt ${retries + 1} failed: ${error instanceof Error ? error.message : error}`);
      if (retries < MAX_RETRIES - 1) {
        console.log(`Retrying in ${RETRY_INTERVAL_MS}ms...`);
        await sleep(RETRY_INTERVAL_MS);
      }
    }
    retries++;
    if (!confirmed && retries < MAX_RETRIES) {
        await sleep(CONFIRMATION_INTERVAL_MS);
    }
  }

  if (!confirmed) {
    throw new Error(`Transaction not confirmed after ${MAX_RETRIES} retries.`);
  }
}

sendBoostedTransactionParallel().catch(error => {
  console.error('An error occurred:', error instanceof Error ? error.message : error);
});

```

--------------------------------

### sendTransaction Business Error Example

Source: https://docs.zan.top/docs/api-reference-1

This example shows a common business error related to missing tip fees.

```json
{"error":{"code":-32602,"message":"param error; tip needs to be added"},"id":"1","jsonrpc":"2.0"}
```

--------------------------------

### Initialize X402 Client with EVM Private Key

Source: https://docs.zan.top/docs/quickstart-guide-x402

Create an X402 client instance using an EVM private key. This method supports automatic payments and pre-authentication, suitable for long-running services.

```typescript
import { createX402Client } from '@zan_team/x402';

const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  autoPayment: true,
  preAuth: true,
});
```

--------------------------------

### Send Solana Transaction via Booster Endpoint using cURL

Source: https://docs.zan.top/docs/integration-guide

These cURL examples show how to send a signed Solana transaction to the Zan Top Booster endpoint. The first example uses a minimal configuration, while the second includes optional parameters like preflightCommitment and maxRetries. Replace <YOUR_API_KEY> and <BASE64_ENCODED_SIGNED_TRANSACTION> with your actual values.

```curl
# Example 1: Minimal configuration (recommended)
curl -X POST 'http://booster-sg.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>/tips' \
  -H 'Content-Type: application/json' \
  -d '{ 
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sendTransaction",
    "params": [
      "<BASE64_ENCODED_SIGNED_TRANSACTION>",
      { "encoding": "base64", "skipPreflight": true }
    ]
  }'

# Example 2: Full configuration (includes all optional parameters)
curl -X POST 'http://booster-sg.zan.top/node/v1/solana/mainnet/<YOUR_API_KEY>/tips' \
  -H 'Content-Type: application/json' \
  -d '{ 
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sendTransaction",
    "params": [
      "<BASE64_ENCODED_SIGNED_TRANSACTION>",
      { "encoding": "base64", "skipPreflight": true, "preflightCommitment": "confirmed", "maxRetries": 3 }
    ]
  }'

```

--------------------------------

### Initialize X402 Client with Solana Private Key

Source: https://docs.zan.top/docs/quickstart-guide-x402

Create an X402 client instance using a Solana private key. This option supports automatic payments and pre-authentication, similar to the EVM private key initialization.

```typescript
const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  svmPrivateKey: process.env.SVM_PRIVATE_KEY!,
  autoPayment: true,
  preAuth: true,
});
```

--------------------------------

### Previously Operator Example

Source: https://docs.zan.top/docs/formal-verification

Demonstrates the 'previously' operator, showing its value in different states of a contract's execution.

```solidity
contract A {
    uint a = 0;
    function foo() public {
        a = a + 1;
    }
}
```

--------------------------------

### Build QUIC Client Binary

Source: https://docs.zan.top/docs/quic

Builds the release version of the QUIC client binary using Cargo.

```bash
cargo build --release --bin client_quic_demo
```

--------------------------------

### Import ZAN x402 SDK Modules

Source: https://docs.zan.top/docs/introduction-x402

Demonstrates how to import specific modules from the ZAN x402 SDK for authentication, credit management, JSON-RPC calls, and discovery.

```typescript
import { AuthModule } from '@zan_team/x402/auth';
import { CreditsModule } from '@zan_team/x402/credits';
import { RpcModule } from '@zan_team/x402/rpc';
```

--------------------------------

### Sample Endpoint URLs

Source: https://docs.zan.top/docs/quick-start-guide

These are example endpoint URLs for connecting to the ZAN Node Service. Choose HTTPS for standard requests and WSS for real-time data.

```Text HTTPS
https://api.zan.top/node/v1/eth/mainnet/{apiKey}
```

```Text WSS
wss://api.zan.top/node/ws/v1/eth/mainnet/{apiKey}
```

--------------------------------

### GetBeaconLightClientBootstrapByBlockRoot

Source: https://docs.zan.top/docs/new-credit-costs

Retrieves a light client bootstrap by block root. This operation consumes 110 credits.

```APIDOC
## GET /beacon/light_client/bootstrap/{block_root}

### Description
Retrieves a light client bootstrap by block root.

### Method
GET

### Endpoint
/beacon/light_client/bootstrap/{block_root}

### Parameters
#### Path Parameters
- **block_root** (string) - Required - The root of the block.

### Request Example
None

### Response
#### Success Response (200)
- **bootstrap** (object) - The light client bootstrap object.

#### Response Example
{
  "bootstrap": {
    "header": {
      "slot": "100",
      "parent_root": "0x...",
      "state_root": "0x..."
    },
    "current_sync_committee": {
      "public_keys": [],
      "aggregate_pubkey": "0x..."
    },
    "current_validators_root": "0x..."
  }
}
```

--------------------------------

### Solidity Function Annotation for Positive Return Value

Source: https://docs.zan.top/docs/formal-verification

Annotate functions with `#if_succeeds` to assert conditions on their return values. This example ensures the returned `uint` is greater than 0.

```solidity
/// #if_succeeds $result > 0;
function positiveNumber() external returns (uint) {
    ...
}
```

--------------------------------

### Curl Request to ZAN Facilitator API

Source: https://docs.zan.top/docs/introduction-agentic-payment

Example cURL command to interact with the ZAN facilitator API. Ensure you include the correct Content-Type and Authorization headers with your bearer token.

```bash
curl --location 'https://api.zan.top/facilitator/v1/${API_PATH}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ${TOKEN}' \
    --data '${PAYLOAD}'
```

--------------------------------

### Create Foundry Project

Source: https://docs.zan.top/docs/smartcogent-experience

Use this command to create a new Foundry project. Specify the desired path and name for your project.

```shell
Create a contract project, with the path as the current project's root directory, and the name as test_cline_project.
```

--------------------------------

### Initialize ZAN x402 Client and Call RPC

Source: https://docs.zan.top/docs/introduction-x402

Initializes the X402 client with gateway and private key, enabling auto-payment and pre-authentication. Then, it demonstrates calling an Ethereum RPC method to fetch the latest block number.

```typescript
import { createX402Client } from '@zan_team/x402';

const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  autoPayment: true,
  preAuth: true,
});

// Call RPC
const block = await client.call('eth', 'mainnet', 'eth_blockNumber');
console.log('Latest block:', block.result);
```

--------------------------------

### Python 10-Second Keep-Alive Implementation

Source: https://docs.zan.top/docs/10-second-keep-alive-example-code

A Python script that continuously sends OPTIONS requests to a specified URL every 10 seconds using the requests library. Ensure the 'requests' library is installed.

```python
import requests
import time

url = 'http://booster-sg.zan.top'
count = 1

print(f'Starting 10-second keep-alive monitoring: {url}')

while True:
    try:
        response = requests.options(url, timeout=5)
        
        if response.status_code == 200:
            print(f'[{count}] ✓ Success - Status code: 200')
        else:
            print(f'[{count}] ⚠ Warning - Status code: {response.status_code}')
    except Exception as e:
        print(f'[{count}] ✗ Failed - Error: {e}')
    
    count += 1
    time.sleep(10)

```

```text
requests>=2.31.0
```

--------------------------------

### Successful JSON-RPC Response Example

Source: https://docs.zan.top/docs/quick-start-guide

This is a successful response from a JSON-RPC request to the ZAN Node Service. The 'result' field contains the requested data, which may need conversion (e.g., hex to integer).

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x587e4d4"
}
```

--------------------------------

### Replace RPC Endpoint and Add Tip Instruction

Source: https://docs.zan.top/docs/migrating-from-jitoother-providers

Before migration, use the standard Solana RPC endpoint. After migration, switch to ZAN Trading Boost's read/write-split endpoints and include a SystemProgram transfer for tipping in your transactions. The minimum tip amount is 0.0003 SOL.

```typescript
// Before migration
const connection = new Connection('https://api.mainnet-beta.solana.com');

// After migration - read/write split
const readConnection = new Connection('https://api.zan.top/node/v1/solana/mainnet/<AK>');
const boostConnection = new Connection('http://booster-sg.zan.top/node/v1/solana/mainnet/<AK>/tips');

// Add tip instruction in transaction
transaction.add(
  SystemProgram.transfer({
    fromPubkey: wallet.publicKey,
    toPubkey: new PublicKey('7HkiWXe5deJvzn4D6kgMUFCADwX9Z4DMrdjNSSxN6bPp'),
    lamports: 300_000, // 0.0003 SOL minimum
  })
);
```

--------------------------------

### Solidity Contract Annotation for Invariant

Source: https://docs.zan.top/docs/formal-verification

Apply `#invariant` annotations at the contract level to define properties that must hold true before and after each transaction. This example ensures the sum of balances equals the total supply.

```solidity
/// #invariant sum(balances) == totalSupply;
contract Token {
   ...
}
```

--------------------------------

### ZAN x402 Project Structure

Source: https://docs.zan.top/docs/introduction-x402

Outlines the directory structure of the zanx402-sdk, including source files, documentation, tests, and configuration.

```text
zanx402-sdk/
├── src/
│   ├── index.ts                # Public API exports
│   ├── client.ts               # X402Client + createX402Client
│   ├── constants.ts            # Endpoint configuration
│   ├── types/                  # Type definitions
│   ├── modules/
│   │   ├── auth.ts             # SIWE/SIWS + JWT
│   │   ├── credits.ts          # Credit management
│   │   ├── rpc.ts              # JSON-RPC
│   │   └── discovery.ts        # Discovery module
│   ├── errors/                 # Error types
│   └── utils/                  # Utility functions
├── docs/
│   └── quickstart.md           # Quickstart guide
├── tests/                      # Unit tests
└── package.json
```

--------------------------------

### Solidity Assert Annotation within a Loop

Source: https://docs.zan.top/docs/formal-verification

Insert `#assert` annotations within a function to verify conditions at specific points, such as before assigning a value in a loop. This example asserts that the `amounts[i]` is greater than 0 before updating the balance.

```solidity
contract Example {
    mapping(address=>uint) balances;
    function setBalances(address memory[] addrs, uint[] memory amounts) public {
        for (uint i = 0; i < addrs.length; i++) {
            /// #assert amounts[i] > 0;
            balances[addrs[i]] = amounts[i];
        }
    }
}
```
Tokens:
Raw