agentwallet-sdk 2.4.0 → 2.5.0

package/README.md

@@ -4,11 +4,24 @@
 
 Agent Wallet gives AI agents autonomous spending power with hard on-chain limits. No more choosing between "agent can drain everything" and "every transaction needs manual approval."
 
-```
+```text
 Agent wants to spend $15 → ✅ Auto-approved (under $25 limit)
 Agent wants to spend $500 → ⏳ Queued for your approval
 Agent spent $490 today → 🛑 Next tx queued ($500/day limit hit)
-```
+```text
+
+## How We Compare
+
+| | **agentwallet-sdk** | **Coinbase Agentic Wallet** | **MoonPay Agents** |
+|---|---|---|---|
+| **Custody** | Non-custodial (keys on device) | Semi-custodial (TEE) | Non-custodial (claimed) |
+| **Spend Limits** | On-chain (smart contract) | API-enforced | Not documented |
+| **Chains** | 5 (Base, ETH, Arb, Polygon, Sepolia) | Base only | Unclear |
+| **Agent Identity** | ERC-8004 + ERC-6551 | None | None |
+| **Open Source** | MIT | Partial | Closed |
+| **x402 Payments** | Native | Supported | "Compatible" |
+
+> On-chain spend limits can't be bypassed even if the API layer is compromised. That's the difference between policy and math.
 
 ## Why Agent Wallet?
 
