@elizaos/plugin-wallet 2.0.0-beta.1 → 2.0.3-beta.6

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

@@ -0,0 +1,131 @@
+/**
+ * SolanaBridgeModule — CCTP V2 cross-chain USDC bridge between EVM chains and Solana.
+ *
+ * Uses Circle's Cross-Chain Transfer Protocol (CCTP) V2 for trustless USDC transfers.
+ * EVM side uses viem; Solana side uses @solana/web3.js as an optional peer dependency.
+ *
+ * Sources:
+ *   - Circle CCTP Solana docs: https://developers.circle.com/cctp/docs/solana
+ *   - Solana USDC mint: https://solana.com/ecosystem/usdc
+ *   - CCTP domain IDs: https://developers.circle.com/cctp/references/contract-addresses
+ */
+import { type Address, type Hash, type Hex, type WalletClient } from "viem";
+import { type EVMBridgeChain } from "./types.js";
+/** Solana CCTP domain ID */
+export declare const SOLANA_CCTP_DOMAIN = 5;
+/** Native USDC mint on Solana Mainnet */
+export declare const SOLANA_USDC_MINT: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+/**
+ * Solana CCTP V2 TokenMessengerMinterV2 program address.
+ * This is the V2 program (not V1 CCTPiPYP...). The V2 program combines
+ * TokenMessengerV2 + TokenMinterV2 into a single program.
+ * Source: https://developers.circle.com/cctp/references/solana-programs
+ * Verified: https://github.com/circlefin/solana-cctp-contracts (programs/v2)
+ */
+export declare const SOLANA_TOKEN_MESSENGER: "CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe";
+/**
+ * Solana CCTP V2 MessageTransmitterV2 program address.
+ * This is the V2 program (not V1 CCTPmbSD...).
+ * Source: https://developers.circle.com/cctp/references/solana-programs
+ * Verified: https://github.com/circlefin/solana-cctp-contracts (programs/v2)
+ */
+export declare const SOLANA_MESSAGE_TRANSMITTER: "CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC";
+/** Default Solana Mainnet RPC endpoint */
+export declare const SOLANA_DEFAULT_RPC: "https://api.mainnet-beta.solana.com";
+/**
+ * Decode a 32-byte hex buffer back to a Solana base58 public key.
+ * Used when interpreting Solana→EVM message recipient fields.
+ */
+export declare function bytes32ToSolanaPubkey(bytes32: Hex): string;
+export interface EVMToSolanaOptions {
+    /** Solana recipient address (base58). Defaults to the EVM signer's address re-encoded — usually wrong; always specify. */
+    solanaRecipient: string;
+    /** EVM source chain. Defaults to 'base'. */
+    fromChain?: EVMBridgeChain;
+    /** Optional EVM RPC URL override. */
+    evmRpcUrl?: string;
+    /** Finality threshold: FAST (0) or FINALIZED (1000). Default: FAST. */
+    minFinalityThreshold?: number;
+    /** Max bridge fee in USDC base units. Default: 0 (no fee). */
+    maxFee?: bigint;
+    /** Circle IRIS API URL override. */
+    attestationApiUrl?: string;
+}
+export interface EVMToSolanaResult {
+    /** EVM burn transaction hash */
+    burnTxHash: Hash;
+    /** Circle message hash (used to poll for attestation) */
+    messageHash: Hex;
+    /** Raw CCTP message bytes (for manual receiveMessage on Solana) */
+    messageBytes: Hex;
+    /** Circle attestation signature (for receiveMessage on Solana) */
+    attestation: Hex;
+    /** The Solana CCTP domain (5) */
+    destinationDomain: number;
+    /** Amount bridged in USDC base units */
+    amount: bigint;
+    /** Elapsed time in milliseconds */
+    elapsedMs: number;
+}
+/**
+ * Bridge USDC from an EVM chain to Solana using CCTP V2.
+ *
+ * This function handles the EVM burn side and attestation polling.
+ * The Solana receive side must be completed by calling `receiveMessageOnSolana()`
+ * or by the Solana recipient manually submitting the message and attestation
+ * to the Solana MessageTransmitter program.
+ *
+ * @param walletClient - Viem WalletClient with a signer attached (for EVM)
+ * @param amount - Amount to bridge in USDC base units (6 decimals, e.g. 1_000_000n = 1 USDC)
+ * @param options - Bridge options including solanaRecipient (required)
+ * @returns Burn tx hash, attestation, and message bytes for Solana receive
+ */
+export declare function bridgeEVMToSolana(walletClient: WalletClient, amount: bigint, options: EVMToSolanaOptions): Promise<EVMToSolanaResult>;
+export interface SolanaToEVMOptions {
+    /** EVM destination chain */
+    toChain: EVMBridgeChain;
+    /** Optional EVM destination RPC URL override */
+    evmRpcUrl?: string;
+    /** EVM recipient address. Defaults to the EVM walletClient's account address. */
+    evmRecipient?: Address;
+    /** Circle IRIS API URL override */
+    attestationApiUrl?: string;
+    /** Solana RPC URL override */
+    solanaRpcUrl?: string;
+}
+export interface SolanaToEVMBurnParams {
+    /** Raw CCTP message bytes from Solana burn transaction */
+    messageBytes: Hex;
+    /** Circle message hash */
+    messageHash: Hex;
+    /** Source domain (should be SOLANA_CCTP_DOMAIN = 5) */
+    sourceDomain: number;
+}
+export interface SolanaToEVMResult {
+    /** EVM mint transaction hash */
+    mintTxHash: Hash;
+    /** Amount received in USDC base units */
+    amount: bigint;
+    /** EVM destination chain */
+    toChain: EVMBridgeChain;
+    /** EVM recipient address */
+    recipient: Address;
+    /** Elapsed time in milliseconds */
+    elapsedMs: number;
+}
+/**
+ * Complete the Solana→EVM bridge by polling for Circle's attestation and minting on EVM.
+ *
+ * The caller is responsible for initiating the Solana burn via the Solana
+ * CCTP MessageTransmitter and passing the resulting messageBytes + messageHash here.
+ *
+ * @param walletClient - Viem WalletClient (for EVM signing)
+ * @param burnParams - Message bytes and hash from the Solana burn transaction
+ * @param options - Destination chain and optional overrides
+ */
+export declare function receiveFromSolanaOnEVM(walletClient: WalletClient, burnParams: SolanaToEVMBurnParams, options: SolanaToEVMOptions): Promise<SolanaToEVMResult>;
+export type SolanaBridgeErrorCode = "NO_WALLET_CLIENT" | "INVALID_AMOUNT" | "INVALID_RECIPIENT" | "INSUFFICIENT_ALLOWANCE" | "BURN_FAILED" | "ATTESTATION_ERROR" | "ATTESTATION_TIMEOUT" | "MINT_FAILED";
+export declare class SolanaBridgeError extends Error {
+    readonly code: SolanaBridgeErrorCode;
+    constructor(code: SolanaBridgeErrorCode, message: string);
+}

