@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/destination-calldata.d.ts

@@ -0,0 +1,118 @@
+import { type Hex } from 'viem';
+import type { TokenBridgeInfo } from './chain-info.js';
+import type { Pathway } from './config.js';
+import type { Token } from './types.js';
+/**
+ * The shape of a call an external executor (an aggregator's destination-chain
+ * contract, e.g. LI.FI's executor or Relay's solver) must perform to push
+ * bridged funds into the omnibridge toward the home chain.
+ */
+export type DestinationCall = {
+    /** Contract the executor calls (mediator, native router, or the token itself) */
+    to: Hex;
+    /** Native value to attach to the call (non-zero only for native-asset entry) */
+    value: bigint;
+    /** Encoded calldata for the call */
+    data: Hex;
+    /**
+     * Contract that must hold an ERC20 approval from the executor before the
+     * call, or null when no approval is needed (native value transfers and
+     * ERC677 transferAndCall, which moves tokens itself)
+     */
+    approvalTarget: Hex | null;
+    /**
+     * The mediator that validates the amount and emits the bridge message.
+     *
+     * NOT THE SAME AS `to`, and that is the point. `to` is whatever the executor
+     * calls — the mediator for an ordinary token, the router for a native asset,
+     * the token itself for an ERC677 transfer — but all three funnel into this
+     * one contract, and this is the contract whose limits decide whether the
+     * transfer happens at all. Proved by experiment on a fork: raising its
+     * `minPerTx` alone, with the far side untouched, reverts the entry call.
+     */
+    entryMediator: Hex;
+    /**
+     * The address the mediator keys its per-token limits by.
+     *
+     * For a native asset this is the WRAPPED address, because the router wraps
+     * before the mediator sees anything. Reading limits under the zero address
+     * instead returns the mediator's fallback default, which is a real number
+     * for a different question.
+     */
+    entryTokenAddress: Hex;
+    /** Conservative gas budget for executing the call on the destination chain */
+    gasLimit: bigint;
+};
+/**
+ * Conservative per-shape gas budgets for omnibridge entry calls executed by an
+ * aggregator on the destination chain. An undershoot reverts the executor's
+ * call and strands funds at the aggregator's fallback address, so these err
+ * high; the aggregator prices unused gas into the quote rather than burning it.
+ *
+ * MEASURED against the deployed mediators on a fork of Ethereum mainnet,
+ * 2026-08-31, by `destination-calldata.fork.test.ts`:
+ *
+ *   relayTokens         195,967   USD Coin, an ordinary registered token
+ *   wrapAndRelayTokens  200,347   native ether through the router
+ *   transferAndCall     187,000   wrapped Pulse, a bridged representation home
+ *                                 to 204,000, depending on the fork block
+ *
+ * The figures move with block state — whether a storage slot the call touches
+ * is already warm — so treat them as a band, not a constant. The spread
+ * measured across two blocks minutes apart was about nine percent.
+ *
+ * THE BUDGET STAYS AT 400,000, and the headroom is deliberate. Every figure
+ * above is a token the bridge has carried before. The first crossing of a
+ * token the mediator has not seen writes its limits as well, and a token with
+ * a transfer hook costs more again — neither is measured here, and both fail
+ * by stranding the user's funds rather than by costing us a little gas. The
+ * fork test asserts each shape stays under the budget, so a regression that
+ * eats the headroom fails a test rather than a transfer.
+ */
+export declare const destinationGasLimits: {
+    readonly relayTokens: 400000n;
+    readonly transferAndCall: 400000n;
+    readonly wrapAndRelayTokens: 400000n;
+};
+/**
+ * Builds the call an aggregator's executor must perform on the bridge's
+ * foreign chain (e.g. Ethereum) to relay just-bridged funds onward through the
+ * omnibridge to the recipient on the home chain (e.g. PulseChain).
+ *
+ * This is the second leg of a consolidated route: the aggregator bridges the
+ * user's funds to the foreign chain with a guaranteed minimum amount, then its
+ * executor performs this call. Because the executor — not the user — is the
+ * caller, the result always encodes the fixed `amount` and names the user as
+ * `recipient`; delivery-fee encoding never applies (home-chain gas handout is
+ * a separate automatic system).
+ *
+ * @param pathway - the bridge pathway whose foreign side the executor enters
+ * @param assetIn - the foreign-chain token the aggregator delivers (zero address for native)
+ * @param recipient - the user's address on the home chain
+ * @param sender - the user's address, threaded through pathways that take an extra sender param
+ * @param assetLink - the asset link for the token, used to detect bridged representations
+ * @param amount - the exact token amount the executor will relay
+ * @returns the destination call, or null when the inputs cannot form a valid call
+ */
+export declare const buildDestinationCalldata: ({ pathway, assetIn, recipient, sender, assetLink, amount, unwrap, }: {
+    pathway: Pathway | null;
+    assetIn: Token | null;
+    recipient: Hex | null;
+    sender: Hex | null;
+    assetLink: TokenBridgeInfo | null;
+    amount: bigint;
+    /**
+     * Deliver the chain's own coin rather than its wrapped token.
+     *
+     * ONLY ONE INPUT PER PATHWAY CAN DO THIS: the pathway's own
+     * `bridgedNativeAssetOut`, which is the wrapped native asset of the chain the
+     * funds are heading TO, held on the chain they leave from. Wrapped Pulse on
+     * Ethereum is the case that matters here — it arrives as wrapped Pulse on
+     * PulseChain, and the destination router turns that into native Pulse.
+     *
+     * Asked for on any other token it is IGNORED rather than obeyed, because the
+     * bridge would ignore it too and a call built as though it would not is a
+     * call that does something different from what the caller believes.
+     */
+    unwrap?: boolean;
+}) => DestinationCall | null;

