agentwallet-sdk 5.0.5 → 5.1.1

package/dist/mev/risk.js

@@ -0,0 +1,95 @@
+/** Popular tokens that are heavily watched by MEV bots */
+const POPULAR_TOKENS = new Set([
+    'ETH', 'WETH', 'USDC', 'USDT', 'DAI', 'WBTC', 'SOL', 'WSOL',
+]);
+/** Deterministic MEV risk scorer — no external calls required */
+export class MEVRiskAssessor {
+    /**
+     * Assess MEV risk for a proposed swap.
+     * Scoring model produces a 0-100 risk score mapped to a risk level.
+     */
+    assess(params) {
+        const { fromToken, toToken, amountUsd, slippageBps, gasPriceGwei, chain } = params;
+        let score = 0;
+        // 1. Size risk
+        if (amountUsd >= 10000)
+            score += 40;
+        else if (amountUsd >= 1000)
+            score += 20;
+        else if (amountUsd >= 100)
+            score += 10;
+        // < $100 = 0 pts
+        // 2. Slippage risk (high slippage = easy sandwich)
+        if (slippageBps > 200)
+            score += 20;
+        else if (slippageBps >= 50)
+            score += 10;
+        // 3. Popular pair risk (heavily watched by bots)
+        if (this.isPopularPair(fromToken, toToken))
+            score += 15;
+        // 4. Gas spike risk (high gas = bots are active)
+        if (gasPriceGwei > 100)
+            score += 25;
+        else if (gasPriceGwei > 50)
+            score += 15;
+        // 5. Chain risk
+        const chainLower = chain.toLowerCase();
+        if (chainLower === 'ethereum' || chainLower === 'mainnet')
+            score += 10;
+        else if (chainLower === 'arbitrum')
+            score += 5;
+        else if (chainLower === 'base')
+            score += 3;
+        // Cap at 100
+        score = Math.min(100, score);
+        // Map score to risk level
+        let riskLevel;
+        if (score >= 76)
+            riskLevel = 'critical';
+        else if (score >= 51)
+            riskLevel = 'high';
+        else if (score >= 26)
+            riskLevel = 'medium';
+        else
+            riskLevel = 'low';
+        // Recommended method by risk level
+        let recommendedMethod;
+        if (riskLevel === 'critical')
+            recommendedMethod = 'flashbots-bundle';
+        else if (riskLevel === 'high')
+            recommendedMethod = 'flashbots-protect';
+        else if (riskLevel === 'medium')
+            recommendedMethod = 'private-rpc';
+        else
+            recommendedMethod = 'none';
+        // Estimated savings: risk-weighted sandwich loss model
+        // ~0.5-2% of swap size; simplified: amountUsd * riskScore/100 * 0.01
+        const estimatedSavingsUsd = amountUsd * (score / 100) * 0.01;
+        // Derive factor labels
+        const gasPrice = gasPriceGwei > 100 ? 'spike' :
+            gasPriceGwei > 50 ? 'high' :
+                gasPriceGwei > 20 ? 'normal' : 'low';
+        const tokenPairLiquidity = this.isPopularPair(fromToken, toToken) ? 'high' : 'low';
+        const marketVolatility = gasPriceGwei > 100 ? 'extreme' :
+            gasPriceGwei > 50 ? 'volatile' : 'stable';
+        return {
+            riskLevel,
+            riskScore: score,
+            factors: {
+                swapSizeUsd: amountUsd,
+                slippageBps,
+                tokenPairLiquidity,
+                marketVolatility,
+                gasPrice,
+                isPopularPair: this.isPopularPair(fromToken, toToken),
+            },
+            recommendedMethod,
+            estimatedSavingsUsd,
+        };
+    }
+    /** Check if a token pair is "popular" (highly watched by MEV bots) */
+    isPopularPair(fromToken, toToken) {
+        return POPULAR_TOKENS.has(fromToken.toUpperCase()) && POPULAR_TOKENS.has(toToken.toUpperCase());
+    }
+}
+//# sourceMappingURL=risk.js.map

package/dist/mev/risk.js.map

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

package/dist/mev/types.d.ts