package/dist/sdk/bridge/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module bridge/types
+ * Type definitions and constants for the CCTP V2 cross-chain USDC bridge.
+ *
+ * Supports 10 EVM chains + Solana via Circle's Cross-Chain Transfer Protocol V2.
+ * EVM chains: Ethereum, Avalanche, Optimism, Arbitrum, Base, Polygon,
+ *             Unichain, Linea, Sonic, Worldchain.
+ * Non-EVM: Solana (via bridge/solana.ts — uses separate CCTP V2 programs).
+ *
+ * Contract addresses verified against:
+ * - CCTP V2 EVM: https://developers.circle.com/cctp/references/contract-addresses
+ * - Solana V2 programs: https://developers.circle.com/cctp/references/solana-programs
+ * - USDC addresses: https://developers.circle.com/stablecoins/usdc-contract-addresses
+ */
+import type { Address, Hash, Hex } from "viem";
+/** Supported bridge destination chains */
+export type BridgeChain = "ethereum" | "avalanche" | "optimism" | "arbitrum" | "base" | "polygon" | "unichain" | "linea" | "sonic" | "worldchain" | "solana";
+/** EVM-only bridge chains (excludes non-EVM like Solana) */
+export type EVMBridgeChain = Exclude<BridgeChain, "solana">;
+/**
+ * CCTP V2 domain IDs — official Circle domain identifiers.
+ * Source: https://developers.circle.com/cctp/references/contract-addresses
+ * Solana domain: 5 — https://developers.circle.com/cctp/docs/solana
+ */
+export declare const CCTP_DOMAIN_IDS: Record<BridgeChain, number>;
+/**
+ * EVM chain IDs for EVM-compatible bridge chains.
+ * Solana is excluded — use solana.ts for Solana-specific operations.
+ */
+export declare const BRIDGE_CHAIN_IDS: Record<EVMBridgeChain, number>;
+/**
+ * USDC contract addresses per chain (native Circle USDC, not bridged variants).
+ * Solana USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v (stored as string, not Address/Hex)
+ */
+export declare const USDC_CONTRACT: Record<EVMBridgeChain, Address>;
+/** Solana USDC mint address */
+export declare const SOLANA_USDC_MINT: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export declare const TOKEN_MESSENGER_V2: Record<EVMBridgeChain, Address>;
+export declare const MESSAGE_TRANSMITTER_V2: Record<EVMBridgeChain, Address>;
+/**
+ * CCTP V2 minFinalityThreshold values.
+ * - FAST (0): ~12 seconds. Circle fast attestation.
+ * - FINALIZED (1000): Full on-chain finality.
+ */
+export declare const FINALITY_THRESHOLD: {
+    readonly FAST: 0;
+    readonly FINALIZED: 1000;
+};
+/** Circle IRIS attestation API base URL */
+export declare const CIRCLE_ATTESTATION_API = "https://iris-api.circle.com";
+/** Max attestation polling attempts before timeout */
+export declare const MAX_ATTESTATION_POLLS = 60;
+/** Polling interval for attestation (milliseconds) */
+export declare const ATTESTATION_POLL_INTERVAL_MS = 5000;
+/** Options for a bridge operation */
+export interface BridgeOptions {
+    minFinalityThreshold?: number;
+    maxFee?: bigint;
+    destinationAddress?: Address;
+    destinationRpcUrl?: string;
+    attestationApiUrl?: string;
+}
+/** Result of a bridge.burn() operation */
+export interface BurnResult {
+    burnTxHash: Hash;
+    nonce: bigint;
+    messageHash: Hex;
+    messageBytes: Hex;
+    sourceDomain: number;
+    destinationDomain: number;
+}
+/** Circle attestation status */
+export type AttestationStatus = "pending_confirmations" | "complete" | "error";
+/** Circle IRIS API response for an attestation */
+export interface AttestationResponse {
+    status: AttestationStatus;
+    attestation: Hex | null;
+    error?: string;
+}
+/** Result of the full EVM↔EVM bridge() operation */
+export interface BridgeResult {
+    burnTxHash: Hash;
+    mintTxHash: Hash;
+    amount: bigint;
+    fromChain: EVMBridgeChain;
+    toChain: EVMBridgeChain;
+    recipient: Address;
+    nonce: bigint;
+    elapsedMs: number;
+}
+/** Error codes for actionable bridge error messages */
+export type BridgeErrorCode = "UNSUPPORTED_CHAIN" | "INSUFFICIENT_ALLOWANCE" | "INSUFFICIENT_BALANCE" | "BURN_FAILED" | "ATTESTATION_TIMEOUT" | "ATTESTATION_ERROR" | "MINT_FAILED" | "INVALID_AMOUNT" | "NO_WALLET_CLIENT";