package/dist/destination-calldata.js

@@ -0,0 +1,152 @@
+import { getAddress } from 'viem';
+import { destinationDataParam, interactingWithBridgeToken, transactionInputs, } from './settings.js';
+/**
+ * Conservative per-shape gas budgets for omnibridge entry calls executed by an
+ * aggregator on the destination chain. An undershoot reverts the executor's
+ * call and strands funds at the aggregator's fallback address, so these err
+ * high; the aggregator prices unused gas into the quote rather than burning it.
+ *
+ * MEASURED against the deployed mediators on a fork of Ethereum mainnet,
+ * 2026-08-31, by `destination-calldata.fork.test.ts`:
+ *
+ *   relayTokens         195,967   USD Coin, an ordinary registered token
+ *   wrapAndRelayTokens  200,347   native ether through the router
+ *   transferAndCall     187,000   wrapped Pulse, a bridged representation home
+ *                                 to 204,000, depending on the fork block
+ *
+ * The figures move with block state — whether a storage slot the call touches
+ * is already warm — so treat them as a band, not a constant. The spread
+ * measured across two blocks minutes apart was about nine percent.
+ *
+ * THE BUDGET STAYS AT 400,000, and the headroom is deliberate. Every figure
+ * above is a token the bridge has carried before. The first crossing of a
+ * token the mediator has not seen writes its limits as well, and a token with
+ * a transfer hook costs more again — neither is measured here, and both fail
+ * by stranding the user's funds rather than by costing us a little gas. The
+ * fork test asserts each shape stays under the budget, so a regression that
+ * eats the headroom fails a test rather than a transfer.
+ */
+export const destinationGasLimits = {
+    relayTokens: 400000n,
+    transferAndCall: 400000n,
+    wrapAndRelayTokens: 400000n,
+};
+/**
+ * Builds the call an aggregator's executor must perform on the bridge's
+ * foreign chain (e.g. Ethereum) to relay just-bridged funds onward through the
+ * omnibridge to the recipient on the home chain (e.g. PulseChain).
+ *
+ * This is the second leg of a consolidated route: the aggregator bridges the
+ * user's funds to the foreign chain with a guaranteed minimum amount, then its
+ * executor performs this call. Because the executor — not the user — is the
+ * caller, the result always encodes the fixed `amount` and names the user as
+ * `recipient`; delivery-fee encoding never applies (home-chain gas handout is
+ * a separate automatic system).
+ *
+ * @param pathway - the bridge pathway whose foreign side the executor enters
+ * @param assetIn - the foreign-chain token the aggregator delivers (zero address for native)
+ * @param recipient - the user's address on the home chain
+ * @param sender - the user's address, threaded through pathways that take an extra sender param
+ * @param assetLink - the asset link for the token, used to detect bridged representations
+ * @param amount - the exact token amount the executor will relay
+ * @returns the destination call, or null when the inputs cannot form a valid call
+ */
+export const buildDestinationCalldata = ({ pathway, assetIn, recipient, sender, assetLink, amount, unwrap = false, }) => {
+    if (amount <= 0n) {
+        return null;
+    }
+    // `transactionInputs` rejects both of these too, but it cannot say so to the
+    // type checker, and the entry fields below are read straight off them. Asking
+    // first keeps the answer honest rather than asserted.
+    if (!pathway || !assetLink) {
+        return null;
+    }
+    // THE UNWRAP RIDES THE DATA PARAMETER, which is the same slot the recipient
+    // travels in. Naming the destination router there and the recipient after it
+    // tells the home mediator to hand the arriving tokens to the router, which
+    // unwraps them and forwards the coin on. `destinationDataParam` owns that
+    // encoding for the direct path already, so it owns it here too rather than
+    // being restated.
+    //
+    // The gate is the pathway's own bridged native asset. Anything else arrives
+    // wrapped whatever the caller asked for, so obeying the request would build a
+    // call that does something other than what the caller believes it does.
+    const unwrapOnArrival = unwrap &&
+        assetIn !== null &&
+        pathway.destinationRouter !== null &&
+        getAddress(assetIn.address) === getAddress(pathway.bridgedNativeAssetOut);
+    const destinationData = unwrapOnArrival
+        ? destinationDataParam({
+            recipient,
+            bridgePathway: pathway,
+            assetIn,
+            destinationRouter: pathway.destinationRouter,
+            feeDirectorStructEncoded: null,
+            assetLink,
+            shouldDeliver: false,
+            unwrap: true,
+        })
+        : recipient;
+    // Only reachable when the unwrap was asked for and could not be encoded.
+    // Falling back to a plain recipient would quietly deliver the wrapped token.
+    if (destinationData === null) {
+        return null;
+    }
+    const inputs = transactionInputs({
+        // NO READER COMPOSED THIS CALL, so there is no pair on screen for it to
+        // disagree with. An aggregator's executor performs it on the entry chain
+        // after the reader has already signed their own transaction, and the chain
+        // pair IS this pathway. See `crossingRefusal` for why the field is nullable
+        // rather than optional: every caller has to say which of the two it is.
+        bridgeKey: null,
+        signedCrossing: null,
+        bridgePathway: pathway,
+        assetIn,
+        recipient,
+        account: sender,
+        assetLink,
+        // for bridged tokens the data param rides transferAndCall and the
+        // mediator decodes it as the home-chain recipient
+        destinationDataParam: destinationData,
+        amountToBridge: amount,
+        feeDirectorStructEncoded: null,
+        shouldDeliver: false,
+    });
+    if (!inputs) {
+        return null;
+    }
+    const isNativeEntry = inputs.value > 0n;
+    const isBridgeTokenEntry = interactingWithBridgeToken({
+        assetLink,
+        assetInAddress: assetIn?.address ?? null,
+    });
+    // Both are the same for every shape: the pathway's own mediator, and the
+    // on-chain address the link resolved (already the wrapped one for a native
+    // asset, because `tokenBridgeInfo` substitutes it before looking anything up).
+    const entry = {
+        entryMediator: pathway.from,
+        entryTokenAddress: assetLink.assetInAddress,
+    };
+    if (isNativeEntry) {
+        return {
+            ...inputs,
+            ...entry,
+            approvalTarget: null,
+            gasLimit: destinationGasLimits.wrapAndRelayTokens,
+        };
+    }
+    if (isBridgeTokenEntry) {
+        return {
+            ...inputs,
+            ...entry,
+            approvalTarget: null,
+            gasLimit: destinationGasLimits.transferAndCall,
+        };
+    }
+    return {
+        ...inputs,
+        ...entry,
+        approvalTarget: inputs.to,
+        gasLimit: destinationGasLimits.relayTokens,
+    };
+};