@@ -0,0 +1,49 @@
+export type MEVRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+export type ProtectionMethod = 'flashbots-protect' | 'flashbots-bundle' | 'cowswap-order' | 'private-rpc' | 'none';
+export interface MEVRiskAssessment {
+    riskLevel: MEVRiskLevel;
+    riskScore: number;
+    factors: {
+        swapSizeUsd: number;
+        slippageBps: number;
+        tokenPairLiquidity: 'high' | 'medium' | 'low';
+        marketVolatility: 'stable' | 'volatile' | 'extreme';
+        gasPrice: 'low' | 'normal' | 'high' | 'spike';
+        isPopularPair: boolean;
+    };
+    recommendedMethod: ProtectionMethod;
+    estimatedSavingsUsd: number;
+}
+export interface MEVProtectionConfig {
+    enabled: boolean;
+    /** Risk threshold above which protection is auto-applied */
+    autoProtectAboveRisk?: MEVRiskLevel;
+    /** Flashbots RPC endpoint */
+    flashbotsRpcUrl?: string;
+    /** MEV Blocker RPC (alternative) */
+    mevBlockerRpcUrl?: string;
+    /** Max extra latency accepted for protection (ms) */
+    maxProtectionLatencyMs?: number;
+    /** Minimum swap USD value to trigger protection */
+    minSwapUsdForProtection?: number;
+}
+export interface ProtectedSwapResult {
+    success: boolean;
+    txHash?: string;
+    protectionMethod: ProtectionMethod;
+    bundleHash?: string;
+    riskAssessment: MEVRiskAssessment;
+    /** Gas saved vs public mempool (estimated) */
+    gasSavedGwei?: number;
+    /** MEV loss avoided (estimated USD) */
+    mevSavedUsd?: number;
+    blockNumber?: number;
+    latencyMs: number;
+}
+export interface FlashbotsBundle {
+    transactions: string[];
+    blockNumber: string;
+    minTimestamp?: number;
+    maxTimestamp?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mev/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mev/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAElE,MAAM,MAAM,gBAAgB,GACxB,mBAAmB,GACnB,kBAAkB,GAClB,eAAe,GACf,aAAa,GACb,MAAM,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,YAAY,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;QAC9C,gBAAgB,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;QACpD,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;QAC9C,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,iBAAiB,EAAE,gBAAgB,CAAC;IACpC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,YAAY,CAAC;IACpC,6BAA6B;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,iBAAiB,CAAC;IAClC,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/mev/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mev/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mev/types.ts"],"names":[],"mappings":""}

package/dist/plugins/elizaos.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @elizaos/plugin-agentwallet
+ *
+ * ElizaOS plugin for agentwallet-sdk — non-custodial AI agent wallet with
+ * x402 payment support, CCTP V2 cross-chain transfers, and on-chain spend limits.
+ *
+ * Your agent holds its own private key. No custodian. No KYC.
+ */
+import type { Plugin } from '@elizaos/core';
+import { createWallet } from '../index.js';
+type AgentWallet = ReturnType<typeof createWallet>;
+export interface AgentWalletPluginConfig {
+    /** Agent private key — stays in your environment, never transmitted */
+    privateKey: `0x${string}`;
+    /** Deployed AgentAccountV2 contract address */
+    accountAddress: `0x${string}`;
+    /** Chain to connect to (default: 'base') */
+    chain?: 'base' | 'base-sepolia' | 'ethereum' | 'arbitrum' | 'polygon' | 'etherlink';
+    /** Optional custom RPC URL */
+    rpcUrl?: string;
+    /** Optional daily x402 spend limit in USDC base units (default: 50 USDC = 50_000_000n) */
+    x402DailyLimit?: bigint;
+}
+/**
+ * Get or create the agent wallet singleton.
+ */
+export declare function getAgentWallet(config: AgentWalletPluginConfig): AgentWallet;
+/**
+ * Create an x402-enabled fetch function for the agent to pay APIs automatically.
+ */
+export declare function createAgentFetch(config: AgentWalletPluginConfig): typeof fetch;
+/**
+ * ElizaOS Plugin definition for agentwallet-sdk.
+ *
+ * Usage in your Eliza character config:
+ *
+ * ```json
+ * {
+ *   "plugins": ["@elizaos/plugin-agentwallet"],
+ *   "settings": {
+ *     "AGENT_PRIVATE_KEY": "0x...",
+ *     "AGENT_ACCOUNT_ADDRESS": "0x...",
+ *     "AGENT_CHAIN": "base",
+ *     "X402_DAILY_LIMIT": "50000000"
+ *   }
+ * }
+ * ```
+ */
+declare const AgentWalletPlugin: Plugin;
+export default AgentWalletPlugin;
+export { AgentWalletPlugin };
+//# sourceMappingURL=elizaos.d.ts.map

package/dist/plugins/elizaos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elizaos.d.ts","sourceRoot":"","sources":["../../src/plugins/elizaos.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,YAAY,EAGb,MAAM,aAAa,CAAC;AAGrB,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAInD,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,UAAU,EAAE,KAAK,MAAM,EAAE,CAAC;IAC1B,+CAA+C;IAC/C,cAAc,EAAE,KAAK,MAAM,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACpF,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,WAAW,CAuB3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,gBAK/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,iBAAiB,EAAE,MAiCxB,CAAC;AAEF,eAAe,iBAAiB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/plugins/elizaos.js

@@ -0,0 +1,89 @@
+import { createWallet, createX402Fetch, } from '../index.js';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+let walletInstance = null;
+/**
+ * Get or create the agent wallet singleton.
+ */
+export function getAgentWallet(config) {
+    if (!walletInstance) {
+        const account = privateKeyToAccount(config.privateKey);
+        const rpcUrls = {
+            base: 'https://mainnet.base.org',
+            'base-sepolia': 'https://sepolia.base.org',
+            ethereum: 'https://eth.llamarpc.com',
+            arbitrum: 'https://arb1.arbitrum.io/rpc',
+            polygon: 'https://polygon-rpc.com',
+            etherlink: 'https://node.mainnet.etherlink.com',
+        };
+        const chain = config.chain ?? 'base';
+        const walletClient = createWalletClient({
+            account,
+            transport: http(config.rpcUrl ?? rpcUrls[chain] ?? rpcUrls.base),
+        });
+        walletInstance = createWallet({
+            accountAddress: config.accountAddress,
+            chain,
+            walletClient,
+        });
+    }
+    return walletInstance;
+}
+/**
+ * Create an x402-enabled fetch function for the agent to pay APIs automatically.
+ */
+export function createAgentFetch(config) {
+    const wallet = getAgentWallet(config);
+    return createX402Fetch(wallet, {
+        globalDailyLimit: config.x402DailyLimit ?? 50000000n, // 50 USDC default
+    });
+}
+/**
+ * ElizaOS Plugin definition for agentwallet-sdk.
+ *
+ * Usage in your Eliza character config:
+ *
+ * ```json
+ * {
+ *   "plugins": ["@elizaos/plugin-agentwallet"],
+ *   "settings": {
+ *     "AGENT_PRIVATE_KEY": "0x...",
+ *     "AGENT_ACCOUNT_ADDRESS": "0x...",
+ *     "AGENT_CHAIN": "base",
+ *     "X402_DAILY_LIMIT": "50000000"
+ *   }
+ * }
+ * ```
+ */
+const AgentWalletPlugin = {
+    name: '@elizaos/plugin-agentwallet',
+    description: 'Non-custodial agent wallet for ElizaOS — x402 payments, CCTP cross-chain, on-chain spend limits. Agent holds its own keys.',
+    actions: [],
+    providers: [
+        {
+            name: 'agentWallet',
+            description: 'Provides agent wallet and x402 fetch capability to the runtime',
+            async get(runtime) {
+                const privateKey = runtime.getSetting('AGENT_PRIVATE_KEY');
+                const accountAddress = runtime.getSetting('AGENT_ACCOUNT_ADDRESS');
+                const chain = (runtime.getSetting('AGENT_CHAIN') ?? 'base');
+                const dailyLimitStr = runtime.getSetting('X402_DAILY_LIMIT');
+                const x402DailyLimit = dailyLimitStr ? BigInt(dailyLimitStr) : 50000000n;
+                if (!privateKey || !accountAddress) {
+                    return 'AgentWallet not configured: AGENT_PRIVATE_KEY and AGENT_ACCOUNT_ADDRESS required.';
+                }
+                const config = { privateKey, accountAddress, chain, x402DailyLimit };
+                const wallet = getAgentWallet(config);
+                const x402Fetch = createAgentFetch(config);
+                // Expose on runtime for actions to use
+                runtime.agentWallet = wallet;
+                runtime.x402Fetch = x402Fetch;
+                return `AgentWallet ready — non-custodial, keys stay local. Chain: ${chain}. x402 daily limit: ${x402DailyLimit / 1000000n} USDC.`;
+            },
+        },
+    ],
+    evaluators: [],
+};
+export default AgentWalletPlugin;
+export { AgentWalletPlugin };
+//# sourceMappingURL=elizaos.js.map

package/dist/plugins/elizaos.js.map

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

package/dist/settlement/index.d.ts

@@ -0,0 +1,4 @@
+export { SettlementVerifier } from './verifier.js';
+export type { SettlementVerifierConfig, SettlementStatus, SettlementResult, BridgeSettlementResult, BridgeSettlementStatus, PaymentSettlementResult, } from './types.js';
+export { SETTLEMENT_ALCHEMY_NETWORKS, SETTLEMENT_PUBLIC_RPCS, CIRCLE_ATTESTATION_API, ERC20_TRANSFER_TOPIC, SOLANA_RPC_URL, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/settlement/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/settlement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EACV,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/settlement/index.js

@@ -0,0 +1,3 @@
+export { SettlementVerifier } from './verifier.js';
+export { SETTLEMENT_ALCHEMY_NETWORKS, SETTLEMENT_PUBLIC_RPCS, CIRCLE_ATTESTATION_API, ERC20_TRANSFER_TOPIC, SOLANA_RPC_URL, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/settlement/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/settlement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AASnD,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/settlement/types.d.ts

@@ -0,0 +1,66 @@
+export interface SettlementVerifierConfig {
+    /** Alchemy API key (optional — falls back to public RPC if not provided) */
+    alchemyApiKey?: string;
+}
+/** Status of an on-chain settlement */
+export type SettlementStatus = 'confirmed' | 'pending' | 'failed' | 'not_found';
+/** Result of verifying a single transaction */
+export interface SettlementResult {
+    status: SettlementStatus;
+    txHash: string;
+    /** Block number where the tx was included (0 if pending/not found) */
+    blockNumber: bigint;
+    /** Number of confirmations at query time */
+    confirmations: number;
+    /** Gas used by the transaction */
+    gasUsed?: bigint;
+    /** Whether the tx succeeded (status=1) or reverted (status=0) */
+    success?: boolean;
+    /** Any error message if verification failed */
+    error?: string;
+}
+/** Result of verifying a CCTP bridge transfer end-to-end */
+export interface BridgeSettlementResult {
+    /** Overall bridge status */
+    status: BridgeSettlementStatus;
+    /** Source chain burn transaction */
+    sourceTx: SettlementResult;
+    /** Destination chain mint transaction (if found) */
+    destinationTx?: SettlementResult;
+    /** Circle attestation status */
+    attestationStatus?: 'pending_confirmations' | 'complete' | 'error';
+    /** Amount that was bridged (from source tx logs) */
+    amount?: bigint;
+    /** Destination address that received funds */
+    recipient?: string;
+    /** Any error or warning messages */
+    error?: string;
+}
+export type BridgeSettlementStatus = 'source_confirmed_awaiting_attestation' | 'attestation_complete_awaiting_mint' | 'complete' | 'source_failed' | 'source_pending' | 'not_found' | 'error';
+/** Result of verifying an x402 payment */
+export interface PaymentSettlementResult {
+    status: SettlementStatus;
+    txHash: string;
+    /** Whether the payment went to the expected payee */
+    payeeVerified: boolean;
+    /** Whether the amount matches */
+    amountVerified: boolean;
+    /** Actual amount transferred (from event logs) */
+    actualAmount?: bigint;
+    /** Actual payee address (from event logs) */
+    actualPayee?: string;
+    /** Token contract address */
+    tokenAddress?: string;
+    error?: string;
+}
+/** Alchemy network slugs for settlement verification (subset: EVM chains with Alchemy support) */
+export declare const SETTLEMENT_ALCHEMY_NETWORKS: Record<string, string>;
+/** Public RPC fallbacks for chains without Alchemy Gas Manager support */
+export declare const SETTLEMENT_PUBLIC_RPCS: Record<string, string>;
+/** Circle CCTP attestation API base URL */
+export declare const CIRCLE_ATTESTATION_API = "https://iris-api.circle.com/attestations";
+/** ERC20 Transfer event topic: keccak256("Transfer(address,address,uint256)") */
+export declare const ERC20_TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+/** Solana RPC endpoint */
+export declare const SOLANA_RPC_URL = "https://api.mainnet-beta.solana.com";
+//# sourceMappingURL=types.d.ts.map

package/dist/settlement/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/settlement/types.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEhF,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,oCAAoC;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,oDAAoD;IACpD,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,gCAAgC;IAChC,iBAAiB,CAAC,EAAE,uBAAuB,GAAG,UAAU,GAAG,OAAO,CAAC;IACnE,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,sBAAsB,GAC9B,uCAAuC,GACvC,oCAAoC,GACpC,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,WAAW,GACX,OAAO,CAAC;AAEZ,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;IACvB,iCAAiC;IACjC,cAAc,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kGAAkG;AAClG,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO9D,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiBzD,CAAC;AAEF,2CAA2C;AAC3C,eAAO,MAAM,sBAAsB,6CAA6C,CAAC;AAEjF,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,uEACqC,CAAC;AAEvE,0BAA0B;AAC1B,eAAO,MAAM,cAAc,wCAAwC,CAAC"}

package/dist/settlement/types.js

@@ -0,0 +1,37 @@
+// Settlement Verification — Types
+// Verify that transactions, bridge transfers, and x402 payments actually settled on-chain.
+/** Alchemy network slugs for settlement verification (subset: EVM chains with Alchemy support) */
+export const SETTLEMENT_ALCHEMY_NETWORKS = {
+    ethereum: 'eth-mainnet',
+    base: 'base-mainnet',
+    arbitrum: 'arb-mainnet',
+    optimism: 'opt-mainnet',
+    polygon: 'polygon-mainnet',
+    worldchain: 'worldchain-mainnet',
+};
+/** Public RPC fallbacks for chains without Alchemy Gas Manager support */
+export const SETTLEMENT_PUBLIC_RPCS = {
+    ethereum: 'https://eth.llamarpc.com',
+    base: 'https://mainnet.base.org',
+    arbitrum: 'https://arb1.arbitrum.io/rpc',
+    optimism: 'https://mainnet.optimism.io',
+    polygon: 'https://polygon-rpc.com',
+    worldchain: 'https://worldchain-mainnet.g.alchemy.com/public',
+    avalanche: 'https://api.avax.network/ext/bc/C/rpc',
+    unichain: 'https://mainnet.unichain.org',
+    linea: 'https://rpc.linea.build',
+    sonic: 'https://rpc.soniclabs.com',
+    sei: 'https://evm-rpc.sei-apis.com',
+    ink: 'https://rpc-gel.inkonchain.com',
+    hyperevm: 'https://rpc.hyperliquid.xyz/evm',
+    plume: 'https://rpc.plumenetwork.xyz',
+    xdc: 'https://rpc.xinfin.network',
+    codex: 'https://rpc.codex.storage',
+};
+/** Circle CCTP attestation API base URL */
+export const CIRCLE_ATTESTATION_API = 'https://iris-api.circle.com/attestations';
+/** ERC20 Transfer event topic: keccak256("Transfer(address,address,uint256)") */
+export const ERC20_TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+/** Solana RPC endpoint */
+export const SOLANA_RPC_URL = 'https://api.mainnet-beta.solana.com';
+//# sourceMappingURL=types.js.map

package/dist/settlement/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/settlement/types.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,2FAA2F;AAsE3F,kGAAkG;AAClG,MAAM,CAAC,MAAM,2BAA2B,GAA2B;IACjE,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,aAAa;IACvB,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,iBAAiB;IAC1B,UAAU,EAAE,oBAAoB;CACjC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC5D,QAAQ,EAAE,0BAA0B;IACpC,IAAI,EAAE,0BAA0B;IAChC,QAAQ,EAAE,8BAA8B;IACxC,QAAQ,EAAE,6BAA6B;IACvC,OAAO,EAAE,yBAAyB;IAClC,UAAU,EAAE,iDAAiD;IAC7D,SAAS,EAAE,uCAAuC;IAClD,QAAQ,EAAE,8BAA8B;IACxC,KAAK,EAAE,yBAAyB;IAChC,KAAK,EAAE,2BAA2B;IAClC,GAAG,EAAE,8BAA8B;IACnC,GAAG,EAAE,gCAAgC;IACrC,QAAQ,EAAE,iCAAiC;IAC3C,KAAK,EAAE,8BAA8B;IACrC,GAAG,EAAE,4BAA4B;IACjC,KAAK,EAAE,2BAA2B;CACnC,CAAC;AAEF,2CAA2C;AAC3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,0CAA0C,CAAC;AAEjF,iFAAiF;AACjF,MAAM,CAAC,MAAM,oBAAoB,GAC/B,oEAAoE,CAAC;AAEvE,0BAA0B;AAC1B,MAAM,CAAC,MAAM,cAAc,GAAG,qCAAqC,CAAC"}

package/dist/settlement/verifier.d.ts

@@ -0,0 +1,75 @@
+import type { SettlementVerifierConfig, SettlementResult, BridgeSettlementResult, PaymentSettlementResult } from './types.js';
+export declare class SettlementVerifier {
+    private readonly alchemyApiKey;
+    constructor(config?: SettlementVerifierConfig);
+    /**
+     * 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)
+     */
+    verifyEvmTransaction(params: {
+        chain: string;
+        txHash: string;
+        confirmations?: number;
+    }): Promise<SettlementResult>;
+    /**
+     * 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')
+     */
+    verifySolanaTransaction(params: {
+        signature: string;
+        commitment?: 'confirmed' | 'finalized';
+    }): Promise<SettlementResult>;
+    /**
+     * 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)
+     */
+    verifyBridgeSettlement(params: {
+        sourceTxHash: string;
+        sourceChain: string;
+        destinationChain: string;
+        expectedAmount: bigint;
+    }): Promise<BridgeSettlementResult>;
+    /**
+     * 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)
+     */
+    verifyX402Payment(params: {
+        chain: string;
+        txHash: string;
+        expectedPayee: string;
+        expectedAmount: bigint;
+    }): Promise<PaymentSettlementResult>;
+    /** Get the RPC URL for a chain, preferring Alchemy over public RPCs */
+    private _getRpcUrl;
+    /** Make an EVM JSON-RPC call */
+    private _evmRpc;
+    /** Make a Solana JSON-RPC call */
+    private _solanaRpc;
+    /** Check Circle attestation API for a CCTP burn message */
+    private _checkCircleAttestation;
+}
+//# sourceMappingURL=verifier.d.ts.map

package/dist/settlement/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/settlement/verifier.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AASpB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,MAAM,GAAE,wBAA6B;IAMjD;;;;;;;;;OASG;IACG,oBAAoB,CAAC,MAAM,EAAE;QACjC,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2E7B;;;;;OAKG;IACG,uBAAuB,CAAC,MAAM,EAAE;QACpC,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;KACxC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqD7B;;;;;;;;;;OAUG;IACG,sBAAsB,CAAC,MAAM,EAAE;QACnC,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAkEnC;;;;;;;;;;;;OAYG;IACG,iBAAiB,CAAC,MAAM,EAAE;QAC9B,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAqFpC,uEAAuE;IACvE,OAAO,CAAC,UAAU;IAYlB,gCAAgC;YAClB,OAAO;IAoBrB,kCAAkC;YACpB,UAAU;IAmBxB,2DAA2D;YAC7C,uBAAuB;CA0BtC"}