@@ -25,7 +38,7 @@ Built on **ERC-6551** (token-bound accounts). Your agent's wallet is tied to an
 
 ```bash
 npm install @agentwallet/sdk viem
-```
+```text
 
 ```typescript
 import {
@@ -76,11 +89,12 @@ for (const tx of pending) {
   console.log(`Pending #${tx.txId}: ${tx.amount} to ${tx.to}`);
   await approveTransaction(wallet, tx.txId);
 }
-```
+```text
 
 ## API Reference
 
 ### `createWallet(config)`
+
 Connect to an existing AgentAccountV2 contract.
 
 | Param | Type | Description |
@@ -91,6 +105,7 @@ Connect to an existing AgentAccountV2 contract.
 | `rpcUrl?` | `string` | Custom RPC URL |
 
 ### `setSpendPolicy(wallet, policy)` — Owner only
+
 Set per-token spending limits.
 
 | Field | Type | Description |
@@ -101,31 +116,39 @@ Set per-token spending limits.
 | `periodLength` | `number` | Window in seconds (default: 86400 = 24h) |
 
 ### `agentExecute(wallet, { to, value?, data? })`
+
 Execute a native ETH transaction. Auto-approves if within limits, queues if over.
 
 **Returns:** `{ executed: boolean, txHash: Hash, pendingTxId?: bigint }`
 
 ### `agentTransferToken(wallet, { token, to, amount })`
+
 Transfer ERC20 tokens, respecting spend limits.
 
 ### `checkBudget(wallet, token?)`
+
 Check remaining autonomous spending budget.
 
 **Returns:** `{ token, perTxLimit, remainingInPeriod }`
 
 ### `getPendingApprovals(wallet, fromId?, toId?)`
+
 List all pending (unexecuted, uncancelled) transactions awaiting owner approval.
 
 ### `approveTransaction(wallet, txId)` — Owner only
+
 Approve and execute a queued transaction.
 
 ### `cancelTransaction(wallet, txId)` — Owner only
+
 Cancel a queued transaction.
 
 ### `setOperator(wallet, operator, authorized)` — Owner only
+
 Add or remove an agent operator address.
 
 ### `getBudgetForecast(wallet, token?, now?)`
+
 **[MAX-ADDED]** Time-aware budget forecast — know not just what's left, but when it refills.
 
 **Returns:** `BudgetForecast` — includes `remainingInPeriod`, `secondsUntilReset`, `utilizationPercent`, full period metadata.
@@ -133,9 +156,10 @@ Add or remove an agent operator address.
 ```typescript
 const forecast = await getBudgetForecast(wallet, NATIVE_TOKEN);
 console.log(`${forecast.utilizationPercent}% used, resets in ${forecast.secondsUntilReset}s`);
-```
+```text
 
 ### `getWalletHealth(wallet, operators?, tokens?, now?)`
+
 **[MAX-ADDED]** Single-call diagnostic snapshot for agent self-monitoring.
 
 **Returns:** `WalletHealth` — address, NFT binding, operator epoch, active operator statuses, pending queue depth, budget forecasts.
@@ -144,9 +168,10 @@ console.log(`${forecast.utilizationPercent}% used, resets in ${forecast.secondsU
 const health = await getWalletHealth(wallet, [agentHotWallet], [NATIVE_TOKEN, usdcAddress]);
 if (health.pendingQueueDepth > 5) console.warn('Queue backing up!');
 if (!health.activeOperators[0].active) console.error('Agent operator deactivated!');
-```
+```text
 
 ### `batchAgentTransfer(wallet, transfers)`
+
 **[MAX-ADDED]** Execute multiple token transfers sequentially — reduces boilerplate for multi-recipient payments.
 
 ```typescript
@@ -154,9 +179,10 @@ const hashes = await batchAgentTransfer(wallet, [
   { token: USDC, to: serviceA, amount: 100n },
   { token: USDC, to: serviceB, amount: 200n },
 ]);
-```
+```text
 
 ### `getActivityHistory(wallet, { fromBlock?, toBlock? })`
+
 **[MAX-ADDED]** Query on-chain event history for self-auditing — no external indexer needed.
 
 **Returns:** `ActivityEntry[]` — sorted by block number, covers executions, queued txs, approvals, cancellations, policy updates, operator changes.
@@ -166,7 +192,7 @@ const history = await getActivityHistory(wallet, { fromBlock: 10000n });
 for (const entry of history) {
   console.log(`[${entry.type}] block ${entry.blockNumber}: ${JSON.stringify(entry.args)}`);
 }
-```
+```text
 
 ## Supported Chains
 
@@ -207,7 +233,7 @@ const data = await response.json();
 //   - Checked your budget (client-side + on-chain)
 //   - Paid USDC via your AgentWallet contract
 //   - Retried the request with payment proof
-```
+```text
 
 ### Drop-in Fetch Replacement
 
@@ -218,7 +244,7 @@ const x402Fetch = createX402Fetch(wallet, { globalDailyLimit: 100_000_000n });
 
 // Use exactly like fetch()
 const res = await x402Fetch('https://any-x402-api.com/endpoint');
-```
+```text
 
 ### Budget Controls
 
@@ -236,7 +262,7 @@ client.budgetTracker.setServiceBudget({
   maxPerRequest: 2_000_000n,
   dailyLimit: 20_000_000n,
 });
-```
+```text
 
 ### Payment Approval Callback
 
@@ -250,11 +276,11 @@ const client = createX402Client(wallet, {
     console.log(`Paid ${log.amount} via tx ${log.txHash}`);
   },
 });
-```
+```text
 
 ### How x402 Works
 
-```
+```text
 Agent → GET /api/data → Server returns 402 + PAYMENT-REQUIRED header
   ↓
 Client parses payment requirements (amount, token, recipient, network)
@@ -266,7 +292,7 @@ AgentWallet executes USDC transfer on Base
 Client retries request with X-PAYMENT header (payment proof)
   ↓
 Server verifies payment → returns 200 + data
-```
+```text
 
 Your agent's keys never leave the non-custodial wallet. All payments respect on-chain spend limits set by the wallet owner.
 
@@ -275,6 +301,7 @@ Your agent's keys never leave the non-custodial wallet. All payments respect on-
 Give your AI agent a portable, censorship-resistant identity on Ethereum via [ERC-8004 Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004).
 
 ERC-8004 provides three things:
+
 - **Identity Registry** — ERC-721 NFT that resolves to an agent's registration file (name, description, services, capabilities)
 - **Reputation Registry** — On-chain feedback signals (composable scoring)
 - **Validation Registry** — Hooks for stakers, zkML verifiers, and TEE oracles
@@ -324,21 +351,21 @@ console.log(agentData.owner);                      // NFT owner address
 // Validate a registration file before publishing
 const errors = validateRegistrationFile(agentData.registrationFile!);
 if (errors.length === 0) console.log('Valid ERC-8004 registration ✅');
-```
+```text
 
 ### Agent Registry Identifier
 
 Each agent is globally identified by a namespaced string:
 
-```
+```text
 eip155:8453:0xRegistryAddress  ← namespace:chainId:contractAddress
-```
+```text
 
 ```typescript
 import { formatAgentRegistry } from '@agentwallet/sdk';
 const id = formatAgentRegistry(8453, '0xYOUR_REGISTRY');
 // → "eip155:8453:0xYOUR_REGISTRY"
-```
+```text
 
 ### Fully On-Chain Storage (No IPFS Required)
 
@@ -351,7 +378,7 @@ const uri = buildDataURI({ name: 'MyAgent', description: '...', type: '...' });
 
 // Decode it back
 const file = parseDataURI(uri);
-```
+```text
 
 ---
 

package/dist/bridge/abis.d.ts

@@ -0,0 +1,187 @@
+/**
+ * CCTP V2 TokenMessengerV2 ABI (source chain)
+ * Key function: depositForBurn — burns USDC and emits a MessageSent event
+ */
+export declare const TokenMessengerV2Abi: readonly [{
+    readonly name: "depositForBurn";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "destinationDomain";
+        readonly type: "uint32";
+    }, {
+        readonly name: "mintRecipient";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "burnToken";
+        readonly type: "address";
+    }, {
+        readonly name: "destinationCaller";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "maxFee";
+        readonly type: "uint256";
+    }, {
+        readonly name: "minFinalityThreshold";
+        readonly type: "uint32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "nonce";
+        readonly type: "uint64";
+    }];
+}, {
+    readonly name: "depositForBurnWithHook";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "destinationDomain";
+        readonly type: "uint32";
+    }, {
+        readonly name: "mintRecipient";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "burnToken";
+        readonly type: "address";
+    }, {
+        readonly name: "destinationCaller";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "maxFee";
+        readonly type: "uint256";
+    }, {
+        readonly name: "minFinalityThreshold";
+        readonly type: "uint32";
+    }, {
+        readonly name: "hookData";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "nonce";
+        readonly type: "uint64";
+    }];
+}, {
+    readonly name: "localMessageTransmitter";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "localDomain";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint32";
+    }];
+}];
+/**
+ * CCTP V2 MessageTransmitterV2 ABI (destination chain)
+ * Key function: receiveMessage — mints USDC using attested message
+ */
+export declare const MessageTransmitterV2Abi: readonly [{
+    readonly name: "receiveMessage";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "message";
+        readonly type: "bytes";
+    }, {
+        readonly name: "attestation";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "success";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "usedNonces";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "localDomain";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint32";
+    }];
+}];
+/**
+ * Minimal ERC20 ABI — approve + allowance + balanceOf
+ */
+export declare const ERC20BridgeAbi: readonly [{
+    readonly name: "approve";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "allowance";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}];
+/**
+ * MessageTransmitter MessageSent event ABI — emitted during depositForBurn
+ * Used to extract the CCTP message bytes and hash for attestation polling.
+ */
+export declare const MessageSentEventAbi: readonly [{
+    readonly name: "MessageSent";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "message";
+        readonly type: "bytes";
+        readonly indexed: false;
+    }];
+}];
+//# sourceMappingURL=abis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abis.d.ts","sourceRoot":"","sources":["../../src/bridge/abis.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8CtB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyB1B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BjB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;EAQtB,CAAC"}