package/dist/ecosystems.d.ts

@@ -0,0 +1,217 @@
+/**
+ * A source-chain virtual-machine family the bridge can originate a route from.
+ * This is deliberately the `id` of a descriptor in {@link ecosystemRegistry},
+ * not a hand-maintained parallel union: code that needs ecosystem behavior looks
+ * the record up instead of branching on the literal, so adding an ecosystem is
+ * one new descriptor and every reader keeps working.
+ *
+ * The identifiers match the `vmType` strings Relay reports at
+ * https://api.relay.link/chains, so a Relay chain record maps onto an ecosystem
+ * without a translation table.
+ *
+ * Quoting an origin is not the same as being able to SIGN one: the ecosystem
+ * registry is the library-side model, while the wallet adapter that produces a
+ * signature lives in the interface package. Every ecosystem listed here now has
+ * an adapter in this repository's interface, so the two are in step — but the
+ * distinction stands for whatever is added next, and an interface that lacks an
+ * adapter must still reject that origin rather than route it to a signer meant
+ * for another ecosystem.
+ *
+ * ONE IDENTIFIER HERE IS NOT A RELAY NAME, and that is deliberate rather than
+ * an oversight: `zcash`. Relay does not carry Zcash in any form, so there is no
+ * `vmType` string to match and inventing one shaped like the others would imply
+ * a mapping that does not exist. It is also the one family this interface can
+ * never SIGN for — see the note above, and `isDepositAddressChain` in
+ * `chain-names.ts`, which is the predicate a surface actually asks.
+ */
+export type Ecosystem = 'evm' | 'svm' | 'bvm' | 'tvm' | 'tonvm' | 'hypevm' | 'zcash';
+/**
+ * Whether anyone has carried a transfer through this ecosystem from end to
+ * end — connected a wallet, signed the deposit, watched the funds arrive — on
+ * a build a reader can reach.
+ *
+ * THIS IS A RECORD OF PROOF, NOT A SWITCH. Read the name literally: `pending`
+ * says the proof has not been obtained yet, and says nothing at all about
+ * whether the code works. Every ecosystem here is modelled, quoted and wired
+ * to a signer; several have unit tests over real fixtures. None of that is the
+ * same as one funded transfer completing, and this field records only the
+ * latter. So a `pending` ecosystem is a TEMPORARY HOLD on a public claim, and
+ * the way to clear it is to make the transfer and change the word — not to
+ * delete the descriptor, and not to write code around it.
+ *
+ * It exists because the landing page advertises where a transfer can start
+ * from, and an advertised origin that has never been proven is a promise the
+ * product has not earned.
+ *
+ * WHAT A `pending` ANSWER MAKES THE INTERFACE DO, and this is the part that was
+ * got wrong once and corrected by the owner: it QUALIFIES an entry, it does not
+ * remove one. A chain drawn quietly — a dashed edge, a desaturated mark, no
+ * caption — tells a reader the truth without a promise attached to it. A
+ * chain deleted from the list tells them it is not part of this product,
+ * which is a stronger claim than this field carries and a false one. The
+ * treatment used to spell the hold out in words ("not proven yet"), and the
+ * owner corrected that too: the state is now carried visually, plus
+ * `aria-disabled` for a reader who cannot see the desaturation, with no
+ * caption of its own. See `reelTokenProof` and `chainProof` in the interface
+ * — the reel and the chain chips — which turn this answer into a treatment
+ * rather than a filter.
+ *
+ * IT IS NOT THE ONLY REASON AN ORIGIN CAN BE ABSENT. Hyperliquid is `pending`
+ * here and still appears nowhere, because nothing can quote it: the interface's
+ * source picker never offers it, so there is no route to draw quietly. A gate on
+ * proof and a gate on reachability are different questions, and only this one
+ * belongs in this field.
+ */
+export type EndToEndProof = 'verified' | 'pending';
+/**
+ * Everything intrinsic to one ecosystem, in one record. Carries only
+ * framework-agnostic knowledge — nothing about the user interface, wallet
+ * adapters, or providers — so it can live in the library.
+ */
+export type EcosystemDescriptor = {
+    /** The stable key; equals the literal used everywhere else. */
+    id: Ecosystem;
+    /** Fully spelled-out display name. */
+    label: string;
+    /**
+     * The chain-agnostic identifier namespace (the leading segment of a
+     * "namespace:reference:address" identifier). Used to map a connected wallet
+     * identifier back to its ecosystem.
+     */
+    caipNamespace: string;
+    /**
+     * How this ecosystem expresses its native asset as an address string. Kept
+     * byte-equal to the values the Relay request builder currently sends.
+     */
+    nativeAssetSentinel: string;
+    /**
+     * Whether a transfer has been carried through this ecosystem end to end. See
+     * {@link EndToEndProof} — `pending` is a hold on a public claim, never a
+     * statement that the path is broken.
+     *
+     * Held HERE, beside the ecosystem it describes, so re-enabling one is a
+     * single word next to that ecosystem rather than a hunt for an exclusion
+     * list in a component.
+     */
+    endToEndProof: EndToEndProof;
+    /** Pure format check: does this look like a valid address in this ecosystem? */
+    isValidAddress: (value: string) => boolean;
+    /**
+     * Pure normalization to the ecosystem's canonical form. Ethereum applies the
+     * checksum; the already-case-significant encodings are identity.
+     */
+    normalizeAddress: (value: string) => string;
+    /**
+     * Whether two addresses in this ecosystem may differ in case and still be the
+     * same address.
+     *
+     * A FIELD RATHER THAN A BRANCH SOMEWHERE ELSE, and that is the whole point of
+     * it. This rule lived as `ecosystem === 'evm' ? lowercase both : compare
+     * exactly` inside the interface, which is a second place that has to learn
+     * about every family added here — and the least likely place anyone would
+     * think to look. Adding a family is now one entry in this registry.
+     *
+     * `insensitive` is Ethereum's: the checksum is carried in the case, so two
+     * spellings of one address are the same address. `significant` is everyone
+     * else's: base58 and base64url alphabets use case to carry information, so
+     * two addresses can differ by case alone and comparing them loosely would
+     * merge two different accounts.
+     */
+    addressCasing: 'insensitive' | '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.
+ */
+export declare const ecosystemRegistry: readonly EcosystemDescriptor[];
+/**
+ * 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`
+ */
+export declare const ecosystemById: (id: Ecosystem) => EcosystemDescriptor;
+/**
+ * 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
+ */
+export declare const isEcosystemProvenEndToEnd: (id: Ecosystem) => boolean;
+/**
+ * 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
+ */
+export declare const ecosystemByCaipNamespace: (namespace: string) => EcosystemDescriptor | undefined;
+/**
+ * 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
+ */
+export declare const sameAddress: (a: string, b: string, ecosystem: Ecosystem) => boolean;
+/**
+ * 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
+ */
+export declare const isNativeAsset: (value: string, ecosystem: Ecosystem) => boolean;
+/**
+ * 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
+ */
+export declare const isValidAddressIn: (value: string, ecosystem: Ecosystem) => boolean;
+/**
+ * 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
+ */
+export declare const normalizeAddressIn: (value: string, ecosystem: Ecosystem) => string;