package/dist/sdk/convenience.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @module convenience
+ * Environment-variable-driven wallet bootstrap helpers.
+ *
+ * Provides three dead-simple factory functions that read all configuration
+ * from process environment variables so that any agent can set up a fully
+ * functional wallet in 3 lines without touching viem directly:
+ *
+ * ```typescript
+ * import { walletFromEnv, setPolicyFromEnv, x402FromEnv } from 'agentwallet-sdk';
+ *
+ * const wallet = walletFromEnv();
+ * await setPolicyFromEnv(wallet);
+ * const client = x402FromEnv(wallet);
+ * ```
+ *
+ * ### Environment variables
+ *
+ * | Variable              | Required | Default        | Description                                      |
+ * |-----------------------|----------|----------------|--------------------------------------------------|
+ * | AGENT_PRIVATE_KEY     | ✅ yes   | —              | EOA private key (0x-prefixed hex, 32 bytes)      |
+ * | AGENT_WALLET_ADDRESS  | ✅ yes   | —              | AgentAccountV2 smart-wallet address              |
+ * | CHAIN_NAME            | no       | base           | Chain name (base, mainnet, arbitrum, …)          |
+ * | CHAIN_ID              | no       | —              | Alternative to CHAIN_NAME — numeric chain id     |
+ * | RPC_URL               | no       | chain default  | Custom JSON-RPC endpoint                         |
+ * | SPEND_LIMIT_PER_TX    | no       | —              | Per-tx USDC limit (decimal, e.g. "1.00")         |
+ * | SPEND_LIMIT_DAILY     | no       | —              | Daily USDC limit  (decimal, e.g. "10.00")        |
+ * | SPEND_ALLOWLIST       | no       | —              | Comma-separated recipient addresses              |
+ * | X402_SUPPORTED_NETWORKS | no     | (all mainnet)  | Comma-separated "chain:chainId" network strings  |
+ * | X402_GLOBAL_DAILY_LIMIT | no     | —              | Global daily x402 USDC limit (decimal)           |
+ * | X402_PER_REQUEST_MAX  | no       | —              | Per-request max USDC spend (decimal)             |
+ */
+import { createWallet } from "./wallet-core.js";
+import { createX402Client } from "./x402/middleware.js";
+/**
+ * Create a fully configured AgentWallet from environment variables.
+ *
+ * Reads:
+ * - **AGENT_PRIVATE_KEY** — EOA signing key (required; 0x-prefixed 32-byte hex)
+ * - **AGENT_WALLET_ADDRESS** — AgentAccountV2 contract address (required)
+ * - **CHAIN_NAME** or **CHAIN_ID** — target chain (optional; defaults to Base mainnet)
+ * - **RPC_URL** — custom RPC endpoint (optional; uses chain default if omitted)
+ *
+ * @param options - Optional overrides for chain and rpcUrl.
+ * @param options.chain  - Chain name that takes precedence over the env var.
+ * @param options.rpcUrl - RPC endpoint that takes precedence over the env var.
+ * @returns A fully configured wallet object (same shape as `createWallet()`).
+ *
+ * @throws {Error} If AGENT_PRIVATE_KEY is missing or not a valid hex key.
+ * @throws {Error} If AGENT_WALLET_ADDRESS is missing.
+ *
+ * @example
+ * ```typescript
+ * const wallet = walletFromEnv({ chain: 'base-sepolia' });
+ * ```
+ */
+export declare function walletFromEnv(options?: {
+    chain?: string;
+    rpcUrl?: string;
+}): ReturnType<typeof createWallet>;
+/**
+ * Apply a spending policy to a wallet from environment variables.
+ *
+ * Reads:
+ * - **SPEND_LIMIT_PER_TX** — maximum USDC per single transaction (e.g. "1.00")
+ * - **SPEND_LIMIT_DAILY**  — maximum USDC per 24-hour period (e.g. "10.00")
+ * - **SPEND_ALLOWLIST**    — comma-separated ERC-20 token addresses to restrict
+ *
+ * If neither limit is set, logs a warning and falls back to queue-for-approval
+ * mode (perTxLimit = 0, periodLimit = 0) so all agent transactions must be
+ * manually approved. This is the safest default.
+ *
+ * @param wallet - Wallet returned by `walletFromEnv()` (or `createWallet()`).
+ * @returns Promise that resolves to the on-chain tx hash of the policy update.
+ *
+ * @example
+ * ```typescript
+ * await setPolicyFromEnv(wallet);
+ * ```
+ */
+export declare function setPolicyFromEnv(wallet: ReturnType<typeof createWallet>): Promise<string>;
+/**
+ * Create an x402 payment client from environment variables.
+ *
+ * Reads:
+ * - **X402_SUPPORTED_NETWORKS**   — comma-separated "chain:chainId" strings
+ *   (e.g. "base:8453,arbitrum:42161"); defaults to all supported mainnets
+ * - **X402_GLOBAL_DAILY_LIMIT**   — total daily USDC budget across all x402
+ *   services (decimal, e.g. "5.00")
+ * - **X402_PER_REQUEST_MAX**      — per-request USDC ceiling (decimal)
+ *
+ * Sensible defaults: supports all 10 mainnet x402 chains, unlimited daily spend
+ * (rely on the agent's on-chain spend policy as the hard limit), 1 auto-retry.
+ *
+ * @param wallet - Wallet returned by `walletFromEnv()` (or `createWallet()`).
+ * @returns A configured X402Client instance.
+ *
+ * @example
+ * ```typescript
+ * const client = x402FromEnv(wallet);
+ * const data = await client.fetch('https://api.example.com/premium-endpoint');
+ * ```
+ */
+export declare function x402FromEnv(wallet: ReturnType<typeof createWallet>): ReturnType<typeof createX402Client>;

