@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/cjs/ecosystems.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAddressIn = exports.isValidAddressIn = exports.isNativeAsset = exports.sameAddress = exports.ecosystemByCaipNamespace = exports.isEcosystemProvenEndToEnd = exports.ecosystemById = exports.ecosystemRegistry = void 0;
+const viem_1 = require("viem");
+// Solana public keys are base58 (no 0, O, I, l) and 32–44 characters long.
+const base58Solana = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+// Bitcoin mainnet: bech32 (bc1…) or base58 pay-to-key/script (starts 1 or 3).
+const bech32Bitcoin = /^bc1[0-9ac-hj-np-z]{6,87}$/;
+const base58Bitcoin = /^[13][1-9A-HJ-NP-Za-km-z]{25,39}$/;
+// Tron base58check addresses are always 34 characters and always begin with a
+// capital T (the encoding of the 0x41 mainnet prefix byte).
+const base58Tron = /^T[1-9A-HJ-NP-Za-km-z]{33}$/;
+// The Open Network has two interchangeable address encodings, and Relay uses
+// both: the 48-character "user-friendly" base64url form (EQ/UQ on mainnet,
+// kQ/0Q on testnet), and the "raw" form of a workchain, a colon, and a
+// 64-character hex account identifier.
+const friendlyTon = /^[EUk0]Q[A-Za-z0-9_-]{46}$/;
+const rawTon = /^-?\d+:[0-9a-fA-F]{64}$/;
+// HyperCore token identifiers are hex of a length Ethereum never uses: sixteen
+// bytes for most tokens, nineteen for a few. Twenty is allowed too so a token
+// that is addressed by a full Ethereum address still resolves.
+const hyperliquidTokenId = /^0x[0-9a-fA-F]{32,40}$/;
+// Zcash TRANSPARENT addresses only, and the restriction is the service's, not
+// ours: a shielded (`zs1…`) or unified (`u1…`) address is refused at the door
+// with `refundTo is not valid`, before a solver is ever reached. Both
+// transparent forms are base58check over a two-byte prefix, which always
+// encodes to exactly 35 characters: `t1` pays to a public key hash, `t3` to a
+// script hash. The pattern rejects the shielded forms by construction, because
+// neither begins with `t`.
+const transparentZcash = /^t[13][1-9A-HJ-NP-Za-km-z]{33}$/;
+const evmDescriptor = {
+    id: 'evm',
+    label: 'Ethereum Virtual Machine',
+    caipNamespace: 'eip155',
+    // The all-zero address, exactly as the Relay builder uses across every
+    // Ethereum Virtual Machine chain for the native gas token.
+    nativeAssetSentinel: '0x0000000000000000000000000000000000000000',
+    // The only proof the product holds. The bridge's own contracts run on
+    // PulseChain, Ethereum and Binance Smart Chain, and every aggregator origin
+    // LI.FI carries is an Ethereum Virtual Machine chain, so this is the family
+    // real transfers have crossed.
+    endToEndProof: 'verified',
+    isValidAddress: (value) => (0, viem_1.isAddress)(value),
+    // getAddress applies the mixed-case checksum; it throws on a non-address, so
+    // fall back to the raw input to keep normalize total and side-effect-free.
+    normalizeAddress: (value) => ((0, viem_1.isAddress)(value) ? (0, viem_1.getAddress)(value) : value),
+    addressCasing: 'insensitive',
+};
+const svmDescriptor = {
+    id: 'svm',
+    label: 'Solana',
+    caipNamespace: 'solana',
+    // Solana native currency (the System Program address), as Relay expects it.
+    nativeAssetSentinel: '11111111111111111111111111111111',
+    // Connects through the Reown AppKit Solana adapter and signs for real
+    // (`useSolanaDepositSigner` builds a versioned transaction and calls the
+    // wallet's sign-and-send). Every test around it drives a mocked wallet, and
+    // Relay — the only provider that quotes this origin — has never had its
+    // on-chain execution confirmed by a funded transfer.
+    endToEndProof: 'pending',
+    isValidAddress: (value) => base58Solana.test(value),
+    // base58 is case-significant; canonical form is the input unchanged.
+    normalizeAddress: (value) => value,
+    addressCasing: 'significant',
+};
+const bvmDescriptor = {
+    id: 'bvm',
+    label: 'Bitcoin',
+    caipNamespace: 'bip122',
+    // Bitcoin native currency string, as Relay expects it.
+    nativeAssetSentinel: 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8',
+    // The best-evidenced of the four, and still short of proof. A partially
+    // signed transaction the pipeline builds is accepted by a real node, but
+    // that test runs against a local regtest node behind `BITCOIN_REGTEST=1`
+    // and never in the normal suite. The browser wallet that signs in
+    // production is driven by nothing but a mock, and no funded mainnet
+    // transfer has completed.
+    endToEndProof: 'pending',
+    isValidAddress: (value) => bech32Bitcoin.test(value) || base58Bitcoin.test(value),
+    // bech32 and base58 are case-significant; canonical form is the input unchanged.
+    normalizeAddress: (value) => value,
+    addressCasing: 'significant',
+};
+const tvmDescriptor = {
+    id: 'tvm',
+    label: 'Tron',
+    caipNamespace: 'tron',
+    // Tron native currency (TRX), as Relay expects it. Not a real contract: it is
+    // the placeholder address Relay publishes for the chain's native asset.
+    nativeAssetSentinel: 'T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb',
+    // The first wallet the interface reaches outside Reown AppKit: it reads an
+    // injected provider directly. That is more of the connection path owned
+    // here, and therefore more of it unexercised outside a mock. No funded
+    // transfer has completed.
+    endToEndProof: 'pending',
+    isValidAddress: (value) => base58Tron.test(value),
+    // base58check is case-significant; canonical form is the input unchanged.
+    normalizeAddress: (value) => value,
+    addressCasing: 'significant',
+};
+const tonvmDescriptor = {
+    id: 'tonvm',
+    label: 'The Open Network',
+    caipNamespace: 'ton',
+    // Relay publishes Gram — NOT the Toncoin gas asset — as this chain's native
+    // currency, so a native-asset route on The Open Network is denominated in
+    // Gram. Kept byte-equal to Relay's own value rather than "corrected".
+    nativeAssetSentinel: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+    // The second wallet outside Reown AppKit, on a separate connection library,
+    // and the one origin whose deposit identifier is derived from the returned
+    // cell rather than handed back by the wallet. Only a mock has ever returned
+    // that cell. No funded transfer has completed.
+    endToEndProof: 'pending',
+    isValidAddress: (value) => friendlyTon.test(value) || rawTon.test(value),
+    // both encodings are case-significant; canonical form is the input unchanged.
+    normalizeAddress: (value) => value,
+    addressCasing: 'significant',
+};
+const hypevmDescriptor = {
+    id: 'hypevm',
+    label: 'Hyperliquid',
+    caipNamespace: 'hyperliquid',
+    // Relay publishes USD Coin — NOT the Hype gas asset — as this chain's native
+    // currency, and addresses it by a sixteen-byte HyperCore token identifier
+    // rather than the twenty-byte all-zero address every Ethereum Virtual Machine
+    // chain uses. The two sentinels are therefore different strings.
+    nativeAssetSentinel: '0x00000000000000000000000000000000',
+    // THE WORST OF THE SIX, and the one that was actively misleading. The
+    // interface's source picker never offers Hyperliquid — nothing can quote it
+    // — yet the landing page drew a pill for it that set the source chain to
+    // Hyperliquid on click. A reader who pressed it arrived at a chain the form
+    // does not list and no provider answers. Removing the pill removes that dead
+    // end; the descriptor stays because the route layer still has to be able to
+    // NAME the chain.
+    endToEndProof: 'pending',
+    // This predicate checks TOKEN addresses, and HyperCore identifies a token by a
+    // hex string SHORTER than an Ethereum address — sixteen bytes for most,
+    // nineteen for a few — so the twenty-byte `isAddress` check would reject the
+    // very identifiers it exists to accept. Its only consumer silently falls back
+    // to the native sentinel when this returns false, so an over-strict pattern
+    // would quietly swallow valid token links instead of surfacing an error.
+    // Accounts are a different namespace (ordinary twenty-byte Ethereum
+    // addresses) and are validated by the wallet layer, not here.
+    isValidAddress: (value) => hyperliquidTokenId.test(value),
+    // Hex is case-insensitive and Relay emits lower case, so lower case is the
+    // canonical form. It matters: the token-equality check compares non-Ethereum
+    // addresses exactly, and only a single canonical case makes that correct.
+    normalizeAddress: (value) => hyperliquidTokenId.test(value) ? value.toLowerCase() : value,
+    addressCasing: 'significant',
+};
+const zcashDescriptor = {
+    id: 'zcash',
+    label: 'Zcash',
+    // Zcash is not a Relay chain and has no widely-registered chain-agnostic
+    // namespace. `zcash` is this repository's own key, and nothing maps a
+    // connected wallet through it, because no wallet connects to this family.
+    caipNamespace: 'zcash',
+    // DERIVED, NOT INVENTED: the transparent pay-to-public-key-hash address of
+    // an all-zero key hash, base58check over the mainnet prefix `1cb8` followed
+    // by twenty zero bytes. Nobody holds a key for it. It follows the pattern of
+    // Relay's Bitcoin sentinel, an all-zero witness program, and for the same
+    // reason: the sentinel stands where a token address is expected, so it must
+    // pass this family's own address check. Zcash carries no tokens on this
+    // route, so the native asset is the only asset.
+    nativeAssetSentinel: 't1Hsc1LR8yKnbbe3twRp88p6vFfC5t7DLbs',
+    // THE FIRST ECOSYSTEM WITH NO WALLET AT ALL, and therefore the first whose
+    // hold cannot be cleared by connecting one. The reader pays an address by
+    // hand from wherever they hold the coin, so every part of the journey that
+    // this repository owns — the quote, the address, the amount, the deadline,
+    // the status poll — is exercised only by a fixture. Nothing funded has
+    // crossed. Clearing this is one word, after one transfer.
+    endToEndProof: 'pending',
+    isValidAddress: (value) => transparentZcash.test(value),
+    // base58check is case-significant; canonical form is the input unchanged.
+    normalizeAddress: (value) => value,
+    addressCasing: 'significant',
+};
+/**
+ * Every ecosystem the bridge can originate from. LI.FI-compatible one first.
+ *
+ * Registration means the library can MODEL and QUOTE the ecosystem, not that an
+ * interface can sign it — see the note on {@link Ecosystem}.
+ *
+ * It means less than that again where a public claim is concerned: read
+ * {@link EndToEndProof} before listing this registry anywhere a reader will
+ * take it as an offer.
+ */
+exports.ecosystemRegistry = [
+    evmDescriptor,
+    svmDescriptor,
+    bvmDescriptor,
+    tvmDescriptor,
+    tonvmDescriptor,
+    hypevmDescriptor,
+    zcashDescriptor,
+];
+const byId = new Map(exports.ecosystemRegistry.map((descriptor) => [descriptor.id, descriptor]));
+/**
+ * Looks up the descriptor for an ecosystem id. Total over the `Ecosystem` union;
+ * throws only if the registry is ever left incomplete (a programming error the
+ * round-trip test would catch).
+ *
+ * @param id - the ecosystem key
+ * @returns the descriptor whose `id` equals `id`
+ */
+const ecosystemById = (id) => {
+    const descriptor = byId.get(id);
+    if (descriptor === undefined) {
+        throw new Error(`no ecosystem descriptor registered for id "${id}"`);
+    }
+    return descriptor;
+};
+exports.ecosystemById = ecosystemById;
+/**
+ * Whether a transfer has been carried through this ecosystem end to end.
+ *
+ * The predicate a surface calls before ADVERTISING an origin. It is separate
+ * from anything the router asks, and deliberately so: the router must keep
+ * quoting and naming every registered ecosystem, because a reader who reaches
+ * an unproven chain through a link still needs the page to work. This governs
+ * only what the product offers unprompted.
+ *
+ * @param id - the ecosystem key
+ * @returns true when a real transfer has completed through it
+ */
+const isEcosystemProvenEndToEnd = (id) => (0, exports.ecosystemById)(id).endToEndProof === 'verified';
+exports.isEcosystemProvenEndToEnd = isEcosystemProvenEndToEnd;
+const byNamespace = new Map(exports.ecosystemRegistry.map((descriptor) => [descriptor.caipNamespace, descriptor]));
+/**
+ * Resolves an ecosystem from a chain-agnostic identifier namespace.
+ *
+ * @param namespace - the leading segment of a "namespace:reference:address" id
+ * @returns the matching descriptor, or undefined when the namespace is unknown
+ */
+const ecosystemByCaipNamespace = (namespace) => byNamespace.get(namespace);
+exports.ecosystemByCaipNamespace = ecosystemByCaipNamespace;
+/**
+ * Whether two addresses in the same ecosystem name the same thing.
+ *
+ * THE ONE PLACE THIS QUESTION IS ANSWERED. It was answered in two: this
+ * registry, which knows each family's address rules, and a ternary in the
+ * interface's routing module that hard-coded "Ethereum is case-insensitive,
+ * everything else is not". Two homes means a family added here is still
+ * compared wrongly there, silently, because a loose comparison does not fail —
+ * it merges two different accounts into one.
+ *
+ * @param a - an address
+ * @param b - an address, in the same ecosystem
+ * @param ecosystem - the ecosystem both belong to
+ * @returns whether they are the same address
+ */
+const sameAddress = (a, b, ecosystem) => (0, exports.ecosystemById)(ecosystem).addressCasing === 'insensitive'
+    ? a.toLowerCase() === b.toLowerCase()
+    : a === b;
+exports.sameAddress = sameAddress;
+/**
+ * Whether an address is the ecosystem's own native asset rather than a token.
+ *
+ * Every ecosystem already declares its `nativeAssetSentinel`, and this is the
+ * predicate that reads it. The comparison goes through {@link sameAddress}
+ * rather than `toLowerCase()`, which matters for exactly the families where the
+ * hand-written checks were wrong to begin with: Solana's, Bitcoin's and The
+ * Open Network's sentinels are case-significant, so lower-casing them before
+ * comparing can match an address that is not the sentinel.
+ *
+ * @param value - the address to test
+ * @param ecosystem - the ecosystem it belongs to
+ * @returns whether it names the native asset
+ */
+const isNativeAsset = (value, ecosystem) => (0, exports.sameAddress)(value, (0, exports.ecosystemById)(ecosystem).nativeAssetSentinel, ecosystem);
+exports.isNativeAsset = isNativeAsset;
+/**
+ * Whether a string is a well-formed address in this ecosystem.
+ *
+ * A free function over the registry, so a caller needs the ecosystem key and
+ * nothing else. Reaching for viem's `isAddress` directly is the thing this
+ * replaces: it answers only for Ethereum and answers FALSE — confidently — for
+ * every valid Solana, Bitcoin, Tron and Open Network address.
+ *
+ * @param value - the string to test
+ * @param ecosystem - the ecosystem to test it against
+ * @returns whether the string is a valid address there
+ */
+const isValidAddressIn = (value, ecosystem) => (0, exports.ecosystemById)(ecosystem).isValidAddress(value);
+exports.isValidAddressIn = isValidAddressIn;
+/**
+ * The ecosystem's canonical spelling of an address.
+ *
+ * Total and side-effect-free: an input this ecosystem cannot parse comes back
+ * unchanged rather than throwing, because normalizing is something callers do
+ * on the way to a comparison and a throw there would be a crash on a typo.
+ *
+ * @param value - the address to normalize
+ * @param ecosystem - the ecosystem it belongs to
+ * @returns the canonical form, or the input when it cannot be parsed
+ */
+const normalizeAddressIn = (value, ecosystem) => (0, exports.ecosystemById)(ecosystem).normalizeAddress(value);
+exports.normalizeAddressIn = normalizeAddressIn;

