(null);
+
+ useEffect(() => {
+ if (!address) return;
+ const key = address.toLowerCase();
+ let stopped = false;
+ let timer = 0;
+ const client = (id: BridgeChainId) => {
+ const pub = getPublicClient(config, { chainId: id });
+ if (!pub) throw new Error("no client");
+ return pub;
+ };
+ const read: HoldingReader = {
+ native: async (id, who) => client(id).getBalance({ address: who }),
+ token: async (id, token, who) => client(id).readContract({ address: token, abi: erc20Abi, functionName: "balanceOf", args: [who] }),
+ };
+ const tick = async () => {
+ if (!document.hidden) {
+ const holdings = await readExchangeHoldings(read, address);
+ if (stopped) return;
+ const now = Date.now();
+ const saved = watchRef.current?.wallet === key ? watchRef.current : savedWatch(key, now) ?? { wallet: key, startedAt: now, baseline: {} };
+ const watch = { ...saved, baseline: nextExchangeBaseline(saved.baseline, holdings) };
+ watchRef.current = watch;
+ try { window.sessionStorage.setItem(EXCHANGE_WATCH_KEY, serializeExchangeWatch(watch)); } catch { /* watched for this view only */ }
+ setReading({ wallet: key, watch, holdings });
+ }
+ if (!stopped) timer = window.setTimeout(() => void tick(), EXCHANGE_POLL_MS);
+ };
+ void tick();
+ return () => { stopped = true; window.clearTimeout(timer); };
+ }, [address, config]);
+
+ if (!wallet) return EXCHANGE_IDLE;
+ if (reading?.wallet !== wallet) return { checking: true, unreadable: false, arrivals: [] };
+ return { checking: false, unreadable: reading.holdings.length === 0, arrivals: findExchangeArrivals(reading.watch.baseline, reading.holdings) };
+}
+
+/** Ends the watch: the guide was closed on purpose, or its funds were taken to the bridge. */
+export function clearExchangeWatch() {
+ try {
+ window.sessionStorage.removeItem(EXCHANGE_WATCH_KEY);
+ window.sessionStorage.removeItem(EXCHANGE_OPEN_KEY);
+ } catch { /* nothing kept */ }
+}
diff --git a/app/src/components/launchpad/TradePanel.tsx b/app/src/components/launchpad/TradePanel.tsx
index d5b2dbbd..56a6a31d 100644
--- a/app/src/components/launchpad/TradePanel.tsx
+++ b/app/src/components/launchpad/TradePanel.tsx
@@ -1,6 +1,6 @@
"use client";
-import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
import { useRouter } from "next/navigation";
import { useBalance, useConfig, useReadContract, useSwitchChain } from "wagmi";
import { useHydratedAccount } from "@/lib/useHydratedAccount";
@@ -27,6 +27,7 @@ import { friendlyError } from "@/lib/errors";
import { Spinner } from "@/components/Skeleton";
import ConnectWallet from "@/components/ConnectWallet";
import { ChainLogo } from "./ChainLogo";
+import BridgeToBuy from "@/components/bridge/BridgeToBuy";
/**
* In-page buy / sell straight against the token's Uniswap v4 pool via the
@@ -113,6 +114,11 @@ export default function TradePanel({ chain, token, symbol, poolKey, poolId, feeR
const busy = phase.k === "preparing" || phase.k === "approving" || phase.k === "signing" || phase.k === "sent";
const balance = side === "buy" ? (pay.native ? eth.data?.value : (qbal.data as bigint | undefined)) : (tok.data as bigint | undefined);
const insufficient = amountIn !== null && balance !== undefined && amountIn + (side === "buy" ? buyReserve : 0n) > balance;
+ // Bridge, then buy: how far short a buy is, and a way to read the balance at once when bridged funds land
+ const shortBy = side === "buy" && insufficient && amountIn !== null && balance !== undefined ? amountIn + buyReserve - balance : null;
+ const refetchEth = eth.refetch;
+ const refetchQuote = qbal.refetch;
+ const refetchPay = useCallback(() => { void refetchEth(); void refetchQuote(); }, [refetchEth, refetchQuote]);
// the pay asset is part of the key: a TWIG quote never prices an ETH buy, or the other way round
const quoteKey = `${tradeQuoteKey(chain, token, side, amount)}${viaEth ? ":eth" : ""}`;
@@ -409,6 +415,9 @@ export default function TradePanel({ chain, token, symbol, poolKey, poolId, feeR
)}
+ {side === "buy" && isConnected && tradable ? (
+
+ ) : null}
{side === "buy" && quote.key === "twig" && !viaEth && (balance === undefined || balance === 0n || insufficient) ? (
Need TWIG? Wrap GITLAWB 1:1 or buy TWIG at{" "}
diff --git a/app/src/components/wallet-menu.test.ts b/app/src/components/wallet-menu.test.ts
index 591f371e..056fcb91 100644
--- a/app/src/components/wallet-menu.test.ts
+++ b/app/src/components/wallet-menu.test.ts
@@ -79,10 +79,11 @@ test("the header chip carries its network as an avatar badge; only the mobile ro
// the network's name in the desktop chip pushed the Launch button out of the header (up to 49px in the floating pill)
const trigger = source.slice(source.indexOf(""));
assert.match(trigger, /\{block \? /);
- assert.match(trigger, /block \? : /);
+ // a bridge funding network (Ethereum, Arbitrum, Optimism) is known, so it shows no warning, but has no launch-chain logo
+ assert.match(trigger, /block \? : /);
assert.match(trigger, /title=\{block \? undefined : [^\n]*"Unsupported network\. Open to switch"\}/);
const badge = source.slice(source.indexOf("function NetworkBadge"), source.indexOf("type WalletMenuProps"));
- assert.match(badge, /if \(!chain\) return !<\/span>/);
+ assert.match(badge, /if \(!chain\) return known \? null : !<\/span>/);
// the site's chain tile (Arc's white mark needs its dark tile), as on token avatars
assert.match(badge, //);
assert.match(css, /\.networkWarn\s*\{[^}]*position: absolute[^}]*background: var\(--color-warm\)/);
diff --git a/app/src/lib/bridge/approval.test.ts b/app/src/lib/bridge/approval.test.ts
index be59865f..5e29c2eb 100644
--- a/app/src/lib/bridge/approval.test.ts
+++ b/app/src/lib/bridge/approval.test.ts
@@ -2,8 +2,9 @@ import assert from "node:assert/strict";
import test from "node:test";
import { decodeFunctionData, encodeAbiParameters, encodeEventTopics, type Address, type Hex } from "viem";
import { APPROVAL_DISCARD_AFTER_MS, APPROVAL_STORAGE_PREFIX, ARC_APPROVAL_CHAIN_ID, ARC_USDC, EXACT_APPROVAL_ABI, RELAY_APPROVAL_SPENDER, USDC_APPROVAL_EVENT, approvalBlocksSubmission, approvalCanDiscard, approvalRequestKey, approvalStorageKey, createApprovalStore, exactApprovalTransaction, hasMatchingApprovalEvent, isMatchingApprovalTransaction, parseStoredApproval, reconcileApproval, serializeApproval, submitExactApproval, validateApprovalMetadata, type ApprovalDependencies, type ApprovalRequest, type TrackedApproval } from "./approval";
-import { BASE_USDC } from "./types";
-import { canApplyApprovalPoll, recoverApprovalFromEvidence } from "./approval";
+import { BASE_USDC, ELYSIUM_USDC, ROBINHOOD_USDG } from "./types";
+import { canApplyApprovalPoll, CCTP_APPROVAL_SPENDER, recoverApprovalFromEvidence } from "./approval";
+import { CCTP_TOKEN_MESSENGER } from "./cctp";
const ADDRESS = "0x1111111111111111111111111111111111111111" as Address;
const OTHER = "0x2222222222222222222222222222222222222222" as Address;
@@ -84,7 +85,15 @@ test("Base approvals pin Base USDC and retain independent chain identity", () =>
assert.notEqual(approvalRequestKey(request), approvalRequestKey(REQUEST));
assert.throws(() => validateApprovalMetadata({ token: ARC_USDC, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS, 8453));
assert.throws(() => validateApprovalMetadata({ token: BASE_USDC, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS, 5042));
- assert.throws(() => exactApprovalTransaction({ ...request, chainId: 4663 }));
+ // Robinhood Chain approves its own token, USDG, never Base's or Arc's
+ assert.equal(exactApprovalTransaction({ ...request, chainId: 4663 }).to, ROBINHOOD_USDG);
+ assert.throws(() => validateApprovalMetadata({ token: BASE_USDC, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS, 4663));
+ assert.throws(() => validateApprovalMetadata({ token: ROBINHOOD_USDG, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS, 8453));
+ // Elysium approves its own USDC, and only on Elysium
+ assert.equal(exactApprovalTransaction({ ...request, chainId: 99901 }).to, ELYSIUM_USDC);
+ assert.deepEqual(validateApprovalMetadata({ token: ELYSIUM_USDC, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS, 99901), { ...request, chainId: 99901 });
+ assert.throws(() => validateApprovalMetadata({ token: BASE_USDC, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS, 99901));
+ assert.throws(() => validateApprovalMetadata({ token: ELYSIUM_USDC, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS, 8453));
const unlimited = ((1n << 256n) - 1n).toString();
assert.throws(() => exactApprovalTransaction({ ...request, amount: unlimited }));
assert.throws(() => validateApprovalMetadata({ token: BASE_USDC, spender: RELAY_APPROVAL_SPENDER, amount: unlimited }, ADDRESS, 8453));
@@ -356,7 +365,7 @@ test("a confirmed exact replacement recovers a pending hash without resubmitting
assert.throws(() => recoverApprovalFromEvidence(approval, { ...evidence, blockTimestamp: evidence.blockTimestamp + 31n }), /clock/);
assert.throws(() => recoverApprovalFromEvidence(approval, { ...evidence, transaction: { ...evidence.transaction, hash: HASH } }), /network/);
for (const changes of [{ to: ADDRESS, input: "0x" as Hex }, { from: OTHER }, { input: exactApprovalTransaction({ ...REQUEST, amount: "1" }).data }, { value: 1n }]) {
- assert.throws(() => recoverApprovalFromEvidence(approval, { ...evidence, transaction: { ...evidence.transaction, ...changes } }), /exact USDC approval/);
+ assert.throws(() => recoverApprovalFromEvidence(approval, { ...evidence, transaction: { ...evidence.transaction, ...changes } }), /exact token approval/);
}
assert.throws(() => recoverApprovalFromEvidence({ ...approval, status: "confirmed" }, evidence), /already resolved/);
});
@@ -370,3 +379,28 @@ test("a delayed missing-receipt poll cannot undo same-hash confirmation or anoth
for (const change of [{ approvalHash: OTHER_HASH }, { address: OTHER }, { amount: "1" }, { createdAt: NOW + 1 }, { chainId: 8453 as const }]) assert.equal(canApplyApprovalPoll({ ...observed, ...change }, observed), false);
assert.equal(canApplyApprovalPoll(null, observed), false);
});
+
+test("a Circle approval pins Circle's messenger as spender, and no other contract is ever accepted", () => {
+ const circle = { ...REQUEST, spender: CCTP_APPROVAL_SPENDER };
+ assert.deepEqual(validateApprovalMetadata({ token: ARC_USDC, spender: CCTP_TOKEN_MESSENGER, amount: REQUEST.amount }, ADDRESS), circle);
+ // Relay stays the implicit spender, so Relay's records and keys are unchanged
+ assert.deepEqual(validateApprovalMetadata({ token: ARC_USDC, spender: RELAY_APPROVAL_SPENDER, amount: REQUEST.amount }, ADDRESS), REQUEST);
+ assert.equal(approvalRequestKey(REQUEST).includes(CCTP_APPROVAL_SPENDER), false);
+ assert.notEqual(approvalRequestKey(circle), approvalRequestKey(REQUEST));
+ assert.equal(decodeFunctionData({ abi: EXACT_APPROVAL_ABI, data: exactApprovalTransaction(circle).data }).args[0].toLowerCase(), CCTP_APPROVAL_SPENDER);
+ assert.throws(() => validateApprovalMetadata({ token: ARC_USDC, spender: OTHER, amount: REQUEST.amount }, ADDRESS));
+ assert.throws(() => exactApprovalTransaction({ ...REQUEST, spender: OTHER }));
+
+ const approval = tracked({ spender: CCTP_APPROVAL_SPENDER });
+ assert.deepEqual(parseStoredApproval(serializeApproval(approval), ADDRESS), approval);
+ assert.throws(() => parseStoredApproval(serializeApproval(tracked({ spender: OTHER })), ADDRESS));
+ const event = (spender: Address) => ({
+ address: ARC_USDC as Address,
+ topics: encodeEventTopics({ abi: USDC_APPROVAL_EVENT, eventName: "Approval", args: { owner: ADDRESS, spender } }) as Hex[],
+ data: encodeAbiParameters([{ type: "uint256" }], [25_000_000n]),
+ });
+ assert.equal(hasMatchingApprovalEvent(approval, { status: "success", logs: [event(CCTP_TOKEN_MESSENGER)] }), true);
+ // an approval of Relay's depository never stands in for Circle's, nor the reverse
+ assert.equal(hasMatchingApprovalEvent(approval, { status: "success", logs: [event(RELAY_APPROVAL_SPENDER)] }), false);
+ assert.equal(hasMatchingApprovalEvent(tracked(), { status: "success", logs: [event(CCTP_TOKEN_MESSENGER)] }), false);
+});
diff --git a/app/src/lib/bridge/approval.ts b/app/src/lib/bridge/approval.ts
index 720dd455..a92f30d9 100644
--- a/app/src/lib/bridge/approval.ts
+++ b/app/src/lib/bridge/approval.ts
@@ -1,5 +1,6 @@
import { decodeEventLog, encodeFunctionData, isAddress, type Address, type Hex } from "viem";
-import { bridgeCurrency, isBridgeChainId, type BridgeChainId } from "./types";
+import { bridgeCurrency, bridgeTokenAsset, isBridgeChainId, type BridgeChainId } from "./types";
+import { CCTP_TOKEN_MESSENGER } from "./cctp";
// Independently pinned: provider calldata never chooses the token or spender.
// https://docs.arc.io/arc/references/contract-addresses
@@ -7,6 +8,11 @@ import { bridgeCurrency, isBridgeChainId, type BridgeChainId } from "./types";
export const ARC_APPROVAL_CHAIN_ID = 5042 as const;
export const ARC_USDC = "0x3600000000000000000000000000000000000000" as const;
export const RELAY_APPROVAL_SPENDER = "0x4cd00e387622c35bddb9b4c962c136462338bc31" as const;
+// Circle's TokenMessengerV2 (lib/bridge/cctp.ts), which pulls the exact amount it burns.
+export const CCTP_APPROVAL_SPENDER = CCTP_TOKEN_MESSENGER.toLowerCase() as Address;
+/** The only contracts an approval may name. Anything else is refused before the wallet is asked. */
+export const APPROVAL_SPENDERS: readonly Address[] = [RELAY_APPROVAL_SPENDER, CCTP_APPROVAL_SPENDER];
+const spenderOf = (value: unknown): Address | null => typeof value === "string" ? APPROVAL_SPENDERS.find((spender) => spender === value.toLowerCase()) ?? null : null;
export const EXACT_APPROVAL_ABI = [{ type: "function", name: "approve", stateMutability: "nonpayable", inputs: [{ name: "spender", type: "address" }, { name: "amount", type: "uint256" }], outputs: [{ name: "", type: "bool" }] }] as const;
export const USDC_APPROVAL_EVENT = [{ type: "event", name: "Approval", inputs: [{ name: "owner", type: "address", indexed: true }, { name: "spender", type: "address", indexed: true }, { name: "value", type: "uint256", indexed: false }] }] as const;
export const APPROVAL_STORAGE_PREFIX = "openlaunch.bridge.approval.v1:";
@@ -16,13 +22,14 @@ const MAX_APPROVAL_AMOUNT = MAX_UINT / 10n ** 12n;
const HASH = /^0x[0-9a-fA-F]{64}$/;
const STATUSES = ["uncertain", "pending", "confirmed", "reverted", "insufficient"] as const;
-export type ApprovalRequest = { address: Address; amount: string; chainId?: BridgeChainId }; // Omitted chain is legacy Arc; amounts are USDC units, 6 decimals.
+// Omitted chain is legacy Arc; omitted spender is Relay's depository (every record before Circle). Amounts are token units, 6 decimals.
+export type ApprovalRequest = { address: Address; amount: string; chainId?: BridgeChainId; spender?: Address };
export type ApprovalStatus = typeof STATUSES[number];
export type TrackedApproval = ApprovalRequest & {
version: 1;
chainId: BridgeChainId;
token: Address;
- spender: typeof RELAY_APPROVAL_SPENDER;
+ spender: Address;
createdAt: number;
status: ApprovalStatus;
approvalHash?: Hex;
@@ -39,31 +46,36 @@ function validAmount(value: unknown): value is string {
}
export function approvalToken(chainId: BridgeChainId = ARC_APPROVAL_CHAIN_ID): Address {
- if (!isBridgeChainId(chainId) || (chainId !== 8453 && chainId !== 5042)) throw new Error("USDC approvals are not supported on this network.");
- return bridgeCurrency(chainId, "USDC", "input").address;
+ // the chain's one ERC-20 (types.ts): USDC on Base and Arc, USDG on Robinhood Chain
+ const asset = isBridgeChainId(chainId) ? bridgeTokenAsset(chainId) : null;
+ if (!asset) throw new Error("Token approvals are not supported on this network.");
+ return bridgeCurrency(chainId, asset, "input").address;
}
function validateRequest(value: ApprovalRequest): ApprovalRequest {
if (!value || typeof value.address !== "string" || !isAddress(value.address, { strict: false }) || /^0x0{40}$/i.test(value.address) || !validAmount(value.amount)) {
- throw new Error("The USDC approval does not match a valid wallet and exact amount.");
+ throw new Error("The token approval does not match a valid wallet and exact amount.");
}
const chainId = value.chainId ?? ARC_APPROVAL_CHAIN_ID;
approvalToken(chainId);
if (chainId === ARC_APPROVAL_CHAIN_ID && BigInt(value.amount) > MAX_APPROVAL_AMOUNT) throw new Error("The USDC approval amount exceeds Arc's native balance range.");
- return { address: value.address, amount: value.amount, ...(value.chainId !== undefined ? { chainId } : {}) };
+ const spender = value.spender === undefined ? RELAY_APPROVAL_SPENDER : spenderOf(value.spender);
+ if (!spender) throw new Error("The token approval names an unsupported spender.");
+ return { address: value.address, amount: value.amount, ...(value.chainId !== undefined ? { chainId } : {}), ...(spender !== RELAY_APPROVAL_SPENDER ? { spender } : {}) };
}
/** Validate provider metadata before adapting a quote to this fixed approval flow. */
export function validateApprovalMetadata(value: unknown, address: Address, chainId?: BridgeChainId): ApprovalRequest {
const metadata = value as { token?: unknown; spender?: unknown; amount?: unknown } | null;
- if (!metadata || typeof metadata.token !== "string" || metadata.token.toLowerCase() !== approvalToken(chainId).toLowerCase() || typeof metadata.spender !== "string" || metadata.spender.toLowerCase() !== RELAY_APPROVAL_SPENDER || !validAmount(metadata.amount)) {
+ if (!metadata || typeof metadata.token !== "string" || metadata.token.toLowerCase() !== approvalToken(chainId).toLowerCase() || !spenderOf(metadata.spender) || !validAmount(metadata.amount)) {
throw new Error("The bridge requested an unsupported token, spender, or approval amount.");
}
- return validateRequest({ address, amount: metadata.amount, ...(chainId !== undefined ? { chainId } : {}) });
+ return validateRequest({ address, amount: metadata.amount, ...(chainId !== undefined ? { chainId } : {}), spender: spenderOf(metadata.spender)! });
}
export function approvalRequestKey(request: ApprovalRequest | null): string {
- return request ? `${request.address.toLowerCase()}:${request.chainId ?? ARC_APPROVAL_CHAIN_ID}:${request.amount}` : "";
+ const spender = request?.spender?.toLowerCase();
+ return request ? `${request.address.toLowerCase()}:${request.chainId ?? ARC_APPROVAL_CHAIN_ID}:${request.amount}${spender && spender !== RELAY_APPROVAL_SPENDER ? `:${spender}` : ""}` : "";
}
export const approvalStorageKey = (address: Address) => `${APPROVAL_STORAGE_PREFIX}${address.toLowerCase()}`;
@@ -97,7 +109,7 @@ export function canApplyApprovalPoll(current: TrackedApproval | null, observed:
export function exactApprovalTransaction(request: ApprovalRequest): ApprovalTransaction {
const checked = validateRequest(request);
- return { chainId: checked.chainId ?? ARC_APPROVAL_CHAIN_ID, to: approvalToken(checked.chainId), value: 0n, data: encodeFunctionData({ abi: EXACT_APPROVAL_ABI, functionName: "approve", args: [RELAY_APPROVAL_SPENDER, BigInt(checked.amount)] }) };
+ return { chainId: checked.chainId ?? ARC_APPROVAL_CHAIN_ID, to: approvalToken(checked.chainId), value: 0n, data: encodeFunctionData({ abi: EXACT_APPROVAL_ABI, functionName: "approve", args: [checked.spender ?? RELAY_APPROVAL_SPENDER, BigInt(checked.amount)] }) };
}
/** Also bind candidate chain and block time to the journal in the RPC caller. */
@@ -108,7 +120,7 @@ export function isMatchingApprovalTransaction(approval: TrackedApproval, transac
} catch { return false; }
}
-/** Smart-wallet recovery uses the canonical USDC event, never a router's log. */
+/** Smart-wallet recovery uses the token's own Approval event, never a router's log. */
export function hasMatchingApprovalEvent(approval: TrackedApproval, receipt: { status: "success" | "reverted"; logs: readonly { address: Address; data: Hex; topics: readonly Hex[] }[] }): boolean {
if (receipt.status !== "success") return false;
try {
@@ -117,7 +129,7 @@ export function hasMatchingApprovalEvent(approval: TrackedApproval, receipt: { s
if (log.address.toLowerCase() !== checked.token.toLowerCase() || log.topics.length !== 3 || !log.topics.every((topic) => HASH.test(topic)) || !/^0x[0-9a-fA-F]{64}$/.test(log.data)) return false;
try {
const event = decodeEventLog({ abi: USDC_APPROVAL_EVENT, data: log.data, topics: [log.topics[0], ...log.topics.slice(1)], strict: true });
- return event.args.owner.toLowerCase() === checked.address.toLowerCase() && event.args.spender.toLowerCase() === RELAY_APPROVAL_SPENDER && event.args.value.toString() === checked.amount;
+ return event.args.owner.toLowerCase() === checked.address.toLowerCase() && event.args.spender.toLowerCase() === checked.spender && event.args.value.toString() === checked.amount;
} catch { return false; }
});
} catch { return false; }
@@ -127,9 +139,9 @@ export function parseStoredApproval(raw: string, address: Address): TrackedAppro
try {
const entry = JSON.parse(raw) as TrackedApproval;
const request = validateRequest(entry);
- if (entry.version !== 1 || request.address.toLowerCase() !== address.toLowerCase() || !isBridgeChainId(entry.chainId) || typeof entry.token !== "string" || entry.token.toLowerCase() !== approvalToken(entry.chainId).toLowerCase() || entry.spender !== RELAY_APPROVAL_SPENDER || !Number.isSafeInteger(entry.createdAt) || entry.createdAt <= 0 || !STATUSES.includes(entry.status) || (entry.approvalHash !== undefined && !validHash(entry.approvalHash)) || (entry.status !== "uncertain" && !entry.approvalHash)) throw new Error("invalid record");
- return { ...request, version: 1, chainId: entry.chainId, token: approvalToken(entry.chainId), spender: RELAY_APPROVAL_SPENDER, createdAt: entry.createdAt, status: entry.status, ...(entry.approvalHash ? { approvalHash: entry.approvalHash } : {}) };
- } catch { throw new Error("Saved USDC approval recovery data could not be read. Check the approval before trying again."); }
+ if (entry.version !== 1 || request.address.toLowerCase() !== address.toLowerCase() || !isBridgeChainId(entry.chainId) || typeof entry.token !== "string" || entry.token.toLowerCase() !== approvalToken(entry.chainId).toLowerCase() || !spenderOf(entry.spender) || !Number.isSafeInteger(entry.createdAt) || entry.createdAt <= 0 || !STATUSES.includes(entry.status) || (entry.approvalHash !== undefined && !validHash(entry.approvalHash)) || (entry.status !== "uncertain" && !entry.approvalHash)) throw new Error("invalid record");
+ return { ...request, version: 1, chainId: entry.chainId, token: approvalToken(entry.chainId), spender: spenderOf(entry.spender)!, createdAt: entry.createdAt, status: entry.status, ...(entry.approvalHash ? { approvalHash: entry.approvalHash } : {}) };
+ } catch { throw new Error("Saved token approval recovery data could not be read. Check the approval before trying again."); }
}
export function serializeApproval(approval: TrackedApproval): string {
@@ -172,7 +184,7 @@ export function recoverApprovalFromEvidence(approval: TrackedApproval, evidence:
const blockTime = Number(evidence.blockTimestamp) * 1000;
// Approvals have no order ID. Never adopt an old approval from before this attempt.
if (!Number.isSafeInteger(blockTime) || !Number.isSafeInteger(evidence.now) || blockTime < current.createdAt - 30_000 || blockTime > evidence.now + 30_000) throw new Error("This transaction predates the saved approval or your clock differs from the network. Check the hash and device clock.");
- if (!isMatchingApprovalTransaction(current, evidence.transaction) && !hasMatchingApprovalEvent(current, evidence.receipt)) throw new Error("That transaction does not match this wallet's exact USDC approval.");
+ if (!isMatchingApprovalTransaction(current, evidence.transaction) && !hasMatchingApprovalEvent(current, evidence.receipt)) throw new Error("That transaction does not match this wallet's exact token approval.");
return reconcileApproval({ ...current, approvalHash: hash }, evidence);
}
@@ -206,7 +218,7 @@ export function createApprovalStore(storage: () => StorageAdapter) {
update(address, approval, null);
return approval;
} catch {
- const message = "USDC approval recovery storage is unavailable or unreadable. Enable site storage and reload before approving.";
+ const message = "Token approval recovery storage is unavailable or unreadable. Enable site storage and reload before approving.";
update(address, snapshot.approvals[address.toLowerCase()] ?? null, message);
throw new Error(message);
}
@@ -220,7 +232,7 @@ export function createApprovalStore(storage: () => StorageAdapter) {
if (adapter.getItem(approvalStorageKey(approval.address)) !== raw) throw new Error("Storage did not retain approval");
update(approval.address, approval, null);
} catch {
- const message = "Could not save USDC approval recovery details. Keep this page open and check the approval before trying again.";
+ const message = "Could not save token approval recovery details. Keep this page open and check the approval before trying again.";
update(approval.address, approval, message);
throw new Error(message);
}
@@ -228,7 +240,7 @@ export function createApprovalStore(storage: () => StorageAdapter) {
remove(address: Address) {
try { storage().removeItem(approvalStorageKey(address)); update(address, null, null); }
catch {
- const message = "Could not clear the saved USDC approval. Enable site storage and reload before trying again.";
+ const message = "Could not clear the saved token approval. Enable site storage and reload before trying again.";
update(address, snapshot.approvals[address.toLowerCase()] ?? null, message);
throw new Error(message);
}
@@ -265,7 +277,7 @@ function walletRejected(error: unknown): boolean {
/**
* Caller must hold the same per-wallet Web Lock as deposit submission/recovery.
- * This only approves USDC. After confirmation, request and review a NEW quote;
+ * This only approves the source chain's one bridge token. After confirmation, request and review a NEW quote;
* never automatically deposit, and never put this hash in the deposit journal.
*/
export async function submitExactApproval(input: ApprovalRequest, deps: ApprovalDependencies): Promise {
@@ -291,7 +303,7 @@ export async function submitExactApproval(input: ApprovalRequest, deps: Approval
const latest = deps.readApproval(request.address);
if (approvalBlocksSubmission(latest)) throw new Error("Another approval is now being tracked. Check it before continuing.");
const createdAt = Math.max(deps.now(), (latest?.createdAt ?? 0) + 1);
- const tracked: TrackedApproval = { ...request, version: 1, chainId, token: approvalToken(chainId), spender: RELAY_APPROVAL_SPENDER, createdAt, status: "uncertain" };
+ const tracked: TrackedApproval = { ...request, version: 1, chainId, token: approvalToken(chainId), spender: request.spender ?? RELAY_APPROVAL_SPENDER, createdAt, status: "uncertain" };
serializeApproval(tracked);
const restore = () => { if (latest) deps.saveApproval(latest); else deps.removeApproval(request.address); };
try { deps.saveApproval(tracked); }
diff --git a/app/src/lib/bridge/cctp-server.test.ts b/app/src/lib/bridge/cctp-server.test.ts
new file mode 100644
index 00000000..460f47bc
--- /dev/null
+++ b/app/src/lib/bridge/cctp-server.test.ts
@@ -0,0 +1,300 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { decodeFunctionData } from "viem";
+import { CCTP_BURN_ABI, CCTP_FORWARD_HOOK, CCTP_TOKEN_MESSENGER, cctpBurnData } from "./cctp";
+import { CCTP_MAX_BURN, CCTP_UPSTREAM_PER_MINUTE, CCTP_UPSTREAM_PER_SECOND, cctpMaxFee, getCctpQuote, getCctpStatus, parseCctpFees, parseCctpStatus, parseCctpStatusRequest, type CctpStatusRequest } from "./cctp-server";
+import { validateBridgeQuote } from "./client";
+import { getBridgeQuote } from "./relay";
+import { FIXTURE_INPUT, FIXTURE_NOW, addApprovalFixture, relayChainsFixture, relayRouteFixture } from "./relay.fixture";
+import { ARBITRUM_USDC, ARC_USDC, type BridgeQuoteRequest } from "./types";
+import { BridgeApiError } from "./validation";
+import { GET as STATUS } from "../../app/api/bridge/status/route";
+
+const WALLET = "0x6376ca7e839f1c3dd7f23cc8a1a58329f60db125" as const;
+const NOW = 1_790_000_000_000;
+const REQUEST: BridgeQuoteRequest = { address: WALLET, originChainId: 42161, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC", amount: "25000000" };
+// The shape Circle's fee endpoint returned on 2026-11-10 (basis points, then the forward in USDC's smallest unit).
+const FEES = [
+ { finalityThreshold: 1000, minimumFee: 1.3, forwardFee: { low: 10_000, med: 11_000, high: 12_000 } },
+ { finalityThreshold: 2000, minimumFee: 0, forwardFee: { low: 10_000, med: 11_000, high: 12_000 } },
+];
+
+type Call = { url: string; init: RequestInit };
+type Answers = { fees?: unknown; allowance?: unknown; gas?: unknown; message?: unknown; failFees?: number };
+function circle(answers: Answers = {}) {
+ const calls: Call[] = [];
+ const fetcher = async (url: string, init: RequestInit) => {
+ calls.push({ url, init });
+ if (init.method === "POST") return Response.json({ jsonrpc: "2.0", id: 1, result: answers.gas ?? "0x5f5e100" });
+ const path = url.replace("https://iris-api.circle.com", "");
+ if (path.startsWith("/v2/burn/USDC/fees/")) return answers.failFees ? new Response("", { status: answers.failFees }) : Response.json(answers.fees ?? FEES);
+ if (path === "/v2/fastBurn/USDC/allowance") return Response.json({ allowance: answers.allowance ?? 53_837_639.760122, lastUpdated: "2026-11-10T13:15:36.376Z" });
+ if (path.startsWith("/v2/messages/")) return answers.message === undefined ? new Response("", { status: 404 }) : Response.json(answers.message);
+ throw new Error(`unexpected ${url}`);
+ };
+ return { fetcher, calls, paths: () => calls.map((call) => call.init.method === "POST" ? `rpc:${JSON.parse(String(call.init.body)).method}` : call.url.replace("https://iris-api.circle.com", "")) };
+}
+
+test("Circle's fee is read for the burn's finality, bounded, and never from an exponent or fraction of a unit", () => {
+ assert.deepEqual(parseCctpFees(FEES, 1000), { microBps: 1_300_000n, forwardFee: 12_000n });
+ assert.deepEqual(parseCctpFees(FEES, 2000), { microBps: 0n, forwardFee: 12_000n });
+ assert.deepEqual(parseCctpFees([{ finalityThreshold: 1000, minimumFee: 0.325, forwardFee: { low: 18509, med: 18959, high: 18959 } }], 1000), { microBps: 325_000n, forwardFee: 18_959n });
+ const entry = FEES[0];
+ for (const [name, value] of [
+ ["missing finality", [FEES[1]]],
+ ["empty", []],
+ ["too many", Array(9).fill(entry)],
+ ["not an array", entry],
+ ["exponent", [{ ...entry, minimumFee: 1e-7 }]],
+ ["negative", [{ ...entry, minimumFee: -1 }]],
+ ["string", [{ ...entry, minimumFee: "1.3" }]],
+ ["seven decimals", [{ ...entry, minimumFee: 1.0000001 }]],
+ ["over 1%", [{ ...entry, minimumFee: 100.000001 }]],
+ ["forward over $5", [{ ...entry, forwardFee: { high: 5_000_001 } }]],
+ ["forward fraction", [{ ...entry, forwardFee: { high: 12_000.5 } }]],
+ ["no forward", [{ ...entry, forwardFee: null }]],
+ ] as const) assert.throws(() => parseCctpFees(value, 1000), (error) => error instanceof BridgeApiError && error.status === 502, name);
+});
+
+test("the whole fee is Circle's share of the amount rounded up, plus the forward", () => {
+ assert.equal(cctpMaxFee(25_000_000n, { microBps: 1_300_000n, forwardFee: 12_000n }), 15_250n);
+ assert.equal(cctpMaxFee(25_000_000n, { microBps: 325_000n, forwardFee: 18_959n }), 813n + 18_959n);
+ assert.equal(cctpMaxFee(1n, { microBps: 1n, forwardFee: 0n }), 1n);
+ assert.equal(cctpMaxFee(25_000_000n, { microBps: 0n, forwardFee: 63_895n }), 63_895n);
+});
+
+test("a Circle quote is built from pinned contracts and the bounded fee, and passes the browser's own check", async () => {
+ const c = circle();
+ const quote = await getCctpQuote(REQUEST, c.fetcher, () => NOW);
+ assert.ok(quote);
+ assert.deepEqual(c.paths().sort(), ["/v2/burn/USDC/fees/3/6?forward=true", "/v2/fastBurn/USDC/allowance", "rpc:eth_gasPrice"]);
+ assert.equal(quote.provider, "cctp");
+ assert.match(quote.requestId, /^0x[0-9a-f]{64}$/);
+ assert.equal(quote.amountOut, "24984750");
+ assert.equal(quote.minimumAmountOut, "24984750");
+ assert.equal(quote.relayFee, "0.01525");
+ assert.equal(quote.sourceGas, "0.000022");
+ assert.equal(quote.totalImpactPercent, "-0.061");
+ assert.equal(quote.timeEstimate, 25);
+ assert.equal(quote.expiresAt, NOW + 45_000);
+ assert.deepEqual(quote.approval, { token: ARBITRUM_USDC, spender: CCTP_TOKEN_MESSENGER, amount: "25000000" });
+ assert.deepEqual(quote.transaction, { to: CCTP_TOKEN_MESSENGER, data: cctpBurnData(REQUEST, 15_250n), value: "0", chainId: 42161 });
+ const args = decodeFunctionData({ abi: CCTP_BURN_ABI, data: quote.transaction.data }).args;
+ assert.deepEqual([args[0], args[1], args[5], args[6], args[7]], [25_000_000n, 6, 15_250n, 1000, CCTP_FORWARD_HOOK]);
+ assert.deepEqual(validateBridgeQuote(quote, REQUEST, NOW), quote);
+ // every request is a plain GET or one read-only RPC call, with no redirects followed
+ for (const call of c.calls) assert.equal(call.init.redirect, "error");
+});
+
+test("an Arc burn is Standard: no Fast capacity is asked, and Arc's 18-decimal balance receives it", async () => {
+ const c = circle({ fees: [{ finalityThreshold: 2000, minimumFee: 0, forwardFee: { low: 54811, med: 62505, high: 63895 } }] });
+ const request: BridgeQuoteRequest = { address: WALLET, originChainId: 5042, destinationChainId: 8453, destinationAsset: "USDC", amount: "25000000" };
+ const quote = await getCctpQuote(request, c.fetcher, () => NOW);
+ assert.ok(quote);
+ assert.deepEqual(c.paths().sort(), ["/v2/burn/USDC/fees/26/6?forward=true", "rpc:eth_gasPrice"]);
+ assert.equal(decodeFunctionData({ abi: CCTP_BURN_ABI, data: quote.transaction.data }).args[6], 2000);
+ assert.equal(quote.approval?.token, ARC_USDC);
+ assert.equal(quote.amountOut, (25_000_000n - 63_895n).toString());
+ assert.equal(quote.timeEstimate, 15);
+ const inbound = await getCctpQuote({ address: WALLET, originChainId: 8453, destinationChainId: 5042, originAsset: "USDC", amount: "25000000" }, circle().fetcher, () => NOW);
+ assert.equal(inbound?.amountOut, ((25_000_000n - 15_250n) * 10n ** 12n).toString());
+});
+
+test("Circle offers nothing it cannot carry right now, without asking when the answer is already known", async () => {
+ const none = circle();
+ for (const request of [
+ { ...REQUEST, destinationAsset: "ETH" as const },
+ { ...REQUEST, originChainId: 4663 as const, originAsset: "USDG" as const },
+ { ...REQUEST, amount: (CCTP_MAX_BURN + 1n).toString() },
+ ]) assert.equal(await getCctpQuote(request, none.fetcher, () => NOW), null);
+ assert.equal(none.calls.length, 0);
+ // Fast capacity below the amount: Circle would fall back to Standard and charge the Fast fee
+ assert.equal(await getCctpQuote(REQUEST, circle({ allowance: 24.999999 }).fetcher, () => NOW), null);
+ assert.ok(await getCctpQuote(REQUEST, circle({ allowance: 25 }).fetcher, () => NOW));
+ // above 5% in fees: 0.2 USDC pays a 0.012 forward
+ assert.equal(await getCctpQuote({ ...REQUEST, amount: "200000" }, circle().fetcher, () => NOW), null);
+});
+
+test("Circle and RPC failures throw, and a failure is never reused", async () => {
+ const busy = circle({ failFees: 429 });
+ await assert.rejects(getCctpQuote(REQUEST, busy.fetcher, () => NOW), (error) => error instanceof BridgeApiError && error.status === 429);
+ await assert.rejects(getCctpQuote(REQUEST, circle({ failFees: 500 }).fetcher, () => NOW), (error) => error instanceof BridgeApiError && error.status === 502);
+ await assert.rejects(getCctpQuote(REQUEST, circle({ fees: [FEES[1]] }).fetcher, () => NOW), (error) => error instanceof BridgeApiError && error.status === 502);
+ await assert.rejects(getCctpQuote(REQUEST, circle({ gas: "0x0" }).fetcher, () => NOW), BridgeApiError);
+ await assert.rejects(getCctpQuote(REQUEST, circle({ gas: 1 }).fetcher, () => NOW), BridgeApiError);
+ await assert.rejects(getCctpQuote(REQUEST, circle({ allowance: "lots" }).fetcher, () => NOW), BridgeApiError);
+ await assert.rejects(getCctpQuote(REQUEST, busy.fetcher, () => NOW + 1), BridgeApiError);
+ assert.equal(busy.paths().filter((path) => path.startsWith("/v2/burn")).length, 2);
+});
+
+test("Circle's fee and capacity answers are reused briefly", async () => {
+ const c = circle();
+ await getCctpQuote(REQUEST, c.fetcher, () => NOW);
+ await getCctpQuote({ ...REQUEST, amount: "30000000" }, c.fetcher, () => NOW + 10_000);
+ assert.equal(c.paths().filter((path) => path.startsWith("/v2/burn")).length, 1);
+ assert.equal(c.paths().filter((path) => path.startsWith("/v2/fastBurn")).length, 1);
+ await getCctpQuote(REQUEST, c.fetcher, () => NOW + 31_000);
+ assert.equal(c.paths().filter((path) => path.startsWith("/v2/burn")).length, 2);
+});
+
+const statusRequest = (n: number): CctpStatusRequest => ({ originChainId: 42161, destinationChainId: 8453, hash: `0x${n.toString(16).padStart(64, "0")}`, address: WALLET, amount: "25000000" });
+const circleBusy = (error: unknown) => error instanceof BridgeApiError && error.status === 429;
+
+test("Circle quotes and statuses share one rolling burst budget, and cache hits cost nothing", async () => {
+ const c = circle();
+ const burstAt = NOW + 999;
+ await getCctpQuote(REQUEST, c.fetcher, () => burstAt);
+ // The quote uses two Circle requests plus one RPC read. Only Circle counts toward this budget.
+ for (let n = 1; n <= CCTP_UPSTREAM_PER_SECOND - 2; n++) await getCctpStatus(statusRequest(n), c.fetcher, () => burstAt);
+ const next = statusRequest(CCTP_UPSTREAM_PER_SECOND);
+ await assert.rejects(getCctpStatus(next, c.fetcher, () => burstAt), circleBusy);
+ await assert.rejects(getCctpStatus(next, c.fetcher, () => NOW + 1_000), circleBusy);
+ assert.deepEqual(await getCctpStatus(statusRequest(1), c.fetcher, () => NOW + 1_000), { status: "waiting", inTxHashes: [], txHashes: [] });
+ assert.equal(c.calls.length, CCTP_UPSTREAM_PER_SECOND + 1);
+ await getCctpStatus(next, c.fetcher, () => burstAt + 1_000);
+ assert.equal(c.calls.length, CCTP_UPSTREAM_PER_SECOND + 2);
+});
+
+test("Circle caps sustained traffic even below its burst limit", async () => {
+ const status = circle();
+ for (let n = 1; n <= CCTP_UPSTREAM_PER_MINUTE; n++) await getCctpStatus(statusRequest(n), status.fetcher, () => NOW + (n - 1) * 100);
+ const next = statusRequest(CCTP_UPSTREAM_PER_MINUTE + 1);
+ await assert.rejects(getCctpStatus(next, status.fetcher, () => NOW + 59_999), circleBusy);
+ await getCctpStatus(next, status.fetcher, () => NOW + 60_000);
+ assert.equal(status.calls.length, CCTP_UPSTREAM_PER_MINUTE + 1);
+});
+
+test("the status route takes exactly one Circle burn: route, transaction, wallet and amount", () => {
+ const hash = `0x${"AB".repeat(32)}`;
+ const params = (patch: Record = {}) => {
+ const values: Record = { provider: "cctp", origin: "42161", destination: "8453", hash, address: WALLET.toUpperCase().replace("0X", "0x"), amount: "25000000", ...patch };
+ return new URLSearchParams(Object.entries(values).filter((entry): entry is [string, string] => entry[1] !== null));
+ };
+ assert.deepEqual(parseCctpStatusRequest(params()), { originChainId: 42161, destinationChainId: 8453, hash: hash.toLowerCase(), address: WALLET, amount: "25000000" });
+ const duplicate = params();
+ duplicate.append("hash", hash);
+ for (const [name, value] of [
+ ["provider", params({ provider: "relay" })],
+ ["missing", params({ amount: null })],
+ ["extra", new URLSearchParams([...params(), ["requestId", hash]])],
+ ["duplicate", duplicate],
+ ["not a Circle route", params({ origin: "4663" })],
+ ["funding destination", params({ destination: "1" })],
+ ["origin text", params({ origin: "42161.0" })],
+ ["hash", params({ hash: "0x1234" })],
+ ["zero address", params({ address: `0x${"0".repeat(40)}` })],
+ ["address", params({ address: "0x1234" })],
+ ["zero amount", params({ amount: "0" })],
+ ["leading zero", params({ amount: "025000000" })],
+ ["over the limit", params({ amount: (CCTP_MAX_BURN + 1n).toString() })],
+ ] as const) assert.throws(() => parseCctpStatusRequest(value), (error) => error instanceof BridgeApiError && error.status === 400, name);
+});
+
+// Circle's record of a real forwarded burn, Ethereum USDC to Arc (transaction 0x0095…ce01), read on 2026-11-10.
+const BURN_HASH = "0x009551050ec596b833a8957d635c759dbd22b63d45977c9d4cde5dcc79bece01" as const;
+const MINT_HASH = "0xec343f34384181675084e7bb39863235c060fa075521984a2a22eedd05029531" as const;
+const RECORD = {
+ eventNonce: "0x355ab67f28b1f2bc40b323e4278f3995aba6858f3d7f7a2d6e161dd44bdbbaea", cctpVersion: 2, status: "complete",
+ decodedMessage: {
+ sourceDomain: "0", destinationDomain: "26", nonce: "0x355ab67f28b1f2bc40b323e4278f3995aba6858f3d7f7a2d6e161dd44bdbbaea",
+ sender: "0x28b5a0e9c621a5badaa536219b3a228c8168cf5d", recipient: "0x28b5a0e9c621a5badaa536219b3a228c8168cf5d",
+ destinationCaller: `0x${"0".repeat(64)}`, minFinalityThreshold: "1000", finalityThresholdExecuted: "1000",
+ decodedMessageBody: {
+ burnToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", mintRecipient: WALLET, amount: "2343317655", messageSender: WALLET,
+ maxFee: "89262", feeExecuted: "89262", expirationBlock: "30692704", hookData: CCTP_FORWARD_HOOK,
+ },
+ decodedCctpXMessageBody: null,
+ },
+ delayReason: null, forwardState: "COMPLETE", forwardTxHash: MINT_HASH, destinationMintTxHash: MINT_HASH,
+};
+const STATUS_REQUEST: CctpStatusRequest = { originChainId: 1, destinationChainId: 5042, hash: BURN_HASH, address: WALLET, amount: "2343317655" };
+type Record_ = typeof RECORD;
+const record = (patch: Partial = {}, body: Partial = {}, message: Partial = {}) =>
+ ({ ...RECORD, ...patch, decodedMessage: { ...RECORD.decodedMessage, ...message, decodedMessageBody: { ...RECORD.decodedMessage.decodedMessageBody, ...body } } });
+
+test("Circle's record maps onto the bridge's statuses only when it is this wallet's burn", () => {
+ const status = (value: unknown) => parseCctpStatus({ messages: [value] }, STATUS_REQUEST);
+ assert.deepEqual(status(RECORD), { status: "success", inTxHashes: [BURN_HASH], txHashes: [MINT_HASH] });
+ assert.equal(status(record({ forwardState: "PENDING", forwardTxHash: null as unknown as string })).status, "submitted");
+ assert.equal(status(record({ forwardState: "FAILED", forwardTxHash: null as unknown as string })).status, "delayed");
+ assert.equal(status(record({ forwardState: "PENDING", delayReason: "insufficient_fee" as unknown as null })).status, "delayed");
+ assert.equal(status(record({ status: "pending_confirmations", forwardState: "PENDING" })).status, "pending");
+ assert.equal(status(record({ status: "pending_confirmations", forwardState: "PENDING", delayReason: "insufficient_allowance_available" as unknown as null })).status, "delayed");
+ // before Circle decodes the burn, a lone record only says it is pending
+ assert.deepEqual(status({ status: "pending_confirmations", decodedMessage: null }), { status: "pending", inTxHashes: [BURN_HASH], txHashes: [] });
+ for (const [name, value] of [
+ ["recipient", record({}, { mintRecipient: "0x1111111111111111111111111111111111111111" })],
+ ["sender", record({}, { messageSender: "0x1111111111111111111111111111111111111111" })],
+ ["amount", record({}, { amount: "2343317656" })],
+ ["token", record({}, { burnToken: ARBITRUM_USDC.toLowerCase() })],
+ ["hook", record({}, { hookData: "0x" })],
+ ["destination", record({}, {}, { destinationDomain: "6" })],
+ ["source", record({}, {}, { sourceDomain: "3" })],
+ ["finality", record({}, {}, { minFinalityThreshold: "2000" })],
+ ["delivered without a hash", record({ forwardTxHash: "0x1234" })],
+ ["unknown status", record({ status: "lost" })],
+ ["undecoded and complete", { status: "complete", decodedMessage: null }],
+ ] as const) assert.throws(() => status(value), (error) => error instanceof BridgeApiError && error.status === 502, name);
+ assert.throws(() => parseCctpStatus({ messages: [RECORD, RECORD] }, STATUS_REQUEST), BridgeApiError);
+ assert.throws(() => parseCctpStatus({ messages: [] }, STATUS_REQUEST), BridgeApiError);
+ assert.deepEqual(parseCctpStatus({ messages: [record({}, { amount: "1" }), RECORD] }, STATUS_REQUEST).status, "success");
+});
+
+test("Circle status asks by source domain and transaction, and an unknown burn is still waiting", async () => {
+ const unseen = circle();
+ assert.deepEqual(await getCctpStatus(STATUS_REQUEST, unseen.fetcher, () => NOW), { status: "waiting", inTxHashes: [], txHashes: [] });
+ assert.deepEqual(unseen.paths(), [`/v2/messages/0?transactionHash=${BURN_HASH}`]);
+ assert.equal((await getCctpStatus(STATUS_REQUEST, circle({ message: { messages: [RECORD] } }).fetcher, () => NOW)).status, "success");
+});
+
+function relayAndCircle(circleAnswers: Answers, relayFails = false) {
+ const { input, quote } = relayRouteFixture(8453, 5042, "USDC", "USDC");
+ addApprovalFixture(quote, input);
+ const relay = async (url: string) => {
+ if (url.endsWith("/chains")) return Response.json(relayChainsFixture());
+ return relayFails ? new Response("", { status: 500 }) : Response.json(quote);
+ };
+ return { input, relay, circle: circle(circleAnswers) };
+}
+// Base to Arc, 25 USDC: Relay delivers 24.94; Circle's Fast fee here is 0.325 bp plus the forward.
+const BASE_ARC_FEES = (forward: number) => [{ finalityThreshold: 1000, minimumFee: 0.325, forwardFee: { low: forward, med: forward, high: forward } }];
+
+test("the bridge quotes Relay and Circle together and offers whichever delivers more", async () => {
+ const cheaper = relayAndCircle({ fees: BASE_ARC_FEES(18_959) });
+ const viaCircle = await getBridgeQuote(cheaper.input, cheaper.relay, () => FIXTURE_NOW, cheaper.circle.fetcher);
+ assert.equal(viaCircle.provider, "cctp");
+ assert.equal(viaCircle.amountOut, ((25_000_000n - 813n - 18_959n) * 10n ** 12n).toString());
+
+ const dearer = relayAndCircle({ fees: BASE_ARC_FEES(100_000) });
+ const viaRelay = await getBridgeQuote(dearer.input, dearer.relay, () => FIXTURE_NOW, dearer.circle.fetcher);
+ assert.equal(viaRelay.provider, undefined);
+ assert.equal(viaRelay.amountOut, ((25_000_000n - 60_000n) * 10n ** 12n).toString());
+
+ // one side failing leaves the other; Relay's error stands when neither can quote
+ const relayDown = relayAndCircle({ fees: BASE_ARC_FEES(100_000) }, true);
+ assert.equal((await getBridgeQuote(relayDown.input, relayDown.relay, () => FIXTURE_NOW, relayDown.circle.fetcher)).provider, "cctp");
+ const circleDown = relayAndCircle({ failFees: 500 });
+ assert.equal((await getBridgeQuote(circleDown.input, circleDown.relay, () => FIXTURE_NOW, circleDown.circle.fetcher)).provider, undefined);
+ const bothDown = relayAndCircle({ failFees: 500 }, true);
+ await assert.rejects(getBridgeQuote(bothDown.input, bothDown.relay, () => FIXTURE_NOW, bothDown.circle.fetcher), (error) => error instanceof BridgeApiError && /No bridge quote/.test(error.message));
+});
+
+test("routes Circle cannot carry never ask Circle, and injected fetchers leave Circle out by default", async () => {
+ const c = circle();
+ const { quote } = relayRouteFixture(8453, 4663);
+ await getBridgeQuote(FIXTURE_INPUT, async (url) => Response.json(url.endsWith("/chains") ? relayChainsFixture() : quote), () => FIXTURE_NOW, c.fetcher);
+ assert.equal(c.calls.length, 0);
+ const { input, relay } = relayAndCircle({});
+ assert.equal((await getBridgeQuote(input, relay, () => FIXTURE_NOW)).provider, undefined);
+});
+
+
+test("HTTP status boundary sends a malformed Circle request nowhere and answers privately", async () => {
+ const hash = `0x${"ab".repeat(32)}`;
+ const base = `provider=cctp&origin=42161&destination=8453&hash=${hash}&address=${WALLET}&amount=25000000`;
+ for (const query of [`${base}&requestId=${hash}`, base.replace("cctp", "relay"), base.replace("8453", "4663"), base.replace("25000000", "0"), "provider=cctp"]) {
+ const response = await STATUS(new Request(`https://openlaunch.example/api/bridge/status?${query}`, { headers: { "fly-client-ip": "bridge-cctp-status-invalid" } }));
+ assert.equal(response.status, 400, query);
+ assert.match(response.headers.get("cache-control")!, /private, no-store/);
+ }
+});
diff --git a/app/src/lib/bridge/cctp-server.ts b/app/src/lib/bridge/cctp-server.ts
new file mode 100644
index 00000000..b53a13ea
--- /dev/null
+++ b/app/src/lib/bridge/cctp-server.ts
@@ -0,0 +1,235 @@
+import "server-only";
+import { formatEther, formatUnits, isAddress, parseUnits, toHex, type Hex } from "viem";
+import { CCTP_FAST_FINALITY, CCTP_FORWARD_HOOK, CCTP_MAX_FEE_PERCENT, CCTP_TOKEN_MESSENGER, cctpAmountOut, cctpBurnData, cctpRoute, type CctpRoute } from "./cctp";
+import { readBridgeJson } from "./read-json";
+import { bridgeRpcUpstream } from "./rpc";
+import { bridgeFeePercent, isBridgeChainId, type BridgeChainId, type BridgeQuote, type BridgeQuoteRequest, type BridgeStatus, type BridgeStatusResponse } from "./types";
+import { BridgeApiError, QUOTE_TTL_MS, isRequestId } from "./validation";
+
+/**
+ * Circle's side of the bridge: a CCTP quote built entirely from pinned values plus Circle's published fee, and the
+ * status of a burn read from Circle's attestation service. Circle never supplies calldata, an address or a recipient
+ * here; its answers only set the fee (bounded below) and report progress. Any failure returns no Circle quote, so
+ * Relay's quote or error stands exactly as before.
+ */
+const IRIS = "https://iris-api.circle.com";
+const TIMEOUT_MS = 8_000;
+type Fetcher = (url: string, init: RequestInit) => Promise;
+type ObjectValue = Record;
+
+/** Circle burns at most 10,000,000 USDC per message (TokenMinterV2.burnLimitsPerMessage, read on all five networks). */
+export const CCTP_MAX_BURN = 10_000_000_000_000n;
+/** The fee tier never goes above 1% of the amount, nor the forwarding fee above $5, whatever the API says. */
+const MAX_FEE_MICRO_BPS = 100_000_000n;
+const MAX_FORWARD_FEE = 5_000_000n;
+/** Gas a forwarded burn uses on the source network, for the estimate shown before the wallet is asked (~150k observed). */
+export const CCTP_BURN_GAS = 220_000n;
+/** Seconds to arrival: Fast attestation (about 8 s on the rollups, 20 s on Ethereum, 0.5 s on Arc) plus Circle's forward. */
+const CCTP_SECONDS: Record = { 8453: 25, 42161: 25, 10: 25, 1: 40, 5042: 15, 4663: 0, 99901: 0 };
+
+// Circle blocks requests for five minutes above 40 per second. All Circle endpoints share rolling budgets within
+// this process. Keep headroom for other workers sharing the same egress IP.
+export const CCTP_UPSTREAM_PER_SECOND = 15;
+export const CCTP_UPSTREAM_PER_MINUTE = 600;
+const FEES_TTL_MS = 30_000;
+const ALLOWANCE_TTL_MS = 15_000;
+const STATUS_TTL_MS = 5_000;
+type Cached = { at: number; value: Promise };
+const caches = new WeakMap>>();
+const budgets = new WeakMap();
+
+function ensure(condition: unknown, message = "Circle returned an unreadable answer."): asserts condition {
+ if (!condition) throw new BridgeApiError(message, 502);
+}
+function object(value: unknown): ObjectValue {
+ ensure(value && typeof value === "object" && !Array.isArray(value));
+ return value as ObjectValue;
+}
+/** A JSON number as an exact decimal with at most `decimals` places: no exponents, no negatives. */
+function decimal(value: unknown, decimals: number): bigint {
+ ensure(typeof value === "number" && Number.isFinite(value) && value >= 0);
+ const text = String(value);
+ ensure(text.length <= 40 && (decimals > 0 ? new RegExp(`^\\d+(?:\\.\\d{1,${decimals}})?$`) : /^\d+$/).test(text));
+ return parseUnits(text, decimals);
+}
+
+function spend(fetcher: Fetcher, at: number) {
+ const previous = budgets.get(fetcher) ?? [];
+ // A backward clock adjustment must not open a fresh window.
+ const now = Math.max(at, previous.at(-1) ?? at);
+ const recent = previous.filter((sentAt) => now - sentAt < 60_000);
+ const burst = recent.filter((sentAt) => now - sentAt < 1_000).length;
+ if (recent.length >= CCTP_UPSTREAM_PER_MINUTE || burst >= CCTP_UPSTREAM_PER_SECOND) {
+ throw new BridgeApiError("Circle is busy. Please try again shortly.", 429);
+ }
+ recent.push(now);
+ budgets.set(fetcher, recent);
+}
+
+/** One reused answer per key for `ttl`; a failure is never kept, so the next caller asks again. */
+function cached(fetcher: Fetcher, key: string, ttl: number, at: number, load: () => Promise): Promise {
+ let cache = caches.get(fetcher);
+ if (!cache) caches.set(fetcher, cache = new Map());
+ const hit = cache.get(key) as Cached | undefined;
+ if (hit && at - hit.at < ttl && at >= hit.at) return hit.value;
+ spend(fetcher, at);
+ const value = load();
+ if (cache.size >= 1_000) cache.clear();
+ cache.set(key, { at, value });
+ value.catch(() => { if (cache.get(key)?.value === value) cache.delete(key); });
+ return value;
+}
+
+async function iris(path: string, fetcher: Fetcher, maxBytes: number): Promise<{ status: number; body: unknown }> {
+ let response: Response;
+ try {
+ response = await fetcher(`${IRIS}${path}`, { method: "GET", cache: "no-store", redirect: "error", signal: AbortSignal.timeout(TIMEOUT_MS), headers: { Accept: "application/json" } });
+ } catch { throw new BridgeApiError("Circle is unavailable right now.", 502); }
+ if (response.status === 429) throw new BridgeApiError("Circle is busy. Please try again shortly.", 429);
+ if (response.status === 404) { void response.body?.cancel().catch(() => {}); return { status: 404, body: null }; }
+ if (!response.ok) { void response.body?.cancel().catch(() => {}); throw new BridgeApiError("Circle is unavailable right now.", 502); }
+ return { status: response.status, body: await readBridgeJson(response.body, maxBytes, TIMEOUT_MS) };
+}
+
+export type CctpFee = { microBps: bigint; forwardFee: bigint };
+/** Circle's fee for this route at the burn's finality: basis points (kept to six decimals) and the forwarding fee. */
+export function parseCctpFees(value: unknown, finality: number): CctpFee {
+ ensure(Array.isArray(value) && value.length > 0 && value.length <= 8);
+ const entry = object(value.find((item) => object(item).finalityThreshold === finality));
+ const microBps = decimal(entry.minimumFee, 6);
+ // Circle recommends its middle tier or higher; the high tier costs fractions of a cent more and never under-pays a
+ // forward when gas moves between the quote and the burn.
+ const forwardFee = decimal(object(entry.forwardFee).high, 0);
+ ensure(microBps <= MAX_FEE_MICRO_BPS && forwardFee <= MAX_FORWARD_FEE);
+ return { microBps, forwardFee };
+}
+
+/** The whole fee a burn may take: Circle's fee on the amount, rounded up, plus the forward. */
+export function cctpMaxFee(amount: bigint, fee: CctpFee): bigint {
+ const protocol = (amount * fee.microBps + 10_000_000_000n - 1n) / 10_000_000_000n;
+ return protocol + fee.forwardFee;
+}
+
+async function gasPrice(chainId: BridgeChainId, fetcher: Fetcher): Promise {
+ const upstream = bridgeRpcUpstream(chainId);
+ ensure(upstream, "No RPC for this network.");
+ const response = await fetcher(upstream, { method: "POST", cache: "no-store", redirect: "error", signal: AbortSignal.timeout(TIMEOUT_MS), headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_gasPrice", params: [] }) });
+ ensure(response.ok);
+ const result = object(await readBridgeJson(response.body, 4_096, TIMEOUT_MS)).result;
+ ensure(typeof result === "string" && /^0x[0-9a-fA-F]{1,32}$/.test(result));
+ const price = BigInt(result);
+ ensure(price > 0n && price < 10n ** 15n);
+ return price;
+}
+
+const randomId = (): Hex => toHex(crypto.getRandomValues(new Uint8Array(32)));
+
+/**
+ * A Circle quote for a USDC to USDC route between Circle networks, or null when Circle cannot carry it right now:
+ * not a Circle route, above the per-burn limit, more than 5% in fees, or Fast Transfer capacity below the amount.
+ * Throws only when Circle or the source RPC fails; the caller then keeps Relay's answer.
+ */
+export async function getCctpQuote(input: BridgeQuoteRequest, fetcher: Fetcher, now: () => number = Date.now): Promise {
+ const route = cctpRoute(input);
+ const amount = BigInt(input.amount);
+ if (!route || amount <= 0n || amount > CCTP_MAX_BURN) return null;
+ const at = now();
+ const [fees, allowance, price] = await Promise.all([
+ cached(fetcher, `fees:${route.sourceDomain}:${route.destinationDomain}`, FEES_TTL_MS, at, () => iris(`/v2/burn/USDC/fees/${route.sourceDomain}/${route.destinationDomain}?forward=true`, fetcher, 8_192).then(({ status, body }) => { ensure(status === 200); return parseCctpFees(body, route.finality); })),
+ // Fast Transfer draws on one global allowance; a Standard burn (Arc) does not.
+ route.finality === CCTP_FAST_FINALITY ? cached(fetcher, "allowance", ALLOWANCE_TTL_MS, at, () => iris("/v2/fastBurn/USDC/allowance", fetcher, 1_024).then(({ status, body }) => { ensure(status === 200); return decimal(object(body).allowance, 6); })) : Promise.resolve(null),
+ gasPrice(input.originChainId, fetcher),
+ ]);
+ if (allowance !== null && allowance < amount) return null;
+ const maxFee = cctpMaxFee(amount, fees);
+ if (maxFee <= 0n || maxFee >= amount || maxFee * 100n > amount * CCTP_MAX_FEE_PERCENT) return null;
+ return cctpQuoteFrom(input, route, maxFee, price, at);
+}
+
+/** The quote itself, from pinned contracts and the bounded fee alone. */
+export function cctpQuoteFrom(input: BridgeQuoteRequest, route: CctpRoute, maxFee: bigint, gasPriceWei: bigint, at: number): BridgeQuote {
+ const amount = BigInt(input.amount);
+ const amountOut = cctpAmountOut(amount, maxFee, route.outputDecimals).toString();
+ const expiresAt = at + QUOTE_TTL_MS;
+ return {
+ ...input, provider: "cctp", requestId: randomId(), amountOut, minimumAmountOut: amountOut,
+ relayFee: formatUnits(maxFee, 6), sourceGas: formatEther(gasPriceWei * CCTP_BURN_GAS),
+ totalImpactPercent: `-${bridgeFeePercent(maxFee, amount)}`,
+ approval: { token: route.burnToken, spender: CCTP_TOKEN_MESSENGER, amount: input.amount },
+ timeEstimate: CCTP_SECONDS[input.originChainId], expiresAt, ttlMs: QUOTE_TTL_MS,
+ transaction: { to: CCTP_TOKEN_MESSENGER, data: cctpBurnData(input, maxFee), value: "0", chainId: input.originChainId },
+ };
+}
+
+export type CctpStatusRequest = { originChainId: BridgeChainId; destinationChainId: BridgeChainId; hash: Hex; address: Hex; amount: string };
+
+/** The status route's Circle parameters, exactly: provider, origin, destination, hash, address and amount. */
+export function parseCctpStatusRequest(params: URLSearchParams): CctpStatusRequest {
+ const keys = ["provider", "origin", "destination", "hash", "address", "amount"];
+ const invalid = () => new BridgeApiError("Invalid Circle transfer.", 400);
+ if (params.size !== keys.length || !keys.every((key) => params.getAll(key).length === 1) || params.get("provider") !== "cctp") throw invalid();
+ const originChainId = Number(params.get("origin"));
+ const destinationChainId = Number(params.get("destination"));
+ const hash = params.get("hash")!;
+ const address = params.get("address")!;
+ const amount = params.get("amount")!;
+ if (!/^\d{1,6}$/.test(params.get("origin")!) || !/^\d{1,6}$/.test(params.get("destination")!) || !isBridgeChainId(originChainId) || !isBridgeChainId(destinationChainId)) throw invalid();
+ if (!cctpRoute({ originChainId, destinationChainId, originAsset: "USDC", destinationAsset: "USDC" })) throw invalid();
+ if (!isRequestId(hash) || !isAddress(address, { strict: false }) || /^0x0{40}$/i.test(address) || !/^[1-9]\d{0,77}$/.test(amount) || BigInt(amount) > CCTP_MAX_BURN) throw invalid();
+ return { originChainId, destinationChainId, hash: hash.toLowerCase() as Hex, address: address.toLowerCase() as Hex, amount };
+}
+
+const lower = (value: unknown) => typeof value === "string" ? value.toLowerCase() : null;
+
+/**
+ * Circle's record of one burn, mapped onto the bridge's statuses. Not found yet is "waiting". A record must name this
+ * wallet, amount, token, route and the forwarding hook before it counts; one that names anything else is an error,
+ * never progress. Delivered means attested, and the mint forwarded with a destination transaction hash.
+ */
+export function parseCctpStatus(value: unknown, request: CctpStatusRequest): BridgeStatusResponse {
+ const route = cctpRoute({ ...request, originAsset: "USDC", destinationAsset: "USDC" })!;
+ const messages = object(value).messages;
+ ensure(Array.isArray(messages) && messages.length >= 1 && messages.length <= 10);
+ const matches = messages.map(object).filter((message) => {
+ const decoded = message.decodedMessage;
+ if (!decoded || typeof decoded !== "object") return false;
+ const m = decoded as ObjectValue;
+ const body = m.decodedMessageBody && typeof m.decodedMessageBody === "object" ? m.decodedMessageBody as ObjectValue : null;
+ return !!body && m.sourceDomain === String(route.sourceDomain) && m.destinationDomain === String(route.destinationDomain)
+ && lower(body.burnToken) === route.burnToken.toLowerCase() && lower(body.mintRecipient) === request.address && lower(body.messageSender) === request.address
+ && body.amount === request.amount && lower(body.hookData) === CCTP_FORWARD_HOOK && m.minFinalityThreshold === String(route.finality);
+ });
+ // Before attestation Circle may not have decoded the burn yet; a lone undecoded record only says it is pending.
+ if (matches.length === 0) {
+ const pending = messages.length === 1 && !object(messages[0]).decodedMessage && ["pending_confirmations", "pending"].includes(String(object(messages[0]).status));
+ ensure(pending, "Circle's record does not match this transfer.");
+ return { status: "pending", inTxHashes: [request.hash], txHashes: [] };
+ }
+ ensure(matches.length === 1, "Circle's record does not match this transfer.");
+ const message = matches[0];
+ const delayed = typeof message.delayReason === "string" && message.delayReason.length > 0;
+ let status: BridgeStatus;
+ const txHashes: Hex[] = [];
+ if (message.status === "complete") {
+ const forwardHash = message.forwardTxHash;
+ if (message.forwardState === "COMPLETE") {
+ ensure(isRequestId(forwardHash));
+ status = "success";
+ txHashes.push(forwardHash);
+ } else status = delayed || (message.forwardState !== undefined && message.forwardState !== null && message.forwardState !== "PENDING") ? "delayed" : "submitted";
+ } else {
+ ensure(["pending_confirmations", "pending"].includes(String(message.status)));
+ status = delayed ? "delayed" : "pending";
+ }
+ return { status, inTxHashes: [request.hash], txHashes };
+}
+
+export async function getCctpStatus(request: CctpStatusRequest, fetcher: Fetcher = fetch, now: () => number = Date.now): Promise {
+ const domain = cctpRoute({ ...request, originAsset: "USDC", destinationAsset: "USDC" })!.sourceDomain;
+ const key = `status:${domain}:${request.hash}:${request.address}:${request.amount}:${request.destinationChainId}`;
+ return cached(fetcher, key, STATUS_TTL_MS, now(), async () => {
+ const { status, body } = await iris(`/v2/messages/${domain}?transactionHash=${request.hash}`, fetcher, 64_000);
+ if (status === 404) return { status: "waiting", inTxHashes: [], txHashes: [] } satisfies BridgeStatusResponse;
+ return parseCctpStatus(body, request);
+ });
+}
diff --git a/app/src/lib/bridge/cctp.live.test.ts b/app/src/lib/bridge/cctp.live.test.ts
new file mode 100644
index 00000000..b7a4a73c
--- /dev/null
+++ b/app/src/lib/bridge/cctp.live.test.ts
@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createPublicClient, http } from "viem";
+import { CCTP_DESTINATIONS, CCTP_DOMAINS, CCTP_TOKEN_MESSENGER, cctpBurnData, cctpRoute, isCctpBurnLog } from "./cctp.ts";
+import { getCctpQuote, getCctpStatus } from "./cctp-server.ts";
+import { validateBridgeQuote, type TrackedBridgeTransfer } from "./client.ts";
+import { BRIDGE_CHAINS, type BridgeChainId } from "./types.ts";
+
+// Explicit opt-in, read-only: Circle's public fee and message endpoints and public RPC nodes. No wallet, no signing.
+const live = { skip: process.env.RUN_BRIDGE_LIVE_TESTS !== "1" };
+const DUMMY = "0x1111111111111111111111111111111111111111" as const;
+
+for (const originChainId of Object.keys(CCTP_DOMAINS).map(Number) as BridgeChainId[]) for (const destinationChainId of CCTP_DESTINATIONS) {
+ if (originChainId === destinationChainId) continue;
+ test(`read-only live Circle quote ${BRIDGE_CHAINS[originChainId].name} USDC to ${BRIDGE_CHAINS[destinationChainId].name} USDC`, live, async (t) => {
+ const request = { address: DUMMY, originChainId, destinationChainId, originAsset: "USDC" as const, destinationAsset: "USDC" as const, amount: "25000000" };
+ assert.ok(cctpRoute(request));
+ const quote = await getCctpQuote(request, fetch);
+ assert.ok(quote, "Circle offered no quote");
+ assert.deepEqual(validateBridgeQuote(quote, request, Date.now()), quote);
+ t.diagnostic(`fee ${quote.relayFee} USDC, receives ${quote.amountOut}, about ${quote.timeEstimate}s`);
+ });
+}
+
+// A real forwarded burn, Ethereum USDC to Arc: the calldata this bridge builds must produce exactly its event, and
+// Circle's record of it must read as delivered with the mint transaction it reported on 2026-11-10.
+test("read-only live Circle burn matches this bridge's own encoding and reads as delivered", live, async () => {
+ const hash = "0x009551050ec596b833a8957d635c759dbd22b63d45977c9d4cde5dcc79bece01" as const;
+ const transfer: TrackedBridgeTransfer = {
+ provider: "cctp", address: "0x6376ca7e839f1c3dd7f23cc8a1a58329f60db125", originChainId: 1, destinationChainId: 5042, originAsset: "USDC", destinationAsset: "USDC",
+ amount: "2343317655", requestId: `0x${"1".repeat(64)}`, destinationHashes: [], status: "pending", createdAt: 1, depositKind: "erc20",
+ depositData: cctpBurnData({ address: "0x6376ca7e839f1c3dd7f23cc8a1a58329f60db125", originChainId: 1, destinationChainId: 5042, originAsset: "USDC", destinationAsset: "USDC", amount: "2343317655" }, 89_262n),
+ };
+ const client = createPublicClient({ transport: http("https://ethereum-rpc.publicnode.com", { timeout: 30_000 }) });
+ const receipt = await client.getTransactionReceipt({ hash });
+ const burns = receipt.logs.filter((log) => log.address.toLowerCase() === CCTP_TOKEN_MESSENGER.toLowerCase());
+ assert.equal(burns.length, 1);
+ assert.equal(isCctpBurnLog(burns[0], transfer), true);
+ const status = await getCctpStatus({ originChainId: 1, destinationChainId: 5042, hash, address: transfer.address, amount: transfer.amount }, fetch);
+ assert.deepEqual(status, { status: "success", inTxHashes: [hash], txHashes: ["0xec343f34384181675084e7bb39863235c060fa075521984a2a22eedd05029531"] });
+});
diff --git a/app/src/lib/bridge/cctp.test.ts b/app/src/lib/bridge/cctp.test.ts
new file mode 100644
index 00000000..5bd05185
--- /dev/null
+++ b/app/src/lib/bridge/cctp.test.ts
@@ -0,0 +1,234 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { encodeAbiParameters, encodeEventTopics, encodeFunctionData, pad, parseAbi, type Address, type Hex } from "viem";
+import { CCTP_BURN_ABI, CCTP_BURN_EVENT, CCTP_FORWARD_HOOK, CCTP_TOKEN_MESSENGER, cctpAmountOut, cctpBurnData, cctpBurnFee, cctpRoute, isCctpBurnLog } from "./cctp";
+import { bridgeStatusUrl, CCTP_NOT_SEEN, CCTP_SCAN_BLOCKS, DISCARD_AFTER_MS, findCctpBurn, hasMatchingDepositEvent, isMatchingSourceDeposit, parseStoredTransfer, serializeTransfer, submitBridgeDeposit, transferCanDiscard, validateBridgeQuote, type DepositDependencies, type TrackedBridgeTransfer } from "./client";
+import { ARBITRUM_USDC, ARC_USDC, BASE_USDC, ETHEREUM_USDC, OPTIMISM_USDC, bridgeFeePercent, type BridgeQuote, type BridgeQuoteRequest } from "./types";
+
+const WALLET = "0x6376ca7e839f1c3dd7f23cc8a1a58329f60db125" as const;
+const OTHER = "0x1111111111111111111111111111111111111111" as const;
+const ZERO_WORD = `0x${"0".repeat(64)}` as Hex;
+const HASH = `0x${"ab".repeat(32)}` as Hex;
+// Arbitrum USDC to Base USDC: 25 USDC, the fee Circle quoted for Fast plus its forward
+const REQUEST: BridgeQuoteRequest = { address: WALLET, originChainId: 42161, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC", amount: "25000000" };
+const FEE = 21_211n;
+
+function burn(overrides: Partial<{ amount: bigint; domain: number; recipient: Hex; token: Address; caller: Hex; maxFee: bigint; finality: number; hook: Hex }> = {}): Hex {
+ return encodeFunctionData({ abi: CCTP_BURN_ABI, functionName: "depositForBurnWithHook", args: [
+ overrides.amount ?? 25_000_000n, overrides.domain ?? 6, overrides.recipient ?? pad(WALLET), overrides.token ?? ARBITRUM_USDC,
+ overrides.caller ?? ZERO_WORD, overrides.maxFee ?? FEE, overrides.finality ?? 1000, overrides.hook ?? CCTP_FORWARD_HOOK,
+ ] });
+}
+
+test("Circle carries only USDC to USDC into Base or Arc, from the five Circle networks", () => {
+ assert.deepEqual(cctpRoute(REQUEST), { sourceDomain: 3, destinationDomain: 6, burnToken: ARBITRUM_USDC, outputDecimals: 6, finality: 1000 });
+ assert.deepEqual(cctpRoute({ originChainId: 1, destinationChainId: 5042, originAsset: "USDC" }), { sourceDomain: 0, destinationDomain: 26, burnToken: ETHEREUM_USDC, outputDecimals: 18, finality: 1000 });
+ assert.deepEqual(cctpRoute({ originChainId: 10, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC" })?.burnToken, OPTIMISM_USDC);
+ // Arc's own asset is USDC, so the default asset counts; Arc burns at Standard finality (final in about half a second)
+ assert.deepEqual(cctpRoute({ originChainId: 5042, destinationChainId: 8453, destinationAsset: "USDC" }), { sourceDomain: 26, destinationDomain: 6, burnToken: ARC_USDC, outputDecimals: 6, finality: 2000 });
+ assert.equal(cctpRoute({ originChainId: 8453, destinationChainId: 5042, originAsset: "USDC" })?.burnToken, BASE_USDC);
+ for (const route of [
+ { originChainId: 8453, destinationChainId: 5042 }, // Base ETH
+ { originChainId: 8453, destinationChainId: 5042, originAsset: "USDC", destinationAsset: "ETH" },
+ { originChainId: 42161, destinationChainId: 8453, originAsset: "USDC" }, // Base default asset is ETH
+ { originChainId: 8453, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC" },
+ { originChainId: 8453, destinationChainId: 4663, originAsset: "USDC", destinationAsset: "USDG" }, // Robinhood has no USDC route
+ { originChainId: 4663, destinationChainId: 8453, originAsset: "USDG", destinationAsset: "USDC" },
+ { originChainId: 8453, destinationChainId: 1, originAsset: "USDC", destinationAsset: "USDC" }, // funding networks only send
+ ] as const) assert.equal(cctpRoute(route), null, JSON.stringify(route));
+});
+
+test("a burn's fee is read back only from the exact calldata this bridge builds", () => {
+ assert.equal(cctpBurnData(REQUEST, FEE), burn());
+ assert.equal(cctpBurnFee(burn(), REQUEST), FEE);
+ // exactly 5% is the ceiling; a wei above it is refused
+ assert.equal(cctpBurnFee(burn({ maxFee: 1_250_000n }), REQUEST), 1_250_000n);
+ assert.equal(cctpBurnFee(burn({ maxFee: 1_250_001n }), REQUEST), null);
+ for (const [name, data] of [
+ ["recipient", burn({ recipient: pad(OTHER) })],
+ ["amount", burn({ amount: 25_000_001n })],
+ ["domain", burn({ domain: 26 })],
+ ["token", burn({ token: BASE_USDC })],
+ ["caller", burn({ caller: pad(OTHER) })],
+ ["finality", burn({ finality: 2000 })],
+ ["hook", burn({ hook: "0x" })],
+ ["hook payload", burn({ hook: `${CCTP_FORWARD_HOOK}00000001` })],
+ ["trailing bytes", `${burn()}00` as Hex],
+ ["other function", encodeFunctionData({ abi: parseAbi(["function approve(address,uint256)"]), functionName: "approve", args: [CCTP_TOKEN_MESSENGER, 25_000_000n] })],
+ ] as const) assert.equal(cctpBurnFee(data, REQUEST), null, name);
+ for (const data of [undefined, 1, "", "0x", "not hex", `0x${"00".repeat(500)}`]) assert.equal(cctpBurnFee(data, REQUEST), null);
+ assert.throws(() => cctpBurnData(REQUEST, 0n));
+ assert.throws(() => cctpBurnData(REQUEST, 25_000_000n));
+ assert.throws(() => cctpBurnData({ ...REQUEST, destinationAsset: "ETH" }, FEE));
+});
+
+test("what arrives is the amount less the whole fee, in the destination's own units", () => {
+ assert.equal(cctpAmountOut(25_000_000n, FEE, 6), 24_978_789n);
+ assert.equal(cctpAmountOut(25_000_000n, FEE, 18), 24_978_789_000_000_000_000n);
+});
+
+function burnLog(overrides: Partial<{ address: Address; depositor: Address; finality: number; amount: bigint; maxFee: bigint; hook: Hex; recipient: Hex; domain: number; caller: Hex }> = {}) {
+ const topics = encodeEventTopics({ abi: CCTP_BURN_EVENT, eventName: "DepositForBurn", args: { burnToken: ARBITRUM_USDC, depositor: overrides.depositor ?? WALLET, minFinalityThreshold: overrides.finality ?? 1000 } }) as Hex[];
+ const data = encodeAbiParameters(
+ [{ type: "uint256" }, { type: "bytes32" }, { type: "uint32" }, { type: "bytes32" }, { type: "bytes32" }, { type: "uint256" }, { type: "bytes" }],
+ [overrides.amount ?? 25_000_000n, overrides.recipient ?? pad(WALLET), overrides.domain ?? 6, pad(CCTP_TOKEN_MESSENGER), overrides.caller ?? ZERO_WORD, overrides.maxFee ?? FEE, overrides.hook ?? CCTP_FORWARD_HOOK],
+ );
+ return { address: overrides.address ?? CCTP_TOKEN_MESSENGER, data, topics, transactionHash: HASH };
+}
+
+const TRANSFER: TrackedBridgeTransfer = { ...REQUEST, provider: "cctp", sourceBlock: "1000", requestId: `0x${"12".repeat(32)}`, destinationHashes: [], status: "pending", createdAt: 1, depositData: burn(), depositKind: "erc20" };
+
+test("only Circle's own burn event with every saved field counts as this transfer's burn", () => {
+ assert.equal(isCctpBurnLog(burnLog(), TRANSFER), true);
+ for (const [name, log] of [
+ ["emitter", burnLog({ address: OTHER })],
+ ["depositor", burnLog({ depositor: OTHER })],
+ ["finality", burnLog({ finality: 2000 })],
+ ["amount", burnLog({ amount: 1n })],
+ ["fee", burnLog({ maxFee: FEE + 1n })],
+ ["hook", burnLog({ hook: "0x" })],
+ ["recipient", burnLog({ recipient: pad(OTHER) })],
+ ["domain", burnLog({ domain: 26 })],
+ ["caller", burnLog({ caller: pad(OTHER) })],
+ ] as const) assert.equal(isCctpBurnLog(log, TRANSFER), false, name);
+ assert.equal(isCctpBurnLog({ ...burnLog(), topics: burnLog().topics.slice(0, 3) }, TRANSFER), false);
+ assert.equal(isCctpBurnLog(burnLog(), { ...TRANSFER, depositData: undefined }), false);
+ assert.equal(hasMatchingDepositEvent(TRANSFER, { status: "success", logs: [burnLog({ amount: 1n }), burnLog()] }), true);
+ assert.equal(hasMatchingDepositEvent(TRANSFER, { status: "reverted", logs: [burnLog()] }), false);
+ assert.equal(isMatchingSourceDeposit(TRANSFER, { from: WALLET, to: CCTP_TOKEN_MESSENGER, input: burn(), value: 0n }), true);
+ assert.equal(isMatchingSourceDeposit(TRANSFER, { from: OTHER, to: CCTP_TOKEN_MESSENGER, input: burn(), value: 0n }), false);
+ assert.equal(isMatchingSourceDeposit(TRANSFER, { from: WALLET, to: OTHER, input: burn(), value: 0n }), false);
+ assert.equal(isMatchingSourceDeposit(TRANSFER, { from: WALLET, to: CCTP_TOKEN_MESSENGER, input: burn(), value: 1n }), false);
+});
+
+function circleQuote(overrides: Partial = {}, now = 1_000): BridgeQuote {
+ const out = cctpAmountOut(25_000_000n, FEE, 6).toString();
+ return {
+ ...REQUEST, provider: "cctp", requestId: `0x${"12".repeat(32)}`, amountOut: out, minimumAmountOut: out, relayFee: "0.021211", sourceGas: "0.0000022",
+ totalImpactPercent: `-${bridgeFeePercent(FEE, 25_000_000n)}`, approval: { token: ARBITRUM_USDC, spender: CCTP_TOKEN_MESSENGER, amount: REQUEST.amount },
+ timeEstimate: 25, expiresAt: now + 45_000, ttlMs: 45_000, transaction: { to: CCTP_TOKEN_MESSENGER, data: burn(), value: "0", chainId: 42161 },
+ ...overrides,
+ };
+}
+
+test("the browser accepts a Circle quote only when it is exactly the burn it would build itself", () => {
+ assert.deepEqual(validateBridgeQuote(circleQuote(), REQUEST, 1_000), circleQuote());
+ const tx = circleQuote().transaction;
+ for (const [name, quote] of [
+ ["provider", circleQuote({ provider: "other" as "cctp" })],
+ ["spender", circleQuote({ approval: { token: ARBITRUM_USDC, spender: "0x4cd00e387622c35bddb9b4c962c136462338bc31", amount: REQUEST.amount } })],
+ ["approval token", circleQuote({ approval: { token: BASE_USDC, spender: CCTP_TOKEN_MESSENGER, amount: REQUEST.amount } })],
+ ["approval amount", circleQuote({ approval: { token: ARBITRUM_USDC, spender: CCTP_TOKEN_MESSENGER, amount: "25000001" } })],
+ ["no approval", circleQuote({ approval: undefined })],
+ ["target", circleQuote({ transaction: { ...tx, to: OTHER } })],
+ ["value", circleQuote({ transaction: { ...tx, value: "1" } })],
+ ["chain", circleQuote({ transaction: { ...tx, chainId: 8453 } })],
+ ["recipient", circleQuote({ transaction: { ...tx, data: burn({ recipient: pad(OTHER) }) } })],
+ ["hook", circleQuote({ transaction: { ...tx, data: burn({ hook: "0x" }) } })],
+ ["output", circleQuote({ amountOut: "24978790", minimumAmountOut: "24978790" })],
+ ["minimum", circleQuote({ minimumAmountOut: "24978788" })],
+ ["fee shown", circleQuote({ relayFee: "0.02" })],
+ ] as const) assert.throws(() => validateBridgeQuote(quote, REQUEST, 1_000), Error, name);
+ // a different fee is fine when every number agrees with it
+ const cheaper = burn({ maxFee: 20_000n });
+ const out = cctpAmountOut(25_000_000n, 20_000n, 6).toString();
+ assert.doesNotThrow(() => validateBridgeQuote(circleQuote({ transaction: { ...tx, data: cheaper }, amountOut: out, minimumAmountOut: out, relayFee: "0.02", totalImpactPercent: "-0.08" }), REQUEST, 1_000));
+});
+
+test("a Circle record survives storage only with its burn intact, and old Relay records are unchanged", () => {
+ const sent = { ...TRANSFER, sourceHash: HASH };
+ const saved = serializeTransfer(sent);
+ assert.equal(JSON.parse(saved).version, 4);
+ assert.deepEqual(parseStoredTransfer(saved, WALLET), sent);
+ const withoutBlock: TrackedBridgeTransfer = { ...sent };
+ delete withoutBlock.sourceBlock;
+ assert.deepEqual(parseStoredTransfer(serializeTransfer(withoutBlock), WALLET), withoutBlock);
+ const tamper = (patch: Record) => JSON.stringify({ ...JSON.parse(saved), ...patch });
+ for (const [name, raw] of [
+ ["version", tamper({ version: 3 })],
+ ["recipient", tamper({ depositData: burn({ recipient: pad(OTHER) }) })],
+ ["amount", tamper({ amount: "26000000" })],
+ ["kind", tamper({ depositKind: undefined })],
+ ["block", tamper({ sourceBlock: "-1" })],
+ ["block type", tamper({ sourceBlock: 1000 })],
+ ["provider", tamper({ provider: "relay" })],
+ ] as const) assert.throws(() => parseStoredTransfer(raw, WALLET), Error, name);
+ // a Relay record never carries Circle's fields
+ const relay = { address: WALLET, originChainId: 8453, destinationChainId: 4663, amount: "1", requestId: TRANSFER.requestId, destinationHashes: [], status: "pending", createdAt: 1, version: 1 };
+ assert.doesNotThrow(() => parseStoredTransfer(JSON.stringify(relay), WALLET));
+ assert.throws(() => parseStoredTransfer(JSON.stringify({ ...relay, sourceBlock: "1" }), WALLET));
+});
+
+test("Circle status is asked by the burn's own transaction, and not at all before there is one", () => {
+ assert.equal(bridgeStatusUrl({ ...TRANSFER, provider: undefined }), `/api/bridge/status?requestId=${TRANSFER.requestId}`);
+ assert.equal(bridgeStatusUrl(TRANSFER), null);
+ const url = new URL(bridgeStatusUrl({ ...TRANSFER, sourceHash: HASH })!, "https://openlaunch.lol");
+ assert.deepEqual(Object.fromEntries(url.searchParams), { provider: "cctp", origin: "42161", destination: "8453", hash: HASH, address: WALLET, amount: "25000000" });
+});
+
+test("a burn the wallet never reported is found by its own event, once, inside the scan window", async () => {
+ const calls: { fromBlock: bigint; toBlock: bigint; args: unknown }[] = [];
+ const reader = (latest: bigint, logs: ReturnType[]) => ({
+ getBlockNumber: async () => latest,
+ getLogs: async (args: { fromBlock: bigint; toBlock: bigint; args: unknown }) => { calls.push(args); return logs; },
+ });
+ const range = { fromBlock: 1_000n, toBlock: 1_050n, headBlock: 1_050n, complete: true };
+ assert.deepEqual(await findCctpBurn(reader(1_050n, [burnLog({ amount: 1n }), burnLog()]), TRANSFER), { kind: "found", hash: HASH, ...range });
+ assert.deepEqual(calls.at(-1), { address: CCTP_TOKEN_MESSENGER, event: CCTP_BURN_EVENT[0], args: { burnToken: ARBITRUM_USDC, depositor: WALLET }, fromBlock: 1_000n, toBlock: 1_050n });
+ assert.deepEqual(await findCctpBurn(reader(1_000_000n, []), TRANSFER), { kind: "not-found", fromBlock: 1_000n, toBlock: 1_000n + CCTP_SCAN_BLOCKS, headBlock: 1_000_000n, complete: false });
+ assert.equal(calls.at(-1)!.toBlock, 1_000n + CCTP_SCAN_BLOCKS);
+ // the same burn in two logs is one burn; two different burns are ambiguous
+ assert.deepEqual(await findCctpBurn(reader(1_050n, [burnLog(), burnLog()]), TRANSFER), { kind: "found", hash: HASH, ...range });
+ const otherHash = `0x${"cd".repeat(32)}` as Hex;
+ assert.deepEqual(await findCctpBurn(reader(1_050n, [burnLog(), { ...burnLog(), transactionHash: otherHash }]), TRANSFER), { kind: "ambiguous", hashes: [HASH, otherHash], ...range });
+ assert.deepEqual(await findCctpBurn(reader(1_050n, [burnLog({ depositor: OTHER })]), TRANSFER), { kind: "not-found", ...range });
+ assert.deepEqual(await findCctpBurn({ getBlockNumber: async () => 1_050n, getLogs: async () => [{ ...burnLog(), transactionHash: null }] }, TRANSFER), { kind: "ambiguous", hashes: [], ...range });
+ const before = calls.length;
+ assert.deepEqual(await findCctpBurn(reader(999n, [burnLog()]), TRANSFER), { kind: "unavailable", reason: "head-before-source" });
+ assert.deepEqual(await findCctpBurn(reader(1_050n, [burnLog()]), { ...TRANSFER, sourceBlock: undefined }), { kind: "unavailable", reason: "missing-source-block" });
+ assert.deepEqual(await findCctpBurn(reader(1_050n, [burnLog()]), { ...TRANSFER, provider: undefined }), { kind: "unavailable", reason: "unsupported-route" });
+ assert.equal(calls.length, before);
+ assert.deepEqual(await findCctpBurn({ ...reader(1_050n, []), getBlockNumber: async () => { throw new Error("offline"); } }, TRANSFER), { kind: "unavailable", reason: "rpc-error" });
+ assert.deepEqual(await findCctpBurn({ ...reader(1_050n, []), getLogs: async () => { throw new Error("log range refused"); } }, TRANSFER), { kind: "unavailable", reason: "rpc-error" });
+});
+
+test("a Circle deposit records its provider and the block to look from, and still sends if that block is unknown", async () => {
+ const quote = circleQuote({}, Date.now());
+ const saved: TrackedBridgeTransfer[] = [];
+ const deps = (sourceBlock: DepositDependencies["sourceBlock"]): DepositDependencies => ({
+ now: () => quote.expiresAt - 45_000, currentRequest: () => REQUEST, readWallet: async () => ({ address: WALLET, chainId: 42161 }),
+ switchChain: async () => {}, prepare: async () => ({ gas: 1n, maxFeePerGas: 1n, maxPriorityFeePerGas: 1n }), readTransfer: () => null,
+ saveTransfer: (transfer) => { saved.push(transfer); }, removeTransfer: () => {}, sourceBlock, send: async () => HASH, phase: () => {},
+ });
+ const sent = await submitBridgeDeposit(quote, deps(async () => 77n));
+ assert.equal(sent.kind, "sent");
+ assert.equal(saved[0].provider, "cctp");
+ assert.equal(saved[0].sourceBlock, "77");
+ saved.length = 0;
+ const unknown = await submitBridgeDeposit(quote, deps(async () => { throw new Error("rpc down"); }));
+ assert.equal(unknown.kind, "sent");
+ assert.equal(saved[0].provider, "cctp");
+ assert.equal(saved[0].sourceBlock, undefined);
+});
+
+test("Circle recovery keeps an uncertain broadcast after the discard timeout", async (t) => {
+ const now = TRANSFER.createdAt + DISCARD_AFTER_MS + 60_000;
+ const reader = { getBlockNumber: async () => 1_100n, getLogs: async () => [burnLog()] };
+ const cases = [
+ { name: "missing source block", transfer: { ...TRANSFER, sourceBlock: undefined }, reader },
+ { name: "multiple matching burns", transfer: TRANSFER, reader: { ...reader, getLogs: async () => [burnLog(), { ...burnLog(), transactionHash: `0x${"cd".repeat(32)}` as Hex }] } },
+ { name: "burn beyond the scan window", transfer: TRANSFER, reader: { getBlockNumber: async () => 1_000n + CCTP_SCAN_BLOCKS + 2n, getLogs: async ({ toBlock }: { toBlock: bigint }) => toBlock > 1_000n + CCTP_SCAN_BLOCKS ? [burnLog()] : [] } },
+ { name: "empty complete scan still permits a future burn", transfer: TRANSFER, reader: { ...reader, getLogs: async () => [] } },
+ { name: "single matching burn", transfer: TRANSFER, reader },
+ ];
+ for (const example of cases) await t.test(example.name, async () => {
+ const burn = await findCctpBurn(example.reader, example.transfer);
+ assert.equal(transferCanDiscard(example.transfer, { requestId: TRANSFER.requestId, status: CCTP_NOT_SEEN, sourceMined: burn.kind === "found" || burn.kind === "ambiguous", observedAt: now }, now), false);
+ });
+});
+
+test("a known Circle source hash cannot expire into a safe discard, even days later", () => {
+ const now = TRANSFER.createdAt + 7 * 24 * 60 * 60_000;
+ const transfer = { ...TRANSFER, sourceHash: HASH };
+ assert.equal(transferCanDiscard(transfer, { requestId: TRANSFER.requestId, status: CCTP_NOT_SEEN, sourceMined: false, observedAt: now }, now), false);
+});
diff --git a/app/src/lib/bridge/cctp.ts b/app/src/lib/bridge/cctp.ts
new file mode 100644
index 00000000..5d7d3f8b
--- /dev/null
+++ b/app/src/lib/bridge/cctp.ts
@@ -0,0 +1,130 @@
+import { decodeEventLog, decodeFunctionData, encodeFunctionData, pad, type Address, type Hex } from "viem";
+import { bridgeCurrency, defaultBridgeAsset, type BridgeAsset, type BridgeChainId, type BridgeQuoteRequest } from "./types";
+
+/**
+ * Circle's CCTP v2 as the bridge's second route, for USDC to USDC only. The wallet burns USDC on the source network
+ * through Circle's TokenMessengerV2 with a Fast finality threshold and Circle's Forwarding Service hook, and Circle
+ * mints the same USDC (less one fixed fee) to the same wallet on the destination. There is no second wallet step and
+ * no gas is needed on the destination.
+ *
+ * Everything here is pinned and pure, shared by the server (which builds the quote) and the browser (which rebuilds
+ * the exact calldata before the wallet is asked): no response from Circle ever chooses a contract, a recipient or a
+ * hook. Facts checked on-chain on 2026-11-10: the two contracts below are deployed at these addresses on all five
+ * networks, `localDomain()` returns the domains listed, and live forwarded burns carry exactly `CCTP_FORWARD_HOOK`
+ * with a zero destination caller.
+ * https://developers.circle.com/cctp/references/contract-addresses
+ */
+export const CCTP_TOKEN_MESSENGER = "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d" as const;
+export const CCTP_MESSAGE_TRANSMITTER = "0x81D40F21F12A8F0E3252Bccb954D722d4c464B64" as const;
+/** Circle's domain for each network the bridge can burn on. Robinhood Chain has a domain (35) but no live USDC route. */
+export const CCTP_DOMAINS = { 1: 0, 10: 2, 42161: 3, 8453: 6, 5042: 26 } as const;
+export type CctpChainId = keyof typeof CCTP_DOMAINS;
+/** Launch chains Circle can mint to. */
+export const CCTP_DESTINATIONS = [8453, 5042] as const;
+/** Fast Transfer: attested at soft finality (about 8 seconds on the rollups, 20 on Ethereum) for a small fee in basis points. */
+export const CCTP_FAST_FINALITY = 1000;
+/** Standard Transfer. Arc has no Fast Transfer as a source: its blocks are final in about half a second anyway. */
+export const CCTP_STANDARD_FINALITY = 2000;
+/** The finality a burn from this network asks for. */
+export const cctpFinality = (originChainId: BridgeChainId) => originChainId === 5042 ? CCTP_STANDARD_FINALITY : CCTP_FAST_FINALITY;
+/** "cctp-forward" right-padded to 32 bytes: version 0, no payload. Circle relays the mint to the recipient. */
+export const CCTP_FORWARD_HOOK = "0x636374702d666f72776172640000000000000000000000000000000000000000" as const;
+const ZERO_WORD = `0x${"0".repeat(64)}` as const;
+/** Burns above this share of the amount are never offered: the same 5% ceiling as Relay's fee. */
+export const CCTP_MAX_FEE_PERCENT = 5n;
+
+export const CCTP_BURN_ABI = [{
+ type: "function", name: "depositForBurnWithHook", 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: [],
+}] as const;
+export const CCTP_BURN_EVENT = [{
+ type: "event", name: "DepositForBurn",
+ inputs: [
+ { name: "burnToken", type: "address", indexed: true }, { name: "amount", type: "uint256", indexed: false },
+ { name: "depositor", type: "address", indexed: true }, { name: "mintRecipient", type: "bytes32", indexed: false },
+ { name: "destinationDomain", type: "uint32", indexed: false }, { name: "destinationTokenMessenger", type: "bytes32", indexed: false },
+ { name: "destinationCaller", type: "bytes32", indexed: false }, { name: "maxFee", type: "uint256", indexed: false },
+ { name: "minFinalityThreshold", type: "uint32", indexed: true }, { name: "hookData", type: "bytes", indexed: false },
+ ],
+}] as const;
+
+type Route = Pick;
+export type CctpRoute = { sourceDomain: number; destinationDomain: number; burnToken: Address; outputDecimals: 6 | 18; finality: number };
+
+const isCctpChain = (chainId: BridgeChainId): chainId is CctpChainId => Object.hasOwn(CCTP_DOMAINS, chainId);
+const asset = (chainId: BridgeChainId, value: BridgeAsset | undefined) => value ?? defaultBridgeAsset(chainId);
+
+/** The CCTP leg for a USDC to USDC route between Circle networks, or null when Circle cannot carry it. */
+export function cctpRoute(route: Route): CctpRoute | null {
+ const { originChainId, destinationChainId } = route;
+ if (originChainId === destinationChainId || !isCctpChain(originChainId) || !(CCTP_DESTINATIONS as readonly BridgeChainId[]).includes(destinationChainId)) return null;
+ if (asset(originChainId, route.originAsset) !== "USDC" || asset(destinationChainId, route.destinationAsset) !== "USDC") return null;
+ return {
+ sourceDomain: CCTP_DOMAINS[originChainId],
+ destinationDomain: CCTP_DOMAINS[destinationChainId as CctpChainId],
+ burnToken: bridgeCurrency(originChainId, "USDC", "input").address,
+ outputDecimals: bridgeCurrency(destinationChainId, "USDC", "output").decimals,
+ finality: cctpFinality(originChainId),
+ };
+}
+
+/** The one burn this bridge ever asks for: the exact amount, to the same wallet, at the source's finality, forwarded by Circle. */
+export function cctpBurnData(request: Route & Pick, maxFee: bigint): Hex {
+ const route = cctpRoute(request);
+ if (!route) throw new Error("Circle does not carry this route.");
+ const amount = BigInt(request.amount);
+ if (amount <= 0n || maxFee <= 0n || maxFee >= amount) throw new Error("Invalid Circle burn amounts.");
+ return encodeFunctionData({
+ abi: CCTP_BURN_ABI, functionName: "depositForBurnWithHook",
+ args: [amount, route.destinationDomain, pad(request.address), route.burnToken, ZERO_WORD, maxFee, route.finality, CCTP_FORWARD_HOOK],
+ });
+}
+
+/**
+ * The fee a burn's calldata allows, when and only when that calldata is exactly the burn `cctpBurnData` builds for
+ * this request (re-encoding also rejects trailing bytes). Null for anything else, including a fee at or above the
+ * 5% ceiling.
+ */
+export function cctpBurnFee(data: unknown, request: Route & Pick): bigint | null {
+ if (typeof data !== "string" || !/^0x[0-9a-fA-F]+$/.test(data) || data.length > 2 + 2 * 420) return null;
+ try {
+ const { functionName, args } = decodeFunctionData({ abi: CCTP_BURN_ABI, data: data as Hex });
+ if (functionName !== "depositForBurnWithHook") return null;
+ const maxFee = args[5];
+ if (maxFee * 100n > BigInt(request.amount) * CCTP_MAX_FEE_PERCENT) return null;
+ return cctpBurnData(request, maxFee).toLowerCase() === data.toLowerCase() ? maxFee : null;
+ } catch { return null; }
+}
+
+/**
+ * What arrives, in the destination's output units (Arc's native balance has 18 decimals): the amount less the whole
+ * fee. With forwarding, Circle executes the full maxFee (every live forwarded burn checked showed feeExecuted equal to
+ * maxFee), so this is what the wallet receives, not a floor under it.
+ */
+export function cctpAmountOut(amount: bigint, maxFee: bigint, outputDecimals: 6 | 18): bigint {
+ return (amount - maxFee) * 10n ** BigInt(outputDecimals - 6);
+}
+
+type Log = { address: Address; data: Hex; topics: readonly Hex[]; transactionHash?: Hex | null };
+/**
+ * Whether a source-chain log is this transfer's burn: Circle's own event, from the pinned messenger, with every field
+ * the saved calldata set. Used to adopt a hash the wallet never returned, and for smart wallets that burn from an
+ * inner call.
+ */
+export function isCctpBurnLog(log: Log, transfer: Route & Pick & { depositData?: Hex }): boolean {
+ if (!transfer.depositData || log.address.toLowerCase() !== CCTP_TOKEN_MESSENGER.toLowerCase() || log.topics.length !== 4) return false;
+ const maxFee = cctpBurnFee(transfer.depositData, transfer);
+ const route = cctpRoute(transfer);
+ if (maxFee === null || !route) return false;
+ try {
+ const { eventName, args } = decodeEventLog({ abi: CCTP_BURN_EVENT, data: log.data, topics: log.topics as [Hex, ...Hex[]], strict: true });
+ return eventName === "DepositForBurn" && args.burnToken.toLowerCase() === route.burnToken.toLowerCase() && args.depositor.toLowerCase() === transfer.address.toLowerCase()
+ && args.amount === BigInt(transfer.amount) && args.mintRecipient.toLowerCase() === pad(transfer.address).toLowerCase() && args.destinationDomain === route.destinationDomain
+ && args.destinationCaller === ZERO_WORD && args.maxFee === maxFee && args.minFinalityThreshold === route.finality && args.hookData.toLowerCase() === CCTP_FORWARD_HOOK;
+ } catch { return false; }
+}
diff --git a/app/src/lib/bridge/chains.ts b/app/src/lib/bridge/chains.ts
index 0516d178..3133afd8 100644
--- a/app/src/lib/bridge/chains.ts
+++ b/app/src/lib/bridge/chains.ts
@@ -1,10 +1,23 @@
import type { Chain } from "viem";
-import { CHAINS } from "../chainPublic";
-import type { BridgeChainId } from "./types";
+import { arbitrum, mainnet, optimism } from "viem/chains";
+import { CHAINS, SITE_URL } from "../chainPublic";
+import { BRIDGE_CHAINS, BRIDGE_FUNDING_IDS, type BridgeChainId } from "./types";
-/** Wallet chains by Relay's numeric id. Arc is a launch chain like the others (chainPublic.ts); one definition for both. */
+/** Wallet chains by Relay's numeric id. Arc and Elysium are launch chains like the others (chainPublic.ts); one definition for both. */
export const BRIDGE_WALLET_CHAINS: Record = {
8453: CHAINS.base,
4663: CHAINS.robinhood,
5042: CHAINS.arc,
+ 99901: CHAINS.elysium,
+ 1: mainnet,
+ 42161: arbitrum,
+ 10: optimism,
};
+
+/** The funding networks the wallet config adds next to the launch chains, so a wallet can switch to them and send. */
+export const BRIDGE_FUNDING_WALLET_CHAINS: readonly Chain[] = BRIDGE_FUNDING_IDS.map((id) => BRIDGE_WALLET_CHAINS[id]);
+
+/** Browser reads on a funding network go through the same-origin RPC proxy, like the launch chains (api/rpc). */
+export function bridgeFundingRpc(id: (typeof BRIDGE_FUNDING_IDS)[number]): string {
+ return `${SITE_URL}/api/rpc?chain=${BRIDGE_CHAINS[id].key}`;
+}
diff --git a/app/src/lib/bridge/client-chains.test.ts b/app/src/lib/bridge/client-chains.test.ts
index c88fbbd4..d5ba3bfb 100644
--- a/app/src/lib/bridge/client-chains.test.ts
+++ b/app/src/lib/bridge/client-chains.test.ts
@@ -1,11 +1,11 @@
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import test from "node:test";
-import { CHAINS, CHAIN_KEYS } from "../chainPublic";
-import { BRIDGE_WALLET_CHAINS } from "./chains";
+import { CHAINS, CHAIN_KEYS, SITE_URL } from "../chainPublic";
+import { BRIDGE_FUNDING_WALLET_CHAINS, BRIDGE_WALLET_CHAINS, bridgeFundingRpc } from "./chains";
import { BRIDGE_CHAIN_IDS, BRIDGE_CHAINS } from "./types";
-test("every bridge source has a matching wallet chain, and Arc is the registry's own chain", () => {
+test("every bridge source has a matching wallet chain, and Arc and Elysium are the registry's own chains", () => {
for (const id of BRIDGE_CHAIN_IDS) {
const walletChain = BRIDGE_WALLET_CHAINS[id];
assert.equal(walletChain.id, id);
@@ -13,8 +13,13 @@ test("every bridge source has a matching wallet chain, and Arc is the registry's
assert.equal(walletChain.nativeCurrency.decimals, 18);
assert.ok(walletChain.rpcUrls.default.http.length > 0);
}
- // Elysium is a launchpad chain but not (yet) a bridge source: Relay serves it, the bridge dialog does not offer it
+ // every launchpad chain is a bridge network, and the bridge reuses its wallet chain
assert.deepEqual(CHAIN_KEYS, ["base", "robinhood", "arc", "elysium"]);
+ for (const key of CHAIN_KEYS) assert.equal(BRIDGE_WALLET_CHAINS[CHAINS[key].id as keyof typeof BRIDGE_WALLET_CHAINS], CHAINS[key]);
+ const elysium = BRIDGE_WALLET_CHAINS[99901];
+ assert.equal(elysium.nativeCurrency.symbol, "HYPE");
+ assert.equal(elysium.rpcUrls.default.http[0], "https://rpc.elysium.kinetiq.xyz");
+ assert.equal(BRIDGE_CHAINS[99901].explorer, elysium.blockExplorers?.default.url);
const arc = BRIDGE_WALLET_CHAINS[5042];
assert.equal(arc, CHAINS.arc, "one Arc definition, shared by the launchpad and the bridge");
assert.equal(arc.rpcUrls.default.http[0], "https://rpc.mainnet.arc.io");
@@ -23,11 +28,17 @@ test("every bridge source has a matching wallet chain, and Arc is the registry's
assert.notEqual(arc.id, 5042002);
});
-test("wallet config registers Arc for switching and native-balance reads", () => {
+test("wallet config registers Arc and the funding networks for switching and native-balance reads", () => {
const config = readFileSync(new URL("../wagmi.ts", import.meta.url), "utf8");
- // every registry chain, Arc included, through the same proxied transport; the chain's own rpcUrls stay official for wallet_addEthereumChain
- assert.match(config, /const chains = keys\.map\(\(k\) => CHAINS\[k\]\)/);
- assert.match(config, /transports: Object\.fromEntries\(keys\.map\(\(k\) => \[CHAINS\[k\]\.id, http\(browserRpc\(k\)/);
+ // every registry chain, Arc included, then the bridge's funding networks, all through the same-origin proxy; the
+ // chains' own rpcUrls stay official for wallet_addEthereumChain
+ assert.match(config, /const chains = \[\.\.\.keys\.map\(\(k\) => CHAINS\[k\]\), \.\.\.BRIDGE_FUNDING_WALLET_CHAINS\]/);
+ assert.match(config, /\.\.\.keys\.map\(\(k\) => \[CHAINS\[k\]\.id, http\(browserRpc\(k\), \{ batch: true \}\)\]\)/);
+ assert.match(config, /\.\.\.BRIDGE_FUNDING_IDS\.map\(\(id\) => \[id, http\(bridgeFundingRpc\(id\), \{ batch: true \}\)\]\)/);
+ assert.equal(bridgeFundingRpc(1), `${SITE_URL}/api/rpc?chain=ethereum`);
+ assert.equal(bridgeFundingRpc(42161), `${SITE_URL}/api/rpc?chain=arbitrum`);
+ assert.equal(bridgeFundingRpc(10), `${SITE_URL}/api/rpc?chain=optimism`);
+ assert.deepEqual(BRIDGE_FUNDING_WALLET_CHAINS.map((chain) => chain.id), [1, 42161, 10]);
assert.doesNotMatch(config, /rpc\.mainnet\.arc\.io/);
const hook = readFileSync(new URL("../../components/bridge/useBridge.ts", import.meta.url), "utf8");
assert.match(hook, /chain:\s*BRIDGE_WALLET_CHAINS\[q\.originChainId\]/);
diff --git a/app/src/lib/bridge/client.test.ts b/app/src/lib/bridge/client.test.ts
index 767e8be5..e3564acc 100644
--- a/app/src/lib/bridge/client.test.ts
+++ b/app/src/lib/bridge/client.test.ts
@@ -1,10 +1,10 @@
import assert from "node:assert/strict";
import test from "node:test";
import { encodeAbiParameters, encodeEventTopics, encodeFunctionData, HttpRequestError, InsufficientFundsError, RpcRequestError, SwitchChainError, UnknownRpcError, UserRejectedRequestError, type Address, type Hex } from "viem";
-import { activityAfterWalletChange, anchorQuoteExpiry, bridgeErrorMessage, DISCARD_AFTER_MS, linkedTimeoutSignal, replacementSourceHash, transferCanDiscard, bridgeGasBudget, bridgeRequest, bridgeRequestKey, changeBridgeRoute, ERC20_DEPOSIT_ABI, ERC20_DEPOSIT_EVENT, hasMatchingDepositEvent, isMatchingSourceDeposit, isWalletRejection, mergeBridgeStatus, nativeSourceAmount, NATIVE_DEPOSIT_ABI, NATIVE_DEPOSIT_EVENT, parseBridgeAmount, parseStoredTransfer, RELAY_DEPOSITORY, serializeTransfer, submitBridgeDeposit, transferIsTerminal, validateBridgeQuote, validateBridgeStatus, type DepositDependencies, type TrackedBridgeTransfer } from "./client";
+import { activityAfterWalletChange, anchorQuoteExpiry, bridgeErrorMessage, canReverseBridgeRoute, DISCARD_AFTER_MS, linkedTimeoutSignal, replacementSourceHash, transferCanDiscard, bridgeGasBudget, bridgeRequest, bridgeRequestKey, changeBridgeRoute, ERC20_DEPOSIT_ABI, ERC20_DEPOSIT_EVENT, hasMatchingDepositEvent, isMatchingSourceDeposit, isWalletRejection, mergeBridgeStatus, nativeSourceAmount, NATIVE_DEPOSIT_ABI, NATIVE_DEPOSIT_EVENT, parseBridgeAmount, parseStoredTransfer, RELAY_DEPOSITORY, serializeTransfer, submitBridgeDeposit, transferIsTerminal, validateBridgeQuote, validateBridgeStatus, type DepositDependencies, type TrackedBridgeTransfer } from "./client";
import { bridgeStorageKey, createBridgeTransferStore } from "./client-storage";
import { parseBridgeQuoteRejection } from "./client";
-import { ARC_USDC, BASE_USDC, BRIDGE_CHAIN_IDS, type BridgeQuote, type BridgeQuoteRejection, type BridgeQuoteRequest } from "./types";
+import { ARC_USDC, BASE_USDC, ELYSIUM_USDC, BRIDGE_CHAIN_IDS, BRIDGE_DESTINATION_IDS, BRIDGE_FUNDING_IDS, isBridgeFundingChain, type BridgeQuote, type BridgeQuoteRejection, type BridgeQuoteRequest } from "./types";
const ADDRESS = "0x1111111111111111111111111111111111111111" as Address;
const OTHER = "0x2222222222222222222222222222222222222222" as Address;
@@ -66,12 +66,14 @@ test("amount parsing preserves integer precision and never rounds extra decimal
assert.equal(bridgeRequestKey(bridgeRequest(ADDRESS, 8453, "0.01", 4663)), bridgeRequestKey(bridgeRequest(ADDRESS, 8453, ".0100", 4663)));
});
-test("all six routes use the input currency precision, never native decimals for Arc ERC20", () => {
+test("every route uses the input currency precision, never native decimals for Arc ERC20, and never ends on a funding network", () => {
for (const origin of BRIDGE_CHAIN_IDS) for (const destination of BRIDGE_CHAIN_IDS) {
- const request = bridgeRequest(ADDRESS, origin, origin === 5042 ? "1.000001" : "1.000000000000000001", destination);
- if (origin === destination) assert.equal(request, null);
+ // Arc and Elysium send six-decimal USDC by default, everything else 18-decimal ETH
+ const six = origin === 5042 || origin === 99901;
+ const request = bridgeRequest(ADDRESS, origin, six ? "1.000001" : "1.000000000000000001", destination);
+ if (origin === destination || isBridgeFundingChain(destination)) assert.equal(request, null);
else {
- assert.equal(request?.amount, origin === 5042 ? "1000001" : "1000000000000000001");
+ assert.equal(request?.amount, six ? "1000001" : "1000000000000000001");
assert.equal(request?.destinationChainId, destination);
}
}
@@ -82,6 +84,27 @@ test("all six routes use the input currency precision, never native decimals for
assert.notEqual(bridgeRequestKey(bridgeRequest(ADDRESS, 8453, "1", 4663)), bridgeRequestKey(bridgeRequest(ADDRESS, 8453, "1", 5042)));
});
+test("funding networks send but never receive: no reverse, no destination, and a collision picks another launch chain", () => {
+ const fromArbitrum = { originChainId: 42161, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC", amount: "25" } as const;
+ assert.equal(canReverseBridgeRoute(fromArbitrum), false);
+ assert.deepEqual(changeBridgeRoute(fromArbitrum, { side: "reverse" }), fromArbitrum);
+ for (const id of BRIDGE_FUNDING_IDS) assert.deepEqual(changeBridgeRoute({ ...fromArbitrum, originChainId: 8453, destinationChainId: 4663 }, { side: "destination", chainId: id }), { ...fromArbitrum, originChainId: 8453, destinationChainId: 4663 });
+ // choosing the destination as the source cannot swap a funding network into the destination
+ assert.deepEqual(changeBridgeRoute(fromArbitrum, { side: "origin", chainId: 8453 }), { originChainId: 8453, destinationChainId: 4663, originAsset: "USDC", destinationAsset: "USDG", amount: "25" });
+ assert.deepEqual(changeBridgeRoute({ ...fromArbitrum, destinationChainId: 4663, destinationAsset: "USDG" }, { side: "origin", chainId: 4663 }), { originChainId: 4663, destinationChainId: 8453, originAsset: "USDG", destinationAsset: "USDC", amount: "" });
+ // moving between funding networks keeps the dollar and the amount
+ assert.deepEqual(changeBridgeRoute(fromArbitrum, { side: "origin", chainId: 10 }), { ...fromArbitrum, originChainId: 10 });
+ assert.deepEqual(changeBridgeRoute(fromArbitrum, { side: "origin", chainId: 1 }), { ...fromArbitrum, originChainId: 1 });
+ // and a launch chain still reverses
+ for (const id of BRIDGE_DESTINATION_IDS) assert.equal(canReverseBridgeRoute({ originChainId: id }), true);
+ for (const origin of BRIDGE_FUNDING_IDS) for (const destination of BRIDGE_DESTINATION_IDS) {
+ const usdc = bridgeRequest(ADDRESS, origin, "10.5", destination, "USDC", destination === 4663 ? "USDG" : "USDC");
+ assert.equal(usdc?.amount, "10500000");
+ const eth = bridgeRequest(ADDRESS, origin, "0.01", destination, "ETH", destination === 5042 || destination === 99901 ? "USDC" : "ETH");
+ assert.equal(eth?.amount, "10000000000000000");
+ }
+});
+
test("network selections resolve collisions atomically and never reinterpret ETH amounts as USDC", () => {
const initial = { originChainId: 8453, destinationChainId: 4663, amount: "0.01" } as const;
const toArc = changeBridgeRoute(initial, { side: "destination", chainId: 5042 });
@@ -118,8 +141,51 @@ test("asset selectors clear reinterpreted amounts and preserve supported tokens
assert.deepEqual(usdc, { ...route, originAsset: "USDC", amount: "" });
const funded = { ...usdc, amount: "25" };
assert.deepEqual(changeBridgeRoute(funded, { side: "reverse" }), { ...funded, originChainId: 5042, destinationChainId: 8453 });
- assert.deepEqual(changeBridgeRoute(funded, { side: "origin", chainId: 4663 }), { ...funded, originChainId: 4663, originAsset: "ETH", amount: "" });
+ // a dollar stays a dollar across chains: Base USDC becomes Robinhood USDG, and the amount is still cleared
+ assert.deepEqual(changeBridgeRoute(funded, { side: "origin", chainId: 4663 }), { ...funded, originChainId: 4663, originAsset: "USDG", amount: "" });
+ assert.deepEqual(changeBridgeRoute(funded, { side: "destination", chainId: 4663 }), { ...funded, destinationChainId: 4663, destinationAsset: "USDG" });
+ const fromRobinhood = { originChainId: 4663, destinationChainId: 8453, originAsset: "USDG", destinationAsset: "ETH", amount: "25" } as const;
+ assert.deepEqual(changeBridgeRoute(fromRobinhood, { side: "origin", chainId: 5042 }), { ...fromRobinhood, originChainId: 5042, originAsset: "USDC", amount: "" });
+ assert.deepEqual(changeBridgeRoute(fromRobinhood, { side: "reverse" }), { originChainId: 8453, destinationChainId: 4663, originAsset: "ETH", destinationAsset: "USDG", amount: "" });
+ // Ether has no dollar to map to on Arc, so it falls back to the chain's own asset as before
+ assert.deepEqual(changeBridgeRoute({ ...fromRobinhood, originAsset: "ETH" }, { side: "origin", chainId: 5042 }), { ...fromRobinhood, originChainId: 5042, originAsset: "USDC", amount: "" });
assert.deepEqual(changeBridgeRoute(route, { side: "destination-asset", asset: "ETH" }), route);
+ assert.deepEqual(changeBridgeRoute(fromRobinhood, { side: "origin-asset", asset: "USDC" }), fromRobinhood, "USDC is still not offered on Robinhood Chain");
+});
+
+test("HYPE can be picked to receive on Elysium, and never carried into a send or another chain", () => {
+ const toElysium = { originChainId: 8453, destinationChainId: 99901, originAsset: "USDC", destinationAsset: "USDC", amount: "25" } as const;
+ const hype = changeBridgeRoute(toElysium, { side: "destination-asset", asset: "HYPE" });
+ assert.deepEqual(hype, { ...toElysium, destinationAsset: "HYPE" }, "the amount stays: the source asset did not change");
+ // reversing would send HYPE, so Elysium sends its USDC instead: still USDC, so the amount stands
+ assert.deepEqual(changeBridgeRoute(hype, { side: "reverse" }), { originChainId: 99901, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC", amount: "25" });
+ assert.deepEqual(changeBridgeRoute(hype, { side: "destination", chainId: 8453 }), { originChainId: 99901, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC", amount: "25" });
+ // from Ether, the source becomes USDC, so the amount clears
+ const fromEther = { ...hype, originAsset: "ETH", amount: "0.01" } as const;
+ assert.deepEqual(changeBridgeRoute(fromEther, { side: "reverse" }), { originChainId: 99901, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "ETH", amount: "" });
+ // another destination has no HYPE: it takes that chain's default
+ assert.deepEqual(changeBridgeRoute(hype, { side: "destination", chainId: 4663 }), { ...hype, destinationChainId: 4663, destinationAsset: "ETH" });
+ assert.deepEqual(changeBridgeRoute(hype, { side: "origin", chainId: 42161 }), { ...hype, originChainId: 42161 });
+ const fromElysium = { originChainId: 99901, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "ETH", amount: "25" } as const;
+ assert.deepEqual(changeBridgeRoute(fromElysium, { side: "origin-asset", asset: "HYPE" }), fromElysium, "HYPE is never sent");
+ assert.deepEqual(changeBridgeRoute(toElysium, { side: "destination-asset", asset: "ETH" }), toElysium);
+ assert.deepEqual(changeBridgeRoute({ ...toElysium, destinationChainId: 4663, destinationAsset: "ETH" }, { side: "destination-asset", asset: "HYPE" }), { ...toElysium, destinationChainId: 4663, destinationAsset: "ETH" });
+ assert.equal(bridgeRequest(ADDRESS, 8453, "25", 99901, "USDC", "HYPE").destinationAsset, "HYPE");
+ assert.equal(bridgeRequest(ADDRESS, 99901, "25", 8453, "HYPE", "ETH"), null);
+ assert.equal(bridgeRequest(ADDRESS, 8453, "25", 4663, "USDC", "HYPE"), null);
+});
+
+test("Robinhood USDG is a six-decimal token of its own, never USDC and never Ether", () => {
+ const usdg = bridgeRequest(ADDRESS, 4663, "25.000001", 8453, "USDG", "USDC");
+ assert.equal(usdg?.amount, "25000001");
+ assert.equal(usdg?.originAsset, "USDG");
+ assert.equal(bridgeRequest(ADDRESS, 4663, "1.0000001", 8453, "USDG", "USDC"), null, "a seventh decimal place is refused, not rounded");
+ assert.equal(bridgeRequest(ADDRESS, 8453, "1", 4663, "ETH", "USDG")?.amount, "1000000000000000000");
+ assert.equal(bridgeRequest(ADDRESS, 8453, "1", 5042, "USDG", "USDC"), null, "USDG exists on Robinhood Chain only");
+ assert.equal(bridgeRequest(ADDRESS, 8453, "1", 5042, "USDC", "USDG"), null);
+ // a USDG source has a separate ETH gas balance, like Base USDC and unlike Arc
+ assert.equal(nativeSourceAmount(usdg!), 0n);
+ assert.notEqual(bridgeRequestKey(usdg), bridgeRequestKey({ ...usdg!, originAsset: "ETH" }));
});
test("Base USDC uses exact pinned ERC20 deposits while reserving separate ETH gas", () => {
@@ -138,7 +204,7 @@ test("Base USDC uses exact pinned ERC20 deposits while reserving separate ETH ga
]) assert.throws(() => validateBridgeQuote(changed, q, NOW));
const unlimited = ((1n << 256n) - 1n).toString();
const unlimitedQuote: BridgeQuote = { ...q, amount: unlimited, approval: { ...q.approval!, amount: unlimited }, transaction: { ...q.transaction, data: encodeFunctionData({ abi: ERC20_DEPOSIT_ABI, functionName: "depositErc20", args: [ADDRESS, BASE_USDC, BigInt(unlimited), ORDER] }) } };
- assert.throws(() => validateBridgeQuote(unlimitedQuote, unlimitedQuote, NOW), /Unlimited USDC approvals/);
+ assert.throws(() => validateBridgeQuote(unlimitedQuote, unlimitedQuote, NOW), /Unlimited token approvals/);
});
test("asset changes across awaited preflight cancel a reviewed deposit", async () => {
@@ -479,11 +545,29 @@ test("transfer storage restores per wallet including an unknown transaction hash
assert.equal(restored.read(ADDRESS), null);
});
+test("a token deposit saved without named assets reads back: Elysium's default USDC is written as version three", () => {
+ const depositData = encodeFunctionData({ abi: ERC20_DEPOSIT_ABI, functionName: "depositErc20", args: [ADDRESS, ELYSIUM_USDC, 25_000_000n, ORDER] });
+ const transfer: TrackedBridgeTransfer = { address: ADDRESS, originChainId: 99901, destinationChainId: 8453, amount: "25000000", requestId: REQUEST, destinationHashes: [], status: "pending", createdAt: 1_000_000, depositData, depositKind: "erc20" };
+ const saved = JSON.parse(serializeTransfer(transfer));
+ // version 2 is Arc's alone on read, so this record names its assets and takes version 3
+ assert.deepEqual([saved.version, saved.originAsset, saved.destinationAsset], [3, "USDC", "ETH"]);
+ assert.deepEqual(parseStoredTransfer(serializeTransfer(transfer), ADDRESS), { ...transfer, originAsset: "USDC", destinationAsset: "ETH", sourceHash: undefined });
+ // the old shape for the same record is still refused, which is why it must never be written
+ assert.throws(() => parseStoredTransfer(JSON.stringify({ ...transfer, version: 2 }), ADDRESS));
+ // Arc's own records keep version 2 and read back unchanged
+ const arcData = encodeFunctionData({ abi: ERC20_DEPOSIT_ABI, functionName: "depositErc20", args: [ADDRESS, ARC_USDC, 25_000_000n, ORDER] });
+ const arc: TrackedBridgeTransfer = { ...transfer, originChainId: 5042, depositData: arcData };
+ assert.equal(JSON.parse(serializeTransfer(arc)).version, 2);
+ assert.deepEqual(parseStoredTransfer(serializeTransfer(arc), ADDRESS), { ...arc, sourceHash: undefined });
+});
+
test("version-one recovery keeps old Base/Robinhood records and accepts every distinct Arc route", () => {
for (const originChainId of BRIDGE_CHAIN_IDS) for (const destinationChainId of BRIDGE_CHAIN_IDS) {
if (originChainId === destinationChainId) continue;
const transfer = { ...tracked(), originChainId, destinationChainId };
- assert.deepEqual(parseStoredTransfer(serializeTransfer(transfer), ADDRESS), { ...transfer, sourceHash: undefined });
+ // nothing is ever sent to a funding network, so a saved transfer naming one as its destination is corrupt
+ if (isBridgeFundingChain(destinationChainId)) assert.throws(() => parseStoredTransfer(serializeTransfer(transfer), ADDRESS));
+ else assert.deepEqual(parseStoredTransfer(serializeTransfer(transfer), ADDRESS), { ...transfer, sourceHash: undefined });
}
});
diff --git a/app/src/lib/bridge/client.ts b/app/src/lib/bridge/client.ts
index 33418c5f..10c20ba5 100644
--- a/app/src/lib/bridge/client.ts
+++ b/app/src/lib/bridge/client.ts
@@ -1,9 +1,14 @@
import { BaseError, decodeEventLog, decodeFunctionData, encodeFunctionData, InsufficientFundsError, isAddress, parseUnits, type Address, type Hex } from "viem";
import { friendlyError } from "../errors";
-import { bridgeCurrency, bridgeFeePercent, defaultBridgeAsset, isBridgeAssetSupported, isBridgeChainId, type BridgeAsset, type BridgeChainId, type BridgeQuote, type BridgeQuoteRejection, type BridgeQuoteRequest, type BridgeStatus, type BridgeStatusResponse } from "./types";
+import { CCTP_BURN_EVENT, CCTP_TOKEN_MESSENGER, cctpAmountOut, cctpBurnFee, cctpRoute, isCctpBurnLog } from "./cctp";
+import { BRIDGE_DESTINATION_IDS, bridgeAssets, bridgeCurrency, bridgeFeePercent, defaultBridgeAsset, isBridgeAssetSupported, isBridgeChainId, isBridgeDestination, isDollarAsset, type BridgeAsset, type BridgeChainId, type BridgeProvider, type BridgeQuote, type BridgeQuoteRejection, type BridgeQuoteRequest, type BridgeStatus, type BridgeStatusResponse } from "./types";
export type BridgePhase = "idle" | "quoting" | "review" | "switching" | "confirming" | "pending" | "success" | "refund" | "failure" | "uncertain";
export type TrackedBridgeTransfer = BridgeQuoteRequest & {
+ /** Circle's CCTP, or Relay when omitted. A Circle record is tracked by its source transaction, not by `requestId`. */
+ provider?: BridgeProvider;
+ /** Circle only: the source block before the wallet was asked, where a burn with no returned hash is looked for. */
+ sourceBlock?: string;
requestId: Hex;
sourceHash?: Hex;
destinationHashes: Hex[];
@@ -47,7 +52,7 @@ export function parseBridgeAmount(value: string, decimals: 6 | 18 = 18): bigint
}
export function bridgeRequest(address: Address | undefined, originChainId: BridgeChainId, amount: string, destinationChainId: BridgeChainId, originAsset?: BridgeAsset, destinationAsset?: BridgeAsset): BridgeQuoteRequest | null {
- if (!address || !isAddress(address) || !isBridgeChainId(originChainId) || !isBridgeChainId(destinationChainId) || originChainId === destinationChainId || !isBridgeAssetSupported(originChainId, originAsset ?? defaultBridgeAsset(originChainId)) || !isBridgeAssetSupported(destinationChainId, destinationAsset ?? defaultBridgeAsset(destinationChainId))) return null;
+ if (!address || !isAddress(address) || !isBridgeChainId(originChainId) || !isBridgeDestination(destinationChainId) || originChainId === destinationChainId || !isBridgeAssetSupported(originChainId, originAsset ?? defaultBridgeAsset(originChainId), "input") || !isBridgeAssetSupported(destinationChainId, destinationAsset ?? defaultBridgeAsset(destinationChainId), "output")) return null;
const units = parseBridgeAmount(amount, bridgeCurrency(originChainId, originAsset, "input").decimals);
return units === null ? null : { address, originChainId, destinationChainId, amount: units.toString(), ...(originAsset ? { originAsset } : {}), ...(destinationAsset ? { destinationAsset } : {}) };
}
@@ -55,6 +60,11 @@ export function bridgeRequest(address: Address | undefined, originChainId: Bridg
export type BridgeRouteInputs = { originChainId: BridgeChainId; destinationChainId: BridgeChainId; amount: string; originAsset?: BridgeAsset; destinationAsset?: BridgeAsset };
export type BridgeRouteChange = { side: "origin" | "destination"; chainId: BridgeChainId } | { side: "origin-asset" | "destination-asset"; asset: BridgeAsset } | { side: "reverse" };
+/** A route reverses only when its source can also receive: a funding network (Ethereum, Arbitrum, Optimism) cannot. */
+export function canReverseBridgeRoute(route: Pick): boolean {
+ return isBridgeDestination(route.originChainId);
+}
+
/** Select/swap one distinct pair, clearing currency amounts when the source asset changes. */
export function changeBridgeRoute(current: BridgeRouteInputs, change: BridgeRouteChange): BridgeRouteInputs {
let { originChainId, destinationChainId } = current;
@@ -63,25 +73,36 @@ export function changeBridgeRoute(current: BridgeRouteInputs, change: BridgeRout
const previousOriginAsset = originAsset;
const explicitAssets = current.originAsset !== undefined || current.destinationAsset !== undefined || change.side === "origin-asset" || change.side === "destination-asset";
if (change.side === "reverse") {
+ if (!canReverseBridgeRoute(current)) return current;
[originChainId, destinationChainId] = [destinationChainId, originChainId];
[originAsset, destinationAsset] = [destinationAsset, originAsset];
} else if (change.side === "origin-asset" || change.side === "destination-asset") {
const chainId = change.side === "origin-asset" ? originChainId : destinationChainId;
- if (!isBridgeAssetSupported(chainId, change.asset)) return current;
+ if (!isBridgeAssetSupported(chainId, change.asset, change.side === "origin-asset" ? "input" : "output")) return current;
if (change.side === "origin-asset") originAsset = change.asset;
else destinationAsset = change.asset;
} else if ("chainId" in change) {
if (!isBridgeChainId(change.chainId)) return current;
if (change.side === "origin") {
- if (change.chainId === destinationChainId) { destinationChainId = originChainId; [originAsset, destinationAsset] = [destinationAsset, originAsset]; }
+ // picking the destination as the source swaps the ends, unless the old source is a funding network, which cannot
+ // receive: then the transfer goes to the first other launch chain
+ if (change.chainId === destinationChainId) {
+ if (isBridgeDestination(originChainId)) { destinationChainId = originChainId; [originAsset, destinationAsset] = [destinationAsset, originAsset]; }
+ else destinationChainId = BRIDGE_DESTINATION_IDS.find((id) => id !== change.chainId)!;
+ }
originChainId = change.chainId;
} else {
+ if (!isBridgeDestination(change.chainId)) return current;
if (change.chainId === originChainId) { originChainId = destinationChainId; [originAsset, destinationAsset] = [destinationAsset, originAsset]; }
destinationChainId = change.chainId;
}
}
- if (!isBridgeAssetSupported(originChainId, originAsset)) originAsset = defaultBridgeAsset(originChainId);
- if (!isBridgeAssetSupported(destinationChainId, destinationAsset)) destinationAsset = defaultBridgeAsset(destinationChainId);
+ // An asset the new chain lacks on that side falls back to the chain's default, except that a dollar stays a dollar:
+ // USDC on Base or Arc becomes USDG on Robinhood Chain, and back. HYPE, which Elysium only receives, cannot be sent.
+ const kept = (chainId: BridgeChainId, asset: BridgeAsset, side: "input" | "output"): BridgeAsset => isBridgeAssetSupported(chainId, asset, side) ? asset
+ : (isDollarAsset(asset) ? bridgeAssets(chainId, side).find(isDollarAsset) : undefined) ?? defaultBridgeAsset(chainId);
+ originAsset = kept(originChainId, originAsset, "input");
+ destinationAsset = kept(destinationChainId, destinationAsset, "output");
const amount = previousOriginAsset === originAsset ? current.amount : "";
return { originChainId, destinationChainId, amount, ...(explicitAssets ? { originAsset, destinationAsset } : {}) };
}
@@ -111,8 +132,8 @@ export function parseBridgeQuoteRejection(value: unknown, request: BridgeQuoteRe
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
const rejected = value as BridgeQuoteRejection;
const allowed = ["address", "originChainId", "destinationChainId", "originAsset", "destinationAsset", "amount", "reason", "relayFee", "relayFeePercent", "sourceGas", "totalImpactPercent"];
- if (Object.keys(value).some((key) => !allowed.includes(key)) || !isAddress(rejected.address ?? "") || !isBridgeChainId(rejected.originChainId) || !isBridgeChainId(rejected.destinationChainId) || rejected.originChainId === rejected.destinationChainId || !isWei(rejected.amount, true)) return null;
- if ((rejected.originAsset !== undefined && !isBridgeAssetSupported(rejected.originChainId, rejected.originAsset)) || (rejected.destinationAsset !== undefined && !isBridgeAssetSupported(rejected.destinationChainId, rejected.destinationAsset)) || bridgeRequestKey(rejected) !== bridgeRequestKey(request)) return null;
+ if (Object.keys(value).some((key) => !allowed.includes(key)) || !isAddress(rejected.address ?? "") || !isBridgeChainId(rejected.originChainId) || !isBridgeDestination(rejected.destinationChainId) || rejected.originChainId === rejected.destinationChainId || !isWei(rejected.amount, true)) return null;
+ if ((rejected.originAsset !== undefined && !isBridgeAssetSupported(rejected.originChainId, rejected.originAsset, "input")) || (rejected.destinationAsset !== undefined && !isBridgeAssetSupported(rejected.destinationChainId, rejected.destinationAsset, "output")) || bridgeRequestKey(rejected) !== bridgeRequestKey(request)) return null;
const decimals = bridgeCurrency(rejected.originChainId, rejected.originAsset, "input").decimals;
for (const [fee, precision] of [[rejected.relayFee, decimals], [rejected.sourceGas, 18]] as const) {
if (typeof fee !== "string" || fee.length > 100 || !new RegExp(`^\\d+(?:\\.\\d{1,${precision}})?$`).test(fee) || parseUnits(fee, precision) > MAX_UINT) return null;
@@ -130,7 +151,7 @@ export function parseBridgeQuoteRejection(value: unknown, request: BridgeQuoteRe
export function validateBridgeQuote(value: unknown, request: BridgeQuoteRequest, now: number): BridgeQuote {
if (!value || typeof value !== "object") throw new Error("The bridge returned an invalid quote. Request a new quote.");
const quote = value as BridgeQuote;
- if (!isAddress(quote.address ?? "") || !isBridgeChainId(quote.originChainId) || !isBridgeChainId(quote.destinationChainId) || !isBridgeAssetSupported(quote.originChainId, quote.originAsset ?? defaultBridgeAsset(quote.originChainId)) || !isBridgeAssetSupported(quote.destinationChainId, quote.destinationAsset ?? defaultBridgeAsset(quote.destinationChainId)) || bridgeRequestKey(quote) !== bridgeRequestKey(request) || quote.destinationChainId === quote.originChainId) {
+ if (!isAddress(quote.address ?? "") || !isBridgeChainId(quote.originChainId) || !isBridgeDestination(quote.destinationChainId) || !isBridgeAssetSupported(quote.originChainId, quote.originAsset ?? defaultBridgeAsset(quote.originChainId), "input") || !isBridgeAssetSupported(quote.destinationChainId, quote.destinationAsset ?? defaultBridgeAsset(quote.destinationChainId), "output") || bridgeRequestKey(quote) !== bridgeRequestKey(request) || quote.destinationChainId === quote.originChainId) {
throw new Error("The quote no longer matches this wallet, amount, or route. Review a new quote.");
}
if (!isHash(quote.requestId) || !isWei(quote.amount, true) || !isWei(quote.amountOut, true) || !isWei(quote.minimumAmountOut, true) || BigInt(quote.minimumAmountOut) > BigInt(quote.amountOut)) {
@@ -150,9 +171,10 @@ export function validateBridgeQuote(value: unknown, request: BridgeQuoteRequest,
}
const tx = quote.transaction;
const erc20 = !/^0x0{40}$/.test(inputCurrency.address);
- if (erc20 && BigInt(request.amount) === MAX_UINT) throw new Error("Unlimited USDC approvals are not supported. Enter an exact transfer amount.");
+ if (erc20 && BigInt(request.amount) === MAX_UINT) throw new Error("Unlimited token approvals are not supported. Enter an exact transfer amount.");
+ if (quote.provider !== undefined) return validateCctpQuote(quote, request);
if (erc20 ? !quote.approval || quote.approval.token?.toLowerCase() !== inputCurrency.address.toLowerCase() || quote.approval.spender?.toLowerCase() !== RELAY_DEPOSITORY || quote.approval.amount !== request.amount : quote.approval !== undefined) {
- throw new Error("The approval did not match the exact USDC deposit on this network.");
+ throw new Error("The approval did not match the exact token deposit on this network.");
}
if (!tx || tx.chainId !== request.originChainId || typeof tx.to !== "string" || tx.to.toLowerCase() !== RELAY_DEPOSITORY || tx.value !== (erc20 ? "0" : request.amount) || typeof tx.data !== "string" || !new RegExp(`^0x[0-9a-fA-F]{${erc20 ? 264 : 136}}$`).test(tx.data)) {
throw new Error("The bridge transaction did not pass the deposit safety check.");
@@ -167,6 +189,25 @@ export function validateBridgeQuote(value: unknown, request: BridgeQuoteRequest,
return quote;
}
+/**
+ * A Circle quote is only ever the one burn `cctpBurnData` builds: the pinned messenger, this wallet as recipient, the
+ * exact amount, Circle's forwarding hook, and a fee under 5%. What arrives is the amount less that fee, exactly.
+ */
+function validateCctpQuote(quote: BridgeQuote, request: BridgeQuoteRequest): BridgeQuote {
+ const route = quote.provider === "cctp" ? cctpRoute(request) : null;
+ const tx = quote.transaction;
+ const maxFee = route && tx ? cctpBurnFee(tx.data, request) : null;
+ if (!route || maxFee === null || !quote.approval || quote.approval.token?.toLowerCase() !== route.burnToken.toLowerCase() || quote.approval.spender?.toLowerCase() !== CCTP_TOKEN_MESSENGER.toLowerCase() || quote.approval.amount !== request.amount) {
+ throw new Error("The approval did not match the exact Circle burn on this network.");
+ }
+ if (tx.chainId !== request.originChainId || typeof tx.to !== "string" || tx.to.toLowerCase() !== CCTP_TOKEN_MESSENGER.toLowerCase() || tx.value !== "0") {
+ throw new Error("The bridge transaction did not pass the deposit safety check.");
+ }
+ const out = cctpAmountOut(BigInt(request.amount), maxFee, route.outputDecimals).toString();
+ if (quote.amountOut !== out || quote.minimumAmountOut !== out || parseUnits(quote.relayFee, 6) !== maxFee) throw new Error("The Circle quote did not match its own burn.");
+ return quote;
+}
+
/**
* The server states how long a quote stays valid; only this device's clock
* decides when that runs out. Anchoring on the request time also absorbs the
@@ -213,13 +254,14 @@ export const DISCARD_AFTER_MS = 15 * 60_000;
export type ProviderObservation = { requestId: Hex; status: BridgeStatusResponse; sourceMined: boolean; observedAt: number };
/**
- * Bounded escape hatch for a deposit that never happened: the provider still
+ * Relay-only escape hatch for a deposit that never happened: the provider still
* reports "waiting" with no deposit, no wallet hash is mined, and the order
* deadline (about a minute) is long past. A record with any on-chain evidence,
- * or a stale observation, keeps blocking until it settles.
+ * or a stale observation, keeps blocking until it settles. Circle burns have no
+ * deadline: even a complete empty scan cannot rule out a later confirmation.
*/
export function transferCanDiscard(transfer: TrackedBridgeTransfer | null, observation: ProviderObservation | null, now: number): boolean {
- if (!transfer || transferIsTerminal(transfer) || !observation || observation.requestId !== transfer.requestId) return false;
+ if (!transfer || transfer.provider === "cctp" || transferIsTerminal(transfer) || !observation || observation.requestId !== transfer.requestId) return false;
if (observation.status.status !== "waiting" || observation.status.inTxHashes.length > 0 || observation.status.txHashes.length > 0 || observation.sourceMined) return false;
return now - transfer.createdAt >= DISCARD_AFTER_MS && now - observation.observedAt <= 60_000 && now >= observation.observedAt;
}
@@ -260,12 +302,14 @@ export function mergeBridgeStatus(transfer: TrackedBridgeTransfer, status: Bridg
/** Recovery without a wallet-returned hash must bind the provider's hash on-chain. */
export function isMatchingSourceDeposit(transfer: TrackedBridgeTransfer, transaction: { from: Address; to: Address | null; input: Hex; value: bigint }): boolean {
+ if (transfer.provider === "cctp") return !!transfer.depositData && transaction.from.toLowerCase() === transfer.address.toLowerCase() && transaction.to?.toLowerCase() === CCTP_TOKEN_MESSENGER.toLowerCase() && transaction.value === 0n && transaction.input.toLowerCase() === transfer.depositData.toLowerCase();
return !!transfer.depositData && transaction.from.toLowerCase() === transfer.address.toLowerCase() && transaction.to?.toLowerCase() === RELAY_DEPOSITORY && transaction.value.toString() === (transfer.depositKind === "erc20" ? "0" : transfer.amount) && transaction.input.toLowerCase() === transfer.depositData.toLowerCase();
}
/** Smart wallets may deposit through an internal call rather than the outer tx. */
export function hasMatchingDepositEvent(transfer: TrackedBridgeTransfer, receipt: { status: "success" | "reverted"; logs: readonly { address: Address; data: Hex; topics: readonly Hex[] }[] }): boolean {
if (!transfer.depositData || receipt.status !== "success") return false;
+ if (transfer.provider === "cctp") return receipt.logs.some((log) => isCctpBurnLog(log, transfer));
try {
const erc20 = transfer.depositKind === "erc20";
const orderId = erc20 ? decodeFunctionData({ abi: ERC20_DEPOSIT_ABI, data: transfer.depositData }).args[3] : decodeFunctionData({ abi: NATIVE_DEPOSIT_ABI, data: transfer.depositData }).args[1];
@@ -333,6 +377,8 @@ export type DepositDependencies = {
readTransfer: (address: Address) => TrackedBridgeTransfer | null;
saveTransfer: (transfer: TrackedBridgeTransfer) => void;
removeTransfer: (address: Address) => void;
+ /** Circle only: the source network's current block, so a burn whose hash the wallet never returned can be found. */
+ sourceBlock?: (quote: BridgeQuote) => Promise;
send: (quote: BridgeQuote, gas: PreparedBridgeGas) => Promise;
phase: (phase: "switching" | "confirming") => void;
};
@@ -362,7 +408,12 @@ export async function submitBridgeDeposit(quote: BridgeQuote, deps: DepositDepen
if (wallet.address?.toLowerCase() !== request.address.toLowerCase() || wallet.chainId !== request.originChainId) throw new Error("Your wallet account or network changed. Review a new quote.");
const latest = deps.readTransfer(request.address);
if (latest && !transferIsTerminal(latest)) throw new Error("Another transfer is now being tracked for this wallet. Check its status before continuing.");
- const tracked: TrackedBridgeTransfer = { ...request, requestId: quote.requestId, destinationHashes: [], status: "uncertain", createdAt: deps.now(), depositData: quote.transaction.data, ...(quote.approval ? { depositKind: "erc20" as const } : {}) };
+ let sourceBlock: string | undefined;
+ if (quote.provider === "cctp" && deps.sourceBlock) {
+ try { sourceBlock = (await deps.sourceBlock(quote)).toString(); } catch { /* recovery then relies on the wallet's hash */ }
+ checkRequest();
+ }
+ const tracked: TrackedBridgeTransfer = { ...request, ...(quote.provider ? { provider: quote.provider } : {}), ...(sourceBlock ? { sourceBlock } : {}), requestId: quote.requestId, destinationHashes: [], status: "uncertain", createdAt: deps.now(), depositData: quote.transaction.data, ...(quote.approval ? { depositKind: "erc20" as const } : {}) };
// This write must succeed before invoking the wallet. A reload during its
// prompt resumes read-only tracking by requestId, even without a tx hash.
try { deps.saveTransfer(tracked); } catch {
@@ -395,18 +446,21 @@ export async function submitBridgeDeposit(quote: BridgeQuote, deps: DepositDepen
export function parseStoredTransfer(raw: string, address: Address): TrackedBridgeTransfer {
const entry = JSON.parse(raw) as TrackedBridgeTransfer & { version?: unknown };
const erc20 = entry?.depositKind === "erc20";
- const assetsValid = isBridgeChainId(entry?.originChainId) && isBridgeChainId(entry?.destinationChainId) && isBridgeAssetSupported(entry.originChainId, entry.originAsset) && isBridgeAssetSupported(entry.destinationChainId, entry.destinationAsset);
+ const cctp = entry?.provider === "cctp";
+ const assetsValid = isBridgeChainId(entry?.originChainId) && isBridgeChainId(entry?.destinationChainId) && isBridgeAssetSupported(entry.originChainId, entry.originAsset, "input") && isBridgeAssetSupported(entry.destinationChainId, entry.destinationAsset, "output");
const legacyAssets = entry?.originAsset === undefined && entry?.destinationAsset === undefined;
- const validVersion = (entry?.version === 1 && legacyAssets && entry.depositKind === undefined) || (entry?.version === 2 && legacyAssets && erc20 && entry.originChainId === 5042 && typeof entry.depositData === "string") || (entry?.version === 3 && assetsValid && typeof entry.depositData === "string" && (entry.depositKind === undefined || erc20) && erc20 === !/^0x0{40}$/.test(bridgeCurrency(entry.originChainId, entry.originAsset, "input").address));
- if (!validVersion || typeof entry.address !== "string" || entry.address.toLowerCase() !== address.toLowerCase() || !isAddress(entry.address) || !isBridgeChainId(entry.originChainId) || !isBridgeChainId(entry.destinationChainId) || entry.destinationChainId === entry.originChainId || !isHash(entry.requestId) || !isWei(entry.amount, true) || !Number.isFinite(entry.createdAt) || entry.createdAt <= 0 || (entry.sourceHash !== undefined && !isHash(entry.sourceHash)) || !Array.isArray(entry.destinationHashes) || entry.destinationHashes.length > 50 || !entry.destinationHashes.every(isHash) || (entry.status !== "uncertain" && !STATUSES.includes(entry.status)) || (entry.depositData !== undefined && !new RegExp(`^0x[0-9a-fA-F]{${erc20 ? 264 : 136}}$`).test(entry.depositData)) || (entry.failureReason !== undefined && entry.failureReason !== "source-reverted")) {
+ const validVersion = cctp ? entry.version === 4 && assetsValid && erc20 && typeof entry.depositData === "string" && cctpBurnFee(entry.depositData, entry) !== null && (entry.sourceBlock === undefined || (typeof entry.sourceBlock === "string" && /^\d{1,20}$/.test(entry.sourceBlock)))
+ : entry?.provider === undefined && entry?.sourceBlock === undefined && ((entry?.version === 1 && legacyAssets && entry.depositKind === undefined) || (entry?.version === 2 && legacyAssets && erc20 && entry.originChainId === 5042 && typeof entry.depositData === "string") || (entry?.version === 3 && assetsValid && typeof entry.depositData === "string" && (entry.depositKind === undefined || erc20) && erc20 === !/^0x0{40}$/.test(bridgeCurrency(entry.originChainId, entry.originAsset, "input").address)));
+ if (!validVersion || typeof entry.address !== "string" || entry.address.toLowerCase() !== address.toLowerCase() || !isAddress(entry.address) || !isBridgeChainId(entry.originChainId) || !isBridgeDestination(entry.destinationChainId) || entry.destinationChainId === entry.originChainId || !isHash(entry.requestId) || !isWei(entry.amount, true) || !Number.isFinite(entry.createdAt) || entry.createdAt <= 0 || (entry.sourceHash !== undefined && !isHash(entry.sourceHash)) || !Array.isArray(entry.destinationHashes) || entry.destinationHashes.length > 50 || !entry.destinationHashes.every(isHash) || (entry.status !== "uncertain" && !STATUSES.includes(entry.status)) || (entry.depositData !== undefined && !cctp && !new RegExp(`^0x[0-9a-fA-F]{${erc20 ? 264 : 136}}$`).test(entry.depositData)) || (entry.failureReason !== undefined && entry.failureReason !== "source-reverted")) {
throw new Error("Saved bridge recovery data could not be read. Check your transfer on Relay before trying again.");
}
- if (erc20) {
+ if (cctp) { /* the burn was re-encoded and bound to this wallet, amount and route above */ }
+ else if (erc20) {
try {
const order = decodeFunctionData({ abi: ERC20_DEPOSIT_ABI, data: entry.depositData! }).args[3];
const canonical = encodeFunctionData({ abi: ERC20_DEPOSIT_ABI, functionName: "depositErc20", args: [entry.address, bridgeCurrency(entry.originChainId, entry.originAsset, "input").address, BigInt(entry.amount), order] });
if (/^0x0+$/.test(order) || canonical.toLowerCase() !== entry.depositData!.toLowerCase()) throw new Error("binding");
- } catch { throw new Error("Saved USDC deposit details could not be verified. Check Relay before trying again."); }
+ } catch { throw new Error("Saved token deposit details could not be verified. Check Relay before trying again."); }
} else if (entry.depositData) {
try {
const order = decodeFunctionData({ abi: NATIVE_DEPOSIT_ABI, data: entry.depositData }).args[1];
@@ -414,10 +468,62 @@ export function parseStoredTransfer(raw: string, address: Address): TrackedBridg
if (/^0x0+$/.test(order) || canonical.toLowerCase() !== entry.depositData.toLowerCase()) throw new Error("binding");
} catch { throw new Error("Saved native deposit details could not be verified. Check Relay before trying again."); }
}
- return { address: entry.address, originChainId: entry.originChainId, destinationChainId: entry.destinationChainId, ...(entry.originAsset ? { originAsset: entry.originAsset } : {}), ...(entry.destinationAsset ? { destinationAsset: entry.destinationAsset } : {}), amount: entry.amount, requestId: entry.requestId, sourceHash: entry.sourceHash, destinationHashes: entry.destinationHashes, status: entry.status, createdAt: entry.createdAt, ...(entry.depositData ? { depositData: entry.depositData } : {}), ...(erc20 ? { depositKind: "erc20" as const } : {}), ...(entry.failureReason ? { failureReason: entry.failureReason } : {}) };
+ return { ...(cctp ? { provider: "cctp" as const, ...(entry.sourceBlock ? { sourceBlock: entry.sourceBlock } : {}) } : {}), address: entry.address, originChainId: entry.originChainId, destinationChainId: entry.destinationChainId, ...(entry.originAsset ? { originAsset: entry.originAsset } : {}), ...(entry.destinationAsset ? { destinationAsset: entry.destinationAsset } : {}), amount: entry.amount, requestId: entry.requestId, sourceHash: entry.sourceHash, destinationHashes: entry.destinationHashes, status: entry.status, createdAt: entry.createdAt, ...(entry.depositData ? { depositData: entry.depositData } : {}), ...(erc20 ? { depositKind: "erc20" as const } : {}), ...(entry.failureReason ? { failureReason: entry.failureReason } : {}) };
}
export function serializeTransfer(transfer: TrackedBridgeTransfer): string {
- const explicitAssets = transfer.originAsset !== undefined || transfer.destinationAsset !== undefined;
- return JSON.stringify({ ...transfer, ...(explicitAssets ? { originAsset: transfer.originAsset ?? defaultBridgeAsset(transfer.originChainId), destinationAsset: transfer.destinationAsset ?? defaultBridgeAsset(transfer.destinationChainId) } : {}), version: explicitAssets ? 3 : transfer.depositKind === "erc20" ? 2 : 1 });
+ // Versions 1 and 2 are the records from before assets were named: a native deposit, and Arc's USDC. Any other token
+ // deposit without named assets (Elysium's USDC is its default) is written with them, as version 3: the reader takes
+ // version 2 from Arc alone, and a record it refuses is a transfer that can no longer be tracked.
+ const explicitAssets = transfer.originAsset !== undefined || transfer.destinationAsset !== undefined || (transfer.depositKind === "erc20" && transfer.originChainId !== 5042);
+ return JSON.stringify({ ...transfer, ...(explicitAssets ? { originAsset: transfer.originAsset ?? defaultBridgeAsset(transfer.originChainId), destinationAsset: transfer.destinationAsset ?? defaultBridgeAsset(transfer.destinationChainId) } : {}), version: transfer.provider === "cctp" ? 4 : explicitAssets ? 3 : transfer.depositKind === "erc20" ? 2 : 1 });
+}
+
+/** Where a tracked transfer's status is read: Relay by request ID, Circle by the burn's source transaction. */
+export function bridgeStatusUrl(transfer: TrackedBridgeTransfer): string | null {
+ if (transfer.provider !== "cctp") return `/api/bridge/status?requestId=${encodeURIComponent(transfer.requestId)}`;
+ if (!transfer.sourceHash) return null;
+ const params = new URLSearchParams({ provider: "cctp", origin: String(transfer.originChainId), destination: String(transfer.destinationChainId), hash: transfer.sourceHash, address: transfer.address.toLowerCase(), amount: transfer.amount });
+ return `/api/bridge/status?${params}`;
+}
+
+/** Local waiting placeholder before a Circle hash is known; not an observation from Circle or proof of no burn. */
+export const CCTP_NOT_SEEN: BridgeStatusResponse = { status: "waiting", inTxHashes: [], txHashes: [] };
+
+type LogReader = {
+ getBlockNumber: () => Promise;
+ getLogs: (args: { address: Address; event: (typeof CCTP_BURN_EVENT)[0]; args: { burnToken: Address; depositor: Address }; fromBlock: bigint; toBlock: bigint }) => Promise;
+};
+/** Blocks searched after the saved source block: about 40 minutes on Arbitrum, hours elsewhere. */
+export const CCTP_SCAN_BLOCKS = 9_999n;
+
+type CctpScanRange = { fromBlock: bigint; toBlock: bigint; headBlock: bigint; complete: boolean };
+export type CctpBurnScan = (
+ | { kind: "found"; hash: Hex }
+ | { kind: "ambiguous"; hashes: Hex[] }
+ | { kind: "not-found" }
+) & CctpScanRange | { kind: "unavailable"; reason: "unsupported-route" | "missing-source-block" | "head-before-source" | "rpc-error" };
+
+/**
+ * Recovery evidence for a wallet that never returned a hash or replaced it (speed-up). Only Circle's own event
+ * matching every saved field counts. Ambiguity, unavailable reads, and the bounded range are explicit: none means
+ * that no burn happened. Even a complete range describes this head only, not a transaction still waiting to mine.
+ */
+export async function findCctpBurn(reader: LogReader, transfer: TrackedBridgeTransfer): Promise {
+ const route = transfer.provider === "cctp" ? cctpRoute(transfer) : null;
+ if (!route) return { kind: "unavailable", reason: "unsupported-route" };
+ if (!transfer.sourceBlock) return { kind: "unavailable", reason: "missing-source-block" };
+ try {
+ const fromBlock = BigInt(transfer.sourceBlock);
+ const headBlock = await reader.getBlockNumber();
+ if (headBlock < fromBlock) return { kind: "unavailable", reason: "head-before-source" };
+ const toBlock = headBlock - fromBlock > CCTP_SCAN_BLOCKS ? fromBlock + CCTP_SCAN_BLOCKS : headBlock;
+ const range = { fromBlock, toBlock, headBlock, complete: toBlock === headBlock };
+ const logs = await reader.getLogs({ address: CCTP_TOKEN_MESSENGER, event: CCTP_BURN_EVENT[0], args: { burnToken: route.burnToken, depositor: transfer.address }, fromBlock, toBlock });
+ const matches = logs.filter((log) => isCctpBurnLog(log, transfer));
+ const hashes = [...new Set(matches.flatMap((log) => isHash(log.transactionHash) ? [log.transactionHash.toLowerCase() as Hex] : []))];
+ if (matches.length === 0) return { kind: "not-found", ...range };
+ if (hashes.length === 1 && matches.every((log) => isHash(log.transactionHash))) return { kind: "found", hash: hashes[0], ...range };
+ return { kind: "ambiguous", hashes, ...range };
+ } catch { return { kind: "unavailable", reason: "rpc-error" }; }
}
diff --git a/app/src/lib/bridge/exchange.test.ts b/app/src/lib/bridge/exchange.test.ts
new file mode 100644
index 00000000..a1060cfd
--- /dev/null
+++ b/app/src/lib/bridge/exchange.test.ts
@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { Address } from "viem";
+import { EXCHANGE_NETWORKS, EXCHANGE_WATCH_MS, exchangeGuideOpen, exchangeNeedsGas, exchangeNext, findExchangeArrivals, nextExchangeBaseline, parseExchangeWatch, readExchangeHoldings, serializeExchangeWatch, type ExchangeArrival } from "./exchange.ts";
+import type { BridgeHolding } from "./fund.ts";
+import { ARBITRUM_USDC, BASE_USDC, BRIDGE_SEND_ASSETS, ETHEREUM_USDC, OPTIMISM_USDC, isBridgeAssetSupported, type BridgeChainId } from "./types.ts";
+
+const WALLET = "0x1111111111111111111111111111111111111111" as Address;
+const eth = (chainId: BridgeChainId, value: number): BridgeHolding => ({ chainId, asset: "ETH", amount: BigInt(Math.round(value * 1e6)) * 10n ** 12n, decimals: 18 });
+const usdc = (chainId: BridgeChainId, value: number): BridgeHolding => ({ chainId, asset: "USDC", amount: BigInt(Math.round(value * 1e6)), decimals: 6 });
+
+test("withdrawals are pointed only at networks the bridge sends ETH and USDC from, Base first", () => {
+ assert.deepEqual([...EXCHANGE_NETWORKS], [8453, 1, 42161, 10]);
+ // each sends ETH and USDC, so every route out of it is one of the send-by-receive pairs the bridge checks live
+ for (const id of EXCHANGE_NETWORKS) {
+ assert.deepEqual([...BRIDGE_SEND_ASSETS[id]], ["ETH", "USDC"], `${id} sends ETH and USDC`);
+ for (const asset of BRIDGE_SEND_ASSETS[id]) assert.ok(isBridgeAssetSupported(id, asset, "input"));
+ }
+ // Robinhood Chain, Arc and Elysium are never suggested as a withdrawal network
+ for (const id of [4663, 5042, 99901]) assert.ok(!(EXCHANGE_NETWORKS as readonly number[]).includes(id), String(id));
+});
+
+test("the watch reads ETH and Circle's USDC on those four networks only, each read standing alone", async () => {
+ const native: number[] = [];
+ const tokens: string[] = [];
+ const holdings = await readExchangeHoldings({
+ native: async (chainId) => { native.push(chainId); if (chainId === 1) throw new Error("rpc down"); return 10n ** 16n; },
+ token: async (chainId, token) => { tokens.push(`${chainId}:${token}`); return 5_000_000n; },
+ }, WALLET);
+ assert.deepEqual([...native].sort(), [1, 10, 42161, 8453].sort());
+ assert.deepEqual(tokens.sort(), [`8453:${BASE_USDC}`, `1:${ETHEREUM_USDC}`, `42161:${ARBITRUM_USDC}`, `10:${OPTIMISM_USDC}`].sort(), "never USDC.e");
+ // Ethereum's ETH did not answer: it is left out, never counted as empty, and its USDC still counts
+ assert.equal(holdings.find((h) => h.chainId === 1 && h.asset === "ETH"), undefined);
+ assert.equal(holdings.find((h) => h.chainId === 1 && h.asset === "USDC")?.amount, 5_000_000n);
+ assert.equal(holdings.length, 7);
+});
+
+test("the baseline starts at what is already there and only ever comes down", () => {
+ const first = nextExchangeBaseline({}, [usdc(42161, 40), eth(42161, 0.01)]);
+ assert.deepEqual(first, { "42161:USDC": 40_000_000n, "42161:ETH": 10n ** 16n });
+ // a rise keeps the baseline, a drop lowers it, and a network read for the first time starts where it stands
+ const next = nextExchangeBaseline(first, [usdc(42161, 65), eth(42161, 0.004), usdc(10, 3)]);
+ assert.deepEqual(next, { "42161:USDC": 40_000_000n, "42161:ETH": 4n * 10n ** 15n, "10:USDC": 3_000_000n });
+ // a network that did not answer keeps its baseline
+ assert.deepEqual(nextExchangeBaseline(next, []), next);
+});
+
+test("an arrival is a rise worth a bridge fee, with the ETH beside it as its gas", () => {
+ const baseline = nextExchangeBaseline({}, [usdc(42161, 40), eth(42161, 0), usdc(8453, 2), eth(8453, 0.01), usdc(10, 0), eth(10, 0)]);
+ // funds already there never count
+ assert.deepEqual(findExchangeArrivals(baseline, [usdc(42161, 40), eth(42161, 0), usdc(8453, 2), eth(8453, 0.01)]), []);
+ const now = [usdc(42161, 290), eth(42161, 0), usdc(8453, 2.5), eth(8453, 0.01), usdc(10, 0), eth(10, 0.0002)];
+ // 250 USDC on Arbitrum with no ETH there; half a dollar on Base and 0.0002 ETH on Optimism are dust
+ assert.deepEqual(findExchangeArrivals(baseline, now), [{ chainId: 42161, asset: "USDC", amount: 250_000_000n, decimals: 6, gas: 0n }]);
+ // a network read for the first time is a baseline, not an arrival
+ assert.deepEqual(findExchangeArrivals(nextExchangeBaseline(baseline, [usdc(1, 500)]), [usdc(1, 500)]), []);
+});
+
+test("a token comes before the ETH that landed beside it, and networks keep their order", () => {
+ const baseline = nextExchangeBaseline({}, [usdc(42161, 0), eth(42161, 0), usdc(8453, 0), eth(1, 0)]);
+ const arrivals = findExchangeArrivals(baseline, [eth(42161, 0.004), usdc(42161, 250), eth(1, 0.05), usdc(8453, 10)]);
+ assert.deepEqual(arrivals.map((a) => `${a.chainId}:${a.asset}`), ["8453:USDC", "1:ETH", "42161:USDC", "42161:ETH"]);
+ assert.equal(arrivals[2].gas, 4n * 10n ** 15n, "the withdrawn ETH pays the USDC's gas");
+ assert.equal(arrivals[3].gas, null, "ETH needs no gas of its own");
+ // Base's USDC with no ETH read on Base: unknown, so no warning
+ assert.equal(arrivals[0].gas, null);
+ assert.deepEqual(arrivals.map(exchangeNeedsGas), [false, false, false, false]);
+ assert.equal(exchangeNeedsGas({ chainId: 10, asset: "USDC", amount: 1n, decimals: 6, gas: 0n }), true);
+});
+
+test("an arrival opens the bridge from where it landed, or needs nothing when it landed where it is wanted", () => {
+ const onArbitrum: ExchangeArrival = { chainId: 42161, asset: "USDC", amount: 25_500_000n, decimals: 6, gas: 0n };
+ assert.deepEqual(exchangeNext(onArbitrum, 5042), { kind: "bridge", originChainId: 42161, originAsset: "USDC", amount: "25.5" });
+ // ETH is left for the sender to size, since some of it pays the gas
+ assert.deepEqual(exchangeNext({ chainId: 1, asset: "ETH", amount: 5n * 10n ** 16n, decimals: 18, gas: null }, 4663), { kind: "bridge", originChainId: 1, originAsset: "ETH", amount: "" });
+ assert.deepEqual(exchangeNext({ chainId: 8453, asset: "USDC", amount: 100_000_000n, decimals: 6, gas: null }, 8453), { kind: "ready" });
+ assert.deepEqual(exchangeNext({ chainId: 8453, asset: "USDC", amount: 100_000_000n, decimals: 6, gas: null }, 99901), { kind: "bridge", originChainId: 8453, originAsset: "USDC", amount: "100" });
+});
+
+test("a saved watch comes back only for its wallet, while fresh, and exactly as saved", () => {
+ const now = Date.UTC(2026, 10, 10, 12, 0);
+ const watch = { wallet: WALLET.toLowerCase(), startedAt: now - 60_000, baseline: { "42161:USDC": 40_000_000n, "8453:ETH": 10n ** 18n } };
+ const raw = serializeExchangeWatch(watch);
+ assert.deepEqual(parseExchangeWatch(raw, WALLET, now), watch, "matched case-insensitively");
+ assert.equal(parseExchangeWatch(raw, "0x2222222222222222222222222222222222222222", now), null, "someone else's");
+ assert.equal(parseExchangeWatch(raw, WALLET, now - 60_000 + EXCHANGE_WATCH_MS + 1), null, "too old");
+ assert.equal(parseExchangeWatch(serializeExchangeWatch({ ...watch, startedAt: now + 120_000 }), WALLET, now), null, "from the future");
+ for (const baseline of [{ "4663:ETH": "1" }, { "42161:USDG": "1" }, { "42161:USDC": "-1" }, { "42161:USDC": "1.5" }, { "42161:USDC": 1 }]) {
+ assert.equal(parseExchangeWatch(JSON.stringify({ wallet: watch.wallet, startedAt: watch.startedAt, baseline }), WALLET, now), null, JSON.stringify(baseline));
+ }
+ for (const junk of [null, "", "{", "[]", "null", JSON.stringify({ wallet: watch.wallet, startedAt: "1", baseline: {} })]) assert.equal(parseExchangeWatch(junk, WALLET, now), null, String(junk));
+ assert.equal(parseExchangeWatch(raw, "", now), null, "no wallet");
+});
+
+test("the guide reopens only when it was left open in this tab recently", () => {
+ const now = Date.UTC(2026, 10, 10, 12, 0);
+ assert.equal(exchangeGuideOpen(String(now - 5 * 60_000), now), true);
+ assert.equal(exchangeGuideOpen(String(now - EXCHANGE_WATCH_MS - 1), now), false);
+ assert.equal(exchangeGuideOpen(String(now + 5 * 60_000), now), false);
+ for (const raw of [null, "", "soon", "NaN"]) assert.equal(exchangeGuideOpen(raw, now), false, String(raw));
+});
diff --git a/app/src/lib/bridge/exchange.ts b/app/src/lib/bridge/exchange.ts
new file mode 100644
index 00000000..84464a8e
--- /dev/null
+++ b/app/src/lib/bridge/exchange.ts
@@ -0,0 +1,124 @@
+import { formatUnits, type Address } from "viem";
+import { FUND_MIN_ETH, FUND_MIN_USD, readHoldingsOn, type BridgeHolding, type HoldingReader } from "./fund";
+import { BRIDGE_SEND_ASSETS, bridgeCurrency, isDollarAsset, type BridgeAsset, type BridgeChainId } from "./types";
+
+/**
+ * From an exchange: the bridge panel's guide for funds that start in an exchange account. The exchange withdraws to the
+ * connected wallet on a network the bridge already sends from, the guide watches that wallet's balances there, and once
+ * the funds land it opens the bridge on that route. Every route it can open is one the bridge already checks; nothing
+ * here signs or sends.
+ *
+ * Relay's deposit addresses (send to an address, the transfer starts by itself) were looked at for this and are not
+ * used: the address cannot be tied to the order it claims to serve. See docs/bridge.md, "From an exchange".
+ */
+
+/**
+ * Where a withdrawal can land: the networks the bridge sends ETH and USDC from. Base comes first because it is also a
+ * launch chain, so funds that land there need no bridge when Base is where they are wanted.
+ */
+export const EXCHANGE_NETWORKS = [8453, 1, 42161, 10] as const satisfies readonly BridgeChainId[];
+export type ExchangeNetworkId = (typeof EXCHANGE_NETWORKS)[number];
+/** How often the balances are read while the guide is open. */
+export const EXCHANGE_POLL_MS = 15_000;
+/** How long a watch is kept in this tab: long enough to close the panel and come back. */
+export const EXCHANGE_WATCH_MS = 2 * 60 * 60_000;
+export const EXCHANGE_OPEN_KEY = "openlaunch.bridge.exchange.open";
+export const EXCHANGE_WATCH_KEY = "openlaunch.bridge.exchange.watch";
+
+export const isExchangeNetwork = (chainId: unknown): chainId is ExchangeNetworkId => (EXCHANGE_NETWORKS as readonly unknown[]).includes(chainId);
+const isNative = (chainId: BridgeChainId, asset: BridgeAsset) => /^0x0{40}$/.test(bridgeCurrency(chainId, asset, "input").address);
+const holdingKey = (holding: { chainId: BridgeChainId; asset: BridgeAsset }) => `${holding.chainId}:${holding.asset}`;
+
+/** What the wallet holds of each sendable asset on the exchange networks. A network that does not answer is left out. */
+export function readExchangeHoldings(read: HoldingReader, wallet: Address): Promise {
+ return readHoldingsOn(read, wallet, EXCHANGE_NETWORKS);
+}
+
+/**
+ * The lowest balance seen per network and asset since the watch began. Arrivals are measured from it: a balance first
+ * read now starts at what it holds now, so funds already there never count as arriving, and a balance that drops (spent
+ * on gas, or bridged away) lowers it, so the next withdrawal is measured from where the wallet really stands.
+ */
+export type ExchangeBaseline = Readonly>;
+export function nextExchangeBaseline(baseline: ExchangeBaseline, holdings: readonly BridgeHolding[]): ExchangeBaseline {
+ const next: Record = { ...baseline };
+ for (const holding of holdings) {
+ const key = holdingKey(holding);
+ const seen = next[key];
+ next[key] = seen !== undefined && seen < holding.amount ? seen : holding.amount;
+ }
+ return next;
+}
+
+/**
+ * Funds that landed since the watch began. `gas` is the ETH on that network beside a token arrival, since a token can
+ * be sent on only with some; null for ETH itself, or when that read failed.
+ */
+export type ExchangeArrival = { chainId: ExchangeNetworkId; asset: BridgeAsset; amount: bigint; decimals: 6 | 18; gas: bigint | null };
+
+/**
+ * Each rise above the baseline worth a bridge fee (the trade panel's dust floors), in network order, a token before the
+ * ETH that landed beside it: that ETH is most likely its gas.
+ */
+export function findExchangeArrivals(baseline: ExchangeBaseline, holdings: readonly BridgeHolding[]): ExchangeArrival[] {
+ const gas = new Map(holdings.filter((h) => isNative(h.chainId, h.asset)).map((h) => [h.chainId, h.amount]));
+ const order = (h: { chainId: BridgeChainId; asset: BridgeAsset }) => EXCHANGE_NETWORKS.indexOf(h.chainId as ExchangeNetworkId) * 10 + (isNative(h.chainId, h.asset) ? 9 : BRIDGE_SEND_ASSETS[h.chainId].indexOf(h.asset));
+ const arrivals: ExchangeArrival[] = [];
+ for (const holding of holdings) {
+ const { chainId } = holding;
+ if (!isExchangeNetwork(chainId)) continue;
+ const before = baseline[holdingKey(holding)];
+ if (before === undefined || holding.amount <= before) continue;
+ const amount = holding.amount - before;
+ if (Number(formatUnits(amount, holding.decimals)) < (isDollarAsset(holding.asset) ? FUND_MIN_USD : FUND_MIN_ETH)) continue;
+ arrivals.push({ chainId, asset: holding.asset, amount, decimals: holding.decimals, gas: isNative(chainId, holding.asset) ? null : gas.get(chainId) ?? null });
+ }
+ return arrivals.sort((a, b) => order(a) - order(b));
+}
+
+/** A token landed where the wallet has no ETH to pay for sending it on. */
+export const exchangeNeedsGas = (arrival: ExchangeArrival) => arrival.gas === 0n;
+
+/**
+ * What to do with an arrival: nothing when it landed on the network it is wanted on, else bridge from there. A token
+ * arrival fills in its amount; ETH is left for the sender to choose, since some of it pays the gas.
+ */
+export type ExchangeNext = { kind: "ready" } | { kind: "bridge"; originChainId: ExchangeNetworkId; originAsset: BridgeAsset; amount: string };
+export function exchangeNext(arrival: ExchangeArrival, destinationChainId: BridgeChainId): ExchangeNext {
+ if (arrival.chainId === destinationChainId) return { kind: "ready" };
+ return { kind: "bridge", originChainId: arrival.chainId, originAsset: arrival.asset, amount: isNative(arrival.chainId, arrival.asset) ? "" : formatUnits(arrival.amount, arrival.decimals) };
+}
+
+/** A watch as kept in this tab's session storage, so closing the panel does not lose what was already there. */
+export type ExchangeWatch = { wallet: string; startedAt: number; baseline: ExchangeBaseline };
+
+export function serializeExchangeWatch(watch: ExchangeWatch): string {
+ return JSON.stringify({ wallet: watch.wallet, startedAt: watch.startedAt, baseline: Object.fromEntries(Object.entries(watch.baseline).map(([key, value]) => [key, value.toString()])) });
+}
+
+/** The saved watch for `wallet`, or null when there is none, it is someone else's, it is too old, or it does not parse. */
+export function parseExchangeWatch(raw: string | null, wallet: string, now: number): ExchangeWatch | null {
+ if (!raw || !wallet) return null;
+ try {
+ const value: unknown = JSON.parse(raw);
+ if (!value || typeof value !== "object") return null;
+ const { wallet: owner, startedAt, baseline } = value as Record;
+ if (typeof owner !== "string" || owner !== wallet.toLowerCase()) return null;
+ if (typeof startedAt !== "number" || !Number.isFinite(startedAt) || startedAt > now + 60_000 || now - startedAt > EXCHANGE_WATCH_MS) return null;
+ if (!baseline || typeof baseline !== "object") return null;
+ const parsed: Record = {};
+ for (const [key, amount] of Object.entries(baseline)) {
+ const [chain, asset] = key.split(":");
+ const chainId = Number(chain);
+ if (!isExchangeNetwork(chainId) || !(BRIDGE_SEND_ASSETS[chainId] as readonly string[]).includes(asset) || typeof amount !== "string" || !/^\d{1,78}$/.test(amount)) return null;
+ parsed[key] = BigInt(amount);
+ }
+ return { wallet: owner, startedAt, baseline: parsed };
+ } catch { return null; }
+}
+
+/** Whether the guide was left open in this tab recently enough to reopen on it. */
+export function exchangeGuideOpen(raw: string | null, now: number): boolean {
+ const openedAt = Number(raw);
+ return raw !== null && Number.isFinite(openedAt) && openedAt <= now + 60_000 && now - openedAt <= EXCHANGE_WATCH_MS;
+}
diff --git a/app/src/lib/bridge/fund.test.ts b/app/src/lib/bridge/fund.test.ts
new file mode 100644
index 00000000..479bb96c
--- /dev/null
+++ b/app/src/lib/bridge/fund.test.ts
@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { Address, Hex } from "viem";
+import { FUND_FOLLOW_MS, bridgeAssetForPay, followedBridge, formatFundAmount, fundStep, pickBridgeSource, readBridgeHoldings, type BridgeHolding } from "./fund.ts";
+import type { BridgeHistoryEntry } from "./history.ts";
+import { ARBITRUM_USDC, ARC_USDC, BASE_USDC, BRIDGE_CHAIN_IDS, BRIDGE_SEND_ASSETS, ELYSIUM_USDC, ETHEREUM_USDC, OPTIMISM_USDC, ROBINHOOD_USDG, type BridgeChainId } from "./types.ts";
+
+const WALLET = "0x1111111111111111111111111111111111111111" as Address;
+const NATIVE = "0x0000000000000000000000000000000000000000" as Address;
+const hash = (n: number) => `0x${n.toString(16).padStart(64, "0")}` as Hex;
+const eth = (chainId: BridgeChainId, value: number): BridgeHolding => ({ chainId, asset: "ETH", amount: BigInt(Math.round(value * 1e6)) * 10n ** 12n, decimals: 18 });
+const usd = (chainId: BridgeChainId, value: number, asset: "USDC" | "USDG" = "USDC"): BridgeHolding => ({ chainId, asset, amount: BigInt(Math.round(value * 1e6)), decimals: 6 });
+
+test("a buy can be bridged for only when it pays with something the bridge delivers", () => {
+ assert.equal(bridgeAssetForPay(8453, { address: NATIVE, native: true }), "ETH");
+ assert.equal(bridgeAssetForPay(4663, { address: NATIVE, native: true }), "ETH");
+ assert.equal(bridgeAssetForPay(5042, { address: NATIVE, native: true }), "USDC", "Arc's gas is USDC");
+ assert.equal(bridgeAssetForPay(5042, { address: ARC_USDC, native: false }), "USDC", "and its ERC-20 face is the same balance");
+ assert.equal(bridgeAssetForPay(8453, { address: BASE_USDC.toLowerCase() as Address, native: false }), "USDC");
+ assert.equal(bridgeAssetForPay(4663, { address: ROBINHOOD_USDG, native: false }), "USDG");
+ assert.equal(bridgeAssetForPay(4663, { address: BASE_USDC, native: false }), null, "Base's USDC address means nothing on Robinhood");
+ assert.equal(bridgeAssetForPay(8453, { address: "0x4200000000000000000000000000000000000006", native: false }), null, "WETH is not a bridge asset");
+ assert.equal(bridgeAssetForPay(8453, { address: "0x9999999999999999999999999999999999999999", native: false }), null, "a pair token or stock is not either");
+ assert.equal(bridgeAssetForPay(99901, { address: NATIVE, native: true }), "HYPE", "HYPE arrives on Elysium, so a HYPE-priced buy can be funded");
+ assert.equal(bridgeAssetForPay(99901, { address: ELYSIUM_USDC, native: false }), "USDC");
+ assert.equal(bridgeAssetForPay(99901, { address: BASE_USDC, native: false }), null);
+});
+
+test("holdings are read on every other network, each read standing alone", async () => {
+ const asked: string[] = [];
+ const holdings = await readBridgeHoldings({
+ native: async (chainId) => { asked.push(`${chainId}:native`); if (chainId === 10) throw new Error("rpc down"); return 7n; },
+ token: async (chainId, token) => { asked.push(`${chainId}:${token}`); return chainId === 1 ? (-1n as bigint) : 5n; },
+ }, WALLET, 4663);
+ assert.ok(!asked.some((call) => call.startsWith("4663:")), "never the destination itself");
+ // every asset the bridge can send, plus HYPE on Elysium: the gas its USDC needs to be sent, which can arrive but never leave
+ const expected = BRIDGE_CHAIN_IDS.filter((id) => id !== 4663).reduce((sum, id) => sum + BRIDGE_SEND_ASSETS[id].length, 0) + 1;
+ assert.equal(asked.length, expected);
+ assert.ok(asked.includes("99901:native"));
+ for (const token of [BASE_USDC, ARC_USDC, ELYSIUM_USDC, ETHEREUM_USDC, ARBITRUM_USDC, OPTIMISM_USDC]) assert.ok(asked.some((call) => call.endsWith(token)), token);
+ assert.deepEqual(holdings.filter((h) => h.chainId === 99901), [{ chainId: 99901, asset: "USDC", amount: 5n, decimals: 6, gas: 7n }]);
+ assert.ok(!holdings.some((h) => h.chainId === 10 && h.asset === "ETH"), "a network that fails is left out, not shown as empty");
+ assert.ok(!holdings.some((h) => h.chainId === 1 && h.asset === "USDC"), "a nonsense answer is dropped");
+ assert.deepEqual(holdings.find((h) => h.chainId === 5042), { chainId: 5042, asset: "USDC", amount: 5n, decimals: 6 });
+ assert.deepEqual(holdings.find((h) => h.chainId === 42161 && h.asset === "ETH"), { chainId: 42161, asset: "ETH", amount: 7n, decimals: 18 });
+});
+
+test("Elysium's USDC counts as a source only beside some HYPE, read with it", async () => {
+ const destination = { chainId: 8453, asset: "USDC" } as const;
+ const elysium = (gas?: bigint): BridgeHolding => ({ ...usd(99901, 300), ...(gas === undefined ? {} : { gas }) });
+ assert.deepEqual(pickBridgeSource([elysium(10n ** 15n), usd(42161, 50), eth(42161, 0.01)], destination, 3000), elysium(10n ** 15n));
+ assert.deepEqual(pickBridgeSource([elysium(0n), usd(42161, 50), eth(42161, 0.01)], destination, 3000), usd(42161, 50), "no HYPE, no send");
+ assert.deepEqual(pickBridgeSource([elysium(), usd(42161, 50), eth(42161, 0.01)], destination, 3000), usd(42161, 50), "an unread HYPE balance is not taken as some");
+ // ETH elsewhere is not gas on Elysium
+ assert.equal(pickBridgeSource([usd(99901, 300), eth(99901, 1)], destination, 3000), null);
+ // a failed HYPE read leaves the USDC holding in place, without gas
+ const holdings = await readBridgeHoldings({
+ native: async (chainId) => { if (chainId === 99901) throw new Error("rpc down"); return 1n; },
+ token: async () => 9n,
+ }, WALLET, 8453);
+ assert.deepEqual(holdings.filter((h) => h.chainId === 99901), [{ chainId: 99901, asset: "USDC", amount: 9n, decimals: 6 }]);
+});
+
+test("the suggested source is the largest one worth moving that can actually be sent", () => {
+ const destination = { chainId: 4663, asset: "ETH" } as const;
+ // with a price: dollars and ETH compare by value
+ assert.deepEqual(pickBridgeSource([eth(42161, 0.02), usd(8453, 120), eth(8453, 0.001)], destination, 3000), usd(8453, 120));
+ assert.deepEqual(pickBridgeSource([eth(42161, 0.05), usd(8453, 120), eth(8453, 0.001)], destination, 3000), eth(42161, 0.05));
+ // a token needs gas beside it; Arc's USDC is its own gas
+ assert.deepEqual(pickBridgeSource([usd(10, 500), eth(10, 0), eth(1, 0.01)], destination, 3000), eth(1, 0.01), "USDC on Optimism with no ETH there cannot be sent");
+ assert.deepEqual(pickBridgeSource([usd(5042, 40), eth(1, 0.001)], destination, 3000), usd(5042, 40));
+ // dust and the destination itself never count
+ assert.equal(pickBridgeSource([eth(42161, 0.0002), usd(5042, 0.5)], destination, 3000), null);
+ assert.equal(pickBridgeSource([eth(4663, 3)], destination, 3000), null);
+ assert.equal(pickBridgeSource([], destination, 3000), null);
+ // no price: like with like, the buy's own kind first
+ assert.deepEqual(pickBridgeSource([usd(8453, 900), eth(42161, 0.01), eth(1, 0.2)], destination, null), eth(1, 0.2));
+ assert.deepEqual(pickBridgeSource([usd(8453, 900), eth(8453, 0.0001), eth(42161, 0.0001)], destination, null), usd(8453, 900), "with no ETH worth moving, dollars are still a route");
+ assert.deepEqual(pickBridgeSource([usd(8453, 30), usd(5042, 80), eth(8453, 1)], { chainId: 4663, asset: "USDG" }, Number.NaN), usd(5042, 80), "a broken price is no price");
+ // equal values: the lower chain id, so the answer never flips between renders
+ assert.equal(pickBridgeSource([usd(42161, 50), usd(8453, 50), eth(42161, 1), eth(8453, 1)], { chainId: 5042, asset: "USDC" }, null)!.chainId, 8453);
+});
+
+test("hint amounts keep four decimals at most and never show dust as zero", () => {
+ assert.equal(formatFundAmount(123456789n, 6), "123.4567");
+ assert.equal(formatFundAmount(1_234_000_000n, 6), "1,234");
+ assert.equal(formatFundAmount(10n ** 13n, 18), "<0.0001");
+ assert.equal(formatFundAmount(0n, 18), "0");
+ assert.equal(formatFundAmount(5n * 10n ** 16n, 18), "0.05");
+});
+
+function row(overrides: Partial = {}): BridgeHistoryEntry {
+ return { requestId: hash(1), originChainId: 42161, destinationChainId: 4663, originAsset: "ETH", destinationAsset: "ETH", amountIn: "50000000000000000", inDecimals: 18, amountOut: "49800000000000000", outDecimals: 18, outKind: "quoted", status: "pending", reverted: false, createdAt: 1_000_000, sourceHash: hash(2), destinationHashes: [], recipient: null, ...overrides };
+}
+
+test("the trade panel follows the newest recent transfer into its network, until dismissed", () => {
+ const now = 1_000_000 + 60_000;
+ const rows = [row(), row({ requestId: hash(3), createdAt: 900_000 }), row({ requestId: hash(4), destinationChainId: 8453, createdAt: 1_050_000 })];
+ assert.equal(followedBridge(rows, 4663, "ETH", now, [])!.requestId, hash(1));
+ assert.equal(followedBridge(rows, 4663, "ETH", now, [hash(1).toUpperCase().replace("0X", "0x")])!.requestId, hash(3), "a dismissed one gives way to the next");
+ assert.equal(followedBridge(rows, 5042, "USDC", now, []), null);
+ assert.equal(followedBridge([row({ createdAt: now - FUND_FOLLOW_MS - 1 })], 4663, "ETH", now, []), null, "an old transfer is history, not a step");
+ assert.equal(followedBridge([row({ createdAt: now + 120_000 })], 4663, "ETH", now, []), null, "a clock far ahead is not trusted");
+ assert.equal(followedBridge([row({ recipient: "0x2222222222222222222222222222222222222222" })], 4663, "ETH", now, []), null, "funds sent elsewhere are no help to this wallet's buy");
+ // ETH that arrived does not pay for a buy priced in dollars: the shortfall stays on show
+ assert.equal(followedBridge(rows, 4663, "USDG", now, []), null, "a transfer in another asset is not this buy's funding");
+ const dollars = row({ requestId: hash(5), destinationAsset: "USDG", createdAt: 950_000 });
+ assert.equal(followedBridge([...rows, dollars], 4663, "USDG", now, [])!.requestId, hash(5), "the older transfer in the right asset is the one followed");
+ assert.equal(followedBridge([row({ destinationChainId: 99901, destinationAsset: "USDC" })], 99901, "HYPE", now, []), null, "USDC on Elysium is not the HYPE a buy there pays with");
+
+ assert.equal(fundStep(null), "short");
+ for (const status of ["waiting", "depositing", "pending", "submitted", "delayed"] as const) assert.equal(fundStep({ status }), "moving", status);
+ assert.equal(fundStep({ status: "success" }), "arrived");
+ for (const status of ["refund", "failure", "uncertain"] as const) assert.equal(fundStep({ status }), "attention", status);
+});
diff --git a/app/src/lib/bridge/fund.ts b/app/src/lib/bridge/fund.ts
new file mode 100644
index 00000000..971e7a02
--- /dev/null
+++ b/app/src/lib/bridge/fund.ts
@@ -0,0 +1,111 @@
+import { formatUnits, type Address } from "viem";
+import type { BridgeHistoryEntry } from "./history";
+import { BRIDGE_CHAIN_IDS, BRIDGE_RECEIVE_ASSETS, BRIDGE_SEND_ASSETS, bridgeCurrency, bridgeCurrencyAsset, bridgesNativeCurrency, isDollarAsset, type BridgeAsset, type BridgeChainId, type BridgeDestinationId } from "./types";
+
+/**
+ * Bridge, then buy: the token page's way to fund a purchase from another network. Two separate steps by design (a
+ * Relay destination call runs from Relay's contract, not the buyer's wallet, so an atomic bridge-and-buy would need its
+ * own review). This file is the pure part: which bridge asset a buy pays with, where the wallet already holds funds,
+ * which of those to suggest, and which recent transfer the trade panel should follow.
+ */
+
+/** The bridge asset a buy pays with on `chainId`, or null when the bridge cannot deliver it (TWIG, GITLAWB, pairs, stocks). */
+export function bridgeAssetForPay(chainId: BridgeDestinationId, pay: { address: Address; native: boolean }): BridgeAsset | null {
+ // the native asset is whichever bridge asset arrives as the native balance: ETH on Base and Robinhood, USDC on Arc,
+ // HYPE on Elysium
+ if (pay.native) return BRIDGE_RECEIVE_ASSETS[chainId].find((asset) => /^0x0{40}$/.test(bridgeCurrency(chainId, asset, "output").address)) ?? null;
+ return bridgeCurrencyAsset(chainId, pay.address)?.asset ?? null;
+}
+
+/**
+ * `gas` is the chain's native balance, read only where the bridge cannot send the native currency (Elysium's HYPE),
+ * since a token there can be sent only with some of it. Left out when that read fails.
+ */
+export type BridgeHolding = { chainId: BridgeChainId; asset: BridgeAsset; amount: bigint; decimals: 6 | 18; gas?: bigint };
+export type HoldingReader = {
+ native: (chainId: BridgeChainId, wallet: Address) => Promise;
+ token: (chainId: BridgeChainId, token: Address, wallet: Address) => Promise;
+};
+
+/**
+ * What the wallet holds of every bridge asset on every network but `destination`. Each read stands alone: a network
+ * that does not answer is left out, never counted as empty and never allowed to fail the others.
+ */
+export function readBridgeHoldings(read: HoldingReader, wallet: Address, destination: BridgeDestinationId): Promise {
+ return readHoldingsOn(read, wallet, BRIDGE_CHAIN_IDS.filter((chainId) => chainId !== destination));
+}
+
+/** The same reads on the given networks only, each standing alone as above. */
+export async function readHoldingsOn(read: HoldingReader, wallet: Address, chains: readonly BridgeChainId[]): Promise {
+ const jobs: Promise[] = [];
+ for (const chainId of chains) {
+ const gas = bridgesNativeCurrency(chainId) ? null : read.native(chainId, wallet).then((amount) => typeof amount === "bigint" && amount >= 0n ? amount : null, () => null);
+ for (const asset of BRIDGE_SEND_ASSETS[chainId]) {
+ const currency = bridgeCurrency(chainId, asset, "input");
+ const native = /^0x0{40}$/.test(currency.address);
+ jobs.push(Promise.all([native ? read.native(chainId, wallet) : read.token(chainId, currency.address, wallet), gas]).then(
+ ([amount, gasAmount]) => typeof amount === "bigint" && amount >= 0n ? { chainId, asset, amount, decimals: currency.decimals, ...(typeof gasAmount === "bigint" ? { gas: gasAmount } : {}) } : null,
+ () => null,
+ ));
+ }
+ }
+ return (await Promise.all(jobs)).filter((holding): holding is BridgeHolding => holding !== null);
+}
+
+/** Below this, a holding is dust: not worth a bridge fee, so never suggested. */
+export const FUND_MIN_USD = 1;
+/** The same floor for ETH when no ETH price is known. */
+export const FUND_MIN_ETH = 0.0005;
+const units = (holding: BridgeHolding) => Number(formatUnits(holding.amount, holding.decimals));
+
+/**
+ * The holding to suggest bridging from: the largest by dollar value, or, with no ETH price, the largest in the same kind
+ * of asset as the buy (ETH for ETH, dollars for dollars). A token can only be sent where the wallet also has gas, so a
+ * USDC holding counts only beside some ETH on its network, or some HYPE on Elysium; on Arc, USDC is the gas. Null when
+ * nothing is worth moving.
+ */
+export function pickBridgeSource(holdings: readonly BridgeHolding[], destination: { chainId: BridgeDestinationId; asset: BridgeAsset }, ethUsd: number | null): BridgeHolding | null {
+ const gas = new Map(holdings.filter((h) => h.asset === "ETH").map((h) => [h.chainId, h.amount]));
+ const hasGas = (h: BridgeHolding) => bridgesNativeCurrency(h.chainId) ? h.asset === "ETH" || h.chainId === 5042 || (gas.get(h.chainId) ?? 0n) > 0n : (h.gas ?? 0n) > 0n;
+ const sendable = holdings.filter((h) => h.chainId !== destination.chainId && h.amount > 0n && hasGas(h));
+ const usd = (h: BridgeHolding) => isDollarAsset(h.asset) ? units(h) : ethUsd !== null && Number.isFinite(ethUsd) && ethUsd > 0 ? units(h) * ethUsd : null;
+ const priced = sendable.map((h) => ({ h, usd: usd(h) }));
+ if (ethUsd !== null && Number.isFinite(ethUsd) && ethUsd > 0) {
+ return priced.filter((p) => p.usd !== null && p.usd >= FUND_MIN_USD).sort((a, b) => b.usd! - a.usd! || a.h.chainId - b.h.chainId)[0]?.h ?? null;
+ }
+ // no ETH price: compare like with like only, the buy's own kind first
+ const worth = sendable.filter((h) => units(h) >= (isDollarAsset(h.asset) ? FUND_MIN_USD : FUND_MIN_ETH));
+ const sameKind = worth.filter((h) => isDollarAsset(h.asset) === isDollarAsset(destination.asset));
+ return (sameKind.length ? sameKind : worth).sort((a, b) => units(b) - units(a) || a.chainId - b.chainId)[0] ?? null;
+}
+
+/** Four decimals at most for a hint; dust reads as "<0.0001", never as 0. */
+export function formatFundAmount(amount: bigint, decimals: number): string {
+ const [whole, fraction = ""] = formatUnits(amount, decimals).split(".");
+ const cut = fraction.slice(0, 4).replace(/0+$/, "");
+ return whole === "0" && !cut && amount > 0n ? "<0.0001" : `${Number(whole).toLocaleString("en-US")}${cut ? `.${cut}` : ""}`;
+}
+
+/** How long a bridge to this network stays on the token page: long enough to come back to, short enough to stay relevant. */
+export const FUND_FOLLOW_MS = 2 * 60 * 60_000;
+
+/**
+ * The newest transfer delivering `asset` to `destination` from the last two hours that the buyer has not dismissed, or
+ * null. A transfer that arrives as something else does not pay for this buy, so it never stands in for the shortfall.
+ */
+export function followedBridge(rows: readonly BridgeHistoryEntry[], destination: BridgeDestinationId, asset: BridgeAsset, now: number, dismissed: readonly string[]): BridgeHistoryEntry | null {
+ const skip = new Set(dismissed.map((id) => id.toLowerCase()));
+ return rows
+ .filter((row) => row.destinationChainId === destination && row.destinationAsset === asset && !row.recipient && !skip.has(row.requestId.toLowerCase()) && row.createdAt <= now + 60_000 && now - row.createdAt <= FUND_FOLLOW_MS)
+ .sort((a, b) => b.createdAt - a.createdAt)[0] ?? null;
+}
+
+export type FundStep = "short" | "moving" | "arrived" | "attention";
+
+/** Where the two steps stand: no bridge yet, one on its way, one delivered (buy next), or one that needs a look. */
+export function fundStep(row: Pick | null): FundStep {
+ if (!row) return "short";
+ if (row.status === "success") return "arrived";
+ if (row.status === "refund" || row.status === "failure" || row.status === "uncertain") return "attention";
+ return "moving";
+}
diff --git a/app/src/lib/bridge/history-store.ts b/app/src/lib/bridge/history-store.ts
new file mode 100644
index 00000000..ade9be33
--- /dev/null
+++ b/app/src/lib/bridge/history-store.ts
@@ -0,0 +1,71 @@
+import type { Address, Hex } from "viem";
+import type { TrackedBridgeTransfer } from "./client";
+import { historyFromTransfer, parseHistoryLedger, serializeHistoryLedger, upsertHistory, type BridgeHistoryEntry } from "./history";
+
+/**
+ * This browser's bridge history: a ledger kept beside the recovery record, never instead of it. The recovery record
+ * (client-storage.ts) guards against sending twice and is cleared when a transfer is done; this one only remembers.
+ * It is best effort by design: a storage failure here is reported, never thrown into a transfer.
+ */
+export const BRIDGE_HISTORY_PREFIX = "openlaunch.bridge.history.v1:";
+export const bridgeHistoryKey = (address: Address | string) => `${BRIDGE_HISTORY_PREFIX}${address.toLowerCase()}`;
+type StorageAdapter = Pick;
+export type HistorySnapshot = { entries: Record; unsaved: Record };
+const EMPTY: HistorySnapshot = { entries: {}, unsaved: {} };
+
+export function createBridgeHistoryStore(storage: () => StorageAdapter) {
+ let snapshot = EMPTY;
+ const listeners = new Set<() => void>();
+ function update(wallet: string, entries: BridgeHistoryEntry[], unsaved: boolean) {
+ const current = snapshot.entries[wallet];
+ if (current && snapshot.unsaved[wallet] === unsaved && serializeHistoryLedger(current) === serializeHistoryLedger(entries)) return;
+ snapshot = { entries: { ...snapshot.entries, [wallet]: entries }, unsaved: { ...snapshot.unsaved, [wallet]: unsaved } };
+ for (const notify of listeners) notify();
+ }
+ function load(wallet: string): BridgeHistoryEntry[] {
+ const raw = storage().getItem(bridgeHistoryKey(wallet));
+ if (raw === null) return [];
+ try { return parseHistoryLedger(raw); } catch { return []; }
+ }
+ function write(wallet: string, entries: BridgeHistoryEntry[]) {
+ try {
+ storage().setItem(bridgeHistoryKey(wallet), serializeHistoryLedger(entries));
+ update(wallet, entries, false);
+ } catch { update(wallet, entries, true); }
+ }
+ return {
+ subscribe(notify: () => void) { listeners.add(notify); return () => { listeners.delete(notify); }; },
+ getSnapshot: () => snapshot,
+ getServerSnapshot: () => EMPTY,
+ /** Re-read from storage, keeping rows only memory has (a write that failed) so nothing seen is lost. */
+ read(address: Address): BridgeHistoryEntry[] {
+ const wallet = address.toLowerCase();
+ let stored: BridgeHistoryEntry[];
+ try { stored = load(wallet); } catch { update(wallet, snapshot.entries[wallet] ?? [], true); return snapshot.entries[wallet] ?? []; }
+ let rows = stored;
+ for (const entry of snapshot.entries[wallet] ?? []) rows = upsertHistory(rows, entry);
+ update(wallet, rows, snapshot.unsaved[wallet] ?? false);
+ return rows;
+ },
+ /** Remember a tracked transfer once it has left the wallet; a no-op until then and when nothing changed. */
+ record(transfer: TrackedBridgeTransfer, quotedOut: string | null = null) {
+ const entry = historyFromTransfer(transfer, quotedOut);
+ if (!entry) return;
+ const wallet = transfer.address.toLowerCase();
+ let base: BridgeHistoryEntry[];
+ try { base = load(wallet); } catch { base = []; }
+ for (const row of snapshot.entries[wallet] ?? []) base = upsertHistory(base, row);
+ const next = upsertHistory(base, entry);
+ if (snapshot.entries[wallet] && !snapshot.unsaved[wallet] && serializeHistoryLedger(next) === serializeHistoryLedger(snapshot.entries[wallet])) return;
+ write(wallet, next);
+ },
+ /** Drop a row for a transfer that was discarded because it never left the wallet. */
+ forget(address: Address, requestId: Hex) {
+ const wallet = address.toLowerCase();
+ let base: BridgeHistoryEntry[];
+ try { base = load(wallet); } catch { base = snapshot.entries[wallet] ?? []; }
+ const next = base.filter((row) => row.requestId.toLowerCase() !== requestId.toLowerCase());
+ if (next.length !== base.length || (snapshot.entries[wallet] ?? []).some((row) => row.requestId.toLowerCase() === requestId.toLowerCase())) write(wallet, next);
+ },
+ };
+}
diff --git a/app/src/lib/bridge/history.test.ts b/app/src/lib/bridge/history.test.ts
new file mode 100644
index 00000000..5e2ce6f3
--- /dev/null
+++ b/app/src/lib/bridge/history.test.ts
@@ -0,0 +1,317 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { Address, Hex } from "viem";
+import type { TrackedBridgeTransfer } from "./client.ts";
+import { BRIDGE_HISTORY_LIMIT, combineHistory, formatHistoryAmount, historyFromTransfer, historyReceived, historyStatus, mergeHistory, parseHistoryEntry, parseHistoryLedger, parseRelayHistory, relayHistoryEntry, serializeHistoryLedger, upsertHistory, validateHistoryResponse, type BridgeHistoryEntry } from "./history.ts";
+import { bridgeHistoryKey, createBridgeHistoryStore } from "./history-store.ts";
+import { BRIDGE_HISTORY_TTL_MS, BRIDGE_HISTORY_UPSTREAM_PER_MINUTE, getBridgeHistory } from "./relay.ts";
+import { ARBITRUM_USDC, ARC_USDC, BASE_USDC, ELYSIUM_USDC, ROBINHOOD_USDG, bridgeCurrencyAsset } from "./types.ts";
+import { GET } from "../../app/api/bridge/history/route.ts";
+
+const WALLET = "0x1111111111111111111111111111111111111111" as Address;
+const OTHER = "0x2222222222222222222222222222222222222222" as Address;
+const hash = (n: number) => `0x${n.toString(16).padStart(64, "0")}` as Hex;
+const NATIVE = "0x0000000000000000000000000000000000000000";
+
+function tracked(overrides: Partial = {}): TrackedBridgeTransfer {
+ return { address: WALLET, originChainId: 42161, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC", amount: "25000000", requestId: hash(1), sourceHash: hash(2), destinationHashes: [], status: "pending", createdAt: 1_790_000_000_000, ...overrides };
+}
+
+function row(overrides: Partial = {}): BridgeHistoryEntry {
+ return { requestId: hash(1), originChainId: 42161, destinationChainId: 8453, originAsset: "USDC", destinationAsset: "USDC", amountIn: "25000000", inDecimals: 6, amountOut: "24970000", outDecimals: 6, outKind: "quoted", status: "pending", reverted: false, createdAt: 1_790_000_000_000, sourceHash: hash(2), destinationHashes: [], recipient: null, ...overrides };
+}
+
+const currency = (chainId: number, address: string, decimals: number, amount: string) => ({ currency: { chainId, address, symbol: "X", name: "X", decimals, metadata: {} }, amount, amountFormatted: "1", amountUsd: "1", minimumAmount: amount });
+type TestCurrency = ReturnType;
+
+/** A GET /requests/v3 request in Relay's published shape, Arbitrum USDC to Base USDC unless overridden. */
+function relayRequest(overrides: Record = {}, route: { from?: TestCurrency; to?: TestCurrency; actualTo?: TestCurrency } = {}) {
+ const from = route.from ?? currency(42161, ARBITRUM_USDC, 6, "25000000");
+ const to = route.to ?? currency(8453, BASE_USDC, 6, "24970000");
+ const actualTo = route.actualTo ?? currency(8453, BASE_USDC, 6, "24975000");
+ return {
+ id: hash(1), status: "success", user: WALLET, sender: WALLET, recipient: WALLET, refundTo: null, depositAddress: null, requestType: "Bridge",
+ data: {
+ slippageTolerance: "50", failReason: null,
+ inTxs: [{ txHash: hash(2), chainId: from.currency.chainId, status: "success" }],
+ outTxs: [{ txHash: hash(3), chainId: actualTo.currency.chainId, status: "success" }],
+ route: {
+ quoted: { origin: { inputCurrency: from }, destination: { outputCurrency: to } },
+ actual: { destination: { outputCurrency: actualTo } },
+ },
+ },
+ createdAt: "2026-11-10T09:30:00.000Z", updatedAt: "2026-11-10T09:30:20.000Z",
+ ...overrides,
+ };
+}
+
+function memoryStorage(fail = false) {
+ const items = new Map();
+ return { items, adapter: { getItem: (key: string) => items.get(key) ?? null, setItem: (key: string, value: string) => { if (fail) throw new Error("quota"); items.set(key, value); } } };
+}
+
+test("a tracked transfer enters the history only once it has left the wallet", () => {
+ assert.equal(historyFromTransfer(tracked({ sourceHash: undefined, status: "waiting" })), null, "a cancelled or unsent wallet prompt is not a transfer");
+ assert.equal(historyFromTransfer(tracked({ sourceHash: undefined, status: "uncertain" })), null);
+ const sent = historyFromTransfer(tracked(), "24970000")!;
+ assert.deepEqual(sent, row());
+ assert.equal(historyFromTransfer(tracked(), "not a number")!.amountOut, null);
+ // settled by Relay without a wallet hash (recovered on another path) still counts
+ assert.equal(historyFromTransfer(tracked({ sourceHash: undefined, status: "success" }))!.status, "success");
+ const reverted = historyFromTransfer(tracked({ status: "failure", failureReason: "source-reverted" }))!;
+ assert.equal(reverted.reverted, true);
+ // Arc's first journal entries were native 18-decimal USDC, and arrive on Arc as the 18-decimal native balance
+ const legacyArc = historyFromTransfer(tracked({ originChainId: 5042, destinationChainId: 8453, originAsset: undefined, destinationAsset: undefined, amount: "5000000000000000000" }))!;
+ assert.equal(legacyArc.inDecimals, 18);
+ assert.equal(legacyArc.originAsset, "USDC");
+ assert.equal(legacyArc.destinationAsset, "ETH");
+ assert.equal(historyFromTransfer(tracked({ originChainId: 8453, destinationChainId: 5042, originAsset: "USDC", destinationAsset: "USDC" }))!.outDecimals, 18);
+});
+
+test("a stored row is checked field by field and copied; anything off drops that row only", () => {
+ assert.deepEqual(parseHistoryEntry({ ...row(), extra: "