agentwallet-sdk 5.0.0 → 5.0.2

package/dist/ap2/index.js

@@ -0,0 +1,255 @@
+/**
+ * AP2Client — ISO 20022 / AP2 European Payment Module for agentwallet-sdk
+ *
+ * Non-custodial AI agent bridge for AP2 payments:
+ *   - Parse ISO 20022 pacs.008 XML → bridge quote
+ *   - Sign x402 payment header locally (private key never leaves agent)
+ *   - Execute USDC → EUR settlement via CCTP V2 (Base → EUR off-ramp)
+ *
+ * AP2 context:
+ *   Nexi + Google Cloud MoU (2026): AP2 processes ~2.9T EUR/year across Europe.
+ *   ISO 20022 is the wire standard. This module makes AI agents first-class
+ *   European payment participants — non-custodially.
+ *
+ * @module ap2
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** USDC decimals (6) */
+const USDC_DECIMALS = 6n;
+const USDC_MULTIPLIER = 10n ** USDC_DECIMALS;
+/** EUR → USDC rate (fallback; production uses Chainlink oracle) */
+const EUR_TO_USDC_RATE = 1.08;
+/** Default facilitator URL */
+const DEFAULT_FACILITATOR_URL = 'http://localhost:8420';
+/** Estimated CCTP V2 settlement time (~20 min) */
+const ESTIMATED_SETTLEMENT_SECONDS = 1200;
+// ---------------------------------------------------------------------------
+// ISO 20022 pacs.008 XML Builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a valid ISO 20022 pacs.008 (FIToFICstmrCdtTrf) XML string
+ * from simple agent-friendly parameters.
+ *
+ * @param params - Payment parameters
+ * @returns ISO 20022 pacs.008 XML string
+ */
+function buildPacs008(params) {
+    const now = params.creationDateTime ?? new Date().toISOString().replace(/\.\d+Z$/, '+00:00');
+    const currency = params.currency ?? 'EUR';
+    const e2eId = params.endToEndId ?? params.messageId;
+    const amount = params.amount.toFixed(2);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
+  <FIToFICstmrCdtTrf>
+    <GrpHdr>
+      <MsgId>${escapeXml(params.messageId)}</MsgId>
+      <CreDtTm>${escapeXml(now)}</CreDtTm>
+      <NbOfTxs>1</NbOfTxs>
+      <SttlmInf>
+        <SttlmMtd>CLRG</SttlmMtd>
+      </SttlmInf>
+    </GrpHdr>
+    <CdtTrfTxInf>
+      <PmtId>
+        <EndToEndId>${escapeXml(e2eId)}</EndToEndId>
+      </PmtId>
+      <IntrBkSttlmAmt Ccy="${escapeXml(currency)}">${amount}</IntrBkSttlmAmt>
+      <ChrgBr>SHAR</ChrgBr>
+      <Dbtr>
+        <Nm>${escapeXml(params.debtorName)}</Nm>
+      </Dbtr>
+      <DbtrAcct>
+        <Id>
+          <IBAN>${escapeXml(params.debtorIban.replace(/\s/g, '').toUpperCase())}</IBAN>
+        </Id>
+      </DbtrAcct>
+      <DbtrAgt>
+        <FinInstnId>
+          <BICFI>${escapeXml(params.debtorBic.toUpperCase())}</BICFI>
+        </FinInstnId>
+      </DbtrAgt>
+      <Cdtr>
+        <Nm>${escapeXml(params.creditorName)}</Nm>
+      </Cdtr>
+      <CdtrAcct>
+        <Id>
+          <IBAN>${escapeXml(params.creditorIban.replace(/\s/g, '').toUpperCase())}</IBAN>
+        </Id>
+      </CdtrAcct>
+      <CdtrAgt>
+        <FinInstnId>
+          <BICFI>${escapeXml(params.creditorBic.toUpperCase())}</BICFI>
+        </FinInstnId>
+      </CdtrAgt>${params.purposeCode ? `
+      <Purp>
+        <Cd>${escapeXml(params.purposeCode)}</Cd>
+      </Purp>` : ''}${params.remittanceInfo ? `
+      <RmtInf>
+        <Ustrd>${escapeXml(params.remittanceInfo)}</Ustrd>
+      </RmtInf>` : ''}
+    </CdtTrfTxInf>
+  </FIToFICstmrCdtTrf>
+</Document>`;
+}
+/** Escape XML special characters. */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/** Convert a decimal USDC string to bigint μUSDC. */
+function usdcToBigInt(usdcStr) {
+    const [whole, frac = ''] = usdcStr.split('.');
+    const fracPadded = frac.padEnd(Number(USDC_DECIMALS), '0').slice(0, Number(USDC_DECIMALS));
+    return BigInt(whole) * USDC_MULTIPLIER + BigInt(fracPadded);
+}
+// ---------------------------------------------------------------------------
+// AP2Client
+// ---------------------------------------------------------------------------
+/**
+ * AP2Client — Non-custodial ISO 20022 / AP2 payment client for AI agents.
+ *
+ * Connects to the AP2 facilitator (ap2_handler.py FastAPI service) to
+ * get bridge quotes and execute payments via CCTP V2 / x402.
+ *
+ * @example
+ * ```typescript
+ * const client = new AP2Client({ facilitatorUrl: 'http://localhost:8420' });
+ *
+ * const xml = AP2Client.buildPacs008({
+ *   messageId: 'MSG-2026-0001',
+ *   amount: 1000,
+ *   debtorName: 'Agent Zero',
+ *   debtorIban: 'DE89370400440532013000',
+ *   debtorBic: 'COBADEFFXXX',
+ *   creditorName: 'Acme GmbH',
+ *   creditorIban: 'FR7630006000011234567890189',
+ *   creditorBic: 'BNPAFRPPXXX',
+ * });
+ *
+ * const quote = await client.quote(xml);
+ * const receipt = await client.pay(xml);
+ * ```
+ */
+export class AP2Client {
+    constructor(config = {}) {
+        this.facilitatorUrl = (config.facilitatorUrl ?? DEFAULT_FACILITATOR_URL).replace(/\/$/, '');
+    }
+    /**
+     * Parse ISO 20022 pacs.008 XML and get a bridge quote from the facilitator.
+     *
+     * @param iso20022Xml - Raw pacs.008 XML string
+     * @returns AP2Quote with USDC amounts and x402 calldata
+     * @throws Error if the facilitator returns an error or the XML is invalid
+     */
+    async quote(iso20022Xml) {
+        const response = await fetch(`${this.facilitatorUrl}/ap2/payment`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/xml' },
+            body: iso20022Xml,
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new AP2Error(`Quote failed (${response.status}): ${body}`);
+        }
+        const json = (await response.json());
+        const bq = json.bridge_quote;
+        const payment = json.payment;
+        return {
+            messageId: payment.message_id,
+            creditorIban: payment.creditor.iban,
+            amountEur: parseFloat(payment.amount),
+            usdcRequired: usdcToBigInt(bq.usdc_amount),
+            bridgeFeeUsdc: usdcToBigInt(bq.bridge_fee_usdc),
+            estimatedSettlementSeconds: ESTIMATED_SETTLEMENT_SECONDS,
+            x402PaymentHeader: bq.x402_payment_header,
+            agentWalletCalldata: bq.agent_wallet_calldata,
+            expiresAt: bq.expires_at,
+        };
+    }
+    /**
+     * Execute the full AP2 payment: sign x402 header + bridge USDC + settle.
+     *
+     * Calls the /ap2/execute endpoint on the facilitator, which:
+     *   1. Parses the XML
+     *   2. Signs x402 header with agent's private key (server-side in this flow)
+     *   3. Submits USDC to CCTP V2 bridge
+     *   4. Returns receipt
+     *
+     * @param iso20022Xml - Raw pacs.008 XML string
+     * @returns AP2Receipt with txHash and SEPA reference
+     * @throws AP2Error on execution failure
+     */
+    async pay(iso20022Xml) {
+        const response = await fetch(`${this.facilitatorUrl}/ap2/execute`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/xml' },
+            body: iso20022Xml,
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new AP2Error(`Execution failed (${response.status}): ${body}`);
+        }
+        const json = (await response.json());
+        const r = json.receipt;
+        return {
+            messageId: r.message_id,
+            txHash: r.tx_hash,
+            usdcBridged: usdcToBigInt(r.usdc_bridged),
+            sepaReference: r.sepa_reference,
+            status: r.status,
+            dryRun: r.dry_run,
+            x402Signature: r.x402_signature,
+            agentAddress: r.agent_address,
+            nonce: r.nonce,
+            executedAt: r.executed_at,
+            creditorIban: r.creditor_iban,
+            bridgeFeeUsdc: usdcToBigInt(r.bridge_fee_usdc),
+        };
+    }
+    /**
+     * Generate a valid ISO 20022 pacs.008 XML string from simple parameters.
+     *
+     * Handles XML escaping, IBAN normalization, and timestamp formatting.
+     * Makes AP2 payments agent-friendly — no ISO 20022 expertise required.
+     *
+     * @param params - Simple payment parameters
+     * @returns Valid pacs.008 XML string
+     */
+    static buildPacs008(params) {
+        return buildPacs008(params);
+    }
+    /**
+     * Estimate USDC required for a given EUR amount.
+     *
+     * Uses the default EUR/USDC rate. For accurate quotes, call quote() instead.
+     *
+     * @param amountEur - Amount in EUR
+     * @returns Estimated USDC amount as bigint (μUSDC, 6 decimals)
+     */
+    static estimateUsdc(amountEur) {
+        const usdc = amountEur * EUR_TO_USDC_RATE;
+        return BigInt(Math.round(usdc * Number(USDC_MULTIPLIER)));
+    }
+}
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+/** AP2-specific error with structured context. */
+export class AP2Error extends Error {
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'AP2Error';
+    }
+}
+// ---------------------------------------------------------------------------
+// Re-export builder as standalone function
+// ---------------------------------------------------------------------------
+export { buildPacs008 };
+//# sourceMappingURL=index.js.map

package/dist/ap2/index.js.map

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

package/dist/bridge/abis.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CCTP V2 TokenMessengerV2 ABI (source chain)
+ * Key function: depositForBurn — burns USDC and emits a MessageSent event
+ */
+export declare const TokenMessengerV2Abi: {
+    name: string;
+    type: string;
+    stateMutability: string;
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+}[];
+/**
+ * CCTP V2 MessageTransmitterV2 ABI (destination chain)
+ * Key function: receiveMessage — mints USDC using attested message
+ */
+export declare const MessageTransmitterV2Abi: {
+    name: string;
+    type: string;
+    stateMutability: string;
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+}[];
+/**
+ * Minimal ERC20 ABI — approve + allowance + balanceOf
+ */
+export declare const ERC20BridgeAbi: {
+    name: string;
+    type: string;
+    stateMutability: string;
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+}[];
+/**
+ * MessageTransmitter MessageSent event ABI — emitted during depositForBurn
+ * Used to extract the CCTP message bytes and hash for attestation polling.
+ */
+export declare const MessageSentEventAbi: {
+    name: string;
+    type: string;
+    inputs: {
+        name: string;
+        type: string;
+        indexed: boolean;
+    }[];
+}[];
+//# 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":"AAEA;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;GA8C/B,CAAC;AACF;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;GAyBnC,CAAC;AACF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;GA4B1B,CAAC;AACF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;GAQ/B,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":"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"}

package/dist/bridge/client.d.ts

@@ -0,0 +1,35 @@
+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';
+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(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BridgeResult>;
+    burn(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BurnResult>;
+    waitForAttestation(messageHash: Hex, apiUrl?: string): Promise<Hex>;
+    mint(messageBytes: Hex, attestation: Hex, toChain: BridgeChain, destinationRpcUrl?: string): Promise<Hash>;
+    getUsdcBalance(): Promise<bigint>;
+    getUsdcAllowance(): Promise<bigint>;
+    private approveUsdc;
+    private depositForBurn;
+    private extractMessageSent;
+    private pollForAttestation;
+    private receiveMessage;
+    private validateBridgeParams;
+    private sleep;
+}
+export declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+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":"AAEA,OAAO,EAML,KAAK,IAAI,EACT,KAAK,GAAG,EAER,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AAOd,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAmBpB,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;IAiB7B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IA0BhG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;IAU5F,kBAAkB,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,GAAE,MAA+B,GAAG,OAAO,CAAC,GAAG,CAAC;IAI3F,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1G,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAUjC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;YAU3B,WAAW;YAuBX,cAAc;IAwC5B,OAAO,CAAC,kBAAkB;YAqBZ,kBAAkB;YA8BlB,cAAc;IA2B5B,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,KAAK;CAGd;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,wBAAgB,YAAY,CAC1B,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,YAAY,CAEd;AAED,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACrE,OAAO,EACL,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAChD,kBAAkB,EAAE,sBAAsB,EAAE,kBAAkB,GAC/D,CAAC"}