package/dist/sdk/escrow/MutualStakeEscrow.d.ts

@@ -0,0 +1,75 @@
+import type { Address, Hex, PublicClient, WalletClient } from "viem";
+import type { CreateEscrowParams, EscrowCreated, EscrowDetails, TxResult } from "./types.js";
+import { TaskStatus } from "./types.js";
+/**
+ * MutualStakeEscrow — SDK class for creating and managing mutual-stake escrow vaults
+ *
+ * Wraps the StakeVault and StakeVaultFactory contracts with a clean TypeScript API.
+ * Both buyer and seller deposit collateral, ensuring aligned incentives.
+ */
+export declare class MutualStakeEscrow {
+    private publicClient;
+    private walletClient;
+    private factoryAddress;
+    private chainId;
+    constructor(params: {
+        publicClient: PublicClient;
+        walletClient: WalletClient;
+        factoryAddress: Address;
+        chainId: number;
+    });
+    /**
+     * Create a new escrow vault via the factory
+     * @param params - Escrow creation parameters
+     * @returns The deployed vault address and transaction hash
+     */
+    create(params: CreateEscrowParams): Promise<EscrowCreated>;
+    /**
+     * Fund an escrow as buyer (deposits payment + buyerStake)
+     * @param vaultAddress - Address of the StakeVault
+     * @param approveAmount - Total amount to approve (payment + buyerStake)
+     */
+    fund(vaultAddress: Address, approveAmount: bigint): Promise<TxResult>;
+    /**
+     * Accept an escrow as seller (deposits sellerStake)
+     * @param vaultAddress - Address of the StakeVault
+     */
+    accept(vaultAddress: Address): Promise<TxResult>;
+    /**
+     * Submit fulfillment proof as seller
+     * @param vaultAddress - Address of the StakeVault
+     * @param proof - Completion proof bytes
+     */
+    fulfill(vaultAddress: Address, proof: Hex): Promise<TxResult>;
+    /**
+     * Verify completion after challenge window (anyone can call)
+     * @param vaultAddress - Address of the StakeVault
+     */
+    verify(vaultAddress: Address): Promise<TxResult>;
+    /**
+     * Challenge a fulfillment as buyer
+     * @param vaultAddress - Address of the StakeVault
+     * @param evidence - Challenge evidence bytes
+     */
+    challenge(vaultAddress: Address, evidence: Hex): Promise<TxResult>;
+    /**
+     * Cancel escrow before seller accepts (buyer only)
+     * @param vaultAddress - Address of the StakeVault
+     */
+    cancel(vaultAddress: Address): Promise<TxResult>;
+    /**
+     * Reclaim funds after deadline expiry
+     * @param vaultAddress - Address of the StakeVault
+     */
+    reclaimExpired(vaultAddress: Address): Promise<TxResult>;
+    /**
+     * Get full escrow details from on-chain
+     * @param vaultAddress - Address of the StakeVault
+     */
+    getDetails(vaultAddress: Address): Promise<EscrowDetails>;
+    /**
+     * Get the current status of an escrow
+     * @param vaultAddress - Address of the StakeVault
+     */
+    getStatus(vaultAddress: Address): Promise<TaskStatus>;
+}

