@lendasat/lendaswap-sdk-pure 0.2.8 → 0.2.10

package/README.md

@@ -15,28 +15,19 @@ This SDK supports the following swap directions:
 
 ### BTC to EVM
 
-| Source       | Target                      | Status    |
-| ------------ | --------------------------- | --------- |
-| Lightning    | Polygon (USDC, USDT)        | Supported |
-| Lightning    | Arbitrum (USDC, USDT)       | Supported |
-| Lightning    | Ethereum (USDC, USDT, WBTC) | Supported |
-| Arkade       | Polygon (USDC, USDT)        | Supported |
-| Arkade       | Arbitrum (USDC, USDT)       | Supported |
-| Arkade       | Ethereum (USDC, USDT, WBTC) | Supported |
-| On-chain BTC | Polygon (USDC, USDT)        | Supported |
-| On-chain BTC | Arbitrum (USDC, USDT)       | Supported |
-| On-chain BTC | Ethereum (USDC, USDT, WBTC) | Supported |
+| Source    | Target                      | Status    |
+| --------- | --------------------------- | --------- |
+| Lightning | Ethereum, Polygon, Arbitrum | Supported |
+| Arkade    | Ethereum, Polygon, Arbitrum | Supported |
+| On-chain  | Ethereum, Polygon, Arbitrum | Supported |
 
 ### EVM to BTC
 
 | Source                      | Target    | Status    |
 | --------------------------- | --------- | --------- |
-| Polygon (USDC, USDT)        | Arkade    | Supported |
-| Polygon (USDC, USDT)        | Lightning | Supported |
-| Arbitrum (USDC, USDT)       | Arkade    | Supported |
-| Arbitrum (USDC, USDT)       | Lightning | Supported |
-| Ethereum (USDC, USDT, WBTC) | Arkade    | Supported |
-| Ethereum (USDC, USDT, WBTC) | Lightning | Supported |
+| Polygon, Arbitrus, Ethereum | Arkade    | Supported |
+| Polygon, Arbitrus, Ethereum | Lightning | Supported |
+| Polygon, Arbitrus, Ethereum | On-chain  | Supported |
 
 **Refund support:**
 
@@ -50,13 +41,12 @@ This SDK supports the following swap directions:
 ### Setup
 
 ```typescript
-import { Client, IdbWalletStorage, IdbSwapStorage } from "@lendasat/lendaswap-sdk-pure";
+import {Client, IdbWalletStorage, IdbSwapStorage} from "@lendasat/lendaswap-sdk-pure";
 
 // Create a client with persistent storage (browser)
 const client = await Client.builder()
   .withSignerStorage(new IdbWalletStorage())
   .withSwapStorage(new IdbSwapStorage())
-  .withApiKey("your-api-key")
   .build();
 
 // Or import an existing wallet
@@ -70,290 +60,178 @@ const client = await Client.builder()
 const mnemonic = client.getMnemonic();
 ```
 
-### Get a Quote
+### Quotes
 
 ```typescript
-// Get available asset pairs
-const pairs = await client.getAssetPairs();
-
-// Get a quote for swapping 100k sats to USDC on Polygon
-const quote = await client.getQuote("btc_arkade", "usdc_pol", 100000);
+import { Asset } from "@lendasat/lendaswap-sdk-pure";
+
+const quote = await client.getQuote({
+  sourceChain: Asset.BTC_ARKADE.chain,      // "Arkade"
+  sourceToken: Asset.BTC_ARKADE.tokenId,    // "btc"
+  targetChain: Asset.USDC_POLYGON.chain,    // "137"
+  targetToken: Asset.USDC_POLYGON.tokenId,  // "0x3c499c..."
+  sourceAmount: 100_000,                    // sats
+});
 console.log(`You'll receive: ${quote.target_amount} USDC`);
 ```
 
 ### Create a Swap
 
-#### Lightning to EVM
+Use `createSwap` for all swap directions. The SDK routes automatically based on the source/target asset:
 
 ```typescript