package/dist/cjs/execution.d.ts

@@ -0,0 +1,346 @@
+import { type Hex, type PublicClient } from 'viem';
+import type { TokenBridgeInfo } from './chain-info.js';
+import { type AggregatorOriginRefusal, type ConsolidatedQuote, type ConsolidatedQuoteRequest } from './consolidated-quote.js';
+import type { FeeType } from './fee-type.js';
+import type { RouteCandidate } from './routing/candidate.js';
+import type { HopEdge, PlannedHop } from './routing/search/graph.js';
+import type { ResolveNodeToken } from './routing/search/plan-route-data.js';
+import type { BridgeKey, Token } from './types.js';
+/**
+ * EXECUTION PLANS. Turns a chosen route into the ordered list of transactions
+ * a wallet sends, one {@link PlannedTx} at a time.
+ *
+ * Every builder here is the one the interface already signs with: the
+ * omnibridge call is `settings.ts`'s `transactionInputs`, the PulseX swap and
+ * the wrap are `routing/swap-transactions.ts`, the aggregator deposit is
+ * `consolidated-quote.ts`'s `aggregatorOriginCalls`, and the approval is
+ * `settings.ts`'s `approveCall` sized by `approvalAmounts`. This module only
+ * orders them and decides which approvals to skip.
+ *
+ * EVERY SPENDER IS ONE THIS CODE ALREADY KNOWS. Approvals are for the exact
+ * amount spent, never unlimited, and go only to:
+ * - the omnibridge pathway's `from` mediator, read from `config.ts`;
+ * - the PulseX router the edge was quoted on, read from `config.ts`;
+ * - an aggregator spender that `aggregatorOriginCalls` checked against a
+ *   fixed table for its provider and chain (LI.FI's Diamond, Relay's
+ *   depository). A quote cannot name its own spender.
+ *
+ * A PLAN IS ORDERED, AND EACH STEP WAITS FOR THE ONE BEFORE IT. An approval
+ * must land before the call that spends it, and a later section spends what
+ * the earlier one delivered. So every transaction except the last carries
+ * `waitForReceipt: true`.
+ *
+ * A RECEIPT IS NOT ARRIVAL. When a later section starts on a different chain
+ * than the one before it ends on, the earlier receipt only says the crossing
+ * started. The wallet must also wait for the funds to arrive on the next
+ * chain (the bridge indexer's delivery status) before it sends that section.
+ */
+/** What one planned transaction does. */
+export type PlannedTxKind = 'approve' | 'bridge' | 'swap' | 'wrap' | 'unwrap' | 'claim';
+/** One transaction for the wallet to sign and send, in plan order. */
+export type PlannedTx = {
+    readonly chainId: number;
+    readonly kind: PlannedTxKind;
+    readonly to: Hex;
+    readonly data: Hex;
+    readonly value: bigint;
+    /** The gas limit the quote names, or null to let the wallet estimate it. */
+    readonly gasLimit: bigint | null;
+    /** True when the next transaction depends on this one, so the wallet must wait for its receipt first. */
+    readonly waitForReceipt: boolean;
+};
+/**
+ * Reads an ERC-20 allowance on chain.
+ *
+ * @param chainId - the chain the token lives on
+ * @param token - the token
+ * @param owner - the account that sends the plan
+ * @param spender - the contract that pulls the token
+ * @returns the current allowance, in the token's base units
+ */
+export type AllowanceReader = (chainId: number, token: Hex, owner: Hex, spender: Hex) => Promise<bigint>;
+/**
+ * An {@link AllowanceReader} that reports no allowance anywhere, so the plan
+ * includes every approval. For a caller that reads allowances itself at send
+ * time.
+ */
+export declare const assumeNoAllowance: AllowanceReader;
+/**
+ * The delivery fee terms, quoted before the plan is built. They become the
+ * on-chain fee director, so the reader sees exactly what the router may take.
+ */
+export type QuotedDeliveryFee = {
+    readonly feeType: FeeType;
+    /**
+     * The most the delivery router may take, in base units of {@link assetOut}.
+     * It is the fee director's `limit` in every mode: the fixed fee, the gas
+     * cap, or the percent fee's own cap.
+     */
+    readonly maximumFee: bigint;
+    /** The percent rate as a fraction of one ether (5e14 is 0.05%). Read in percent mode only. */
+    readonly percentFee: bigint;
+    /** The tip over the gas cost as a fraction of one ether. Read in gas mode only. */
+    readonly gasTipFee: bigint;
+    /** The native-coin price in the delivered token, as `priceCorrective` reads it in `settings.ts`. */
+    readonly priceCorrective: bigint;
+    /** The token the destination router delivers and takes its fee in. */
+    readonly assetOut: Token;
+};
+/**
+ * Whether the reader buys delivery, and at what fee. There is no default: the
+ * caller states it.
+ *
+ * Only a pathway whose `requiresDelivery` is true sells delivery (PulseChain
+ * to Ethereum or BNB Smart Chain). On the way home to PulseChain the bridge
+ * itself delivers, so the only accepted choice there is `shouldDeliver: false`.
+ */
+export type DeliveryChoice = {
+    readonly shouldDeliver: false;
+} | {
+    readonly shouldDeliver: true;
+    readonly fee: QuotedDeliveryFee;
+};
+/** A direct omnibridge crossing: `relayTokens`, `relayTokensAndCall`, `wrapAndRelayTokens` or `transferAndCall`. */
+export type OmnibridgeLeg = {
+    readonly kind: 'omnibridge';
+    readonly bridgeKey: BridgeKey;
+    /** True reads only the mainnet pathways; false also reads the testnet ones. */
+    readonly isProd: boolean;
+    readonly assetIn: Token;
+    readonly assetLink: TokenBridgeInfo;
+    readonly amountIn: bigint;
+    readonly recipient: Hex;
+    readonly delivery: DeliveryChoice;
+    /** Whether the crossing unwraps to the native coin on arrival. Pass the value the pair allows, not only the reader's wish. */
+    readonly unwrap: boolean;
+};
+/** A PulseX swap, signed along the path its hop was priced on. */
+export type PulseXSwapLeg = {
+    readonly kind: 'pulsex-swap';
+    readonly hop: Pick<PlannedHop, 'edge' | 'outcome'>;
+    readonly amountIn: bigint;
+    readonly minAmountOut: bigint;
+    readonly recipient: Hex;
+    /** The unix-seconds deadline the router enforces. */
+    readonly deadline: bigint;
+};
+/** A native-coin wrap or unwrap on the wrapped token's own contract. */
+export type WrapLeg = {
+    readonly kind: 'wrap';
+    readonly edge: HopEdge;
+    readonly amountIn: bigint;
+};
+/** An aggregator's origin deposit, from a LIVE quote asked for the reader's own wallet. */
+export type AggregatorLeg = {
+    readonly kind: 'aggregator';
+    readonly quote: ConsolidatedQuote;
+    readonly request: ConsolidatedQuoteRequest;
+};
+/** One signature's worth of work, in concrete terms. */
+export type ExecutionLeg = OmnibridgeLeg | PulseXSwapLeg | WrapLeg | AggregatorLeg;
+/** Why a leg or a section cannot be planned. */
+export type ExecutionRefusal = {
+    readonly reason: 'amount-not-positive';
+} | {
+    readonly reason: 'no-pathway';
+} | {
+    readonly reason: 'delivery-not-offered';
+} | {
+    readonly reason: 'delivery-fee-missing';
+} | {
+    readonly reason: 'delivery-fee-unencodable';
+} | {
+    readonly reason: 'bridge-call-refused';
+} | {
+    readonly reason: 'swap-refused';
+} | {
+    readonly reason: 'swap-estimate-only';
+} | {
+    readonly reason: 'swap-quote-not-positive';
+} | {
+    readonly reason: 'wrap-refused';
+} | {
+    readonly reason: 'aggregator-origin-refused';
+    readonly origin: AggregatorOriginRefusal;
+} | {
+    readonly reason: 'live-quote-required';
+} | {
+    readonly reason: 'quote-provider-mismatch';
+    readonly quoteProvider: string;
+    readonly sectionCarrier: string;
+} | {
+    readonly reason: 'paid-by-hand';
+} | {
+    readonly reason: 'section-inputs-missing';
+    readonly needs: 'omnibridge' | 'swap';
+} | {
+    readonly reason: 'section-shape';
+    readonly detail: string;
+};
+/** The delivery one omnibridge leg buys. */
+export type DeliveryTerms = {
+    readonly status: 'not-requested';
+} | {
+    readonly status: 'requested';
+    readonly feeType: FeeType;
+    /** The most the router may take, in base units of {@link feeToken}. */
+    readonly maximumFee: bigint;
+    readonly feeToken: Token;
+};
+/** The delivery a planned leg buys, so the wallet can show the fee before signing. */
+export type PlannedDelivery = DeliveryTerms & {
+    readonly legIndex: number;
+};
+/** The transactions for a list of legs, or the first leg that cannot be planned. */
+export type ExecutionPlan = {
+    readonly kind: 'planned';
+    readonly transactions: readonly PlannedTx[];
+    /** One entry per omnibridge leg, in leg order. */
+    readonly deliveries: readonly PlannedDelivery[];
+} | {
+    readonly kind: 'refused';
+    readonly legIndex: number;
+    readonly refusal: ExecutionRefusal;
+};
+/**
+ * Plans the transactions for a list of legs, in order.
+ *
+ * Each leg contributes the exact approval it needs when the allowance on
+ * chain does not cover it (a reset to zero first when a smaller allowance
+ * remains), then its own call. Nothing is sent.
+ *
+ * @param options.account - the account that signs every transaction
+ * @param options.legs - the legs, in the order the wallet signs them
+ * @param options.readAllowance - reads an allowance on chain; see {@link AllowanceReader}
+ * @returns the ordered transactions, or the first leg that cannot be planned
+ */
+export declare const planExecution: ({ account, legs, readAllowance, }: {
+    readonly account: Hex;
+    readonly legs: readonly ExecutionLeg[];
+    readonly readAllowance: AllowanceReader;
+}) => Promise<ExecutionPlan>;
+/**
+ * What the caller supplies for one signature section of a candidate. Each
+ * kind-specific group is read only when the section needs it.
+ */
+export type SectionExecutionInputs = {
+    /** The amount this section spends, in its first token's base units. */
+    readonly amountIn: bigint;
+    /** Where this section delivers: the reader's own wallet, or their chosen address on the last section. */
+    readonly recipient: Hex;
+    /** Needed by an omnibridge section. */
+    readonly omnibridge?: {
+        readonly isProd: boolean;
+        readonly assetLink: TokenBridgeInfo;
+        readonly delivery: DeliveryChoice;
+        readonly unwrap: boolean;
+    };
+    /** Needed by a PulseX swap section. */
+    readonly swap?: {
+        readonly slippageBasisPoints: bigint;
+        /**
+         * The unix-seconds deadline the router enforces. A section planned late
+         * should pass a fresh deadline, not one chosen before the crossing before it.
+         */
+        readonly deadline: bigint;
+        /**
+         * A fresh quote of what the swap delivers for this section's `amountIn`,
+         * read just before signing (see {@link readPulseXSectionQuote}). When
+         * given, the slippage floor comes from it and not from the hop's
+         * search-time figure, so the hop may be an estimate. When absent, the
+         * floor comes from the hop, which must hold a real quote.
+         */
+        readonly quotedAmountOut?: bigint;
+    };
+    /**
+     * Needed by an aggregator section: the LIVE quote asked for this reader's
+     * wallet, recipient and amount, with the request it answered. A route's
+     * display price is a dry probe and cannot be signed, so the candidate's own
+     * quote is never used in its place.
+     */
+    readonly aggregator?: {
+        readonly quote: ConsolidatedQuote;
+        readonly request: ConsolidatedQuoteRequest;
+    };
+};
+/** What {@link planCandidateExecution} reads. */
+export type CandidateExecutionInputs = {
+    readonly candidate: RouteCandidate;
+    readonly account: Hex;
+    readonly readAllowance: AllowanceReader;
+    /** The resolver the candidate was built with; turns a plan's graph node into its token. */
+    readonly resolveToken: ResolveNodeToken;
+    /**
+     * The index of the section that `sections[0]` plans. It defaults to 0.
+     * Pass it to plan a later section after the earlier ones landed, with the
+     * amount that actually arrived and fresh swap figures. Then `sections[i]`
+     * plans section `firstSectionIndex + i`.
+     */
+    readonly firstSectionIndex?: number;
+    /**
+     * One entry per section to plan now, first section first. Pass one entry
+     * to plan only the signature the reader can make now; pass more to plan
+     * later sections whose amounts are already known.
+     */
+    readonly sections: readonly SectionExecutionInputs[];
+};
+/**
+ * The transactions for the planned sections of a candidate, or the first
+ * section that cannot be planned. Every section index is absolute: it counts
+ * from the first section of the candidate, not from `firstSectionIndex`.
+ */
+export type CandidateExecutionPlan = {
+    readonly kind: 'planned';
+    readonly transactions: readonly PlannedTx[];
+    /** One entry per omnibridge section planned; `legIndex` is the absolute section index. */
+    readonly deliveries: readonly PlannedDelivery[];
+    /** How many sections still follow the planned ones (after `firstSectionIndex + sections.length`). Each needs its own plan later. */
+    readonly remainingSectionCount: number;
+} | {
+    readonly kind: 'refused';
+    readonly sectionIndex: number;
+    readonly refusal: ExecutionRefusal;
+};
+/**
+ * Plans the transactions for a chosen route candidate: the candidate
+ * `buildRouteCandidateFromPlan` returns for an engine plan (the interface's
+ * `buildCandidateFromEnginePlan`), or a candidate built without a plan.
+ *
+ * ONE SECTION IS ONE SIGNATURE. A plan's `signatures` groups its hops into
+ * sections; the section's first hop names its carrier. An omnibridge section
+ * becomes a crossing, a PulseX section a swap signed on its recorded path, a
+ * wrap section a wrap or unwrap, and any other wallet-signed carrier an
+ * aggregator deposit from the live quote the caller supplies. A section paid
+ * by hand has nothing to sign and is refused.
+ *
+ * A LATER SECTION CAN BE PLANNED ALONE. Pass `firstSectionIndex` to skip the
+ * sections that already landed. The wallet then plans the swap after the
+ * crossing arrived, from the amount that arrived, with a fresh
+ * `swap.quotedAmountOut` and a fresh `swap.deadline`. The slippage floor and the
+ * deadline are not fixed minutes before the swap is signed. Every safety check
+ * still applies to the later section: verified spenders, live quotes for
+ * aggregator sections, exact approvals.
+ *
+ * Every `sectionIndex` in a refusal and every `legIndex` in `deliveries` is
+ * the absolute section index.
+ *
+ * @param inputs - see {@link CandidateExecutionInputs}
+ * @returns the ordered transactions with the deliveries they buy, or the first section that cannot be planned
+ */
+export declare const planCandidateExecution: (inputs: CandidateExecutionInputs) => Promise<CandidateExecutionPlan>;
+/**
+ * Reads a fresh quote for a PulseX section: what the router's `getAmountsOut`
+ * says the swap delivers for `amountIn`, along the exact path the swap signs
+ * ({@link pulseXSwapPathForHop}) on the edge's own router. A wallet passes the
+ * result as `swap.quotedAmountOut` just before it signs.
+ *
+ * @param options.hop - the swap hop; its recorded path and edge name what to read
+ * @param options.amountIn - the amount the swap spends, in base units
+ * @param options.client - a client that can call `readContract`
+ * @returns the amount the last token of the path delivers, or null when the hop records no path, names no known router, the amount is not positive, or the read fails or returns nothing
+ */
+export declare const readPulseXSectionQuote: ({ hop, amountIn, client, }: {
+    readonly hop: Pick<PlannedHop, "edge" | "outcome">;
+    readonly amountIn: bigint;
+    readonly client: Pick<PublicClient, "readContract">;
+}) => Promise<bigint | null>;