package/dist/sdk/escrow/types.d.ts

@@ -0,0 +1,58 @@
+import type { Address, Hash, Hex } from "viem";
+/** Mirrors the on-chain TaskStatus enum */
+export declare enum TaskStatus {
+    Created = 0,
+    Funded = 1,
+    Fulfilled = 2,
+    Challenged = 3,
+    Resolved = 4,
+    Cancelled = 5
+}
+/** Supported built-in verifier types */
+export type VerifierType = "optimistic" | "hash";
+/** Parameters for creating a new mutual-stake escrow */
+export interface CreateEscrowParams {
+    /** Seller/service-provider address */
+    seller: Address;
+    /** Payment amount in token's smallest unit (e.g., 6 decimals for USDC) */
+    paymentAmount: bigint;
+    /** Buyer's anti-grief collateral */
+    buyerStake: bigint;
+    /** Seller's anti-fraud collateral */
+    sellerStake: bigint;
+    /** Verifier type or custom verifier contract address */
+    verifier: VerifierType | Address;
+    /** Verifier-specific configuration data (auto-generated for built-in verifiers) */
+    verifierData?: Hex;
+    /** Challenge window in seconds after fulfillment */
+    challengeWindow: number;
+    /** Unix timestamp deadline for the task */
+    deadline: number;
+    /** ERC-20 token address (defaults to USDC on Base) */
+    token?: Address;
+}
+/** Result from creating an escrow */
+export interface EscrowCreated {
+    /** Address of the deployed StakeVault contract */
+    address: Address;
+    /** Transaction hash of the factory call */
+    txHash: Hash;
+}
+/** Full escrow details from on-chain */
+export interface EscrowDetails {
+    buyer: Address;
+    seller: Address;
+    token: Address;
+    paymentAmount: bigint;
+    buyerStake: bigint;
+    sellerStake: bigint;
+    verifier: Address;
+    deadline: bigint;
+    challengeWindow: bigint;
+    status: TaskStatus;
+    fulfilledAt: bigint;
+}
+/** Transaction result */
+export interface TxResult {
+    txHash: Hash;
+}

package/dist/sdk/escrow/verifiers.d.ts

@@ -0,0 +1,25 @@
+import { type Address, type Hex } from "viem";
+import type { VerifierType } from "./types.js";
+/**
+ * Known verifier contract addresses on Base mainnet.
+ * These are deployed once and shared by all StakeVault instances.
+ */
+export declare const VERIFIER_ADDRESSES: Record<string, Record<VerifierType, Address>>;
+/**
+ * Resolve a verifier type to its deployed contract address for a given chain
+ * @param verifier - Built-in verifier type or custom contract address
+ * @param chainId - Chain ID to look up
+ * @returns The verifier contract address
+ */
+export declare function resolveVerifierAddress(verifier: VerifierType | Address, chainId: number): Address;
+/**
+ * Encode verifier configuration data for the HashVerifier
+ * @param expectedHash - SHA256 hash of the expected output
+ * @returns ABI-encoded bytes for the verifierData field
+ */
+export declare function encodeHashVerifierData(expectedHash: Hex): Hex;
+/**
+ * Encode verifier configuration data for the OptimisticVerifier
+ * @returns Empty bytes (optimistic verifier has no config)
+ */
+export declare function encodeOptimisticVerifierData(): Hex;