-const result = await client.createLightningToEvmSwapGeneric({
-  targetAddress: "0x1234567890abcdef1234567890abcdef12345678",
-  tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
-  evmChainId: 137,             // 1 (Ethereum), 137 (Polygon), 42161 (Arbitrum)
-  amountIn: 100000,            // Amount in sats (or use amountOut for target amount)
+// BTC → EVM: Arkade to USDC on Polygon
+const result = await client.createSwap({
+  source: Asset.BTC_ARKADE,
+  target: Asset.USDC_POLYGON,
+  sourceAmount: 100_000,         // sats
+  targetAddress: "0x...",        // your EVM address
 });
 
-// Pay the Lightning invoice to complete the swap
-console.log(`Pay this invoice: ${result.response.bolt11_invoice}`);
-console.log(`Swap ID: ${result.response.id}`);
-```
-
-#### Arkade to EVM
+// EVM → BTC: USDC on Polygon to Arkade
+const result = await client.createSwap({
+  source: Asset.USDC_POLYGON,
+  target: Asset.BTC_ARKADE,
+  sourceAmount: 10_000_000,      // 10 USDC (6 decimals)
+  targetAddress: "ark1...",      // your Arkade address
+  userAddress: "0x...",          // your EVM wallet address (required for EVM-sourced swaps)
+});
 
-```typescript
-// Create an Arkade-to-EVM swap (any ERC-20 token via 1inch)
-const result = await client.createArkadeToEvmSwapGeneric({
-  targetAddress: "0x1234567890abcdef1234567890abcdef12345678",
-  tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
-  evmChainId: 137,
-  sourceAmount: 100000, // sats
+// Or use any token by chain + contract address
+const result = await client.createSwap({
+  source: { chain: "42161", tokenId: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" }, // USDC on Arbitrum
+  target: Asset.BTC_LIGHTNING,
+  targetAddress: "lnbc...",      // BOLT11 invoice
 });
 
-// Send BTC to the Arkade VHTLC address
-console.log(`Send BTC to: ${result.response.btc_vhtlc_address}`);
-console.log(`Swap ID: ${result.response.id}`);
-
-// Once the server has funded the EVM HTLC (status: "serverfunded"),
-// claim gaslessly — the server submits the tx on your behalf:
-const claimResult = await client.claimViaGasless(
-  result.response.id,
-  async (digest) => {
-    // Sign the EIP-712 digest with your EVM wallet
-    // e.g. using ethers.js: wallet.signMessage(ethers.getBytes(digest))
-    return { v: 27, r: "0x...", s: "0x..." };
-  },
-  "0x1234567890abcdef1234567890abcdef12345678", // destination
-);
-console.log(`Claimed! TX: ${claimResult.txHash}`);
+const swapId = result.response.id;
 ```
 
-#### On-chain BTC to EVM
+### Fund EVM-Sourced Swaps
+
+EVM-sourced swaps need to be funded after creation. The SDK handles the full Permit2 flow (allowance check, ERC-20
+approval, EIP-712 signing, transaction submission) in a single call:
 
 ```typescript
-const result = await client.createBitcoinToEvmSwap({
-  targetAddress: "0x1234567890abcdef1234567890abcdef12345678",
-  tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
-  evmChainId: 137,
-  sourceAmount: 100000, // sats
-});
+// Fund with an external wallet
+const {txHash} = await client.fundSwap(swapId, signer);
 
-// Send BTC to the on-chain HTLC address
-console.log(`Send BTC to: ${result.response.btc_htlc_address}`);
-console.log(`Swap ID: ${result.response.id}`);
+// Or fund gaslessly (SDK signs internally, server submits via relay)
+const {txHash} = await client.fundSwapGasless(swapId);
 ```
 
-#### EVM to Arkade
+### The EvmSigner Interface
 
-```typescript
-const result = await client.createEvmToArkadeSwapGeneric({
-  targetAddress: "ark1...",      // Your Arkade address
-  tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
-  evmChainId: 137,
-  userAddress: "0x...",          // Your EVM wallet address
-  sourceAmount: 100000000n,      // Amount in token's smallest unit (e.g., 6 decimals for USDC)
-});
+`EvmSigner` is a minimal wallet abstraction. Implement it once for your stack — the SDK stays free of EVM library
+dependencies:
 
-// Fund the EVM HTLC via coordinator
-console.log(`Swap ID: ${result.response.id}`);
+```typescript
+import type {EvmSigner} from "@lendasat/lendaswap-sdk-pure";
 ```
 
-#### EVM to Lightning
+**wagmi / viem:**
 
 ```typescript
-const result = await client.createEvmToLightningSwapGeneric({
-  lightningInvoice: "lnbc...",   // BOLT11 invoice (amount derived from invoice)
-  tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
-  evmChainId: 137,
-  userAddress: "0x...",          // Your EVM wallet address
-});
-
-// Fund the EVM HTLC via coordinator
-console.log(`Swap ID: ${result.response.id}`);
+import {createPublicClient, http} from "viem";
+
+const publicClient = createPublicClient({chain, transport: http()});
+
+const signer: EvmSigner = {
+  address: walletClient.account.address,
+  chainId: chain.id,
+  signTypedData: (td) =>
+    walletClient.signTypedData({...td, account: walletClient.account}),
+  sendTransaction: (tx) =>
+    walletClient.sendTransaction({to: tx.to, data: tx.data, chain, gas: tx.gas}),
+  waitForReceipt: (hash) =>
+    publicClient.waitForTransactionReceipt({hash}).then((r) => ({
+      status: r.status,
+      blockNumber: r.blockNumber,
+      transactionHash: r.transactionHash,
+    })),
+  getTransaction: (hash) =>
+    publicClient.getTransaction({hash}).then((tx) => ({
+      to: tx.to ?? null, input: tx.input, from: tx.from,
+    })),
+  call: (tx) =>
+    publicClient.call({to: tx.to, data: tx.data, account: tx.from, blockNumber: tx.blockNumber})
+      .then((r) => r.data ?? "0x"),
+};
 ```
 
-#### EVM to Bitcoin (on-chain)
+**ethers.js v6:**
 
 ```typescript
-const result = await client.createEvmToBitcoinSwap({
-  tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
-  evmChainId: 137,
-  userAddress: "0x...",          // Your EVM wallet address
-  targetAddress: "bc1p...",      // Your BTC address
-  sourceAmount: 100000000n,      // Amount in token's smallest unit
-});
-
-// Fund the EVM HTLC, then redeem BTC once server funds the BTC HTLC
-console.log(`Swap ID: ${result.response.id}`);
+const signer: EvmSigner = {
+  address: await wallet.getAddress(),
+  chainId: Number((await wallet.provider.getNetwork()).chainId),
+  signTypedData: (td) =>
+    wallet.signTypedData(td.domain, td.types, td.message),
+  sendTransaction: (tx) =>
+    wallet.sendTransaction({to: tx.to, data: tx.data, gasLimit: tx.gas})
+      .then((r) => r.hash),
+  waitForReceipt: (hash) =>
+    wallet.provider.waitForTransaction(hash).then((r) => ({
+        status: r.status === 1 ? "success" : "reverted",
+        blockNumber: BigInt(r.blockNumber),
+        transactionHash: r.hash,
+      })
+    ),
+  getTransaction: (hash) =>
+    wallet.provider.getTransaction(hash).then((tx) => ({
+      to: tx.to, input: tx.data, from: tx.from,
+    })),
+  call: (tx) =>
+    wallet.provider.call({to: tx.to, data: tx.data, from: tx.from, blockTag: tx.blockNumber}),
+};
 ```
 
 ### Monitor Swap Status
 
 ```typescript
-// Get current swap status
-const swap = await client.getSwap("swap-uuid");
+const swap = await client.getSwap(swapId);
 console.log(`Status: ${swap.status}`);
 
-// Status flow: pending -> clientfunded -> serverfunded -> clientredeemed -> serverredeemed
+// Status flow: pending → clientfunded → serverfunded → clientredeemed → serverredeemed
 ```
 
-### Claim EVM Tokens
+### Claim
 
-Once the server has funded the EVM HTLC (`serverfunded` status), claim your tokens:
+For BTC-to-EVM swaps, once the server has funded the EVM HTLC (`serverfunded`), claim your tokens:
 
 ```typescript
-// Gasless claim for Arkade-to-EVM swaps — the server submits the tx
-const claimResult = await client.claimViaGasless(
-  "swap-uuid",
-  async (digest) => {
-    // Sign the EIP-712 digest with your EVM wallet
-    return { v: 27, r: "0x...", s: "0x..." };
-  },
-  "0xYourDestinationAddress",
-);
-console.log(`Claim tx: ${claimResult.txHash}`);
-
-// For other swap types (Lightning/On-chain to EVM), use the existing claim:
-const result = await client.claim("swap-uuid");
+const result = await client.claim(swapId);
 ```
 
-### Refund (if swap times out)
+### Refund
 
-```typescript
-// For on-chain BTC swaps
-const refundResult = await client.refundSwap("swap-uuid", {
-  destinationAddress: "bc1q...",  // Your Bitcoin address
-  feeRateSatPerVb: 5,
-});
+If a swap times out, refund your funds:
 
-// For Arkade swaps
-const refundResult = await client.refundSwap("swap-uuid", {
-  destinationAddress: "ark1...",  // Your Arkade address
+```typescript
+// BTC swaps (on-chain or Arkade)
+const result = await client.refundSwap(swapId, {
+  destinationAddress: "bc1q...",   // or "ark1..."
 });
-```
-
-### Storage
-
-The SDK provides pluggable storage interfaces for persisting wallet and swap data.
-Browser storage uses [Dexie](https://dexie.org/) for IndexedDB access with the database name `lendaswap-v3`.
-
-**Storage Types:**
 
-- `WalletStorage` - Stores mnemonic and key derivation index
-- `SwapStorage` - Stores `StoredSwap` records (API response + client-side params)
+// EVM swaps — manual refund (after timelock expires, user pays gas)
+const {txHash} = await client.refundEvmWithSigner(swapId, signer, "direct");
 
-**StoredSwap Structure:**
+// EVM swaps — collaborative refund (instant, gasless, server cosigns)
+const {txHash} = await client.collabRefundEvmWithSigner(swapId, signer, "swap-back");
 
-Each swap is stored with both the API response and client-side parameters needed for claim/refund operations:
-
-```typescript
-interface StoredSwap {
-  version: number;        // Schema version for migrations
-  swapId: string;         // Primary key
-  keyIndex: number;       // Key derivation index
-  response: GetSwapResponse;  // Full API response
-  publicKey: string;      // Hex-encoded compressed public key
-  preimage: string;       // Hex-encoded preimage for claiming HTLCs
-  preimageHash: string;   // Hex-encoded hash lock
-  secretKey: string;      // Hex-encoded secret key for signing
-  storedAt: number;       // Timestamp when first stored
-  updatedAt: number;      // Timestamp when last updated
-}
+// EVM swaps — collaborative refund for gasless swaps (SDK signs internally)
+const {txHash} = await client.collabRefundEvmSwap(swapId, "swap-back");
 ```
 
-**Usage:**
-
-```typescript
-import {
-  InMemoryWalletStorage,
-  InMemorySwapStorage,
-  IdbWalletStorage,     // Browser only (IndexedDB via Dexie)
-  IdbSwapStorage,       // Browser only (IndexedDB via Dexie)
-  idbStorageFactory,    // Factory for creating IDB storage
-  inMemoryStorageFactory,
-  SWAP_STORAGE_VERSION,
-  type StoredSwap,
-} from "@lendasat/lendaswap-sdk-pure";
-
-// In-memory storage (for testing or temporary sessions)
-const walletStorage = new InMemoryWalletStorage();
-const swapStorage = new InMemorySwapStorage();
-
-// IndexedDB storage (for browser persistence)
-// Uses shared "lendaswap-v3" database with "wallet" and "swaps" tables
-const walletStorage = new IdbWalletStorage();
-const swapStorage = new IdbSwapStorage();
-
-// Store a swap
-await swapStorage.store({
-  version: SWAP_STORAGE_VERSION,
-  swapId: "uuid",
-  keyIndex: 0,
-  response: apiResponse,
-  publicKey: "02...",
-  preimage: "...",
-  preimageHash: "...",
-  secretKey: "...",
-  storedAt: Date.now(),
-  updatedAt: Date.now(),
-});
-
-// Update swap response (e.g., after polling for status)
-await swapStorage.update("uuid", newApiResponse);
-
-// Custom storage (implement the WalletStorage/SwapStorage interfaces)
-// For React Native, you might use AsyncStorage or SQLite
-```
+Refund mode controls what token you receive:
 
-## Development
+- `"direct"` — refund as WBTC/TBTC (the HTLC lock token)
+- `"swap-back"` — refund as the original source token (e.g., USDC) via DEX swap
 
-### Project Structure
+### Storage
 
-```
-src/
-├── api/
-│   └── client.ts              # Low-level API client wrapper
-├── generated/
-│   └── api.ts                 # Auto-generated types from OpenAPI spec
-├── create/
-│   ├── index.ts               # Swap creation exports
-│   ├── types.ts               # Type definitions for swap creation
-│   ├── arkade.ts              # Arkade-to-EVM swap creation
-│   ├── bitcoin.ts             # Bitcoin-to-EVM swap creation
-│   ├── bitcoin-to-arkade.ts   # Bitcoin-to-Arkade swap creation
-│   ├── evm-to-arkade.ts       # EVM-to-Arkade swap creation
-│   ├── evm-to-bitcoin.ts      # EVM-to-Bitcoin swap creation
-│   ├── evm-to-lightning.ts    # EVM-to-Lightning swap creation
-│   └── lightning.ts           # Lightning-to-EVM swap creation
-├── redeem/
-│   ├── index.ts               # Claim/redeem operation exports
-│   ├── arkade.ts              # Arkade claim logic
-│   ├── ethereum.ts            # Ethereum claim logic
-│   └── gasless.ts             # Gasless claim logic
-├── refund/
-│   ├── index.ts               # Refund operation exports
-│   ├── arkade.ts              # Arkade refund logic
-│   └── onchain.ts             # On-chain refund logic
-├── evm/
-│   ├── index.ts               # EVM HTLC utilities
-│   ├── coordinator.ts         # Coordinator interaction
-│   ├── htlc.ts                # HTLC contract utilities
-│   └── signing.ts             # EVM signing utilities
-├── signer/
-│   └── index.ts               # HD wallet key derivation (BIP39/BIP32)
-├── storage/
-│   ├── index.ts               # Storage interfaces and in-memory implementations
-│   ├── idb.ts                 # IndexedDB storage for browsers
-│   ├── sqlite.ts              # SQLite storage for Node.js
-│   └── types.ts               # StoredSwap type definition
-├── client.ts                  # High-level Client class with convenience methods
-├── arkade.ts                  # Arkade VHTLC query utilities
-├── delegate.ts                # Delegate settlement utilities
-├── tokens.ts                  # Token helpers and constants
-├── usd-price.ts               # USD price fetching via CoinGecko
-├── price-calculations.ts      # Price calculation utilities
-├── node.ts                    # Node.js-specific exports (SQLite storage)
-└── index.ts                   # Public exports
-```
+The SDK provides pluggable storage interfaces for persisting wallet and swap data.
+Browser storage uses [Dexie](https://dexie.org/) for IndexedDB access with the database name `lendaswap-v3`.
 
 ### Auto-generated API Types
 
@@ -402,11 +280,3 @@ When adding new functionality:
 1. **API methods**: Add convenience methods to `src/client.ts` that wrap the low-level API calls
 2. **New types**: If the backend adds new endpoints, regenerate the API types first
 3. **Exports**: Update `src/index.ts` to export any new public types or classes
-
-### Dependencies
-
-- `openapi-fetch` - Type-safe HTTP client for OpenAPI specs
-- `@noble/hashes` - Cryptographic hash functions
-- `@scure/bip32` - BIP32 HD wallet derivation
-- `@scure/bip39` - BIP39 mnemonic phrase handling
-- `dexie` - IndexedDB wrapper for browser storage

package/dist/cctp/attestation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CCTP attestation client.
+ *
+ * Polls Circle's IRIS API for attestations after a USDC burn.
+ * Used on the destination chain to call MessageTransmitter.receiveMessage().
+ */
+import { type CctpChainName } from "./constants.js";
+export interface FetchAttestationOptions {
+    /** Source chain name (e.g. "Polygon"). */
+    sourceChain: CctpChainName;
+    /** Transaction hash of the burn on the source chain. */
+    txHash: string;
+    /** IRIS API base URL. Defaults to mainnet. */
+    irisApiUrl?: string;
+    /** Polling interval in ms. Defaults to 10000 (10s). */
+    pollIntervalMs?: number;
+    /** Maximum time to wait in ms. Defaults to 900000 (15min). */
+    timeoutMs?: number;
+    /** Optional abort signal. */
+    signal?: AbortSignal;
+}
+export interface AttestationResult {
+    /** Raw CCTP message bytes (hex with 0x prefix). */
+    message: string;
+    /** Attestation signature bytes (hex with 0x prefix). */
+    attestation: string;
+}
+/**
+ * Poll the IRIS V2 API until the attestation is ready for a given burn tx.
+ *
+ * @returns The message and attestation bytes needed to call receiveMessage().
+ * @throws If the attestation is not ready within the timeout, or the request fails.
+ */
+export declare function fetchAttestation(options: FetchAttestationOptions): Promise<AttestationResult>;
+//# sourceMappingURL=attestation.d.ts.map

package/dist/cctp/attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../src/cctp/attestation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,WAAW,EAAE,aAAa,CAAC;IAC3B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CA4D5B"}

package/dist/cctp/attestation.js

@@ -0,0 +1,63 @@
+/**
+ * CCTP attestation client.
+ *
+ * Polls Circle's IRIS API for attestations after a USDC burn.
+ * Used on the destination chain to call MessageTransmitter.receiveMessage().
+ */
+import { CCTP_DOMAINS, IRIS_API_MAINNET, } from "./constants.js";
+/**
+ * Poll the IRIS V2 API until the attestation is ready for a given burn tx.
+ *
+ * @returns The message and attestation bytes needed to call receiveMessage().
+ * @throws If the attestation is not ready within the timeout, or the request fails.
+ */
+export async function fetchAttestation(options) {
+    const { sourceChain, txHash, irisApiUrl = IRIS_API_MAINNET, pollIntervalMs = 10_000, timeoutMs = 900_000, signal, } = options;
+    const sourceDomain = CCTP_DOMAINS[sourceChain];
+    if (sourceDomain === undefined) {
+        throw new Error(`Unknown CCTP source chain: ${sourceChain}`);
+    }
+    const url = `${irisApiUrl}/v2/messages/${sourceDomain}?transactionHash=${txHash}`;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        signal?.throwIfAborted();
+        try {
+            const response = await fetch(url);
+            if (response.status === 404) {
+                // Message not yet indexed, keep polling
+                await sleep(pollIntervalMs, signal);
+                continue;
+            }
+            if (!response.ok) {
+                throw new Error(`IRIS API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            if (data.messages.length > 0 && data.messages[0].status === "complete") {
+                return {
+                    message: data.messages[0].message,
+                    attestation: data.messages[0].attestation,
+                };
+            }
+            // Attestation pending, keep polling
+            await sleep(pollIntervalMs, signal);
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "AbortError") {
+                throw err;
+            }
+            // Network errors — retry after delay
+            await sleep(pollIntervalMs, signal);
+        }
+    }
+    throw new Error(`Attestation not ready after ${timeoutMs / 1000}s for tx ${txHash} on ${sourceChain}`);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new DOMException("Aborted", "AbortError"));
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=attestation.js.map

package/dist/cctp/attestation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.js","sourceRoot":"","sources":["../../src/cctp/attestation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,YAAY,EAEZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAyBxB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,MAAM,EACJ,WAAW,EACX,MAAM,EACN,UAAU,GAAG,gBAAgB,EAC7B,cAAc,GAAG,MAAM,EACvB,SAAS,GAAG,OAAO,EACnB,MAAM,GACP,GAAG,OAAO,CAAC;IAEZ,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IAC/C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,8BAA8B,WAAW,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,UAAU,gBAAgB,YAAY,oBAAoB,MAAM,EAAE,CAAC;IAElF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,SAAS,EAAE,CAAC;QAC1C,MAAM,EAAE,cAAc,EAAE,CAAC;QAEzB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;YAElC,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAC5B,wCAAwC;gBACxC,MAAM,KAAK,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;gBACpC,SAAS;YACX,CAAC;YAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAC5D,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAwB,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAExD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBACvE,OAAO;oBACL,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO;oBACjC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,WAAW;iBAC1C,CAAC;YACJ,CAAC;YAED,oCAAoC;YACpC,MAAM,KAAK,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC7D,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,qCAAqC;YACrC,MAAM,KAAK,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,+BAA+B,SAAS,GAAG,IAAI,YAAY,MAAM,OAAO,WAAW,EAAE,CACtF,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,gBAAgB,CACtB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;QACpD,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cctp/constants.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CCTP (Cross-Chain Transfer Protocol) constants.
+ *
+ * Uses CCTP V2 contracts which share the same address across all EVM chains.
+ * See: https://developers.circle.com/cctp/references/contract-addresses
+ */
+export declare const TOKEN_MESSENGER_V2 = "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d";
+export declare const MESSAGE_TRANSMITTER_V2 = "0x81D40F21F12A8F0E3252Bccb954D722d4c464B64";
+export declare const CCTP_DOMAINS: {
+    readonly Ethereum: 0;
+    readonly Avalanche: 1;
+    readonly Optimism: 2;
+    readonly Arbitrum: 3;
+    readonly Solana: 5;
+    readonly Base: 6;
+    readonly Polygon: 7;
+    readonly Unichain: 10;
+    readonly Linea: 11;
+    readonly Sonic: 13;
+    readonly "World Chain": 14;
+    readonly Monad: 15;
+    readonly Sei: 16;
+    readonly HyperEVM: 19;
+    readonly Ink: 21;
+};
+export type CctpChainName = keyof typeof CCTP_DOMAINS;
+export declare const USDC_ADDRESSES: Record<string, string>;
+export declare const TOKEN_MESSENGER_ADDRESSES: Record<string, string>;
+export declare const MESSAGE_TRANSMITTER_ADDRESSES: Record<string, string>;
+/**
+ * Magic hookData for Circle's Forwarding Service.
+ * Encodes "cctp-forward" + version 0 + data length 0.
+ * When passed to depositForBurnWithHook, Circle auto-mints on destination — zero gas needed.
+ */
+export declare const FORWARDING_SERVICE_HOOK_DATA = "0x636374702d666f72776172640000000000000000000000000000000000000000";
+/** Fast transfer finality threshold. */
+export declare const FINALITY_FAST = 1000;
+/** Standard transfer finality threshold. */
+export declare const FINALITY_STANDARD = 2000;
+/** Forwarding fee for Ethereum destination ($1.25 in USDC units). */
+export declare const FORWARDING_FEE_ETHEREUM = 1250000n;
+/** Forwarding fee for all other destinations ($0.20 in USDC units). */
+export declare const FORWARDING_FEE_OTHER = 200000n;
+export declare const IRIS_API_MAINNET = "https://iris-api.circle.com";
+export declare const IRIS_API_TESTNET = "https://iris-api-sandbox.circle.com";
+//# sourceMappingURL=constants.d.ts.map

package/dist/cctp/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/cctp/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,eAAO,MAAM,kBAAkB,+CAA+C,CAAC;AAC/E,eAAO,MAAM,sBAAsB,+CACW,CAAC;AAO/C,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;CAgBf,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,YAAY,CAAC;AAMtD,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAejD,CAAC;AAOF,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG1D,CAAC;AAEJ,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG9D,CAAC;AAMJ;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,uEAC6B,CAAC;AAEvE,wCAAwC;AACxC,eAAO,MAAM,aAAa,OAAO,CAAC;AAClC,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,WAAa,CAAC;AAClD,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,UAAW,CAAC;AAM7C,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAC9D,eAAO,MAAM,gBAAgB,wCAAwC,CAAC"}