package/dist/bridge/abis.js

@@ -0,0 +1,129 @@
+// [MAX-ADDED] CCTP V2 Contract ABIs — Circle Cross-Chain Transfer Protocol V2
+// Sources: https://developers.circle.com/stablecoins/cctp-protocol-contract
+/**
+ * CCTP V2 TokenMessengerV2 ABI (source chain)
+ * Key function: depositForBurn — burns USDC and emits a MessageSent event
+ */
+export const TokenMessengerV2Abi = [
+    {
+        name: 'depositForBurn',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'amount', type: 'uint256' },
+            { name: 'destinationDomain', type: 'uint32' },
+            { name: 'mintRecipient', type: 'bytes32' },
+            { name: 'burnToken', type: 'address' },
+            { name: 'destinationCaller', type: 'bytes32' },
+            { name: 'maxFee', type: 'uint256' },
+            { name: 'minFinalityThreshold', type: 'uint32' },
+        ],
+        outputs: [{ name: 'nonce', type: 'uint64' }],
+    },
+    {
+        name: 'depositForBurnWithHook',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'amount', type: 'uint256' },
+            { name: 'destinationDomain', type: 'uint32' },
+            { name: 'mintRecipient', type: 'bytes32' },
+            { name: 'burnToken', type: 'address' },
+            { name: 'destinationCaller', type: 'bytes32' },
+            { name: 'maxFee', type: 'uint256' },
+            { name: 'minFinalityThreshold', type: 'uint32' },
+            { name: 'hookData', type: 'bytes' },
+        ],
+        outputs: [{ name: 'nonce', type: 'uint64' }],
+    },
+    {
+        name: 'localMessageTransmitter',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'address' }],
+    },
+    {
+        name: 'localDomain',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'uint32' }],
+    },
+];
+/**
+ * CCTP V2 MessageTransmitterV2 ABI (destination chain)
+ * Key function: receiveMessage — mints USDC using attested message
+ */
+export const MessageTransmitterV2Abi = [
+    {
+        name: 'receiveMessage',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'message', type: 'bytes' },
+            { name: 'attestation', type: 'bytes' },
+        ],
+        outputs: [{ name: 'success', type: 'bool' }],
+    },
+    {
+        name: 'usedNonces',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: '', type: 'bytes32' }],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+    {
+        name: 'localDomain',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'uint32' }],
+    },
+];
+/**
+ * Minimal ERC20 ABI — approve + allowance + balanceOf
+ */
+export const ERC20BridgeAbi = [
+    {
+        name: 'approve',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'spender', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+    {
+        name: 'allowance',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'owner', type: 'address' },
+            { name: 'spender', type: 'address' },
+        ],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+    {
+        name: 'balanceOf',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: 'account', type: 'address' }],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+];
+/**
+ * MessageTransmitter MessageSent event ABI — emitted during depositForBurn
+ * Used to extract the CCTP message bytes and hash for attestation polling.
+ */
+export const MessageSentEventAbi = [
+    {
+        name: 'MessageSent',
+        type: 'event',
+        inputs: [
+            { name: 'message', type: 'bytes', indexed: false },
+        ],
+    },
+];
+//# sourceMappingURL=abis.js.map

