agentwallet-sdk 2.5.0 → 3.1.0

package/dist/settlement/verifier.js

@@ -0,0 +1,354 @@
+// SettlementVerifier — On-chain settlement verification for agent transactions
+//
+// Verifies that bridge transfers, x402 payments, and regular transactions actually
+// settled on-chain. Uses Alchemy RPC for supported chains, public RPCs as fallback.
+//
+// Supported verification types:
+//   - EVM transaction receipts (any EVM chain)
+//   - Solana transaction confirmation
+//   - CCTP bridge transfers end-to-end (source burn + attestation + dest mint)
+//   - x402 ERC20 payment verification (payee + amount from event logs)
+import { SETTLEMENT_ALCHEMY_NETWORKS, SETTLEMENT_PUBLIC_RPCS, CIRCLE_ATTESTATION_API, ERC20_TRANSFER_TOPIC, SOLANA_RPC_URL, } from './types.js';
+export class SettlementVerifier {
+    constructor(config = {}) {
+        this.alchemyApiKey = config.alchemyApiKey;
+    }
+    // ─── EVM Transaction Verification ───
+    /**
+     * Verify that an EVM transaction settled on-chain.
+     *
+     * Uses Alchemy RPC if apiKey is configured and chain is supported,
+     * otherwise falls back to public RPCs.
+     *
+     * @param params.chain - SDK chain name (e.g. 'base', 'arbitrum')
+     * @param params.txHash - Transaction hash to verify
+     * @param params.confirmations - Minimum confirmations required (default: 1)
+     */
+    async verifyEvmTransaction(params) {
+        const requiredConfirmations = params.confirmations ?? 1;
+        const rpcUrl = this._getRpcUrl(params.chain);
+        try {
+            // Get receipt
+            const receiptResp = await this._evmRpc(rpcUrl, 'eth_getTransactionReceipt', [params.txHash]);
+            const receipt = receiptResp.result;
+            if (!receipt) {
+                // Not mined yet — check if it's in the mempool
+                return {
+                    status: 'pending',
+                    txHash: params.txHash,
+                    blockNumber: 0n,
+                    confirmations: 0,
+                };
+            }
+            // Get current block number to compute confirmations
+            const blockResp = await this._evmRpc(rpcUrl, 'eth_blockNumber', []);
+            const currentBlock = BigInt(blockResp.result);
+            const txBlock = BigInt(receipt.blockNumber);
+            const confirmationCount = Number(currentBlock - txBlock) + 1;
+            const success = receipt.status === '0x1';
+            if (!success) {
+                return {
+                    status: 'failed',
+                    txHash: params.txHash,
+                    blockNumber: txBlock,
+                    confirmations: confirmationCount,
+                    gasUsed: BigInt(receipt.gasUsed),
+                    success: false,
+                    error: 'Transaction reverted (status=0)',
+                };
+            }
+            if (confirmationCount < requiredConfirmations) {
+                return {
+                    status: 'pending',
+                    txHash: params.txHash,
+                    blockNumber: txBlock,
+                    confirmations: confirmationCount,
+                    gasUsed: BigInt(receipt.gasUsed),
+                    success: true,
+                };
+            }
+            return {
+                status: 'confirmed',
+                txHash: params.txHash,
+                blockNumber: txBlock,
+                confirmations: confirmationCount,
+                gasUsed: BigInt(receipt.gasUsed),
+                success: true,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'not_found',
+                txHash: params.txHash,
+                blockNumber: 0n,
+                confirmations: 0,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // ─── Solana Transaction Verification ───
+    /**
+     * Verify that a Solana transaction settled on-chain.
+     *
+     * @param params.signature - Solana transaction signature (base58)
+     * @param params.commitment - Commitment level: 'confirmed' or 'finalized' (default: 'confirmed')
+     */
+    async verifySolanaTransaction(params) {
+        const commitment = params.commitment ?? 'confirmed';
+        try {
+            const resp = await this._solanaRpc('getTransaction', [
+                params.signature,
+                { encoding: 'json', commitment, maxSupportedTransactionVersion: 0 },
+            ]);
+            const tx = resp.result;
+            if (!tx) {
+                return {
+                    status: 'not_found',
+                    txHash: params.signature,
+                    blockNumber: 0n,
+                    confirmations: 0,
+                    error: 'Transaction not found or not yet confirmed',
+                };
+            }
+            const success = tx.meta.err === null;
+            // Get current slot for confirmation count approximation
+            const slotResp = await this._solanaRpc('getSlot', [{ commitment }]);
+            const currentSlot = slotResp.result;
+            const confirmations = currentSlot - tx.slot;
+            return {
+                status: success ? 'confirmed' : 'failed',
+                txHash: params.signature,
+                blockNumber: BigInt(tx.slot),
+                confirmations,
+                success,
+                error: !success ? `Solana transaction error: ${JSON.stringify(tx.meta.err)}` : undefined,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'not_found',
+                txHash: params.signature,
+                blockNumber: 0n,
+                confirmations: 0,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // ─── CCTP Bridge Settlement ───
+    /**
+     * Verify a CCTP bridge transfer settled end-to-end:
+     *   1. Verifies source chain burn tx succeeded
+     *   2. Checks Circle attestation API for the message hash
+     *   3. Attempts to find destination mint tx (if attestation is complete)
+     *
+     * @param params.sourceTxHash - Burn tx hash on source chain
+     * @param params.sourceChain - Source chain name (e.g. 'solana', 'base')
+     * @param params.destinationChain - Destination chain name
+     * @param params.expectedAmount - Expected USDC amount in base units (6 decimals)
+     */
+    async verifyBridgeSettlement(params) {
+        // Step 1: verify source tx
+        let sourceTx;
+        if (params.sourceChain === 'solana') {
+            sourceTx = await this.verifySolanaTransaction({ signature: params.sourceTxHash });
+        }
+        else {
+            sourceTx = await this.verifyEvmTransaction({
+                chain: params.sourceChain,
+                txHash: params.sourceTxHash,
+                confirmations: params.sourceChain === 'ethereum' ? 65 : 1, // Ethereum needs more for CCTP
+            });
+        }
+        if (sourceTx.status === 'failed') {
+            return {
+                status: 'source_failed',
+                sourceTx,
+                error: 'Source chain burn transaction failed or reverted',
+            };
+        }
+        if (sourceTx.status === 'pending' || sourceTx.status === 'not_found') {
+            return {
+                status: 'source_pending',
+                sourceTx,
+            };
+        }
+        // Step 2: check Circle attestation API
+        let attestationStatus;
+        try {
+            attestationStatus = await this._checkCircleAttestation(params.sourceTxHash);
+        }
+        catch {
+            attestationStatus = 'error';
+        }
+        if (attestationStatus === 'pending_confirmations') {
+            return {
+                status: 'source_confirmed_awaiting_attestation',
+                sourceTx,
+                attestationStatus,
+            };
+        }
+        if (attestationStatus === 'complete') {
+            // Step 3: Try to find the destination mint tx
+            // For now, we report attestation complete and let the caller poll for mint
+            // A full implementation would index destination chain events
+            return {
+                status: 'attestation_complete_awaiting_mint',
+                sourceTx,
+                attestationStatus,
+            };
+        }
+        // If we can verify source + attestation but not destination, return partial
+        return {
+            status: 'error',
+            sourceTx,
+            attestationStatus,
+            error: 'Could not determine attestation status',
+        };
+    }
+    // ─── x402 Payment Verification ───
+    /**
+     * Verify an x402 payment settled on-chain by inspecting ERC20 Transfer event logs.
+     *
+     * Checks that the tx:
+     *   - Succeeded (status=1)
+     *   - Emitted an ERC20 Transfer event to expectedPayee
+     *   - The transferred amount matches expectedAmount
+     *
+     * @param params.chain - EVM chain name
+     * @param params.txHash - Transaction hash
+     * @param params.expectedPayee - Address that should have received the payment
+     * @param params.expectedAmount - Amount in USDC base units (6 decimals)
+     */
+    async verifyX402Payment(params) {
+        const rpcUrl = this._getRpcUrl(params.chain);
+        try {
+            const receiptResp = await this._evmRpc(rpcUrl, 'eth_getTransactionReceipt', [params.txHash]);
+            const receipt = receiptResp.result;
+            if (!receipt) {
+                return {
+                    status: 'pending',
+                    txHash: params.txHash,
+                    payeeVerified: false,
+                    amountVerified: false,
+                };
+            }
+            if (receipt.status !== '0x1') {
+                return {
+                    status: 'failed',
+                    txHash: params.txHash,
+                    payeeVerified: false,
+                    amountVerified: false,
+                    error: 'Transaction reverted',
+                };
+            }
+            // Find ERC20 Transfer events — topic[0] = Transfer sig, topic[2] = to address
+            const expectedPayeeHex = params.expectedPayee.toLowerCase().replace('0x', '').padStart(64, '0');
+            const transferLog = receipt.logs.find((log) => {
+                return (log.topics[0]?.toLowerCase() === ERC20_TRANSFER_TOPIC &&
+                    log.topics[2]?.toLowerCase() === `0x${expectedPayeeHex}`);
+            });
+            if (!transferLog) {
+                return {
+                    status: 'confirmed',
+                    txHash: params.txHash,
+                    payeeVerified: false,
+                    amountVerified: false,
+                    error: `No ERC20 Transfer found to payee ${params.expectedPayee}`,
+                };
+            }
+            // Decode amount from log.data (ABI-encoded uint256)
+            const actualAmount = BigInt(transferLog.data);
+            const amountVerified = actualAmount === params.expectedAmount;
+            const actualPayee = `0x${transferLog.topics[2]?.slice(-40)}`;
+            const tokenAddress = transferLog.address;
+            return {
+                status: 'confirmed',
+                txHash: params.txHash,
+                payeeVerified: true,
+                amountVerified,
+                actualAmount,
+                actualPayee,
+                tokenAddress,
+                error: amountVerified
+                    ? undefined
+                    : `Amount mismatch: expected ${params.expectedAmount}, got ${actualAmount}`,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'not_found',
+                txHash: params.txHash,
+                payeeVerified: false,
+                amountVerified: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // ─── Internal Helpers ───
+    /** Get the RPC URL for a chain, preferring Alchemy over public RPCs */
+    _getRpcUrl(chain) {
+        if (this.alchemyApiKey && chain in SETTLEMENT_ALCHEMY_NETWORKS) {
+            const slug = SETTLEMENT_ALCHEMY_NETWORKS[chain];
+            return `https://${slug}.g.alchemy.com/v2/${this.alchemyApiKey}`;
+        }
+        const publicRpc = SETTLEMENT_PUBLIC_RPCS[chain];
+        if (!publicRpc) {
+            throw new Error(`No RPC URL available for chain "${chain}"`);
+        }
+        return publicRpc;
+    }
+    /** Make an EVM JSON-RPC call */
+    async _evmRpc(url, method, params) {
+        const resp = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+        });
+        if (!resp.ok) {
+            throw new Error(`EVM RPC error: HTTP ${resp.status}`);
+        }
+        const json = (await resp.json());
+        if (json.error)
+            throw new Error(`EVM RPC error: ${json.error.message}`);
+        return json;
+    }
+    /** Make a Solana JSON-RPC call */
+    async _solanaRpc(method, params) {
+        const resp = await fetch(SOLANA_RPC_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Solana RPC error: HTTP ${resp.status}`);
+        }
+        const json = (await resp.json());
+        if (json.error)
+            throw new Error(`Solana RPC error: ${json.error.message}`);
+        return json;
+    }
+    /** Check Circle attestation API for a CCTP burn message */
+    async _checkCircleAttestation(burnTxHash) {
+        // Circle attestation API: GET /attestations/{messageHash}
+        // For CCTP, the messageHash is derived from the MessageSent event in the burn tx.
+        // Since we don't have the full event parsing here, we query by tx hash pattern.
+        // In production, callers should provide the message hash from the burn tx receipt.
+        const url = `${CIRCLE_ATTESTATION_API}/${burnTxHash}`;
+        const resp = await fetch(url, {
+            headers: { Accept: 'application/json' },
+        });
+        if (resp.status === 404) {
+            return 'pending_confirmations';
+        }
+        if (!resp.ok) {
+            return 'error';
+        }
+        const json = (await resp.json());
+        if (json.status === 'complete')
+            return 'complete';
+        if (json.status === 'pending_confirmations')
+            return 'pending_confirmations';
+        return 'error';
+    }
+}
+//# sourceMappingURL=verifier.js.map

package/dist/settlement/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../../src/settlement/verifier.ts"],"names":[],"mappings":"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"}

package/dist/solana/bridge.d.ts

@@ -0,0 +1,144 @@
+import { Connection, PublicKey, Keypair, type TransactionSignature } from '@solana/web3.js';
+import type { BridgeChain } from '../bridge/types.js';
+import { SOLANA_CCTP_PROGRAMS, SOLANA_USDC_MINT, SOLANA_CCTP_DOMAIN } from '../bridge/types.js';
+export type { BridgeChain };
+export interface SolanaBurnResult {
+    /** Solana transaction signature of the burn tx */
+    signature: TransactionSignature;
+    /** The CCTP message hash (keccak256 of message bytes) */
+    messageHash: string;
+    /** Raw CCTP message bytes (hex-encoded) */
+    messageBytes: string;
+    /** Source domain (Solana = 5) */
+    sourceDomain: number;
+    /** Destination domain ID */
+    destinationDomain: number;
+    /** Nonce (derived from message bytes) */
+    nonce: bigint;
+}
+export interface SolanaBridgeParams {
+    /** Amount in USDC base units (6 decimals) */
+    amount: bigint;
+    /** EVM destination chain */
+    destinationChain: BridgeChain;
+    /** EVM destination address (hex) */
+    destinationAddress: string;
+    /** Apply 0.1% platform fee */
+    applyPlatformFee?: boolean;
+    /** Finality threshold (0 = fast, 1000 = finalized) */
+    minFinalityThreshold?: number;
+    /** Max fee (in USDC base units) for Circle's fee mechanism */
+    maxFee?: bigint;
+    /** Circle attestation API override */
+    attestationApiUrl?: string;
+}
+export interface SolanaReceiveParams {
+    /** CCTP message bytes (from EVM burn) */
+    message: Uint8Array | string;
+    /** Circle attestation bytes */
+    attestation: string;
+    /** Solana wallet to receive USDC (must have USDC ATA) */
+    recipientUsdcAccount?: string;
+}
+export interface SolanaBridgeResult {
+    /** Solana burn signature */
+    burnSignature: TransactionSignature;
+    /** EVM mint transaction hash */
+    evmMintTxHash: string;
+    /** Amount bridged */
+    amount: bigint;
+    /** Platform fee collected */
+    platformFee: bigint;
+    /** Source: Solana */
+    fromChain: 'solana';
+    /** Destination EVM chain */
+    toChain: BridgeChain;
+    /** Recipient address */
+    recipient: string;
+    /** Elapsed time (ms) */
+    elapsedMs: number;
+}
+/**
+ * SolanaCCTPBridge — Handles CCTP V2 burns and receives on Solana.
+ *
+ * For the full Solana→EVM or EVM→Solana flow, use UnifiedBridge which
+ * orchestrates both sides together.
+ *
+ * ```ts
+ * const bridge = new SolanaCCTPBridge({
+ *   connection: new Connection('https://api.mainnet-beta.solana.com'),
+ *   payer: keypair,
+ * });
+ *
+ * // Burn USDC on Solana → receive on Base
+ * const result = await bridge.bridgeToEvm({
+ *   amount: 1_000_000n,
+ *   destinationChain: 'base',
+ *   destinationAddress: '0x...',
+ * });
+ * ```
+ */
+export declare class SolanaCCTPBridge {
+    private readonly connection;
+    private readonly payer;
+    private readonly tokenMessengerMinterProgram;
+    private readonly messageTransmitterProgram;
+    private readonly usdcMint;
+    constructor(config: {
+        connection: Connection;
+        payer: Keypair;
+        /** Override USDC mint (default: mainnet) */
+        usdcMint?: string;
+    });
+    /**
+     * Burn USDC on Solana and return burn result for attestation polling.
+     * Part 1 of the Solana→EVM bridge flow.
+     *
+     * @note The Solana burn instruction calls `depositForBurn` on the
+     *   TokenMessengerMinterV2 program. The message is stored in a PDA
+     *   (MessageSent account) rather than emitted as an EVM log event.
+     *   Circle's IRIS API indexes these events by transaction signature.
+     */
+    depositForBurn(params: {
+        amount: bigint;
+        destinationChain: BridgeChain;
+        destinationAddress: string;
+        minFinalityThreshold?: number;
+        maxFee?: bigint;
+    }): Promise<SolanaBurnResult>;
+    /**
+     * Poll Circle IRIS API for attestation after a Solana burn.
+     * Same API as EVM — IRIS indexes Solana transactions by message hash.
+     */
+    waitForAttestation(messageHash: string, apiUrl?: string): Promise<string>;
+    /**
+     * Receive a CCTP message on Solana (EVM→Solana destination).
+     * Calls receiveMessage on the Solana MessageTransmitterV2 program.
+     *
+     * @param message - CCTP message bytes from EVM burn tx
+     * @param attestation - Circle attestation bytes
+     * @param recipientUsdcAccount - Solana USDC ATA for recipient (must exist)
+     */
+    receiveMessage(params: SolanaReceiveParams): Promise<TransactionSignature>;
+    /**
+     * Ensure the payer's USDC ATA exists (create it if not).
+     */
+    ensureUsdcAta(owner?: PublicKey): Promise<PublicKey>;
+    /**
+     * Fetch the MessageSent account data and extract message bytes.
+     * On Solana, CCTP messages are stored in PDA accounts (not events).
+     */
+    private fetchMessageSent;
+    /**
+     * Convert an EVM hex address to a 32-byte Buffer for Solana mintRecipient.
+     * Per Circle spec: pad the EVM address on the left with 12 zero bytes.
+     */
+    private evmAddressToBytes32;
+    private sleep;
+}
+export declare class SolanaBridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export { SOLANA_CCTP_PROGRAMS, SOLANA_USDC_MINT, SOLANA_CCTP_DOMAIN, };
+//# sourceMappingURL=bridge.d.ts.map

package/dist/solana/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/solana/bridge.ts"],"names":[],"mappings":"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"}