perp-cli 0.12.15 → 0.14.0

package/dist/bridge-engine.js

@@ -9,6 +9,182 @@
  * Handles USDC bridging between Solana ↔ Arbitrum ↔ Base ↔ HyperCore
  * for cross-exchange rebalancing in funding arb.
  */
+import { PerpError, isConnectFailure, isTransportFailure, orderOutcomeUnknown, parsePositiveDecimal, sendFailure } from "./errors.js";
+import { loadSettings } from "./settings.js";
+import { getVenue, networkConfig } from "./exchanges/venue.js";
+import "./exchanges/venues/index.js";
+import { HL_USER_SIGNED } from "./exchanges/venues/hyperliquid.js";
+import { ERC20, assertRpcChainId, erc20Allowance, evmProvider, sendMasterTx } from "./evm-master-tx.js";
+import { isBridgeEvmSigner, isSolanaSigner, pkEvmSigner, pkSolanaSigner, signTypedDataChecked, signVersionedSolanaTx, } from "./bridge-signers.js";
+/**
+ * Canonical USDC decimal string ("5", "5.25") of `amount`. INVALID_PARAMS for anything that is
+ * not a positive plain decimal with at most 6 decimals (USDC has 6).
+ */
+export function parseUsdcAmount(amount, what = "USDC amount") {
+    const raw = typeof amount === "number" ? (Number.isFinite(amount) ? String(amount) : "NaN") : amount;
+    const s = parsePositiveDecimal(raw, what);
+    const frac = s.includes(".") ? s.slice(s.indexOf(".") + 1) : "";
+    if (frac.length > 6) {
+        throw new PerpError("INVALID_PARAMS", `${what} ${s} has more than 6 decimals (USDC has 6) — nothing was sent`, {
+            remediation: "Pass the amount with at most 6 decimals, e.g. 10.123456",
+        });
+    }
+    return formatUnitsPlain(usdcUnitsOf(s), 6);
+}
+/** Exact USDC base units (6 decimals) of a validated decimal string. */
+function usdcUnitsOf(s) {
+    const [whole, frac = ""] = s.split(".");
+    return BigInt(whole === "" ? "0" : whole) * 1000000n + BigInt((frac + "000000").slice(0, 6));
+}
+/** Exact USDC base units of `amount` (validated by parseUsdcAmount). */
+export function usdcUnits(amount, what) {
+    return usdcUnitsOf(parseUsdcAmount(amount, what));
+}
+/** Display-only number of `amount` (never used to build a signed amount). */
+function usdcDisplay(amount) {
+    return Number(parseUsdcAmount(amount));
+}
+function evmSignerOf(k) {
+    if (typeof k === "string") {
+        if (!/^0x[0-9a-fA-F]{64}$/.test(k)) {
+            throw new PerpError("NO_SIGNER_AVAILABLE", "This bridge leg is signed on an EVM chain, and no EVM master signer was supplied", {
+                remediation: "Select the master wallet (perp wallet use <name> or --ows <name>) and run perp funds bridge send / exchange",
+            });
+        }
+        return pkEvmSigner(k);
+    }
+    if (isBridgeEvmSigner(k))
+        return k;
+    throw new PerpError("NO_SIGNER_AVAILABLE", "This bridge leg is signed on an EVM chain, but a Solana signer was supplied", {
+        remediation: "Pass the master wallet's EVM signer for EVM source chains",
+    });
+}
+async function solanaSignerOf(k) {
+    if (typeof k === "string") {
+        if (k.startsWith("ows:")) {
+            throw new PerpError("NO_SIGNER_AVAILABLE", "This bridge leg is signed on Solana, and an OWS wallet reference (not a signer) was supplied", {
+                remediation: "Select the master wallet (perp wallet use <name> or --ows <name>) and run perp funds bridge send / exchange",
+            });
+        }
+        return pkSolanaSigner(k);
+    }
+    if (isSolanaSigner(k))
+        return k;
+    throw new PerpError("NO_SIGNER_AVAILABLE", "This bridge leg is signed on Solana, but an EVM signer was supplied", {
+        remediation: "Pass the master wallet's Solana signer for Solana source chains",
+    });
+}
+/** The signer's address must be the address the quote / order was built for. */
+function assertSignerIs(chain, signerAddress, expected) {
+    const same = chain === "solana" ? signerAddress === expected : signerAddress.toLowerCase() === expected.toLowerCase();
+    if (same)
+        return;
+    throw new PerpError("INVALID_PARAMS", `The bridge order was built for sender ${expected}, not the signing wallet's ${chain} address ${signerAddress} — nothing was sent`, {
+        remediation: "Omit --sender (the master wallet's own address is used)",
+    });
+}
+/** Chain-checked RPC for an EVM source chain (a wrong endpoint never receives a signed tx). */
+async function bridgeEvmRpc(chain) {
+    const chainId = chain === "solana" ? undefined : CHAIN_IDS[chain];
+    if (chainId === undefined) {
+        throw new PerpError("NO_BRIDGE_ROUTE", `No EVM chain id configured for "${chain}" — nothing was sent`, {
+            remediation: "List supported chains with: perp funds bridge chains",
+        });
+    }
+    const url = requireRpcUrl(chain);
+    const rpc = evmProvider(url, chainId);
+    await assertRpcChainId(rpc, url, chainId, "bridge");
+    return { rpc, chainId };
+}
+/**
+ * One master-wallet EVM transaction through sendMasterTx: simulate → gas check → sign → verify
+ * sender → broadcast → receipt. An unreadable outcome after the broadcast is ORDER_PENDING.
+ */
+async function sendBridgeEvmTx(rpc, chainId, chain, signer, provider, label, to, data, value = 0n) {
+    const { txHash } = await sendMasterTx(rpc, {
+        venue: provider, chainLabel: chain, chainId, from: signer.getAddress(), to, data, value, label,
+    }, tx => signer.signTransaction(tx));
+    return txHash;
+}
+/**
+ * Approve the pinned `spender` for EXACTLY `amount` USDC when the current allowance is below it.
+ * Never an unlimited approval: a compromised / mis-targeted spender can take at most this transfer.
+ */
+async function ensureUsdcAllowance(rpc, chainId, chain, signer, provider, spender, amount) {
+    const usdc = USDC_ADDRESSES[chain];
+    if (!usdc)
+        throw new PerpError("NO_BRIDGE_ROUTE", `No USDC address for ${chain} — nothing was sent`);
+    const allowance = await erc20Allowance(rpc, usdc, signer.getAddress(), spender);
+    if (allowance >= amount)
+        return;
+    await sendBridgeEvmTx(rpc, chainId, chain, signer, provider, "USDC approve", usdc, usdcApproveData(spender, amount));
+}
+/** Calldata of the exact USDC approval ensureUsdcAllowance sends (exported for tests). */
+export function usdcApproveData(spender, amount) {
+    return ERC20.encodeFunctionData("approve", [spender, amount]);
+}
+function solanaOutcomeUnknown(signature, what, e) {
+    const pending = orderOutcomeUnknown("bridge", `${what} transaction ${signature}`, e, `Do NOT resend — the transaction was broadcast and may still confirm. Check signature ${signature} on a Solana explorer, then the balances, before doing anything else`);
+    return new PerpError("ORDER_PENDING", pending.message, { exchange: "bridge", signature, txHash: signature, remediation: pending.structured.remediation });
+}
+/**
+ * Broadcast a fully signed Solana transaction and wait for confirmation. The signature is known
+ * before the send: a transport failure after the request left, or any confirmation failure, is
+ * ORDER_PENDING carrying it (never "failed", never resubmitted).
+ */
+async function sendBridgeSolanaTx(connection, tx, what) {
+    const bs58 = (await import("bs58")).default;
+    const signature = bs58.encode(tx.signatures[0]);
+    try {
+        await connection.sendRawTransaction(tx.serialize(), { skipPreflight: false });
+    }
+    catch (e) {
+        if (isConnectFailure(e)) {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `${what}: could not connect to the Solana RPC — nothing was sent`, { exchange: "bridge" });
+        }
+        if (isTransportFailure(e))
+            throw solanaOutcomeUnknown(signature, what, e);
+        throw new PerpError("ACTION_REJECTED", `${what}: the Solana RPC refused the transaction (${e instanceof Error ? e.message : String(e)}) — nothing was sent`, { exchange: "bridge" });
+    }
+    let confirmation;
+    try {
+        confirmation = await connection.confirmTransaction(signature, "confirmed");
+    }
+    catch (e) {
+        throw solanaOutcomeUnknown(signature, what, e);
+    }
+    if (confirmation.value.err !== null && confirmation.value.err !== undefined) {
+        throw new PerpError("ACTION_REJECTED", `${what}: transaction ${signature} failed on-chain (${JSON.stringify(confirmation.value.err)}) — nothing was moved`, {
+            exchange: "bridge", signature, txHash: signature,
+        });
+    }
+    return signature;
+}
+/**
+ * Every route in this module is mainnet-only: the RPCs, USDC / CCTP contract
+ * addresses, Circle Iris, Relay and deBridge endpoints below are mainnet
+ * deployments with no testnet equivalent wired in. A testnet run must never
+ * sign or send through them (it would move real mainnet funds), so it throws
+ * NO_BRIDGE_ROUTE before any key is used.
+ */
+export function assertBridgeNetwork(network) {
+    if (network === "mainnet")
+        return;
+    throw new PerpError("NO_BRIDGE_ROUTE", `Cross-chain bridging has no ${network} route — every bridge provider here (CCTP, Relay, deBridge) is wired to mainnet chains only`, {
+        remediation: "Run without -n testnet to bridge on mainnet, or fund testnet accounts from each venue's testnet faucet",
+    });
+}
+/**
+ * A bridge moves funds between two different chains. Same source and destination is a caller
+ * error, refused before any quote API is called or any key is used.
+ */
+export function assertDistinctBridgeChains(srcChain, dstChain) {
+    if (srcChain !== dstChain)
+        return;
+    throw new PerpError("INVALID_PARAMS", `Bridge source and destination chain are the same (${srcChain}) — nothing to bridge`, {
+        remediation: "Pick two different chains with --from / --to (list them with: perp funds bridge chains)",
+    });
+}
 // ── Chain constants ──
 export const CHAIN_IDS = {
     solana: 7565164,
@@ -67,7 +243,7 @@ const CCTP_FORWARD_HOOK_DATA = "0x636374702d666f72776172640000000000000000000000
  * @param amountUsdc - Transfer amount in USDC (needed to calculate bps-based fee).
  * Returns maxFee in USDC subunits (6 decimals).
  */
-async function getCctpRelayFee(srcDomain, dstDomain, finalityThreshold = 2000, useForwarding = false, amountUsdc = 100) {
+async function getCctpRelayFee(srcDomain, dstDomain, finalityThreshold = 2000, useForwarding = false, amountUsdc = "100") {
     // SSOT rule #2: Circle's CCTP fee schedule is the SSOT for bridge cost.
     // Previously a fetch failure returned a hardcoded $0.50 / $0.25 fallback —
     // that silently set maxFee at a guess, which can either burn user dollars
@@ -94,7 +270,7 @@ async function getCctpRelayFee(srcDomain, dstDomain, finalityThreshold = 2000, u
         throw new Error(`CCTP fee API ${srcDomain}→${dstDomain} returned no fee schedule`);
     }
     // Protocol fee: minimumFee is in basis points → actual fee = amount × bps / 10000
-    const amountSubunits = BigInt(Math.round(amountUsdc * 1e6));
+    const amountSubunits = usdcUnits(amountUsdc);
     const bpsRounded = BigInt(Math.round(schedule.minimumFee * 100));
     const protocolFee = (amountSubunits * bpsRounded) / 1000000n;
     // Add 20% buffer per Circle docs recommendation
@@ -272,14 +448,147 @@ async function getHyperCoreCctpFees(srcDomain, amount) {
 }
 // ── deBridge DLN API ──
 const DLN_API = "https://dln.debridge.finance/v1.0/dln/order";
-// Builder/affiliate config — set via env vars or defaults
-const DEBRIDGE_REFERRAL_CODE = process.env.DEBRIDGE_REFERRAL_CODE ?? "";
-const DEBRIDGE_AFFILIATE_FEE_PERCENT = process.env.DEBRIDGE_AFFILIATE_FEE_PERCENT ?? ""; // e.g. "0.1" for 0.1%
-const DEBRIDGE_AFFILIATE_FEE_RECIPIENT = process.env.DEBRIDGE_AFFILIATE_FEE_RECIPIENT ?? "";
+// deBridge DLN pinned contracts. Source: https://docs.debridge.com/dln-details/overview/deployed-contracts
+// (read 2026-10-13): DlnSource is 0xeF4fB24aD0916217251F553c0596F8Edc630EB66 on Arbitrum and Base;
+// Solana DlnSource program src5qyZHqTqecJV4aY6Cb6zDZLMDzrDKKezs22MPHr4. The create-tx transaction
+// must target this contract; it is also the only spender ever approved (exact amount).
+const DLN_SOURCE_EVM = {
+    arbitrum: "0xeF4fB24aD0916217251F553c0596F8Edc630EB66",
+    base: "0xeF4fB24aD0916217251F553c0596F8Edc630EB66",
+};
+// DlnSource ABI (github.com/debridge-finance/dln-contracts, contracts/DLN/DlnSource.sol and
+// contracts/libraries/DlnOrderLib.sol, read 2026-10-13). The contract pulls exactly
+// OrderCreation.giveAmount of giveTokenAddress from msg.sender (_pullTokens, before the protocol
+// and affiliate fees are deducted from it), requires msg.value == globalFixedNativeFee for an
+// ERC-20 give token, and decodes _affiliateFee as 52 bytes: beneficiary (20) ‖ amount (32).
+const DLN_ORDER_CREATION = "tuple(address giveTokenAddress, uint256 giveAmount, bytes takeTokenAddress, uint256 takeAmount, uint256 takeChainId, bytes receiverDst, address givePatchAuthoritySrc, bytes orderAuthorityAddressDst, bytes allowedTakerDst, bytes externalCall, bytes allowedCancelBeneficiarySrc)";
+const DLN_SOURCE_ABI = [
+    `function createOrder(${DLN_ORDER_CREATION} _orderCreation, bytes _affiliateFee, uint32 _referralCode, bytes _permitEnvelope) payable returns (bytes32)`,
+    `function createSaltedOrder(${DLN_ORDER_CREATION} _orderCreation, uint64 _salt, bytes _affiliateFee, uint32 _referralCode, bytes _permitEnvelope, bytes _metadata) payable returns (bytes32)`,
+];
+function debridgeRefused(msg) {
+    return new PerpError("POLICY_DENIED", `deBridge transaction refused: ${msg}. Nothing was signed or sent.`, {
+        exchange: "debridge",
+        remediation: "Use another provider: --provider cctp | relay",
+    });
+}
+/**
+ * Solana-origin deBridge is refused: the create-tx answer is a full VersionedTransaction (lookup
+ * tables, several instructions) that this CLI cannot decode and check against the order it asked
+ * for, and SSOT forbids signing a payload blindly.
+ */
+export function assertDebridgeSourceSupported(srcChain) {
+    if (srcChain !== "solana")
+        return;
+    throw new PerpError("NO_BRIDGE_ROUTE", "deBridge from Solana is not supported: its Solana transaction cannot be verified locally before signing — nothing was sent", {
+        exchange: "debridge",
+        remediation: "Use Circle CCTP from Solana: perp funds bridge send --from solana --to <chain> --amount <n> --provider cctp",
+    });
+}
+/** Raw bytes of an address on `chain` as DLN encodes it (EVM: 20 bytes, Solana: the 32-byte key). */
+async function dlnAddressBytes(chain, address) {
+    if (chain === "solana") {
+        const { PublicKey } = await import("@solana/web3.js");
+        return "0x" + Buffer.from(new PublicKey(address).toBytes()).toString("hex");
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address))
+        throw debridgeRefused(`${JSON.stringify(address)} is not an EVM address`);
+    return address.toLowerCase();
+}
+/**
+ * Verify a deBridge create-tx EVM transaction before anything is signed: pinned DlnSource target,
+ * createOrder / createSaltedOrder decoded, the give token / amount, take token / chain / amount,
+ * the receiver and destination order authority (the user's own address), source patch authority,
+ * no external call / permit / taker restriction, the affiliate fee, and value ≤ the quoted fixFee.
+ * Returns the verified { to, data, value }.
+ */
+export async function verifyDebridgeEvmTx(tx, x) {
+    const pinned = DLN_SOURCE_EVM[x.srcChain];
+    if (pinned === undefined)
+        throw debridgeRefused(`no pinned DlnSource contract for ${x.srcChain}`);
+    const to = typeof tx.to === "string" ? tx.to : "";
+    if (to.toLowerCase() !== pinned.toLowerCase())
+        throw debridgeRefused(`the transaction targets ${JSON.stringify(tx.to)}, not the pinned DlnSource ${pinned} on ${x.srcChain}`);
+    const data = typeof tx.data === "string" ? tx.data : "";
+    if (!/^0x[0-9a-fA-F]+$/.test(data))
+        throw debridgeRefused("the transaction has no calldata");
+    const valueRaw = tx.value === undefined || tx.value === null ? "0" : String(tx.value);
+    if (!/^\d+$/.test(valueRaw))
+        throw debridgeRefused(`unreadable tx value ${JSON.stringify(tx.value)}`);
+    const value = BigInt(valueRaw);
+    if (value > x.fixFee)
+        throw debridgeRefused(`the transaction sends ${value} wei, more than the quoted fixFee ${x.fixFee}`);
+    const { Interface } = await import("ethers");
+    const iface = new Interface(DLN_SOURCE_ABI);
+    let parsed;
+    try {
+        parsed = iface.parseTransaction({ data, value });
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed === null)
+        throw debridgeRefused("the calldata is neither DlnSource.createOrder nor createSaltedOrder");
+    const salted = parsed.name === "createSaltedOrder";
+    const oc = parsed.args[0];
+    const affiliateFee = String(parsed.args[salted ? 2 : 1]).toLowerCase();
+    const permitEnvelope = String(parsed.args[salted ? 4 : 3]);
+    const usdcSrc = USDC_ADDRESSES[x.srcChain];
+    const usdcDst = USDC_ADDRESSES[x.dstChain];
+    const takeChainId = CHAIN_IDS[x.dstChain];
+    if (usdcSrc === undefined || usdcDst === undefined || takeChainId === undefined)
+        throw debridgeRefused(`no pinned USDC / chain id for ${x.srcChain} → ${x.dstChain}`);
+    if (oc.giveTokenAddress.toLowerCase() !== usdcSrc.toLowerCase())
+        throw debridgeRefused(`the order gives token ${oc.giveTokenAddress}, not USDC ${usdcSrc}`);
+    if (oc.giveAmount !== x.giveAmount)
+        throw debridgeRefused(`the order takes ${oc.giveAmount} USDC units, not the requested ${x.giveAmount}`);
+    if (oc.takeChainId !== BigInt(takeChainId))
+        throw debridgeRefused(`the order pays out on chain ${oc.takeChainId}, not ${x.dstChain} (${takeChainId})`);
+    if (oc.takeTokenAddress.toLowerCase() !== await dlnAddressBytes(x.dstChain, usdcDst))
+        throw debridgeRefused(`the order pays out token ${oc.takeTokenAddress}, not USDC on ${x.dstChain}`);
+    if (oc.takeAmount < x.takeAmount)
+        throw debridgeRefused(`the order pays out ${oc.takeAmount} USDC units, less than the requested ${x.takeAmount}`);
+    const recipientBytes = await dlnAddressBytes(x.dstChain, x.recipient);
+    if (oc.receiverDst.toLowerCase() !== recipientBytes)
+        throw debridgeRefused(`the order pays ${oc.receiverDst}, not the recipient ${x.recipient}`);
+    if (oc.orderAuthorityAddressDst.toLowerCase() !== recipientBytes)
+        throw debridgeRefused(`the destination order authority is ${oc.orderAuthorityAddressDst}, not the recipient ${x.recipient}`);
+    if (oc.givePatchAuthoritySrc.toLowerCase() !== x.sender.toLowerCase())
+        throw debridgeRefused(`the source patch authority is ${oc.givePatchAuthoritySrc}, not the sender ${x.sender}`);
+    const cancel = oc.allowedCancelBeneficiarySrc.toLowerCase();
+    if (cancel !== "0x" && cancel !== x.sender.toLowerCase())
+        throw debridgeRefused(`a cancelled order refunds ${oc.allowedCancelBeneficiarySrc}, not the sender ${x.sender}`);
+    if (oc.externalCall !== "0x")
+        throw debridgeRefused("the order carries a destination external call");
+    if (oc.allowedTakerDst !== "0x")
+        throw debridgeRefused("the order restricts the destination taker");
+    if (permitEnvelope !== "0x")
+        throw debridgeRefused("the order carries a permit envelope (only an exact approve is signed)");
+    if (x.affiliate === null) {
+        if (affiliateFee !== "0x")
+            throw debridgeRefused("the order attaches an affiliate fee, but none is configured (settings bridge.debridgeAffiliate)");
+    }
+    else if (affiliateFee !== "0x") {
+        // 52 bytes: beneficiary (20) ‖ amount (32) — see the ABI note above.
+        if (affiliateFee.length !== 2 + 104)
+            throw debridgeRefused("the affiliate fee is not 52 bytes");
+        const beneficiary = "0x" + affiliateFee.slice(2, 42);
+        const feeAmount = BigInt("0x" + affiliateFee.slice(42));
+        if (beneficiary !== x.affiliate.feeRecipient.toLowerCase())
+            throw debridgeRefused(`the affiliate fee goes to ${beneficiary}, not the configured ${x.affiliate.feeRecipient}`);
+        // feePercent of the give amount (+1 unit rounding).
+        const cap = (x.giveAmount * BigInt(Math.round(x.affiliate.feePercent * 1e6))) / 100000000n + 1n;
+        if (feeAmount > cap)
+            throw debridgeRefused(`the affiliate fee ${feeAmount} exceeds ${x.affiliate.feePercent}% of the amount`);
+    }
+    return { to: pinned, data, value };
+}
 /**
  * Get a bridge quote via deBridge DLN.
  */
 export async function getDebridgeQuote(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress) {
+    assertDistinctBridgeChains(srcChain, dstChain);
+    assertDebridgeSourceSupported(srcChain);
     const srcChainId = CHAIN_IDS[srcChain];
     const dstChainId = CHAIN_IDS[dstChain];
     if (!srcChainId || !dstChainId)
@@ -288,7 +597,8 @@ export async function getDebridgeQuote(srcChain, dstChain, amountUsdc, senderAdd
     const dstToken = USDC_ADDRESSES[dstChain];
     if (!srcToken || !dstToken)
         throw new Error(`No USDC address for ${srcChain} or ${dstChain}`);
-    const amountRaw = String(Math.round(amountUsdc * 1e6));
+    const amountRaw = usdcUnits(amountUsdc).toString();
+    const amountIn = usdcDisplay(amountUsdc);
     // Step 1: Get quote
     const quoteParams = new URLSearchParams({
         srcChainId: String(srcChainId),
@@ -296,7 +606,10 @@ export async function getDebridgeQuote(srcChain, dstChain, amountUsdc, senderAdd
         srcChainTokenInAmount: amountRaw,
         dstChainId: String(dstChainId),
         dstChainTokenOut: dstToken,
-        prependOperatingExpenses: "true",
+        // false: the operating expenses come out of the amount, so exactly --amount USDC leaves the
+        // wallet. "true" ADDS them to the input (live 2026-10-13: --amount 5 spent 5.939652 USDC while
+        // the quote reported amountIn 5 / fee $0.004).
+        prependOperatingExpenses: "false",
     });
     appendDebridgeBuilderParams(quoteParams);
     const quoteRes = await fetch(`${DLN_API}/quote?${quoteParams}`);
@@ -317,6 +630,21 @@ export async function getDebridgeQuote(srcChain, dstChain, amountUsdc, senderAdd
             `Raw estimation=${JSON.stringify(estimation)}`);
     }
     const amountOut = dstAmountNumber / 1e6;
+    // The USDC actually taken from the wallet must equal the request (prependOperatingExpenses=false).
+    const srcInRaw = estimation?.srcChainTokenIn?.amount;
+    if (String(srcInRaw) !== amountRaw) {
+        throw new PerpError("EXCHANGE_ERROR", `deBridge quote takes ${JSON.stringify(srcInRaw)} USDC units, not the requested ${amountRaw}`, {
+            remediation: "Use another provider: --provider cctp | relay",
+        });
+    }
+    // fixFee: the protocol's flat fee in the source chain's native token (wei / lamports), paid as tx value.
+    const fixFeeRaw = quote.fixFee;
+    if (typeof fixFeeRaw !== "string" || !/^\d+$/.test(fixFeeRaw)) {
+        throw new PerpError("EXCHANGE_ERROR", `deBridge quote has no readable fixFee (${JSON.stringify(fixFeeRaw)})`);
+    }
+    const nativeSymbol = srcChain === "solana" ? "SOL" : "ETH";
+    const nativeDecimals = srcChain === "solana" ? 9 : 18;
+    const nativeFee = BigInt(fixFeeRaw) === 0n ? null : { amount: formatUnitsPlain(BigInt(fixFeeRaw), nativeDecimals), symbol: nativeSymbol, usd: null };
     const order = quote.order;
     const fulfillDelayRaw = Number(order?.approximateFulfillmentDelay);
     // approximateFulfillmentDelay is documented as nice-to-have telemetry;
@@ -328,22 +656,33 @@ export async function getDebridgeQuote(srcChain, dstChain, amountUsdc, senderAdd
         provider: "debridge",
         srcChain,
         dstChain,
-        amountIn: amountUsdc,
+        amountIn,
         amountOut,
-        fee: amountUsdc - amountOut,
+        fee: amountIn - amountOut,
         estimatedTime: fulfillDelay,
         gasIncluded: true,
-        gasNote: "DLN market maker fulfills on destination",
-        raw: { quote, senderAddress, recipientAddress, amountRaw },
+        gasNote: nativeFee === null ? "DLN market maker fulfills on destination" : `DLN market maker fulfills on destination; plus a flat ${nativeFee.amount} ${nativeFee.symbol} protocol fee (tx value)`,
+        nativeFee,
+        raw: { quote, senderAddress, recipientAddress, amountRaw, fixFee: fixFeeRaw },
     };
 }
 /**
- * Execute a deBridge bridge transaction.
- * Returns the TX hash after signing and submitting.
+ * Execute a deBridge bridge transaction (EVM origin only). The create-tx answer is verified
+ * against the request (verifyDebridgeEvmTx) before the exact USDC approval and the order are
+ * signed. Returns the TX hash after signing and submitting.
  */
-export async function executeDebridgeBridge(bridgeQuote, signerKey) {
+export async function executeDebridgeBridge(network, bridgeQuote, signerKey) {
+    assertBridgeNetwork(network);
+    assertDistinctBridgeChains(bridgeQuote.srcChain, bridgeQuote.dstChain);
     const { srcChain, dstChain, amountIn, amountOut } = bridgeQuote;
-    const { senderAddress, recipientAddress, amountRaw } = bridgeQuote.raw;
+    assertDebridgeSourceSupported(srcChain);
+    const { senderAddress, recipientAddress, amountRaw, fixFee } = bridgeQuote.raw;
+    // Resolve the signer before any create-tx call: the order is built for senderAddress only.
+    const evmSigner = evmSignerOf(signerKey);
+    assertSignerIs(srcChain, evmSigner.getAddress(), senderAddress);
+    if (!/^\d+$/.test(String(amountRaw)) || !/^\d+$/.test(String(fixFee))) {
+        throw new PerpError("EXCHANGE_ERROR", "deBridge quote is missing its amount / fixFee — nothing was sent", { remediation: "Fetch a fresh quote" });
+    }
     const srcChainId = CHAIN_IDS[srcChain];
     const dstChainId = CHAIN_IDS[dstChain];
     const srcToken = USDC_ADDRESSES[srcChain];
@@ -352,7 +691,11 @@ export async function executeDebridgeBridge(bridgeQuote, signerKey) {
     const quote = bridgeQuote.raw.quote;
     const estimation = quote.estimation;
     const dstOut = estimation?.dstChainTokenOut;
-    const dstAmount = String(dstOut?.recommendedAmount ?? dstOut?.amount ?? "0");
+    const dstAmountRaw = dstOut?.recommendedAmount ?? dstOut?.amount;
+    if (dstAmountRaw === undefined || !/^\d+$/.test(String(dstAmountRaw))) {
+        throw new PerpError("EXCHANGE_ERROR", `deBridge quote has no readable dstChainTokenOut amount (${JSON.stringify(dstAmountRaw)}) — nothing sent`);
+    }
+    const dstAmount = String(dstAmountRaw);
     // Step 2: Create TX
     const createParams = new URLSearchParams({
         srcChainId: String(srcChainId),
@@ -364,7 +707,7 @@ export async function executeDebridgeBridge(bridgeQuote, signerKey) {
         dstChainTokenOutRecipient: recipientAddress,
         srcChainOrderAuthorityAddress: senderAddress,
         dstChainOrderAuthorityAddress: recipientAddress,
-        prependOperatingExpenses: "true",
+        prependOperatingExpenses: "false", // same mode as the quote: exactly amountRaw leaves the wallet
     });
     appendDebridgeBuilderParams(createParams);
     const createRes = await fetch(`${DLN_API}/create-tx?${createParams}`);
@@ -374,14 +717,14 @@ export async function executeDebridgeBridge(bridgeQuote, signerKey) {
     const tx = createTx.tx;
     if (!tx)
         throw new Error("deBridge returned no transaction data");
-    // Step 3: Sign and submit
-    let txHash;
-    if (srcChain === "solana") {
-        txHash = await submitSolanaTransaction(tx, signerKey);
-    }
-    else {
-        txHash = await submitEvmTransaction(tx, signerKey, srcChain);
-    }
+    // Step 3: verify the payload against the request, then approve (exact) + sign + submit.
+    const aff = loadSettings().bridge.debridgeAffiliate;
+    const verified = await verifyDebridgeEvmTx(tx, {
+        srcChain, dstChain, sender: senderAddress, recipient: recipientAddress,
+        giveAmount: BigInt(amountRaw), takeAmount: BigInt(dstAmount), fixFee: BigInt(fixFee),
+        affiliate: aff !== null && aff.feePercent !== null && aff.feeRecipient !== null ? { feePercent: aff.feePercent, feeRecipient: aff.feeRecipient } : null,
+    });
+    const txHash = await submitEvmTransaction(verified, BigInt(amountRaw), evmSigner, srcChain);
     return {
         provider: "debridge",
         txHash,
@@ -392,71 +735,13 @@ export async function executeDebridgeBridge(bridgeQuote, signerKey) {
     };
 }
 /**
- * Submit a Solana transaction from deBridge create-tx response.
+ * Submit a verified deBridge DlnSource order: exact USDC approval of the pinned DlnSource, then
+ * the order transaction.
  */
-async function submitSolanaTransaction(tx, signerKey) {
-    const { Connection, VersionedTransaction, Keypair } = await import("@solana/web3.js");
-    const bs58 = await import("bs58");
-    const connection = new Connection(RPC_URLS.solana, "confirmed");
-    // Decode the keypair
-    let keypair;
-    try {
-        // Try base58 first (standard Solana private key format)
-        keypair = Keypair.fromSecretKey(bs58.default.decode(signerKey));
-    }
-    catch {
-        // Try JSON array (Solana CLI format)
-        try {
-            keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(signerKey)));
-        }
-        catch {
-            throw new Error("Invalid Solana private key format");
-        }
-    }
-    // deBridge returns hex-encoded VersionedTransaction for Solana
-    const txData = String(tx.data);
-    const txBytes = hexToBytes(txData.startsWith("0x") ? txData.slice(2) : txData);
-    const transaction = VersionedTransaction.deserialize(txBytes);
-    // Update blockhash and sign
-    const { blockhash } = await connection.getLatestBlockhash();
-    transaction.message.recentBlockhash = blockhash;
-    transaction.sign([keypair]);
-    const signature = await connection.sendTransaction(transaction, { skipPreflight: false });
-    await connection.confirmTransaction(signature, "confirmed");
-    return signature;
-}
-/**
- * Submit an EVM transaction from deBridge create-tx response.
- */
-async function submitEvmTransaction(tx, privateKey, chain) {
-    const { ethers } = await import("ethers");
-    const rpc = requireRpcUrl(chain);
-    const provider = new ethers.JsonRpcProvider(rpc);
-    const wallet = new ethers.Wallet(privateKey, provider);
-    // Check and approve USDC allowance if needed
-    const usdcAddr = USDC_ADDRESSES[chain];
-    const spenderAddr = String(tx.to);
-    const value = BigInt(String(tx.value ?? "0"));
-    if (usdcAddr && spenderAddr) {
-        const usdc = new ethers.Contract(usdcAddr, [
-            "function allowance(address,address) view returns (uint256)",
-            "function approve(address,uint256) returns (bool)",
-        ], wallet);
-        const allowance = await usdc.allowance(wallet.address, spenderAddr);
-        // Approve max if allowance insufficient
-        if (allowance < ethers.parseUnits("1000000", 6)) {
-            const approveTx = await usdc.approve(spenderAddr, ethers.MaxUint256);
-            await approveTx.wait();
-        }
-    }
-    // Send the bridge transaction
-    const txResponse = await wallet.sendTransaction({
-        to: String(tx.to),
-        data: String(tx.data),
-        value,
-    });
-    const receipt = await txResponse.wait();
-    return receipt.hash;
+async function submitEvmTransaction(tx, giveAmount, signer, chain) {
+    const { rpc, chainId } = await bridgeEvmRpc(chain);
+    await ensureUsdcAllowance(rpc, chainId, chain, signer, "debridge", tx.to, giveAmount);
+    return sendBridgeEvmTx(rpc, chainId, chain, signer, "debridge", "deBridge order", tx.to, tx.data, tx.value);
 }
 // ── Circle CCTP V2 (EVM + Solana) ──
 export const CCTP_DOMAINS = {
@@ -480,6 +765,23 @@ const USDC_MINT_SOLANA = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
 const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
 const ASSOCIATED_TOKEN_PROGRAM = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
 const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+/**
+ * HyperCore → Solana is refused. The sendToEvmWithData action built below is EVM-only: it sends
+ * the recipient with addressEncoding "hex" and signs with signatureChainId = the destination's
+ * chain id. Hyperliquid documents addressEncoding "hex" | "base58" and signatureChainId as "the id
+ * of the chain used when signing" (hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/
+ * exchange-endpoint, read 2026-10-13) — a base58 Solana recipient sent as "hex", signed for the
+ * deBridge pseudo chain id 7565164, would not be what HyperCore expects. The Solana encoding is
+ * not implemented against documentation, so the route is refused before anything is signed.
+ */
+export function assertCctpRouteSupported(srcChain, dstChain) {
+    if (!(srcChain === "hyperliquid" && dstChain === "solana"))
+        return;
+    throw new PerpError("NO_BRIDGE_ROUTE", "HyperCore → Solana (CCTP sendToEvmWithData) is not supported: the Solana recipient encoding is not implemented — nothing was sent", {
+        exchange: "bridge",
+        remediation: "Go through Arbitrum: perp funds bridge exchange --from hyperliquid --to lighter (HyperCore → Arbitrum), then perp funds bridge send --from arbitrum --to solana --amount <n> --provider cctp",
+    });
+}
 /**
  * Check if CCTP is supported for a given chain.
  */
@@ -496,11 +798,14 @@ function isCctpSupported(chain) {
  * @param fast - If true, use fast finality (1000): ~1-2 min, $1-1.3 + $0.20 forwarding.
  *               If false (default), use standard finality (2000): ~2-5 min, ~$0.20 forwarding.
  */
-export async function getCctpQuote(srcChain, dstChain, amountUsdc, fast = false) {
+export async function getCctpQuote(srcChain, dstChain, amount, fast = false) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
+    assertDistinctBridgeChains(srcChain, dstChain);
     if (!isCctpSupported(srcChain))
         throw new Error(`CCTP not supported on ${srcChain}`);
     if (!isCctpSupported(dstChain))
         throw new Error(`CCTP not supported on ${dstChain}`);
+    assertCctpRouteSupported(srcChain, dstChain);
     // HyperCore → EVM: HL withdrawal + CCTP forwarding (~0.20 USDC fee)
     if (srcChain === "hyperliquid") {
         const forwardingFee = 0.20; // CCTP forwarding fee for Arbitrum
@@ -544,7 +849,7 @@ export async function getCctpQuote(srcChain, dstChain, amountUsdc, fast = false)
     const dstDomain = CCTP_DOMAINS[dstChain];
     // Use Forwarding Service when dst is NOT Solana (Solana dst doesn't support forwarding)
     const canForward = dstChain !== "solana";
-    const { maxFee, feeUsdc, forwardingAvailable } = await getCctpRelayFee(srcDomain, dstDomain, finality, canForward, amountUsdc);
+    const { maxFee, feeUsdc, forwardingAvailable } = await getCctpRelayFee(srcDomain, dstDomain, finality, canForward, amount);
     const estimatedTime = fast
         ? ((srcChain === "solana" || dstChain === "solana") ? 90 : 60)
         : (forwardingAvailable
@@ -574,46 +879,39 @@ export async function getCctpQuote(srcChain, dstChain, amountUsdc, fast = false)
  * @param fast - If true, use fast finality (1000): Circle auto-relays, no manual receiveMessage.
  *               If false (default), use standard finality (2000): cheaper but requires manual relay.
  */
-export async function executeCctpBridge(srcChain, dstChain, amountUsdc, signerKey, recipientAddress, dstSignerKey, // EVM key for receiveMessage (Solana→EVM) or Solana key for receiveMessage (EVM→Solana)
+export async function executeCctpBridge(network, srcChain, dstChain, amount, signerKey, recipientAddress, dstSignerKey, // destination-chain signer for receiveMessage (EVM→Solana standard finality)
 fast = false) {
+    usdcUnits(amount); // INVALID_PARAMS for a malformed / over-precise amount before anything else
+    assertBridgeNetwork(network);
+    assertDistinctBridgeChains(srcChain, dstChain);
+    assertCctpRouteSupported(srcChain, dstChain);
     // HyperCore route: depositForBurnWithHook via CctpForwarder
     if (dstChain === "hyperliquid") {
         if (srcChain === "solana") {
-            return executeCctpSolanaToHyperCore(amountUsdc, signerKey, recipientAddress);
+            return executeCctpSolanaToHyperCore(amount, signerKey, recipientAddress);
         }
-        return executeCctpEvmToHyperCore(srcChain, amountUsdc, signerKey, recipientAddress);
+        return executeCctpEvmToHyperCore(srcChain, amount, signerKey, recipientAddress);
     }
     // HyperCore → EVM: sendToEvmWithData via HL exchange API
     if (srcChain === "hyperliquid") {
-        return executeCctpHyperCoreToEvm(dstChain, amountUsdc, signerKey, recipientAddress);
+        return executeCctpHyperCoreToEvm(network, dstChain, amount, signerKey, recipientAddress);
     }
     if (srcChain === "solana") {
-        return executeCctpSolanaToEvm(dstChain, amountUsdc, signerKey, recipientAddress, dstSignerKey, fast);
+        return executeCctpSolanaToEvm(dstChain, amount, signerKey, recipientAddress, dstSignerKey, fast);
     }
     if (dstChain === "solana") {
-        return executeCctpEvmToSolana(srcChain, amountUsdc, signerKey, recipientAddress, dstSignerKey, fast);
+        return executeCctpEvmToSolana(srcChain, amount, signerKey, recipientAddress, dstSignerKey, fast);
     }
-    return executeCctpEvmToEvm(srcChain, dstChain, amountUsdc, signerKey, recipientAddress, fast);
+    return executeCctpEvmToEvm(srcChain, dstChain, amount, signerKey, recipientAddress, fast);
 }
 // ── CCTP: Solana → HyperCore (depositForBurnWithHook) ──
-async function executeCctpSolanaToHyperCore(amountUsdc, signerKey, recipientAddress) {
+async function executeCctpSolanaToHyperCore(amount, signerKey, recipientAddress) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
     const { Connection, PublicKey, Keypair, TransactionMessage, VersionedTransaction, SystemProgram } = await import("@solana/web3.js");
-    const bs58 = await import("bs58");
     const { createHash } = await import("crypto");
     const connection = new Connection(RPC_URLS.solana, "confirmed");
-    // Decode Solana keypair
-    let keypair;
-    try {
-        keypair = Keypair.fromSecretKey(bs58.default.decode(signerKey));
-    }
-    catch {
-        try {
-            keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(signerKey)));
-        }
-        catch {
-            throw new Error("Invalid Solana private key format");
-        }
-    }
+    const signer = await solanaSignerOf(signerKey);
+    const keypair = { publicKey: new PublicKey(signer.getPublicKeyBase58()) };
     const tokenMessengerMinter = new PublicKey(CCTP_SOLANA_TOKEN_MESSENGER_MINTER);
     const messageTransmitterProgram = new PublicKey(CCTP_SOLANA_MESSAGE_TRANSMITTER);
     const usdcMint = new PublicKey(USDC_MINT_SOLANA);
@@ -640,7 +938,7 @@ async function executeCctpSolanaToHyperCore(amountUsdc, signerKey, recipientAddr
     // Anchor discriminator: sha256("global:deposit_for_burn_with_hook")[0..8]
     const discriminator = createHash("sha256").update("global:deposit_for_burn_with_hook").digest().subarray(0, 8);
     const amountBuf = Buffer.alloc(8);
-    amountBuf.writeBigUInt64LE(BigInt(Math.round(amountUsdc * 1e6)));
+    amountBuf.writeBigUInt64LE(usdcUnits(amount));
     // Domain as u32 LE for instruction data (different from PDA seed which uses string)
     const domainBuf = Buffer.alloc(4);
     domainBuf.writeUInt32LE(HYPERCORE_CCTP_DOMAIN);
@@ -700,9 +998,8 @@ async function executeCctpSolanaToHyperCore(amountUsdc, signerKey, recipientAddr
         instructions: [instruction],
     }).compileToV0Message();
     const transaction = new VersionedTransaction(messageV0);
-    transaction.sign([keypair, eventDataKeypair]);
-    const signature = await connection.sendTransaction(transaction, { skipPreflight: false });
-    await connection.confirmTransaction(signature, "confirmed");
+    await signVersionedSolanaTx(signer, transaction, [eventDataKeypair]);
+    const signature = await sendBridgeSolanaTx(connection, transaction, "CCTP depositForBurnWithHook (Solana → HyperCore)");
     return {
         provider: "cctp (HyperCore)",
         txHash: signature,
@@ -728,9 +1025,14 @@ const USDC_EIP712_VERSION = {
     base: "2",
 };
 // ── CCTP: HyperCore → EVM (sendToEvmWithData via HL exchange API) ──
-async function executeCctpHyperCoreToEvm(dstChain, amountUsdc, signerKey, recipientAddress) {
-    const { ethers, Signature: EthSig } = await import("ethers");
-    const wallet = new ethers.Wallet(signerKey);
+async function executeCctpHyperCoreToEvm(network, dstChain, amount, signerKey, recipientAddress) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
+    assertBridgeNetwork(network);
+    const { Signature: EthSig } = await import("ethers");
+    // HL environment + /exchange host from the venue definition (never a hardcoded "Mainnet").
+    const { hyperliquidChain } = HL_USER_SIGNED[network];
+    const hlExchangeUrl = `${networkConfig(getVenue("hyperliquid"), network).restUrl}/exchange`;
+    const signer = evmSignerOf(signerKey);
     const dstDomain = CCTP_DOMAINS[dstChain];
     if (dstDomain === undefined)
         throw new Error(`No CCTP domain for ${dstChain}`);
@@ -742,10 +1044,10 @@ async function executeCctpHyperCoreToEvm(dstChain, amountUsdc, signerKey, recipi
     // Build action payload
     const action = {
         type: "sendToEvmWithData",
-        hyperliquidChain: "Mainnet",
+        hyperliquidChain,
         signatureChainId,
         token: "USDC",
-        amount: String(amountUsdc),
+        amount: parseUsdcAmount(amount),
         sourceDex: "spot", // unified accounts hold funds in spot
         destinationRecipient: recipientAddress,
         addressEncoding: "hex",
@@ -776,32 +1078,39 @@ async function executeCctpHyperCoreToEvm(dstChain, amountUsdc, signerKey, recipi
         ],
     };
     const message = {
-        hyperliquidChain: "Mainnet",
+        hyperliquidChain,
         token: "USDC",
-        amount: String(amountUsdc),
+        amount: parseUsdcAmount(amount),
         sourceDex: "spot",
         destinationRecipient: recipientAddress,
         addressEncoding: "hex",
         destinationChainId: dstDomain,
-        gasLimit: BigInt(200000),
+        // Plain numbers (not BigInt): the OWS signer serializes typed data as JSON. Both are safe integers.
+        gasLimit: 200000,
         data: "0x",
-        nonce: BigInt(timestamp),
+        nonce: timestamp,
     };
-    const sigHex = await wallet.signTypedData(domain, types, message);
+    const sigHex = await signTypedDataChecked(signer, domain, types, message, "HyperCore sendToEvmWithData");
     const sig = EthSig.from(sigHex);
-    // Submit to HL exchange API
-    const resp = await fetch("https://api.hyperliquid.xyz/exchange", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-            action,
-            nonce: timestamp,
-            signature: { r: sig.r, s: sig.s, v: sig.v },
-        }),
-    });
-    const result = await resp.json();
+    // Submit to HL exchange API. A failure after the request left is an unknown outcome.
+    let result;
+    try {
+        const resp = await fetch(hlExchangeUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                action,
+                nonce: timestamp,
+                signature: { r: sig.r, s: sig.s, v: sig.v },
+            }),
+        });
+        result = await resp.json();
+    }
+    catch (e) {
+        throw sendFailure("hyperliquid", "sendToEvmWithData (HyperCore → EVM bridge)", e, "Do NOT resend — the withdrawal may have been accepted. Check the Hyperliquid account history and the destination balance first");
+    }
     if (result.status !== "ok") {
-        throw new Error(`HyperCore withdrawal failed: ${JSON.stringify(result)}`);
+        throw new PerpError("ACTION_REJECTED", `HyperCore withdrawal rejected: ${JSON.stringify(result)}`, { exchange: "hyperliquid" });
     }
     return {
         provider: "cctp (HyperCore → EVM via sendToEvmWithData)",
@@ -816,11 +1125,11 @@ async function executeCctpHyperCoreToEvm(dstChain, amountUsdc, signerKey, recipi
 // ── CCTP: EVM → HyperCore ──
 // Arbitrum: CctpExtension.batchDepositForBurnWithAuth (1-TX, no approve)
 // Other EVM chains: approve + TokenMessengerV2.depositForBurnWithHook (2-TX fallback)
-async function executeCctpEvmToHyperCore(srcChain, amountUsdc, signerKey, recipientAddress) {
+async function executeCctpEvmToHyperCore(srcChain, amount, signerKey, recipientAddress) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
     const { ethers } = await import("ethers");
-    const srcRpc = requireRpcUrl(srcChain);
-    const srcProvider = new ethers.JsonRpcProvider(srcRpc);
-    const srcWallet = new ethers.Wallet(signerKey, srcProvider);
+    const signer = evmSignerOf(signerKey);
+    const { rpc, chainId: rpcChainId } = await bridgeEvmRpc(srcChain);
     const usdcAddr = USDC_ADDRESSES[srcChain];
     if (!usdcAddr)
         throw new Error(`No USDC address for ${srcChain}`);
@@ -831,12 +1140,12 @@ async function executeCctpEvmToHyperCore(srcChain, amountUsdc, signerKey, recipi
     if (!chainId)
         throw new Error(`No chain ID for ${srcChain}`);
     const fees = await getHyperCoreCctpFees(srcDomain, amountUsdc);
-    const amountRaw = BigInt(Math.round(amountUsdc * 1e6));
+    const amountRaw = usdcUnits(amount);
     // mintRecipient & destinationCaller = CctpForwarder (bytes32)
     const forwarderBytes32 = ethers.zeroPadValue(HYPERCORE_CCTP_FORWARDER, 32);
     const hookData = encodeHyperCoreHookData(recipientAddress, HYPERCORE_DEX_PERPS);
     const cctpExtensionAddr = CCTP_EXTENSION[srcChain];
-    let depositTx;
+    let txHash;
     let providerLabel;
     if (cctpExtensionAddr) {
         // ── Path A: CctpExtension (Arbitrum) — single TX, no approve ──
@@ -861,47 +1170,42 @@ async function executeCctpEvmToHyperCore(srcChain, amountUsdc, signerKey, recipi
             ],
         };
         const receiveAuthValue = {
-            from: srcWallet.address,
+            from: signer.getAddress(),
             to: cctpExtensionAddr,
-            value: amountRaw,
+            // Decimal string (not BigInt): the OWS signer serializes typed data as JSON.
+            value: amountRaw.toString(),
             validAfter,
             validBefore,
             nonce: authNonce,
         };
-        const sig = await srcWallet.signTypedData(usdcDomain, receiveAuthTypes, receiveAuthValue);
+        const sig = await signTypedDataChecked(signer, usdcDomain, receiveAuthTypes, receiveAuthValue, "USDC ReceiveWithAuthorization");
         const { v, r, s } = ethers.Signature.from(sig);
         const authParams = [amountRaw, validAfter, validBefore, authNonce, v, r, s];
         const burnParams = [amountRaw, HYPERCORE_CCTP_DOMAIN, forwarderBytes32, forwarderBytes32, BigInt(fees.maxFee), 1000, hookData];
-        const cctpExtension = new ethers.Contract(cctpExtensionAddr, [
+        const cctpExtension = new ethers.Interface([
             "function batchDepositForBurnWithAuth(tuple(uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s) authParams, tuple(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, bytes32 destinationCaller, uint256 maxFee, uint32 minFinalityThreshold, bytes hookData) burnParams)",
-        ], srcWallet);
-        depositTx = await cctpExtension.batchDepositForBurnWithAuth(authParams, burnParams);
+        ]);
+        txHash = await sendBridgeEvmTx(rpc, rpcChainId, srcChain, signer, "cctp", "CCTP batchDepositForBurnWithAuth", cctpExtensionAddr, cctpExtension.encodeFunctionData("batchDepositForBurnWithAuth", [authParams, burnParams]));
         providerLabel = "cctp (HyperCore via CctpExtension)";
     }
     else {
         // ── Path B: approve + depositForBurnWithHook (Base, other EVM chains) ──
         const tokenMessengerAddr = CCTP_TOKEN_MESSENGER[srcChain];
         if (!tokenMessengerAddr)
-            throw new Error(`CCTP not configured for ${srcChain}`);
-        const usdc = new ethers.Contract(usdcAddr, [
-            "function allowance(address,address) view returns (uint256)",
-            "function approve(address,uint256) returns (bool)",
-        ], srcWallet);
-        const allowance = await usdc.allowance(srcWallet.address, tokenMessengerAddr);
-        if (allowance < amountRaw) {
-            const approveTx = await usdc.approve(tokenMessengerAddr, ethers.MaxUint256);
-            await approveTx.wait();
-        }
-        const tokenMessenger = new ethers.Contract(tokenMessengerAddr, [
+            throw new PerpError("NO_BRIDGE_ROUTE", `CCTP not configured for ${srcChain}`);
+        await ensureUsdcAllowance(rpc, rpcChainId, srcChain, signer, "cctp", tokenMessengerAddr, amountRaw);
+        const tokenMessenger = new ethers.Interface([
             "function depositForBurnWithHook(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, address burnToken, bytes32 destinationCaller, uint256 maxFee, uint32 minFinalityThreshold, bytes hookData) returns (uint64 nonce)",
-        ], srcWallet);
-        depositTx = await tokenMessenger.depositForBurnWithHook(amountRaw, HYPERCORE_CCTP_DOMAIN, forwarderBytes32, usdcAddr, forwarderBytes32, BigInt(fees.maxFee), 1000, hookData);
+        ]);
+        txHash = await sendBridgeEvmTx(rpc, rpcChainId, srcChain, signer, "cctp", "CCTP depositForBurnWithHook", tokenMessengerAddr, tokenMessenger.encodeFunctionData("depositForBurnWithHook", [
+            amountRaw, HYPERCORE_CCTP_DOMAIN, forwarderBytes32, usdcAddr,
+            forwarderBytes32, BigInt(fees.maxFee), 1000, hookData,
+        ]));
         providerLabel = "cctp (HyperCore via depositForBurnWithHook)";
     }
-    const receipt = await depositTx.wait();
     return {
         provider: providerLabel,
-        txHash: receipt.hash,
+        txHash,
         srcChain,
         dstChain: "hyperliquid",
         amountIn: amountUsdc,
@@ -909,79 +1213,65 @@ async function executeCctpEvmToHyperCore(srcChain, amountUsdc, signerKey, recipi
     };
 }
 // ── CCTP: EVM → EVM ──
-async function executeCctpEvmToEvm(srcChain, dstChain, amountUsdc, signerKey, recipientAddress, fast = false) {
+async function executeCctpEvmToEvm(srcChain, dstChain, amount, signerKey, recipientAddress, fast = false) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
     const { ethers } = await import("ethers");
-    const srcRpc = requireRpcUrl(srcChain);
-    const srcProvider = new ethers.JsonRpcProvider(srcRpc);
-    const srcWallet = new ethers.Wallet(signerKey, srcProvider);
+    const signer = evmSignerOf(signerKey);
     const usdcAddr = USDC_ADDRESSES[srcChain];
     const tokenMessengerAddr = CCTP_TOKEN_MESSENGER[srcChain];
     const dstDomain = CCTP_DOMAINS[dstChain];
     const srcDomain = CCTP_DOMAINS[srcChain];
     if (!usdcAddr || !tokenMessengerAddr || dstDomain === undefined || srcDomain === undefined) {
-        throw new Error(`CCTP not configured for ${srcChain} → ${dstChain}`);
+        throw new PerpError("NO_BRIDGE_ROUTE", `CCTP not configured for ${srcChain} → ${dstChain}`);
     }
+    const { rpc, chainId } = await bridgeEvmRpc(srcChain);
     // Step 0: Check USDC balance
-    const balance = await getEvmUsdcBalance(srcChain, srcWallet.address);
+    const balance = await getEvmUsdcBalance(srcChain, signer.getAddress());
     if (balance < amountUsdc) {
-        throw new Error(`Insufficient USDC on ${srcChain}: have ${balance.toFixed(2)}, need ${amountUsdc}`);
+        throw new PerpError("INSUFFICIENT_BALANCE", `Insufficient USDC on ${srcChain}: have ${balance.toFixed(2)}, need ${amountUsdc} — nothing was sent`, {
+            remediation: `Fund ${signer.getAddress()} with USDC on ${srcChain}, or lower --amount`,
+        });
     }
-    const amountRaw = BigInt(Math.round(amountUsdc * 1e6));
+    const amountRaw = usdcUnits(amount);
     // Step 1: Approve USDC
-    const usdc = new ethers.Contract(usdcAddr, [
-        "function allowance(address,address) view returns (uint256)",
-        "function approve(address,uint256) returns (bool)",
-    ], srcWallet);
-    const allowance = await usdc.allowance(srcWallet.address, tokenMessengerAddr);
-    if (allowance < amountRaw) {
-        const approveTx = await usdc.approve(tokenMessengerAddr, ethers.MaxUint256);
-        await approveTx.wait();
-    }
+    await ensureUsdcAllowance(rpc, chainId, srcChain, signer, "cctp", tokenMessengerAddr, amountRaw);
     // Step 2: Get fee (with forwarding — Circle handles dst mint)
     const finality = fast ? 1000 : 2000;
-    const { maxFee } = await getCctpRelayFee(srcDomain, dstDomain, finality, true, amountUsdc);
+    const { maxFee } = await getCctpRelayFee(srcDomain, dstDomain, finality, true, amount);
     // Step 3: depositForBurnWithHook + Forwarding Service
     // Circle Forwarding: include forward hook data → Circle broadcasts receiveMessage on dst.
     // No manual relay needed. No dst chain gas needed.
     const mintRecipient = ethers.zeroPadValue(recipientAddress, 32);
     const destinationCaller = ethers.ZeroHash; // must be zero for forwarding
-    const tokenMessenger = new ethers.Contract(tokenMessengerAddr, [
+    const tokenMessenger = new ethers.Interface([
         "function depositForBurnWithHook(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, address burnToken, bytes32 destinationCaller, uint256 maxFee, uint32 minFinalityThreshold, bytes hookData) returns (uint64 nonce)",
-    ], srcWallet);
-    const depositTx = await tokenMessenger.depositForBurnWithHook(amountRaw, dstDomain, mintRecipient, usdcAddr, destinationCaller, maxFee, finality, CCTP_FORWARD_HOOK_DATA);
-    const receipt = await depositTx.wait();
-    const txHash = receipt.hash;
+    ]);
+    const txHash = await sendBridgeEvmTx(rpc, chainId, srcChain, signer, "cctp", "CCTP depositForBurnWithHook", tokenMessengerAddr, tokenMessenger.encodeFunctionData("depositForBurnWithHook", [
+        amountRaw, dstDomain, mintRecipient, usdcAddr,
+        destinationCaller, maxFee, finality, CCTP_FORWARD_HOOK_DATA,
+    ]));
     const feeUsdc = Number(maxFee) / 1e6;
     const providerLabel = fast ? "cctp (fast+forward)" : "cctp (forward)";
     return { provider: providerLabel, txHash, srcChain, dstChain, amountIn: amountUsdc, amountOut: amountUsdc - feeUsdc };
 }
 // ── CCTP: Solana → EVM ──
-async function executeCctpSolanaToEvm(dstChain, amountUsdc, signerKey, recipientAddress, _dstSignerKey, // EVM key for manual receiveMessage (standard finality only)
+async function executeCctpSolanaToEvm(dstChain, amount, signerKey, recipientAddress, _dstSignerKey, // unused: Circle forwarding handles the destination mint
 fast = false) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
     const { Connection, PublicKey, Keypair, TransactionMessage, VersionedTransaction, SystemProgram } = await import("@solana/web3.js");
-    const bs58 = await import("bs58");
     const { createHash } = await import("crypto");
     const connection = new Connection(RPC_URLS.solana, "confirmed");
     const dstDomain = CCTP_DOMAINS[dstChain];
     if (dstDomain === undefined)
-        throw new Error(`Unknown CCTP domain for ${dstChain}`);
-    // Decode Solana keypair
-    let keypair;
-    try {
-        keypair = Keypair.fromSecretKey(bs58.default.decode(signerKey));
-    }
-    catch {
-        try {
-            keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(signerKey)));
-        }
-        catch {
-            throw new Error("Invalid Solana private key format");
-        }
-    }
+        throw new PerpError("NO_BRIDGE_ROUTE", `Unknown CCTP domain for ${dstChain}`);
+    const signer = await solanaSignerOf(signerKey);
+    const keypair = { publicKey: new PublicKey(signer.getPublicKeyBase58()) };
     // Check USDC balance
     const balance = await getSolanaUsdcBalance(keypair.publicKey.toBase58());
     if (balance < amountUsdc) {
-        throw new Error(`Insufficient USDC on Solana: have ${balance.toFixed(2)}, need ${amountUsdc}`);
+        throw new PerpError("INSUFFICIENT_BALANCE", `Insufficient USDC on Solana: have ${balance.toFixed(2)}, need ${amountUsdc} — nothing was sent`, {
+            remediation: `Fund ${keypair.publicKey.toBase58()} with USDC on Solana, or lower --amount`,
+        });
     }
     const tokenMessengerMinter = new PublicKey(CCTP_SOLANA_TOKEN_MESSENGER_MINTER);
     const messageTransmitterProgram = new PublicKey(CCTP_SOLANA_MESSAGE_TRANSMITTER);
@@ -1008,7 +1298,7 @@ fast = false) {
     // Use deposit_for_burn_with_hook for Forwarding Service (Circle handles dst mint)
     const discriminator = createHash("sha256").update("global:deposit_for_burn_with_hook").digest().subarray(0, 8);
     const amountBuf = Buffer.alloc(8);
-    amountBuf.writeBigUInt64LE(BigInt(Math.round(amountUsdc * 1e6)));
+    amountBuf.writeBigUInt64LE(usdcUnits(amount));
     // Domain as u32 LE for instruction data (different from PDA seed which uses string)
     const domainBuf = Buffer.alloc(4);
     domainBuf.writeUInt32LE(dstDomain);
@@ -1019,7 +1309,7 @@ fast = false) {
     // destinationCaller: all zeros (required for forwarding)
     const destinationCaller = Buffer.alloc(32);
     const finality = fast ? 1000 : 2000;
-    const { maxFee: relayFee } = await getCctpRelayFee(CCTP_DOMAINS.solana, dstDomain, finality, true, amountUsdc);
+    const { maxFee: relayFee } = await getCctpRelayFee(CCTP_DOMAINS.solana, dstDomain, finality, true, amount);
     const maxFeeBuf = Buffer.alloc(8);
     maxFeeBuf.writeBigUInt64LE(relayFee);
     const minFinalityBuf = Buffer.alloc(4);
@@ -1068,9 +1358,8 @@ fast = false) {
         instructions: [instruction],
     }).compileToV0Message();
     const transaction = new VersionedTransaction(messageV0);
-    transaction.sign([keypair, eventDataKeypair]);
-    const signature = await connection.sendTransaction(transaction, { skipPreflight: false });
-    await connection.confirmTransaction(signature, "confirmed");
+    await signVersionedSolanaTx(signer, transaction, [eventDataKeypair]);
+    const signature = await sendBridgeSolanaTx(connection, transaction, "CCTP depositForBurnWithHook (Solana → EVM)");
     const feeUsdc = Number(relayFee) / 1e6;
     const providerLabel = fast ? "cctp (fast+forward)" : "cctp (forward)";
     // Forwarding Service: Circle handles dst chain mint — no manual relay needed.
@@ -1079,38 +1368,40 @@ fast = false) {
 // ── CCTP: EVM → Solana ──
 // NOTE: Circle Forwarding Service does NOT support Solana as destination.
 // Must use depositForBurn + manual receiveMessage (or fast finality for auto-relay).
-async function executeCctpEvmToSolana(srcChain, amountUsdc, signerKey, recipientAddress, // Solana base58 pubkey
-solanaPayerKey, // Solana private key for receiveMessage relay
+async function executeCctpEvmToSolana(srcChain, amount, signerKey, recipientAddress, // Solana base58 pubkey
+solanaPayerKey, // Solana signer for the receiveMessage relay (standard finality)
 fast = false) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
     const { ethers } = await import("ethers");
-    const srcRpc = requireRpcUrl(srcChain);
-    const srcProvider = new ethers.JsonRpcProvider(srcRpc);
-    const srcWallet = new ethers.Wallet(signerKey, srcProvider);
+    const signer = evmSignerOf(signerKey);
     const usdcAddr = USDC_ADDRESSES[srcChain];
     const tokenMessengerAddr = CCTP_TOKEN_MESSENGER[srcChain];
     const solanaDomain = CCTP_DOMAINS.solana; // 5
     if (!usdcAddr || !tokenMessengerAddr)
-        throw new Error(`CCTP not configured for ${srcChain}`);
+        throw new PerpError("NO_BRIDGE_ROUTE", `CCTP not configured for ${srcChain}`);
+    // Standard finality needs our own Solana receiveMessage after the burn: without the Solana
+    // signer the burn would leave the USDC unminted. Refused before anything is sent.
+    if (!fast && solanaPayerKey === undefined) {
+        throw new PerpError("NO_SIGNER_AVAILABLE", `CCTP ${srcChain} → Solana (standard finality) mints with a Solana receiveMessage signed by the master's Solana key, and none was supplied — nothing was sent`, {
+            exchange: "bridge",
+            remediation: "Select a master wallet that has a Solana account (perp wallet use <name> / --ows <name>), or pass --fast",
+        });
+    }
+    const { rpc, chainId } = await bridgeEvmRpc(srcChain);
     // Step 0: Check USDC balance
-    const balance = await getEvmUsdcBalance(srcChain, srcWallet.address);
+    const balance = await getEvmUsdcBalance(srcChain, signer.getAddress());
     if (balance < amountUsdc) {
-        throw new Error(`Insufficient USDC on ${srcChain}: have ${balance.toFixed(2)}, need ${amountUsdc}`);
+        throw new PerpError("INSUFFICIENT_BALANCE", `Insufficient USDC on ${srcChain}: have ${balance.toFixed(2)}, need ${amountUsdc} — nothing was sent`, {
+            remediation: `Fund ${signer.getAddress()} with USDC on ${srcChain}, or lower --amount`,
+        });
     }
-    const amountRaw = BigInt(Math.round(amountUsdc * 1e6));
+    const amountRaw = usdcUnits(amount);
     // Step 1: Approve USDC
-    const usdc = new ethers.Contract(usdcAddr, [
-        "function allowance(address,address) view returns (uint256)",
-        "function approve(address,uint256) returns (bool)",
-    ], srcWallet);
-    const allowance = await usdc.allowance(srcWallet.address, tokenMessengerAddr);
-    if (allowance < amountRaw) {
-        const approveTx = await usdc.approve(tokenMessengerAddr, ethers.MaxUint256);
-        await approveTx.wait();
-    }
+    await ensureUsdcAllowance(rpc, chainId, srcChain, signer, "cctp", tokenMessengerAddr, amountRaw);
     // Step 2: Get relay fee (no forwarding — Solana dst not supported)
     const finality = fast ? 1000 : 2000;
     const srcDomain = CCTP_DOMAINS[srcChain];
-    const { maxFee: relayFee, feeUsdc } = await getCctpRelayFee(srcDomain, solanaDomain, finality, false, amountUsdc);
+    const { maxFee: relayFee, feeUsdc } = await getCctpRelayFee(srcDomain, solanaDomain, finality, false, amount);
     // Step 3: depositForBurn — mintRecipient is the Solana ATA for the recipient
     const { PublicKey } = await import("@solana/web3.js");
     const recipientPubkey = new PublicKey(recipientAddress);
@@ -1121,53 +1412,69 @@ fast = false) {
     // Pad the Solana ATA (32 bytes) to bytes32 for EVM
     const mintRecipient = "0x" + Buffer.from(recipientAta.toBytes()).toString("hex");
     const destinationCaller = ethers.ZeroHash; // permissionless relay
-    const tokenMessenger = new ethers.Contract(tokenMessengerAddr, [
+    const tokenMessenger = new ethers.Interface([
         "function depositForBurn(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, address burnToken, bytes32 destinationCaller, uint256 maxFee, uint32 minFinalityThreshold) returns (uint64 nonce)",
-    ], srcWallet);
-    const depositTx = await tokenMessenger.depositForBurn(amountRaw, solanaDomain, mintRecipient, usdcAddr, destinationCaller, relayFee, finality);
-    const receipt = await depositTx.wait();
-    const txHash = receipt.hash;
+    ]);
+    const txHash = await sendBridgeEvmTx(rpc, chainId, srcChain, signer, "cctp", "CCTP depositForBurn", tokenMessengerAddr, tokenMessenger.encodeFunctionData("depositForBurn", [
+        amountRaw, solanaDomain, mintRecipient, usdcAddr,
+        destinationCaller, relayFee, finality,
+    ]));
     // Fast finality (1000): Circle auto-relays — done.
     if (fast) {
         return { provider: "cctp (fast)", txHash, srcChain, dstChain: "solana", amountIn: amountUsdc, amountOut: amountUsdc - feeUsdc };
     }
-    // Standard finality (2000): poll attestation + manual Solana receiveMessage
-    if (solanaPayerKey) {
-        const attestationUrl = `https://iris-api.circle.com/v2/messages/${srcDomain}?transactionHash=${txHash}`;
-        let messageBytes = "";
-        let attestationBytes = "";
-        for (let i = 0; i < 80; i++) {
-            await new Promise(r => setTimeout(r, 15000));
-            try {
-                const res = await fetch(attestationUrl);
-                if (res.ok) {
-                    const body = await res.json();
-                    const msg = body.messages?.[0];
-                    if (msg?.status === "complete" && msg.attestation && msg.attestation !== "PENDING") {
-                        messageBytes = msg.message;
-                        attestationBytes = msg.attestation;
-                        break;
-                    }
-                }
+    // Standard finality (2000): poll attestation + manual Solana receiveMessage. The burn is final:
+    // anything short of a confirmed mint is ORDER_PENDING (never a normal result, never a resend).
+    const receiveTxHash = await completeEvmToSolanaMint(srcDomain, txHash, recipientAddress, solanaPayerKey);
+    return { provider: "cctp", txHash, receiveTxHash, srcChain, dstChain: "solana", amountIn: amountUsdc, amountOut: amountUsdc - feeUsdc };
+}
+/** Circle Iris V2 message lookup for a source-chain burn. */
+function irisMessageUrl(srcDomain, txHash) {
+    return `https://iris-api.circle.com/v2/messages/${srcDomain}?transactionHash=${txHash}`;
+}
+function burnedMintUnconfirmed(srcDomain, burnTxHash, why) {
+    const iris = irisMessageUrl(srcDomain, burnTxHash);
+    return new PerpError("ORDER_PENDING", `CCTP: USDC burned (tx ${burnTxHash}); mint on Solana not confirmed — ${why}`, {
+        exchange: "bridge", txHash: burnTxHash, attestationUrl: iris,
+        remediation: `Do NOT resend the bridge — the USDC is already burned. Check the attestation at ${iris}; once it is complete the mint can be claimed with a Solana receiveMessage (CCTP is idempotent per message nonce). Then check the Solana USDC balance.`,
+    });
+}
+/**
+ * After an EVM → Solana standard-finality burn: wait for Circle's attestation, then mint on
+ * Solana with receiveMessage. Returns the mint signature. Timeout or a failed / unconfirmed
+ * receiveMessage throws ORDER_PENDING carrying the burn tx hash and the Iris URL.
+ * `opts` exists for tests (poll count / interval, receiveMessage implementation).
+ */
+export async function completeEvmToSolanaMint(srcDomain, burnTxHash, recipientAddress, payer, opts = { attempts: 80, intervalMs: 15_000, receive: executeSolanaReceiveMessage }) {
+    const url = irisMessageUrl(srcDomain, burnTxHash);
+    let message = null;
+    let attestation = null;
+    for (let i = 0; i < opts.attempts && message === null; i++) {
+        await sleep(opts.intervalMs);
+        try {
+            const res = await fetch(url);
+            if (!res.ok)
+                continue; // 404 until Iris indexes the burn: keep polling (read-only)
+            const body = await res.json();
+            const msg = body.messages?.[0];
+            if (msg?.status === "complete" && msg.message && msg.attestation && msg.attestation !== "PENDING") {
+                message = msg.message;
+                attestation = msg.attestation;
             }
-            catch { /* retry */ }
         }
-        if (messageBytes && attestationBytes) {
-            try {
-                const receiveSig = await executeSolanaReceiveMessage(messageBytes, attestationBytes, recipientAddress, solanaPayerKey);
-                return { provider: "cctp", txHash, receiveTxHash: receiveSig, srcChain, dstChain: "solana", amountIn: amountUsdc, amountOut: amountUsdc - feeUsdc };
-            }
-            catch { /* may fail if already relayed */ }
+        catch {
+            // A failed read of the attestation is retried until the poll budget ends (read-only).
         }
     }
-    return {
-        provider: "cctp",
-        txHash,
-        srcChain,
-        dstChain: "solana",
-        amountIn: amountUsdc,
-        amountOut: amountUsdc - feeUsdc,
-    };
+    if (message === null || attestation === null) {
+        throw burnedMintUnconfirmed(srcDomain, burnTxHash, `no complete attestation after ${Math.round(opts.attempts * opts.intervalMs / 1000)}s`);
+    }
+    try {
+        return await opts.receive(message, attestation, recipientAddress, payer);
+    }
+    catch (e) {
+        throw burnedMintUnconfirmed(srcDomain, burnTxHash, `receiveMessage did not confirm (${e instanceof Error ? e.message : String(e)})`);
+    }
 }
 // ── CCTP: Solana receiveMessage (for EVM→Solana relay) ──
 /**
@@ -1178,23 +1485,11 @@ export async function executeSolanaReceiveMessage(messageHex, // "0x..." CCTP me
 attestationHex, // "0x..." attestation from Iris API
 recipientAddress, // Solana wallet pubkey (base58)
 payerKey) {
-    const { Connection, PublicKey, Keypair, TransactionMessage, VersionedTransaction, SystemProgram, ComputeBudgetProgram } = await import("@solana/web3.js");
-    const bs58 = await import("bs58");
+    const { Connection, PublicKey, TransactionMessage, VersionedTransaction, SystemProgram, ComputeBudgetProgram } = await import("@solana/web3.js");
     const { createHash } = await import("crypto");
     const connection = new Connection(RPC_URLS.solana, "confirmed");
-    // Decode payer keypair
-    let payer;
-    try {
-        payer = Keypair.fromSecretKey(bs58.default.decode(payerKey));
-    }
-    catch {
-        try {
-            payer = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(payerKey)));
-        }
-        catch {
-            throw new Error("Invalid Solana private key format");
-        }
-    }
+    const payerSigner = await solanaSignerOf(payerKey);
+    const payer = { publicKey: new PublicKey(payerSigner.getPublicKeyBase58()) };
     // Parse raw bytes
     const messageBytes = Buffer.from(messageHex.replace("0x", ""), "hex");
     const attestationBytes = Buffer.from(attestationHex.replace("0x", ""), "hex");
@@ -1293,10 +1588,8 @@ payerKey) {
         instructions: [computeBudgetIx, instruction],
     }).compileToV0Message(lookupTables);
     const transaction = new VersionedTransaction(messageV0);
-    transaction.sign([payer]);
-    const signature = await connection.sendTransaction(transaction, { skipPreflight: false });
-    await connection.confirmTransaction(signature, "confirmed");
-    return signature;
+    await signVersionedSolanaTx(payerSigner, transaction);
+    return sendBridgeSolanaTx(connection, transaction, "CCTP receiveMessage (Solana)");
 }
 // ── Shared CCTP helpers ──
 /**
@@ -1324,121 +1617,56 @@ async function pollCctpV2Attestation(sourceDomain, txHash, maxAttempts) {
     return { message: null, attestation: null };
 }
 // ── Relay Bridge API ──
-const RELAY_API = "https://api.relay.link";
-// Relay chain IDs (same as standard EVM chain IDs, Solana = 792703809)
-const RELAY_CHAIN_IDS = {
-    solana: 792703809,
-    arbitrum: 42161,
-    base: 8453,
-};
-export async function getRelayQuote(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress) {
-    const srcChainId = RELAY_CHAIN_IDS[srcChain];
-    const dstChainId = RELAY_CHAIN_IDS[dstChain];
-    if (!srcChainId || !dstChainId)
-        throw new Error(`Relay: unsupported chain ${srcChain} or ${dstChain}`);
-    const srcToken = USDC_ADDRESSES[srcChain];
-    const dstToken = USDC_ADDRESSES[dstChain];
-    if (!srcToken || !dstToken)
-        throw new Error(`No USDC for ${srcChain} or ${dstChain}`);
-    const amountRaw = String(Math.round(amountUsdc * 1e6));
-    const body = {
-        user: senderAddress,
-        recipient: recipientAddress,
-        originChainId: srcChainId,
-        destinationChainId: dstChainId,
-        originCurrency: srcToken,
-        destinationCurrency: dstToken,
-        amount: amountRaw,
-        tradeType: "EXACT_INPUT",
-    };
-    const res = await fetch(`${RELAY_API}/quote`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
+// Quote verification, step validation and execution live in ./relay-swap.ts (generic assets,
+// EVM-origin deposits). These two functions are the USDC → USDC entry used by getAllQuotes /
+// executeBestBridge.
+export async function getRelayQuote(srcChain, dstChain, amount, senderAddress, recipientAddress) {
+    const amountUsdc = usdcDisplay(amount); // display / fee estimates only — signed amounts use usdcUnits(amount)
+    assertDistinctBridgeChains(srcChain, dstChain);
+    const { quoteRelaySwap } = await import("./relay-swap.js");
+    // Verified locally (order id, depository, amounts, recipient) — see relay-swap.ts.
+    const q = await quoteRelaySwap({
+        from: srcChain, to: dstChain, fromAsset: "USDC", toAsset: "USDC",
+        amount: parseUsdcAmount(amount), sender: senderAddress, recipient: recipientAddress,
     });
-    if (!res.ok) {
-        const errText = await res.text();
-        throw new Error(`Relay quote failed: ${res.status} ${errText}`);
-    }
-    const data = await res.json();
-    const details = data.details;
-    const fees = data.fees;
-    // SSOT rule #2: refuse to fabricate amountOut/fee from `0 || subtractFee`
-    // back-fill. If Relay didn't quote a real amount-out + relayer fee, the
-    // user's bridge cost is unknown — surface the gap.
-    const currencyOut = details?.currencyOut;
-    const amountFormattedRaw = currencyOut?.amountFormatted;
-    const amountOut = Number(amountFormattedRaw);
-    if (amountFormattedRaw === undefined || !Number.isFinite(amountOut)) {
-        throw new Error(`Relay quote missing details.currencyOut.amountFormatted ` +
-            `(received ${JSON.stringify(amountFormattedRaw)}); refusing silent 0 fallback. ` +
-            `Raw details=${JSON.stringify(details)}`);
-    }
-    const relayerFee = fees?.relayer;
-    const feeUsdRaw = relayerFee?.amountUsd;
-    const feeUsd = Number(feeUsdRaw);
-    if (feeUsdRaw === undefined || !Number.isFinite(feeUsd)) {
-        throw new Error(`Relay quote missing fees.relayer.amountUsd ` +
-            `(received ${JSON.stringify(feeUsdRaw)}); refusing silent 0 fallback. ` +
-            `Raw fees=${JSON.stringify(fees)}`);
-    }
-    // timeEstimate is telemetry only; default 30s is documented Relay median
-    // for healthy routes. Telemetry default, not error fallback.
-    const timeEstimateRaw = Number(details?.timeEstimate);
-    const timeEstimate = Number.isFinite(timeEstimateRaw) ? timeEstimateRaw : 30;
     return {
         provider: "relay",
         srcChain,
         dstChain,
         amountIn: amountUsdc,
-        amountOut,
-        fee: feeUsd,
-        estimatedTime: timeEstimate,
+        amountOut: Number(q.expectedOut),
+        fee: Number(q.fees.relayerUsd),
+        // timeEstimate is telemetry only; 30s is the documented Relay median for healthy routes.
+        estimatedTime: q.timeEstimateSec === null ? 30 : q.timeEstimateSec,
         gasIncluded: true,
         gasNote: "Relay solver handles destination execution",
-        raw: data,
+        raw: q,
     };
 }
-export async function executeRelayBridge(bridgeQuote, signerKey) {
-    const { srcChain, dstChain, amountIn, amountOut } = bridgeQuote;
-    const data = bridgeQuote.raw;
-    const steps = data.steps;
-    if (!steps || steps.length === 0)
-        throw new Error("Relay: no steps in quote");
-    let txHash = "";
-    for (const step of steps) {
-        const kind = step.kind;
-        const items = step.items;
-        if (!items)
-            continue;
-        for (const item of items) {
-            const itemData = item.data;
-            if (!itemData)
-                continue;
-            if (kind === "transaction") {
-                if (srcChain === "solana") {
-                    // Solana transaction
-                    const txData = String(itemData.data ?? "");
-                    if (txData) {
-                        txHash = await submitSolanaTransaction({ data: txData }, signerKey);
-                    }
-                }
-                else {
-                    // EVM transaction
-                    txHash = await submitEvmTransaction({ to: itemData.to, data: itemData.data, value: itemData.value ?? "0" }, signerKey, srcChain);
-                }
-            }
-        }
+/**
+ * Execute a verified Relay USDC quote with the master's EVM signer (OWS vault signer or a raw
+ * key). Only the verified approve (exact amount, pinned depository) + deposit are signed — never
+ * an unlimited approval, never an unchecked target.
+ */
+export async function executeRelayBridge(network, bridgeQuote, signerKey) {
+    assertBridgeNetwork(network);
+    assertDistinctBridgeChains(bridgeQuote.srcChain, bridgeQuote.dstChain);
+    const { executeRelaySwap, assertRelayMinOut } = await import("./relay-swap.js");
+    const q = bridgeQuote.raw;
+    assertRelayMinOut(q, null);
+    const signer = evmSignerOf(signerKey);
+    if (signer.getAddress().toLowerCase() !== q.sender.toLowerCase()) {
+        throw new PerpError("INVALID_PARAMS", `The Relay quote was built for sender ${q.sender}, not the signing wallet's address ${signer.getAddress()} — nothing was sent`);
     }
-    if (!txHash)
-        throw new Error("Relay: no transaction executed");
+    const res = await executeRelaySwap(network, q, tx => signer.signTransaction(tx));
     return {
         provider: "relay",
-        txHash,
-        srcChain,
-        dstChain,
-        amountIn,
-        amountOut,
+        txHash: res.depositTxHash,
+        srcChain: bridgeQuote.srcChain,
+        dstChain: bridgeQuote.dstChain,
+        amountIn: bridgeQuote.amountIn,
+        amountOut: bridgeQuote.amountOut,
+        ...(res.destinationTxHashes.length > 0 ? { receiveTxHash: res.destinationTxHashes[0] } : {}),
     };
 }
 /**
@@ -1450,26 +1678,75 @@ export async function executeRelayBridge(bridgeQuote, signerKey) {
  * Get quotes from ALL available providers in parallel.
  * Returns sorted by amountOut (best first).
  */
-export async function getAllQuotes(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress) {
+/** Plain decimal string of `raw` / 10^decimals (no exponent, trailing zeros trimmed). */
+function formatUnitsPlain(raw, decimals) {
+    const base = 10n ** BigInt(decimals);
+    const whole = raw / base;
+    const frac = (raw % base).toString().padStart(decimals, "0").replace(/0+$/, "");
+    return frac === "" ? whole.toString() : `${whole}.${frac}`;
+}
+/** USD mid of native tokens (ETH / SOL) from Hyperliquid allMids; a failed read leaves them unpriced. */
+async function nativeUsdPrices(symbols) {
+    const out = new Map();
+    try {
+        const res = await fetch("https://api.hyperliquid.xyz/info", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ type: "allMids" }) });
+        if (!res.ok)
+            return out;
+        const mids = await res.json();
+        for (const sym of symbols) {
+            const px = Number(mids[sym]);
+            if (Number.isFinite(px) && px > 0)
+                out.set(sym, px);
+        }
+    }
+    catch {
+        // Unpriced is reported as usd: null and ranks the quote last — never treated as a zero fee.
+    }
+    return out;
+}
+export async function getAllQuotes(srcChain, dstChain, amount, senderAddress, recipientAddress) {
+    usdcUnits(amount); // INVALID_PARAMS before the fan-out (allSettled would hide it as "no route")
+    assertDistinctBridgeChains(srcChain, dstChain);
     const results = await Promise.allSettled([
-        getCctpQuote(srcChain, dstChain, amountUsdc),
-        getRelayQuote(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress),
-        getDebridgeQuote(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress),
+        getCctpQuote(srcChain, dstChain, amount),
+        getRelayQuote(srcChain, dstChain, amount, senderAddress, recipientAddress),
+        getDebridgeQuote(srcChain, dstChain, amount, senderAddress, recipientAddress),
     ]);
     const quotes = [];
     for (const r of results) {
         if (r.status === "fulfilled")
             quotes.push(r.value);
     }
-    // Sort by best deal (highest amountOut)
-    quotes.sort((a, b) => b.amountOut - a.amountOut);
+    // Price native fees (deBridge fixFee) so quotes compare on the same basis; an unpriced native
+    // fee ranks that quote last (its total cost is unknown), never as free.
+    const symbols = [...new Set(quotes.flatMap(q => (q.nativeFee ? [q.nativeFee.symbol] : [])))];
+    if (symbols.length > 0) {
+        const prices = await nativeUsdPrices(symbols);
+        for (const q of quotes) {
+            if (!q.nativeFee)
+                continue;
+            const px = prices.get(q.nativeFee.symbol);
+            q.nativeFee = { ...q.nativeFee, usd: px === undefined ? null : Number(q.nativeFee.amount) * px };
+        }
+    }
+    const net = (q) => (q.nativeFee ? (q.nativeFee.usd === null ? null : q.amountOut - q.nativeFee.usd) : q.amountOut);
+    quotes.sort((a, b) => {
+        const na = net(a), nb = net(b);
+        if (na === null && nb === null)
+            return b.amountOut - a.amountOut;
+        if (na === null)
+            return 1;
+        if (nb === null)
+            return -1;
+        return nb - na;
+    });
     return quotes;
 }
 /**
  * Get the best quote across all providers.
  */
-export async function getBestQuote(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress) {
-    const quotes = await getAllQuotes(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress);
+export async function getBestQuote(srcChain, dstChain, amount, senderAddress, recipientAddress) {
+    const quotes = await getAllQuotes(srcChain, dstChain, amount, senderAddress, recipientAddress);
     if (quotes.length === 0) {
         throw new Error(`No bridge available for ${srcChain} → ${dstChain}`);
     }
@@ -1479,31 +1756,45 @@ export async function getBestQuote(srcChain, dstChain, amountUsdc, senderAddress
  * Execute a bridge using the specified or best available provider.
  * @param provider - Optional: force a specific provider ("cctp" | "relay" | "debridge")
  */
-export async function executeBestBridge(srcChain, dstChain, amountUsdc, signerKey, senderAddress, recipientAddress, dstSignerKey, // Optional EVM key for manual receiveMessage (standard finality)
+export async function executeBestBridge(network, srcChain, dstChain, amount, signerKey, senderAddress, recipientAddress, dstSignerKey, // Optional destination-chain signer for manual receiveMessage (standard finality)
 provider, fast = false) {
+    // Before quoting: a testnet run must not even look up mainnet routes to sign.
+    assertBridgeNetwork(network);
+    assertDistinctBridgeChains(srcChain, dstChain);
+    usdcUnits(amount); // INVALID_PARAMS (> 6 decimals, malformed) before any quote
+    // Specific refusals (the quote fan-out below would only report "not available").
+    assertCctpRouteSupported(srcChain, dstChain);
+    if (provider === "debridge")
+        assertDebridgeSourceSupported(srcChain);
     let quote;
     if (provider) {
         // User specified a provider — get that specific quote
-        const quotes = await getAllQuotes(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress);
+        const quotes = await getAllQuotes(srcChain, dstChain, amount, senderAddress, recipientAddress);
         const match = quotes.find(q => q.provider === provider);
-        if (!match)
-            throw new Error(`Provider "${provider}" not available for ${srcChain} → ${dstChain}`);
+        if (!match) {
+            throw new PerpError("NO_BRIDGE_ROUTE", `Provider "${provider}" not available for ${srcChain} → ${dstChain} — nothing was sent`, {
+                remediation: "Drop --provider to use the best available route (see: perp funds bridge quote)",
+            });
+        }
         quote = match;
     }
     else {
         // Default: prefer deBridge DLN (fastest, ~2s), fallback to best available
-        const quotes = await getAllQuotes(srcChain, dstChain, amountUsdc, senderAddress, recipientAddress);
-        if (quotes.length === 0)
-            throw new Error(`No bridge available for ${srcChain} → ${dstChain}`);
+        const quotes = await getAllQuotes(srcChain, dstChain, amount, senderAddress, recipientAddress);
+        if (quotes.length === 0) {
+            throw new PerpError("NO_BRIDGE_ROUTE", `No bridge available for ${srcChain} → ${dstChain} — nothing was sent`, {
+                remediation: "Check supported routes: perp funds bridge chains",
+            });
+        }
         quote = quotes.find(q => q.provider === "debridge") ?? quotes[0];
     }
     if (quote.provider === "cctp") {
-        return executeCctpBridge(srcChain, dstChain, amountUsdc, signerKey, recipientAddress, dstSignerKey, fast);
+        return executeCctpBridge(network, srcChain, dstChain, amount, signerKey, recipientAddress, dstSignerKey, fast);
     }
     if (quote.provider === "relay") {
-        return executeRelayBridge(quote, signerKey);
+        return executeRelayBridge(network, quote, signerKey);
     }
-    return executeDebridgeBridge(quote, signerKey);
+    return executeDebridgeBridge(network, quote, signerKey);
 }
 /**
  * Check bridge order status via deBridge.
@@ -1516,23 +1807,20 @@ export async function checkDebridgeStatus(orderId) {
 }
 // ── Helpers ──
 /**
- * Append deBridge builder/affiliate params if configured via env vars:
- *   DEBRIDGE_REFERRAL_CODE, DEBRIDGE_AFFILIATE_FEE_PERCENT, DEBRIDGE_AFFILIATE_FEE_RECIPIENT
+ * Append deBridge referral / affiliate params when the user configured them in
+ * settings `bridge.debridgeAffiliate` (`perp settings set bridge.debridgeAffiliate.*`).
+ * Absent (the shipped state) → nothing is sent. No env var is read.
  */
 function appendDebridgeBuilderParams(params) {
-    if (DEBRIDGE_REFERRAL_CODE)
-        params.set("referralCode", DEBRIDGE_REFERRAL_CODE);
-    if (DEBRIDGE_AFFILIATE_FEE_PERCENT && DEBRIDGE_AFFILIATE_FEE_RECIPIENT) {
-        params.set("affiliateFeePercent", DEBRIDGE_AFFILIATE_FEE_PERCENT);
-        params.set("affiliateFeeRecipient", DEBRIDGE_AFFILIATE_FEE_RECIPIENT);
-    }
-}
-function hexToBytes(hex) {
-    const bytes = new Uint8Array(hex.length / 2);
-    for (let i = 0; i < hex.length; i += 2) {
-        bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    const aff = loadSettings().bridge.debridgeAffiliate;
+    if (aff === null)
+        return;
+    if (aff.referralCode !== null)
+        params.set("referralCode", aff.referralCode);
+    if (aff.feePercent !== null && aff.feeRecipient !== null) {
+        params.set("affiliateFeePercent", String(aff.feePercent));
+        params.set("affiliateFeeRecipient", aff.feeRecipient);
     }
-    return bytes;
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));