package/dist/bridge/abis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abis.js","sourceRoot":"","sources":["../../src/bridge/abis.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4EAA4E;AAE5E;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC;QACE,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;YACnC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7C,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE;YAC1C,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;YACtC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,EAAE;YAC9C,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;YACnC,EAAE,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,QAAQ,EAAE;SACjD;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;KAC7C;IACD;QACE,IAAI,EAAE,wBAAwB;QAC9B,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;YACnC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7C,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE;YAC1C,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;YACtC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,EAAE;YAC9C,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;YACnC,EAAE,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,QAAQ,EAAE;YAChD,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE;SACpC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;KAC7C;IACD;QACE,IAAI,EAAE,yBAAyB;QAC/B,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;KACxC;CACO,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC;QACE,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE;YAClC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE;SACvC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KAC7C;IACD;QACE,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACvC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;KACxC;CACO,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B;QACE,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;SACpC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACtC;IACD;QACE,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;YAClC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;SACrC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;CACO,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE;SACnD;KACF;CACO,CAAC"}

package/dist/bridge/client.d.ts

@@ -0,0 +1,106 @@
+import { type Hash, type Hex, type WalletClient } from 'viem';
+import type { BridgeChain, BridgeOptions, BurnResult, BridgeResult } from './types.js';
+import { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD } from './types.js';
+/**
+ * BridgeModule — CCTP V2 cross-chain USDC bridge.
+ *
+ * Usage:
+ * ```ts
+ * const bridge = new BridgeModule(walletClient, 'base', { rpcUrl: '...' });
+ * const result = await bridge.bridge(1_000_000n, 'optimism');
+ * console.log('Minted on Optimism:', result.mintTxHash);
+ * ```
+ */
+export declare class BridgeModule {
+    private readonly walletClient;
+    private readonly publicClient;
+    private readonly fromChain;
+    private readonly fromRpcUrl;
+    constructor(walletClient: WalletClient, fromChain?: BridgeChain, options?: {
+        rpcUrl?: string;
+    });
+    /**
+     * Bridge USDC from the source chain to the destination chain.
+     *
+     * This is the primary method. It orchestrates the full CCTP V2 flow:
+     * approve → burn → attest → mint.
+     *
+     * @param amount - Amount in USDC base units (6 decimals). e.g. 1_000_000n = 1 USDC
+     * @param toChain - Destination chain ('ethereum' | 'optimism' | 'arbitrum')
+     * @param options - Optional overrides (finality, fees, destination address)
+     *
+     * @throws BridgeError with actionable message if anything fails
+     */
+    bridge(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BridgeResult>;
+    /**
+     * Step 1 of 3: Burn USDC on the source chain.
+     * Returns the burn result including message bytes needed for minting.
+     * Use this for manual/split-phase bridging.
+     */
+    burn(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BurnResult>;
+    /**
+     * Step 2 of 3: Poll Circle IRIS API for attestation.
+     * Returns the attestation bytes once Circle confirms the message.
+     */
+    waitForAttestation(messageHash: Hex, apiUrl?: string): Promise<Hex>;
+    /**
+     * Step 3 of 3: Mint USDC on the destination chain using the attestation.
+     */
+    mint(messageBytes: Hex, attestation: Hex, toChain: BridgeChain, destinationRpcUrl?: string): Promise<Hash>;
+    /**
+     * Fetch the current USDC balance on the source chain for the signer's address.
+     */
+    getUsdcBalance(): Promise<bigint>;
+    /**
+     * Fetch the current USDC allowance for the TokenMessengerV2 on source chain.
+     */
+    getUsdcAllowance(): Promise<bigint>;
+    /**
+     * Approve TokenMessengerV2 to spend USDC on behalf of the signer.
+     * Skips if existing allowance is sufficient.
+     */
+    private approveUsdc;
+    /**
+     * Call TokenMessengerV2.depositForBurn and extract MessageSent data.
+     */
+    private depositForBurn;
+    /**
+     * Extract the CCTP MessageSent event from a transaction receipt.
+     * The MessageTransmitter emits this event during depositForBurn.
+     */
+    private extractMessageSent;
+    /**
+     * Poll the Circle IRIS API until the attestation is ready.
+     * Fast finality: ~12 seconds. Full finality: ~15 minutes on Ethereum.
+     */
+    private pollForAttestation;
+    /**
+     * Call MessageTransmitterV2.receiveMessage on the destination chain to mint USDC.
+     */
+    private receiveMessage;
+    private validateBridgeParams;
+    private sleep;
+}
+/**
+ * Structured bridge error with actionable messages and error codes.
+ */
+export declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Create a BridgeModule from an existing AgentWallet object.
+ * Convenience wrapper for wallet.bridge() integration.
+ *
+ * @example
+ * ```ts
+ * const bridge = createBridge(wallet.walletClient, 'base', { rpcUrl: BASE_RPC });
+ * const result = await bridge.bridge(5_000_000n, 'optimism');
+ * ```
+ */
+export declare function createBridge(walletClient: WalletClient, fromChain?: BridgeChain, options?: {
+    rpcUrl?: string;
+}): BridgeModule;
+export type { BridgeChain, BridgeOptions, BurnResult, BridgeResult };
+export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD, };
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bridge/client.ts"],"names":[],"mappings":"AAYA,OAAO,EASL,KAAK,IAAI,EACT,KAAK,GAAG,EAER,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AAQd,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EAGb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAG9C,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAsBnC;;;;;;;;;;;OAWG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC;IAmDxB;;;;OAIG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC;IAYtB;;;OAGG;IACG,kBAAkB,CACtB,WAAW,EAAE,GAAG,EAChB,MAAM,GAAE,MAA+B,GACtC,OAAO,CAAC,GAAG,CAAC;IAIf;;OAEG;IACG,IAAI,CACR,YAAY,EAAE,GAAG,EACjB,WAAW,EAAE,GAAG,EAChB,OAAO,EAAE,WAAW,EACpB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC;IAIhB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAUvC;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAezC;;;OAGG;YACW,WAAW;IA2CzB;;OAEG;YACW,cAAc;IAuE5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA8C1B;;;OAGG;YACW,kBAAkB;IAmEhC;;OAEG;YACW,cAAc;IAsD5B,OAAO,CAAC,oBAAoB;IA6B5B,OAAO,CAAC,KAAK;CAGd;AAID;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAElB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAID;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,YAAY,CAEd;AAGD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACrE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,CAAC"}