@fastxyz/allset-sdk 0.1.11 → 1.0.0

package/dist/index.js

@@ -1,7 +1,927 @@
-/**
- * @fastxyz/allset-sdk — browser-safe core helpers
- *
- * Root exports are pure helpers only. Use `@fastxyz/allset-sdk/node` for
- * provider, executor, wallet, bridge execution, and file-backed config APIs.
- */
-export * from './core/index.js';
+// src/address.ts
+import { fromFastAddress, toHex } from "@fastxyz/sdk";
+function fastAddressToBytes(address) {
+  try {
+    return fromFastAddress(address);
+  } catch (err) {
+    throw new Error(`Invalid Fast address "${address}": ${err.message}`);
+  }
+}
+function fastAddressToBytes32(address) {
+  return toHex(fastAddressToBytes(address));
+}
+
+// src/claims.ts
+import { encodeAbiParameters, keccak256 } from "viem";
+function hexToUint8Array(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+var TRANSFER_CLAIM_ABI_PARAMS = [
+  {
+    type: "tuple",
+    components: [
+      { name: "from", type: "string" },
+      { name: "nonce", type: "uint256" },
+      { name: "asset", type: "string" },
+      { name: "amount", type: "uint256" },
+      { name: "to", type: "string" }
+    ]
+  }
+];
+var INTENT_CLAIM_ABI_PARAMS = [
+  {
+    type: "tuple",
+    components: [
+      { name: "transferFastTxId", type: "bytes32" },
+      { name: "deadline", type: "uint256" },
+      {
+        name: "intents",
+        type: "tuple[]",
+        components: [
+          { name: "action", type: "uint8" },
+          { name: "payload", type: "bytes" },
+          { name: "value", type: "uint256" }
+        ]
+      }
+    ]
+  }
+];
+function encodeTransferClaim(params) {
+  return encodeAbiParameters(TRANSFER_CLAIM_ABI_PARAMS, [
+    {
+      from: params.from.toLowerCase(),
+      nonce: BigInt(params.nonce),
+      asset: params.asset,
+      amount: params.amount,
+      to: params.to
+    }
+  ]);
+}
+function hashTransferClaim(params) {
+  return keccak256(encodeTransferClaim(params));
+}
+function encodeIntentClaim(params) {
+  return encodeAbiParameters(INTENT_CLAIM_ABI_PARAMS, [
+    {
+      transferFastTxId: params.transferFastTxId,
+      deadline: params.deadline,
+      intents: params.intents.map((i) => ({
+        action: i.action,
+        payload: i.payload,
+        value: i.value
+      }))
+    }
+  ]);
+}
+function buildIntentClaimBytes(params) {
+  const deadline = params.deadline ?? BigInt(Math.floor(Date.now() / 1e3) + 3600);
+  const encoded = encodeIntentClaim({
+    transferFastTxId: params.transferFastTxId,
+    deadline,
+    intents: params.intents
+  });
+  return hexToUint8Array(encoded);
+}
+function extractClaimId(crossSignTransaction) {
+  const bytes = new Uint8Array(crossSignTransaction.slice(32, 64));
+  return `0x${Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+// src/deposit.ts
+import { encodeFunctionData } from "viem";
+var BRIDGE_DEPOSIT_ABI = [
+  {
+    type: "function",
+    name: "deposit",
+    inputs: [
+      { name: "token", type: "address" },
+      { name: "amount", type: "uint256" },
+      { name: "receiver", type: "bytes32" }
+    ],
+    outputs: [],
+    stateMutability: "payable"
+  }
+];
+function encodeDepositCalldata(params) {
+  return encodeFunctionData({
+    abi: BRIDGE_DEPOSIT_ABI,
+    functionName: "deposit",
+    args: [params.tokenAddress, params.amount, params.receiverBytes32]
+  });
+}
+function buildDepositTransaction(params) {
+  const receiverBytes32 = fastAddressToBytes32(params.receiver);
+  return {
+    chainId: params.chainId,
+    to: params.bridgeContract,
+    data: encodeDepositCalldata({
+      tokenAddress: params.tokenAddress,
+      amount: params.amount,
+      receiverBytes32
+    }),
+    value: params.isNative ? params.amount : 0n,
+    receiverBytes32
+  };
+}
+
+// src/eip7702.ts
+import {
+  createPublicClient,
+  encodeAbiParameters as encodeAbiParameters2,
+  http,
+  keccak256 as keccak2562,
+  parseAbi
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { getUserOperationTypedData } from "viem/account-abstraction";
+var ENTRY_POINT_V08 = "0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108";
+var TRUSTED_DELEGATES = /* @__PURE__ */ new Set([
+  "0xe6cae83bde06e4c305530e199d7217f42808555b"
+  // Simple7702Account v0.8
+]);
+var ERC20_BALANCEOF_ABI = parseAbi([
+  "function balanceOf(address account) view returns (uint256)"
+]);
+function toEvenHex(n) {
+  let h = n.toString(16);
+  if (h.length % 2 !== 0) h = `0${h}`;
+  return `0x${h}`;
+}
+async function postJson(url, body, timeoutMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: ac.signal
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`POST ${url} failed (${res.status}): ${err}`);
+    }
+    return await res.json();
+  } catch (e) {
+    if (e.name === "AbortError") {
+      throw new Error(`POST ${url} timed out after ${timeoutMs}ms`);
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var InsufficientBalanceError = class extends Error {
+  constructor(balance, required, tokenAddress) {
+    super(
+      `Insufficient token balance: have ${balance}, need ${required} (token ${tokenAddress})`
+    );
+    this.balance = balance;
+    this.required = required;
+    this.tokenAddress = tokenAddress;
+    this.name = "InsufficientBalanceError";
+  }
+};
+function parseUserOp(raw) {
+  return {
+    sender: raw.sender,
+    nonce: BigInt(raw.nonce),
+    callData: raw.callData,
+    callGasLimit: BigInt(raw.callGasLimit),
+    verificationGasLimit: BigInt(raw.verificationGasLimit),
+    preVerificationGas: BigInt(raw.preVerificationGas),
+    maxFeePerGas: BigInt(raw.maxFeePerGas),
+    maxPriorityFeePerGas: BigInt(raw.maxPriorityFeePerGas),
+    ...raw.paymaster && { paymaster: raw.paymaster },
+    ...raw.paymasterVerificationGasLimit && {
+      paymasterVerificationGasLimit: BigInt(raw.paymasterVerificationGasLimit)
+    },
+    ...raw.paymasterPostOpGasLimit && {
+      paymasterPostOpGasLimit: BigInt(raw.paymasterPostOpGasLimit)
+    },
+    ...raw.paymasterData && { paymasterData: raw.paymasterData },
+    ...raw.factory && { factory: raw.factory },
+    ...raw.factoryData && { factoryData: raw.factoryData },
+    signature: "0x"
+  };
+}
+function serializeUserOp(op) {
+  const toHex2 = (n) => `0x${n.toString(16)}`;
+  return {
+    sender: op.sender,
+    nonce: toHex2(op.nonce),
+    callData: op.callData,
+    callGasLimit: toHex2(op.callGasLimit),
+    verificationGasLimit: toHex2(op.verificationGasLimit),
+    preVerificationGas: toHex2(op.preVerificationGas),
+    maxFeePerGas: toHex2(op.maxFeePerGas),
+    maxPriorityFeePerGas: toHex2(op.maxPriorityFeePerGas),
+    ...op.paymaster && { paymaster: op.paymaster },
+    ...op.paymasterVerificationGasLimit !== void 0 && {
+      paymasterVerificationGasLimit: toHex2(op.paymasterVerificationGasLimit)
+    },
+    ...op.paymasterPostOpGasLimit !== void 0 && {
+      paymasterPostOpGasLimit: toHex2(op.paymasterPostOpGasLimit)
+    },
+    ...op.paymasterData && { paymasterData: op.paymasterData },
+    ...op.factory && { factory: op.factory },
+    ...op.factoryData && { factoryData: op.factoryData },
+    ...op.signature && { signature: op.signature }
+  };
+}
+async function smartDeposit(params) {
+  const {
+    privateKey,
+    rpcUrl,
+    allsetApiUrl,
+    tokenAddress,
+    amount,
+    bridgeAddress,
+    depositCalldata,
+    requestTimeoutMs = 6e4
+  } = params;
+  const eoa = privateKeyToAccount(privateKey);
+  const publicClient = createPublicClient({ transport: http(rpcUrl) });
+  const tokenBalance = await publicClient.readContract({
+    address: tokenAddress,
+    abi: ERC20_BALANCEOF_ABI,
+    functionName: "balanceOf",
+    args: [eoa.address]
+  });
+  if (tokenBalance < amount) {
+    throw new InsufficientBalanceError(tokenBalance, amount, tokenAddress);
+  }
+  const chainId = await publicClient.getChainId();
+  const timestamp = Math.floor(Date.now() / 1e3);
+  const nonceBytes = crypto.getRandomValues(new Uint8Array(32));
+  const nonce = `0x${Array.from(nonceBytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+  const DOMAIN_TAG = "AllSet Portal authSig v1";
+  const msgHash = keccak2562(
+    encodeAbiParameters2(
+      [
+        { type: "string" },
+        { type: "uint256" },
+        { type: "bytes32" },
+        { type: "address" },
+        { type: "address" },
+        { type: "uint256" },
+        { type: "address" },
+        { type: "bytes" },
+        { type: "uint256" }
+      ],
+      [
+        DOMAIN_TAG,
+        BigInt(chainId),
+        nonce,
+        eoa.address,
+        tokenAddress,
+        amount,
+        bridgeAddress,
+        depositCalldata,
+        BigInt(timestamp)
+      ]
+    )
+  );
+  const authSig = await eoa.signMessage({ message: { raw: msgHash } });
+  const prepareReq = {
+    rpcUrl,
+    from: eoa.address,
+    tokenAddress,
+    amount: amount.toString(),
+    bridgeAddress,
+    depositCalldata,
+    chainId,
+    nonce,
+    timestamp,
+    authSig
+  };
+  const PREPARE_DELAYS = [0, 500, 1500];
+  let prepared;
+  for (let attempt = 0; attempt < PREPARE_DELAYS.length; attempt++) {
+    if (PREPARE_DELAYS[attempt] > 0) {
+      await new Promise((r) => setTimeout(r, PREPARE_DELAYS[attempt]));
+    }
+    try {
+      prepared = await postJson(
+        `${allsetApiUrl}/userop/prepare`,
+        prepareReq,
+        requestTimeoutMs
+      );
+      break;
+    } catch (e) {
+      const isLast = attempt === PREPARE_DELAYS.length - 1;
+      const msg = e.message ?? "";
+      const isRetryable = !msg.match(/POST .+ failed \([1-4][0-9]{2}\)/) || msg.includes("(429)") || msg.includes("(5");
+      if (isLast || !isRetryable) throw e;
+    }
+  }
+  if (!TRUSTED_DELEGATES.has(prepared.delegate7702Address.toLowerCase())) {
+    throw new Error(
+      `smartDeposit: untrusted delegate address returned by backend: ${prepared.delegate7702Address}`
+    );
+  }
+  let eip7702Auth;
+  if (prepared.needsAuthorization) {
+    const accountNonce = await publicClient.getTransactionCount({
+      address: eoa.address,
+      blockTag: "pending"
+    });
+    const signed = await eoa.signAuthorization({
+      address: prepared.delegate7702Address,
+      chainId,
+      nonce: accountNonce
+    });
+    const yParity = signed.yParity ?? 0;
+    eip7702Auth = {
+      address: prepared.delegate7702Address,
+      chainId: toEvenHex(chainId),
+      nonce: toEvenHex(accountNonce),
+      yParity: toEvenHex(yParity),
+      r: `0x${BigInt(signed.r).toString(16).padStart(64, "0")}`,
+      s: `0x${BigInt(signed.s).toString(16).padStart(64, "0")}`
+    };
+  }
+  const userOpToSign = parseUserOp(prepared.unsignedUserOp);
+  const typedData = getUserOperationTypedData({
+    chainId,
+    entryPointAddress: ENTRY_POINT_V08,
+    userOperation: { ...userOpToSign, signature: "0x" }
+  });
+  const signature = await eoa.signTypedData(typedData);
+  const signedUserOp = { ...userOpToSign, signature };
+  const serialized = serializeUserOp(signedUserOp);
+  if (eip7702Auth) {
+    serialized.eip7702Auth = eip7702Auth;
+  }
+  const submitReq = {
+    rpcUrl,
+    signedUserOp: serialized
+  };
+  const { txHash, userOpHash: returnedUserOpHash } = await postJson(
+    `${allsetApiUrl}/userop/submit`,
+    submitReq,
+    requestTimeoutMs
+  );
+  return {
+    txHash,
+    userOpHash: returnedUserOpHash,
+    userAddress: eoa.address
+  };
+}
+
+// src/evm.ts
+import { createPublicClient as createPublicClient2, createWalletClient, http as http2, parseAbi as parseAbi2 } from "viem";
+import { generatePrivateKey, privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
+import { arbitrum, arbitrumSepolia, base, mainnet as ethereum, sepolia } from "viem/chains";
+function normalizePrivateKey(privateKey) {
+  return privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`;
+}
+function createEvmWallet(privateKey) {
+  const key = privateKey ? normalizePrivateKey(privateKey) : generatePrivateKey();
+  return Object.assign(privateKeyToAccount2(key), { privateKey: key });
+}
+var ERC20_ABI = parseAbi2([
+  "function approve(address spender, uint256 amount) returns (bool)",
+  "function allowance(address owner, address spender) view returns (uint256)",
+  "function balanceOf(address owner) view returns (uint256)"
+]);
+var CHAIN_MAP = {
+  1: ethereum,
+  11155111: sepolia,
+  421614: arbitrumSepolia,
+  42161: arbitrum,
+  8453: base
+};
+function createEvmExecutor(account, rpcUrl, chainOrId) {
+  const chain = typeof chainOrId === "number" ? resolveChain(chainOrId) : chainOrId;
+  const walletClient = createWalletClient({
+    account,
+    chain,
+    transport: http2(rpcUrl)
+  });
+  const publicClient = createPublicClient2({
+    chain,
+    transport: http2(rpcUrl)
+  });
+  return { walletClient, publicClient };
+}
+function resolveChain(chainId) {
+  const chain = CHAIN_MAP[chainId];
+  if (!chain) {
+    throw new Error(
+      `Unsupported EVM chain ID: ${chainId}. Supported: ${Object.keys(CHAIN_MAP).join(", ")}. Pass a viem Chain object directly to avoid this restriction.`
+    );
+  }
+  return chain;
+}
+async function getEvmErc20Balance(rpcUrl, tokenAddress, ownerAddress) {
+  const client = createPublicClient2({ transport: http2(rpcUrl) });
+  return client.readContract({
+    address: tokenAddress,
+    abi: ERC20_ABI,
+    functionName: "balanceOf",
+    args: [ownerAddress]
+  });
+}
+async function getEvmNativeBalance(rpcUrl, address) {
+  const client = createPublicClient2({ transport: http2(rpcUrl) });
+  return client.getBalance({ address });
+}
+
+// src/intents.ts
+import { encodeAbiParameters as encodeAbiParameters3 } from "viem";
+var IntentAction = /* @__PURE__ */ ((IntentAction2) => {
+  IntentAction2[IntentAction2["Execute"] = 0] = "Execute";
+  IntentAction2[IntentAction2["DynamicTransfer"] = 1] = "DynamicTransfer";
+  IntentAction2[IntentAction2["DynamicDeposit"] = 2] = "DynamicDeposit";
+  IntentAction2[IntentAction2["Revoke"] = 3] = "Revoke";
+  return IntentAction2;
+})(IntentAction || {});
+function buildTransferIntent(token, receiver) {
+  const payload = encodeAbiParameters3([{ type: "address" }, { type: "address" }], [token, receiver]);
+  return {
+    action: 1 /* DynamicTransfer */,
+    payload,
+    value: 0n
+  };
+}
+function buildExecuteIntent(target, calldata, value = 0n) {
+  const payload = encodeAbiParameters3([{ type: "address" }, { type: "bytes" }], [target, calldata]);
+  return {
+    action: 0 /* Execute */,
+    payload,
+    value
+  };
+}
+function buildDepositBackIntent(token, fastReceiver) {
+  const receiverBytes = fastAddressToBytes32(fastReceiver);
+  const payload = encodeAbiParameters3([{ type: "address" }, { type: "bytes32" }], [token, receiverBytes]);
+  return {
+    action: 2 /* DynamicDeposit */,
+    payload,
+    value: 0n
+  };
+}
+function buildRevokeIntent() {
+  return {
+    action: 3 /* Revoke */,
+    payload: "0x",
+    value: 0n
+  };
+}
+
+// src/bridge.ts
+import { TransactionCertificateFromRpc } from "@fastxyz/schema";
+import { TransactionBuilder } from "@fastxyz/sdk";
+import { Schema } from "effect";
+import { decodeAbiParameters } from "viem";
+
+// src/errors.ts
+var FastError = class extends Error {
+  code;
+  note;
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "FastError";
+    this.code = code;
+    this.note = opts?.note ?? "";
+  }
+  toJSON() {
+    return { name: this.name, code: this.code, message: this.message, note: this.note };
+  }
+};
+
+// src/relay.ts
+async function relayExecute(params) {
+  const {
+    relayerUrl,
+    encodedTransferClaim,
+    transferProof,
+    transferFastTxId,
+    fastsetAddress,
+    externalAddress,
+    encodedIntentClaim,
+    intentProof,
+    intentFastTxId,
+    intentClaimId,
+    externalTokenAddress
+  } = params;
+  const body = {
+    encoded_transfer_claim: encodedTransferClaim,
+    transfer_proof: transferProof,
+    transfer_fast_tx_id: transferFastTxId,
+    transfer_claim_id: transferFastTxId,
+    fastset_address: fastsetAddress,
+    external_address: externalAddress
+  };
+  if (encodedIntentClaim && intentProof) {
+    body.encoded_intent_claim = encodedIntentClaim;
+    body.intent_proof = intentProof;
+  }
+  if (intentFastTxId) {
+    body.intent_fast_tx_id = intentFastTxId;
+  }
+  if (intentClaimId) {
+    body.intent_claim_id = intentClaimId;
+  }
+  if (externalTokenAddress) {
+    body.external_token_address = externalTokenAddress;
+  }
+  const relayRes = await fetch(`${relayerUrl.replace(/\/$/, "")}/relay`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!relayRes.ok) {
+    const text = await relayRes.text();
+    throw new FastError("TX_FAILED", `Relayer request failed (${relayRes.status}): ${text}`, {
+      note: "The intent was submitted to Fast network but the relayer rejected it. Try again."
+    });
+  }
+  return { success: true };
+}
+
+// src/bridge.ts
+function hexToUint8Array2(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function bigIntToNumber(obj) {
+  if (typeof obj === "bigint") return Number(obj);
+  if (obj instanceof Uint8Array) return Array.from(obj);
+  if (Array.isArray(obj)) return obj.map(bigIntToNumber);
+  if (obj !== null && typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = bigIntToNumber(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function resolveExternalAddress(intents, externalAddressOverride) {
+  if (externalAddressOverride) return externalAddressOverride;
+  for (const intent of intents) {
+    if (intent.action === 1 /* DynamicTransfer */) {
+      try {
+        const [, receiver] = decodeAbiParameters(
+          [{ type: "address" }, { type: "address" }],
+          intent.payload
+        );
+        return receiver;
+      } catch {
+        continue;
+      }
+    }
+    if (intent.action === 0 /* Execute */) {
+      try {
+        const [target] = decodeAbiParameters(
+          [{ type: "address" }, { type: "bytes" }],
+          intent.payload
+        );
+        return target;
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+async function sendTx(clients, tx) {
+  const walletClient = clients.walletClient;
+  const hash = await walletClient.sendTransaction({
+    to: tx.to,
+    data: tx.data,
+    value: BigInt(tx.value),
+    gas: tx.gas ? BigInt(tx.gas) : void 0
+  });
+  const receipt = await clients.publicClient.waitForTransactionReceipt({
+    hash
+  });
+  return {
+    txHash: hash,
+    status: receipt.status === "success" ? "success" : "reverted"
+  };
+}
+async function checkAllowance(clients, token, spender, owner) {
+  return clients.publicClient.readContract({
+    address: token,
+    abi: ERC20_ABI,
+    functionName: "allowance",
+    args: [owner, spender]
+  });
+}
+async function approveErc20(clients, token, spender, amount) {
+  const walletClient = clients.walletClient;
+  const hash = await walletClient.writeContract({
+    address: token,
+    abi: ERC20_ABI,
+    functionName: "approve",
+    args: [spender, BigInt(amount)]
+  });
+  const receipt = await clients.publicClient.waitForTransactionReceipt({ hash });
+  if (receipt.status === "reverted") {
+    throw new FastError(
+      "TX_FAILED",
+      `ERC-20 approve transaction reverted: ${hash}`,
+      {
+        note: "Check that you have sufficient ETH for gas fees."
+      }
+    );
+  }
+  const amountBig = BigInt(amount);
+  const walletAddress = walletClient.account?.address;
+  for (let attempt = 0; attempt < 10; attempt++) {
+    const current = await checkAllowance(clients, token, spender, walletAddress);
+    if (current >= amountBig) break;
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+}
+async function evmSign(certificate, crossSignUrl) {
+  const wireFormat = Schema.encodeSync(TransactionCertificateFromRpc)(
+    certificate
+  );
+  const serialized = bigIntToNumber(wireFormat);
+  const res = await fetch(crossSignUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "crossSign_evmSignCertificate",
+      params: { certificate: serialized }
+    })
+  });
+  if (!res.ok) {
+    throw new FastError(
+      "TX_FAILED",
+      `Cross-sign request failed: ${res.status}`,
+      {
+        note: "The AllSet cross-sign service rejected the request."
+      }
+    );
+  }
+  const json = await res.json();
+  if (json.error) {
+    throw new FastError(
+      "TX_FAILED",
+      `Cross-sign error: ${json.error.message}`,
+      {
+        note: "The certificate could not be cross-signed."
+      }
+    );
+  }
+  if (!json.result?.transaction || !json.result?.signature) {
+    throw new FastError("TX_FAILED", "Cross-sign returned invalid response", {
+      note: "Missing transaction or signature in response."
+    });
+  }
+  return json.result;
+}
+async function executeDeposit(params) {
+  const {
+    chainId,
+    bridgeContract,
+    tokenAddress,
+    isNative = false,
+    amount,
+    receiverAddress,
+    evmClients
+  } = params;
+  let depositPlan;
+  try {
+    depositPlan = buildDepositTransaction({
+      chainId,
+      bridgeContract,
+      tokenAddress,
+      isNative,
+      amount: BigInt(amount),
+      receiver: receiverAddress
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new FastError(
+      "INVALID_ADDRESS",
+      `Failed to decode Fast receiver address "${receiverAddress}": ${msg}`,
+      {
+        note: "The receiver address must be a valid Fast network bech32m address (fast1...)."
+      }
+    );
+  }
+  let txHash;
+  if (isNative) {
+    const receipt = await sendTx(evmClients, {
+      to: depositPlan.to,
+      data: depositPlan.data,
+      value: depositPlan.value.toString()
+    });
+    if (receipt.status === "reverted") {
+      throw new FastError(
+        "TX_FAILED",
+        `Deposit transaction reverted: ${receipt.txHash}`,
+        {
+          note: "Check that you have sufficient ETH balance."
+        }
+      );
+    }
+    txHash = receipt.txHash;
+  } else {
+    await approveErc20(evmClients, tokenAddress, bridgeContract, amount);
+    const receipt = await sendTx(evmClients, {
+      to: depositPlan.to,
+      data: depositPlan.data,
+      value: depositPlan.value.toString()
+    });
+    if (receipt.status === "reverted") {
+      throw new FastError(
+        "TX_FAILED",
+        `Deposit transaction reverted: ${receipt.txHash}`,
+        {
+          note: "Check that you have sufficient token balance and the approval succeeded."
+        }
+      );
+    }
+    txHash = receipt.txHash;
+  }
+  return { txHash, orderId: txHash, estimatedTime: "1-5 minutes" };
+}
+async function executeIntent(params) {
+  const {
+    fastBridgeAddress,
+    relayerUrl,
+    crossSignUrl,
+    tokenEvmAddress,
+    tokenFastTokenId,
+    amount,
+    intents,
+    externalAddress: externalAddressOverride,
+    deadlineSeconds = 3600,
+    signer,
+    provider,
+    networkId
+  } = params;
+  if (!intents || intents.length === 0) {
+    throw new FastError(
+      "INVALID_PARAMS",
+      "executeIntent requires at least one intent",
+      {
+        note: "Use intent builders like buildTransferIntent(), buildExecuteIntent(), etc."
+      }
+    );
+  }
+  if (externalAddressOverride && !externalAddressOverride.startsWith("0x")) {
+    throw new FastError(
+      "INVALID_PARAMS",
+      "executeIntent externalAddress must be an EVM address",
+      {
+        note: "Pass a 0x-prefixed address for the relayer target."
+      }
+    );
+  }
+  const tokenId = hexToUint8Array2(tokenFastTokenId);
+  const publicKey = await signer.getPublicKey();
+  const fastAddress = await signer.getFastAddress();
+  const accountInfo1 = await provider.getAccountInfo({
+    address: publicKey,
+    tokenBalancesFilter: null,
+    stateKeyFilter: null,
+    certificateByNonce: null
+  });
+  const transferEnvelope = await new TransactionBuilder({
+    networkId,
+    signer,
+    nonce: accountInfo1.nextNonce
+  }).addTokenTransfer({
+    tokenId,
+    recipient: fastAddressToBytes(fastBridgeAddress),
+    amount: BigInt(amount),
+    userData: null
+  }).sign();
+  const transferResult = await provider.submitTransaction(transferEnvelope);
+  if (transferResult.type !== "Success") {
+    throw new FastError(
+      "TX_FAILED",
+      `Token transfer submission incomplete: ${transferResult.type}`,
+      {
+        note: "The transfer transaction was not fully confirmed. Try again."
+      }
+    );
+  }
+  const transferCrossSign = await evmSign(transferResult.value, crossSignUrl);
+  const transferFastTxId = extractClaimId(transferCrossSign.transaction);
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + deadlineSeconds);
+  const intentClaimEncoded = encodeIntentClaim({
+    transferFastTxId,
+    deadline,
+    intents
+  });
+  const intentBytes = hexToUint8Array2(intentClaimEncoded);
+  const accountInfo2 = await provider.getAccountInfo({
+    address: publicKey,
+    tokenBalancesFilter: null,
+    stateKeyFilter: null,
+    certificateByNonce: null
+  });
+  const intentEnvelope = await new TransactionBuilder({
+    networkId,
+    signer,
+    nonce: accountInfo2.nextNonce
+  }).addExternalClaim({
+    claim: {
+      verifierCommittee: [],
+      verifierQuorum: 0,
+      claimData: intentBytes
+    },
+    signatures: []
+  }).sign();
+  const intentResult = await provider.submitTransaction(intentEnvelope);
+  if (intentResult.type !== "Success") {
+    throw new FastError(
+      "TX_FAILED",
+      `Intent claim submission incomplete: ${intentResult.type}`,
+      {
+        note: "The intent claim transaction was not fully confirmed. Try again."
+      }
+    );
+  }
+  const intentCrossSign = await evmSign(intentResult.value, crossSignUrl);
+  const intentFastTxId = extractClaimId(intentCrossSign.transaction);
+  const externalAddress = resolveExternalAddress(
+    intents,
+    externalAddressOverride
+  );
+  if (!externalAddress) {
+    throw new FastError(
+      "INVALID_PARAMS",
+      "executeIntent requires externalAddress when intents do not include a transfer recipient or execute target",
+      {
+        note: "Pass externalAddress for flows like buildDepositBackIntent() or buildRevokeIntent()."
+      }
+    );
+  }
+  await relayExecute({
+    relayerUrl,
+    encodedTransferClaim: Array.from(
+      new Uint8Array(transferCrossSign.transaction.map(Number))
+    ),
+    transferProof: transferCrossSign.signature,
+    transferFastTxId,
+    fastsetAddress: fastAddress,
+    externalAddress,
+    encodedIntentClaim: Array.from(
+      new Uint8Array(intentCrossSign.transaction.map(Number))
+    ),
+    intentProof: intentCrossSign.signature,
+    intentFastTxId,
+    intentClaimId: intentFastTxId,
+    externalTokenAddress: tokenEvmAddress
+  });
+  return {
+    txHash: transferFastTxId,
+    orderId: transferFastTxId,
+    estimatedTime: "1-5 minutes"
+  };
+}
+async function executeWithdraw(params) {
+  const { receiverEvmAddress, tokenEvmAddress, ...rest } = params;
+  const intent = buildTransferIntent(tokenEvmAddress, receiverEvmAddress);
+  return executeIntent({ ...rest, tokenEvmAddress, intents: [intent] });
+}
+export {
+  CHAIN_MAP,
+  ERC20_ABI,
+  FastError,
+  InsufficientBalanceError,
+  IntentAction,
+  buildDepositBackIntent,
+  buildDepositTransaction,
+  buildExecuteIntent,
+  buildIntentClaimBytes,
+  buildRevokeIntent,
+  buildTransferIntent,
+  createEvmExecutor,
+  createEvmWallet,
+  encodeDepositCalldata,
+  encodeIntentClaim,
+  encodeTransferClaim,
+  evmSign,
+  executeDeposit,
+  executeIntent,
+  executeWithdraw,
+  extractClaimId,
+  fastAddressToBytes,
+  fastAddressToBytes32,
+  getEvmErc20Balance,
+  getEvmNativeBalance,
+  hashTransferClaim,
+  relayExecute,
+  smartDeposit
+};