@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/execution.d.ts

@@ -0,0 +1,359 @@
+import { type Hex, type PublicClient } from 'viem';
+import type { TokenBridgeInfo } from './chain-info.js';
+import { type SwapVenues } from './swap-venues.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 swap router the edge was quoted on, found in the swap venues (the defaults in `config.ts` unless the caller passes its own);
+ * - 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}
+ * @param options.swapVenues - the routers swaps may sign on, merged over the defaults; a swap whose router is in none of them throws
+ * @returns the ordered transactions, or the first leg that cannot be planned
+ * @throws when a swap leg's router is not in the swap venues
+ */
+export declare const planExecution: ({ account, legs, readAllowance, swapVenues, }: {
+    readonly account: Hex;
+    readonly legs: readonly ExecutionLeg[];
+    readonly readAllowance: AllowanceReader;
+    readonly swapVenues?: SwapVenues;
+}) => 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 routers swaps may sign on, merged over the defaults: a chain named
+     * here replaces that chain's default list. Pass the SAME venues the route
+     * search used. A swap whose router is in none of them throws.
+     */
+    readonly swapVenues?: SwapVenues;
+    /**
+     * 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`
+ * @param options.swapVenues - the routers swaps may sign on, merged over the defaults
+ * @returns the amount the last token of the path delivers, or null when the hop records no path, the amount is not positive, or the read fails or returns nothing
+ * @throws when the hop records a path but its router is not in the swap venues
+ */
+export declare const readPulseXSectionQuote: ({ hop, amountIn, client, swapVenues, }: {
+    readonly hop: Pick<PlannedHop, "edge" | "outcome">;
+    readonly amountIn: bigint;
+    readonly client: Pick<PublicClient, "readContract">;
+    readonly swapVenues?: SwapVenues;
+}) => Promise<bigint | null>;