@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/cjs/claims.d.ts

@@ -0,0 +1,198 @@
+import { type Hex } from 'viem';
+import type { PlannedTx } from './execution.js';
+/**
+ * MANUAL CLAIMS. A home-to-foreign crossing (PulseChain to Ethereum, for
+ * example) ends with a release on the destination chain. When nobody delivers
+ * it, the reader claims it by hand: they send the validators' signatures and
+ * the encoded message to the destination bridge. This module builds that
+ * transaction from the bridge indexer's `UserRequest` record.
+ *
+ * THE INDEXER ASSUMPTION. The indexer collects the signatures in
+ * `handleSignedFor` (`packages/indexer/src/index.ts`, the handler for
+ * `HomeAMB:SignedForUserRequest` and `HomeAMB:SignedForAffirmation`). It does
+ * not read the signature from the event. It decodes the TRANSACTION's own
+ * input as `submitSignature(bytes signature, bytes message)`. That works only
+ * when a validator sends `submitSignature` straight to the home bridge from
+ * its own account.
+ *
+ * When a validator signs some other way (through a multisig wallet, a proxy,
+ * a batching contract, or any call whose top-level input is not
+ * `submitSignature`), the decode fails and the handler drops that signature.
+ * It still counts it: `confirmedSignatures` goes up by one, but `signatures`
+ * stays one short. `finishedSigning` does NOT stay false. The separate
+ * `HomeAMB:CollectedSignatures` event sets it to true regardless. So the
+ * record says "signed" while it holds too few signatures, and a claim built
+ * from it reverts on the destination bridge, which checks the count against
+ * its required-signature threshold. {@link buildClaimTransaction} refuses
+ * that record with `signatures-incomplete` rather than build a claim that
+ * cannot succeed.
+ */
+/** A signature split into the three parts the destination bridge reads, each as hex without a `0x` prefix. */
+export type SignatureParts = {
+    readonly v: string;
+    readonly r: string;
+    readonly s: string;
+};
+/**
+ * Splits one 65-byte validator signature into its `v`, `r` and `s` parts.
+ *
+ * @param rawSignature - the signature as the indexer stores it, with or without a `0x` prefix
+ * @returns the three parts, hex without prefixes
+ */
+export declare const signatureToVRS: (rawSignature: string) => SignatureParts;
+/**
+ * Packs signatures in the layout the bridge's `executeSignatures` reads: one
+ * count byte, then every `v`, then every `r`, then every `s`.
+ *
+ * @param signatures - the split signatures, in the order the validators signed
+ * @returns the packed signatures as one hex string
+ */
+export declare const packSignatures: (signatures: readonly SignatureParts[]) => Hex;
+/**
+ * The calldata for a release that pays no delivery tip: a direct call to the
+ * destination bridge.
+ *
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for `safeExecuteSignaturesWithAutoGasLimit`
+ */
+export declare const encodeReleaseWithoutTipData: ({ encodedData, encodedSignatures, }: {
+    encodedData: Hex;
+    encodedSignatures: Hex;
+}) => Hex;
+/**
+ * The calldata for a release sent through the pathway's destination output
+ * router, the path a fee-director (delivery) request uses.
+ *
+ * @param options.validator - the pathway's validator contract
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for the router's `safeExecuteSignaturesWithAutoGasLimit`
+ */
+export declare const encodeReleaseToRouterData: ({ validator, encodedData, encodedSignatures, }: {
+    validator: Hex;
+    encodedData: Hex;
+    encodedSignatures: Hex;
+}) => Hex;
+/**
+ * Where a claim is sent.
+ *
+ * - `direct` sends it to the destination bridge and pays no delivery tip.
+ * - `router` sends it through the pathway's destination output router, which
+ *   pays the tip a fee-director request carries. Read both addresses from the
+ *   pathway (`pathway(bridgeKey)`'s `destinationRouter` and `validator`).
+ */
+export type ClaimRoute = {
+    readonly kind: 'direct';
+} | {
+    readonly kind: 'router';
+    readonly destinationRouter: Hex;
+    readonly validator: Hex;
+};
+/**
+ * The one place a claim's target and calldata come from. The interface's
+ * release hook and {@link buildClaimTransaction} both call it.
+ *
+ * @param options.encodedData - the bridge message
+ * @param options.signatures - the raw validator signatures, in signing order
+ * @param options.destinationAmbAddress - the destination bridge, used by the `direct` route
+ * @param options.via - which contract receives the claim
+ * @returns the target contract and the calldata
+ */
+export declare const claimCall: ({ encodedData, signatures, destinationAmbAddress, via, }: {
+    readonly encodedData: Hex;
+    readonly signatures: readonly string[];
+    readonly destinationAmbAddress: Hex;
+    readonly via: ClaimRoute;
+}) => {
+    readonly to: Hex;
+    readonly data: Hex;
+};
+/**
+ * The bridge indexer's `UserRequest` fields a claim reads. The names match the
+ * indexer's GraphQL type, so a caller passes the record it fetched as it is.
+ * The indexer sends its big-integer scalars as decimal strings, so the counts
+ * and the chain id accept a string as well.
+ */
+export type ClaimableUserRequest = {
+    /** `'signature'` for a home-to-foreign request. Only those are claimed by hand. */
+    readonly type: string;
+    readonly encodedData: string;
+    /** The JSON list of raw validator signatures, or null on a request type that collects none. */
+    readonly signatures?: unknown;
+    /** How many `SignedFor` events the indexer counted for this request. */
+    readonly confirmedSignatures: bigint | number | string;
+    /**
+     * The bridge's required-signature threshold in force for this request, as
+     * the indexer links it. When absent, the builder demands every counted
+     * signature, which is stricter than the bridge.
+     */
+    readonly requiredSignatures?: {
+        readonly value: bigint | number | string;
+    } | null;
+    readonly destinationAmbAddress: string;
+    readonly destinationChainId: bigint | number | string;
+    /** True once the indexer saw `CollectedSignatures` (or the delivery itself). */
+    readonly finishedSigning: boolean;
+    /** True once the release executed on the destination chain. */
+    readonly delivered: boolean;
+};
+/**
+ * Why a request cannot be claimed. Each case names a different action for the
+ * reader:
+ *
+ * - `wrong-type` — not a signature request. An affirmation request is
+ *   executed by the validators themselves; there is nothing to claim.
+ * - `already-delivered` — the release already executed. A claim would revert.
+ * - `not-signed-yet` — the validators have not finished signing. Wait.
+ * - `signatures-incomplete` — the indexer stored fewer signatures than the
+ *   bridge needs (the threshold, or every counted signature when the request
+ *   carries no threshold). See this module's note on the `submitSignature`
+ *   assumption. Waiting does not fix this one.
+ * - `malformed-request` — a field is not the shape the indexer documents.
+ */
+export type ClaimRefusal = {
+    readonly reason: 'wrong-type';
+    readonly type: string;
+} | {
+    readonly reason: 'already-delivered';
+} | {
+    readonly reason: 'not-signed-yet';
+} | {
+    readonly reason: 'signatures-incomplete';
+    readonly stored: number;
+    readonly needed: number;
+} | {
+    readonly reason: 'malformed-request';
+    readonly field: string;
+};
+/** A claim transaction, or the typed reason none can be built. */
+export type ClaimPlan = {
+    readonly kind: 'claim';
+    readonly transaction: PlannedTx;
+} | {
+    readonly kind: 'refused';
+    readonly refusal: ClaimRefusal;
+};
+/**
+ * Builds the manual-claim transaction for one bridge request, or refuses with
+ * a typed reason.
+ *
+ * The checks run in this order: request type, delivery, signing, then the
+ * stored signature count. A delivered request is refused before the signing
+ * check, because delivery also sets `finishedSigning`.
+ *
+ * ASSUMPTION: the signatures are only complete when every validator sent
+ * `submitSignature` directly to the home bridge. The indexer drops a
+ * signature sent any other way; see this module's head note. This builder
+ * catches the drop by comparing the stored list with the required-signature
+ * threshold, or with `confirmedSignatures` when the record carries no threshold.
+ *
+ * @param options.request - the indexer's `UserRequest` record
+ * @param options.via - the claim target; see {@link ClaimRoute}
+ * @returns a `claim` plan whose transaction runs on the destination chain, or a refusal
+ */
+export declare const buildClaimTransaction: ({ request, via, }: {
+    readonly request: ClaimableUserRequest;
+    readonly via: ClaimRoute;
+}) => ClaimPlan;

package/dist/cjs/claims.js

@@ -0,0 +1,182 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildClaimTransaction = exports.claimCall = exports.encodeReleaseToRouterData = exports.encodeReleaseWithoutTipData = exports.packSignatures = exports.signatureToVRS = void 0;
+const viem_1 = require("viem");
+const abis = __importStar(require("./abis.js"));
+const strip0x = (input) => input.replace(/^0x/, '');
+/**
+ * Splits one 65-byte validator signature into its `v`, `r` and `s` parts.
+ *
+ * @param rawSignature - the signature as the indexer stores it, with or without a `0x` prefix
+ * @returns the three parts, hex without prefixes
+ */
+const signatureToVRS = (rawSignature) => {
+    const signature = strip0x(rawSignature);
+    const word = 32;
+    const word2 = word * 2;
+    const word4 = word2 * 2;
+    const r = signature.slice(0, word2);
+    const s = signature.slice(word2, word4);
+    const v = signature.slice(word4);
+    return { v, r, s };
+};
+exports.signatureToVRS = signatureToVRS;
+/**
+ * Packs signatures in the layout the bridge's `executeSignatures` reads: one
+ * count byte, then every `v`, then every `r`, then every `s`.
+ *
+ * @param signatures - the split signatures, in the order the validators signed
+ * @returns the packed signatures as one hex string
+ */
+const packSignatures = (signatures) => {
+    const length = strip0x((0, viem_1.numberToHex)(signatures.length));
+    const countByte = length.length === 1 ? `0${length}` : length;
+    const v = signatures.map((signature) => signature.v).join('');
+    const r = signatures.map((signature) => signature.r).join('');
+    const s = signatures.map((signature) => signature.s).join('');
+    return `0x${countByte}${v}${r}${s}`;
+};
+exports.packSignatures = packSignatures;
+/**
+ * The calldata for a release that pays no delivery tip: a direct call to the
+ * destination bridge.
+ *
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for `safeExecuteSignaturesWithAutoGasLimit`
+ */
+const encodeReleaseWithoutTipData = ({ encodedData, encodedSignatures, }) => (0, viem_1.encodeFunctionData)({
+    abi: abis.relayTokensDirect,
+    functionName: 'safeExecuteSignaturesWithAutoGasLimit',
+    args: [encodedData, encodedSignatures],
+});
+exports.encodeReleaseWithoutTipData = encodeReleaseWithoutTipData;
+/**
+ * The calldata for a release sent through the pathway's destination output
+ * router, the path a fee-director (delivery) request uses.
+ *
+ * @param options.validator - the pathway's validator contract
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for the router's `safeExecuteSignaturesWithAutoGasLimit`
+ */
+const encodeReleaseToRouterData = ({ validator, encodedData, encodedSignatures, }) => (0, viem_1.encodeFunctionData)({
+    abi: abis.outputRouter,
+    functionName: 'safeExecuteSignaturesWithAutoGasLimit',
+    args: [validator, encodedData, encodedSignatures],
+});
+exports.encodeReleaseToRouterData = encodeReleaseToRouterData;
+/**
+ * The one place a claim's target and calldata come from. The interface's
+ * release hook and {@link buildClaimTransaction} both call it.
+ *
+ * @param options.encodedData - the bridge message
+ * @param options.signatures - the raw validator signatures, in signing order
+ * @param options.destinationAmbAddress - the destination bridge, used by the `direct` route
+ * @param options.via - which contract receives the claim
+ * @returns the target contract and the calldata
+ */
+const claimCall = ({ encodedData, signatures, destinationAmbAddress, via, }) => {
+    const encodedSignatures = (0, exports.packSignatures)(signatures.map(exports.signatureToVRS));
+    if (via.kind === 'router') {
+        return {
+            to: via.destinationRouter,
+            data: (0, exports.encodeReleaseToRouterData)({ validator: via.validator, encodedData, encodedSignatures }),
+        };
+    }
+    return { to: destinationAmbAddress, data: (0, exports.encodeReleaseWithoutTipData)({ encodedData, encodedSignatures }) };
+};
+exports.claimCall = claimCall;
+const isSignatureList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && (0, viem_1.isHex)(entry));
+const refused = (refusal) => ({ kind: 'refused', refusal });
+/**
+ * Builds the manual-claim transaction for one bridge request, or refuses with
+ * a typed reason.
+ *
+ * The checks run in this order: request type, delivery, signing, then the
+ * stored signature count. A delivered request is refused before the signing
+ * check, because delivery also sets `finishedSigning`.
+ *
+ * ASSUMPTION: the signatures are only complete when every validator sent
+ * `submitSignature` directly to the home bridge. The indexer drops a
+ * signature sent any other way; see this module's head note. This builder
+ * catches the drop by comparing the stored list with the required-signature
+ * threshold, or with `confirmedSignatures` when the record carries no threshold.
+ *
+ * @param options.request - the indexer's `UserRequest` record
+ * @param options.via - the claim target; see {@link ClaimRoute}
+ * @returns a `claim` plan whose transaction runs on the destination chain, or a refusal
+ */
+const buildClaimTransaction = ({ request, via, }) => {
+    if (request.type !== 'signature')
+        return refused({ reason: 'wrong-type', type: request.type });
+    if (request.delivered)
+        return refused({ reason: 'already-delivered' });
+    if (!request.finishedSigning)
+        return refused({ reason: 'not-signed-yet' });
+    if (!isSignatureList(request.signatures))
+        return refused({ reason: 'malformed-request', field: 'signatures' });
+    if (!(0, viem_1.isHex)(request.encodedData))
+        return refused({ reason: 'malformed-request', field: 'encodedData' });
+    if (!(0, viem_1.isHex)(request.destinationAmbAddress)) {
+        return refused({ reason: 'malformed-request', field: 'destinationAmbAddress' });
+    }
+    const needed = Number(request.requiredSignatures?.value ?? request.confirmedSignatures);
+    const stored = request.signatures.length;
+    if (stored < needed)
+        return refused({ reason: 'signatures-incomplete', stored, needed });
+    const { to, data } = (0, exports.claimCall)({
+        encodedData: request.encodedData,
+        signatures: request.signatures,
+        destinationAmbAddress: request.destinationAmbAddress,
+        via,
+    });
+    return {
+        kind: 'claim',
+        transaction: {
+            chainId: Number(request.destinationChainId),
+            kind: 'claim',
+            to,
+            data,
+            value: 0n,
+            // The calldata itself asks the bridge to pick its own gas limit
+            // (`safeExecuteSignaturesWithAutoGasLimit`); the wallet estimates the rest.
+            gasLimit: null,
+            waitForReceipt: false,
+        },
+    };
+};
+exports.buildClaimTransaction = buildClaimTransaction;

package/dist/cjs/config.d.ts

@@ -0,0 +1,240 @@
+import { type Hex } from 'viem';
+import type { BridgeKey, Token, TokenOut } from './types.js';
+/**
+ * Add here your chain id as hex, be sure to add your chain in the chainsMetadata object too
+ */
+export declare enum Chains {
+    PLS = "0x171",
+    ETH = "0x1",
+    BNB = "0x38",
+    SEP = "0xaa36a7",
+    V4PLS = "0x3af"
+}
+/** The key of a chain - human readable for query params */
+export type ChainKey = keyof typeof Chains;
+/** A map of chain ids to chain keys */
+export declare const chainIdToKey: Map<Chains, "PLS" | "ETH" | "BNB" | "SEP" | "V4PLS">;
+/**
+ * Converts a chain id to a chain key
+ * @param chainId - the chain id
+ * @returns the chain key
+ */
+export declare const toChain: (chainId: number | string) => Chains;
+/**
+ * Converts a chain id to a chain key
+ * @param chainId - the chain id
+ * @returns the chain key
+ */
+export declare const toChainKey: (chainId: number | string) => "PLS" | "ETH" | "BNB" | "SEP" | "V4PLS" | undefined;
+export declare const Providers: {
+    readonly PULSECHAIN: "pulsechain";
+    readonly TOKENSEX: "tokensex";
+};
+export type Provider = (typeof Providers)[keyof typeof Providers];
+/** A map of chains to native asset out addresses */
+export declare const nativeAssetOut: Record<Chains, Hex>;
+/**
+ * Four PulseChain mainnet tokens that no other constant in this package
+ * names. The PulseX carrier routes swaps through them
+ * (`routing/carriers/pulsex-paths.ts`), and the interface builds its
+ * PulseChain hub nodes from the two stablecoins.
+ *
+ * Each address was already in the repository before it moved here: USDC and
+ * USDT from the interface's `HUB_STABLECOIN_ADDRESSES`
+ * (`packages/ui/src/lib/state/useRouteSearch.ts`), PLSX and HEX from
+ * `scripts/route-parity-corpus.ts`. Each one was read on chain again on
+ * 2026-10-06 (`symbol()`, `decimals()`): PLSX 18, HEX 8, USDC 6, USDT 6.
+ * `getAddress` checksums them at load, so a mistyped character fails the
+ * build rather than silently matching nothing.
+ */
+export declare const pulsechainTokenAddresses: Readonly<{
+    /** PulseX, the exchange's own token. */
+    PLSX: `0x${string}`;
+    /** HEX. */
+    HEX: `0x${string}`;
+    /** USD Coin, bridged from Ethereum. */
+    USDC: `0x${string}`;
+    /** Tether USD, bridged from Ethereum. */
+    USDT: `0x${string}`;
+}>;
+/** A map of chains to deprecated native asset out addresses */
+export declare const deprecatedNativeAssetOut: Partial<Record<Chains, Set<Hex>>>;
+/** A map of chains to uni v2 router addresses */
+export declare const uniV2Routers: Record<Chains, Hex[]>;
+/**
+ * Each {@link uniV2Routers} entry's OWN factory address, same index, same
+ * chain — `router.factory()` read live from `one.valve.city` on 2026-09-24.
+ * Only PulseChain mainnet is filled: PulseX carries funds nowhere else
+ * (`routing/carriers/pulsex.ts`'s own `pulseXCarries`), so no other chain's
+ * factory has ever been needed or verified.
+ *
+ * MEASURED, NOT ASSUMED (owner Rule 13). Reading each factory's `getPair`
+ * and the resulting pool's `getReserves`, then recomputing `getAmountsOut`
+ * from the standard constant-product formula, showed the SAME fee ratio for
+ * both — `9971/10000` (0.29%) — to the base unit, on both a one-hop and a
+ * two-hop path. "V1 and V2 differ" was the assumption going in; measurement
+ * said otherwise, so `routing/carriers/pulsex.ts`'s `exact` uses one shared
+ * fee constant rather than two.
+ *
+ * `0x1715a3E4A142d8b698131108995174F37aEBA10D` (the V1 factory, index 0) is
+ * NOT a copy-paste of the omnibridge's Ethereum mediator address from
+ * `pathways` above — it is the same string on a DIFFERENT chain (PulseChain,
+ * not Ethereum), confirmed by reading it fresh from `one.valve.city/…/evm/369`.
+ * Two unrelated contracts landing on the same address on two different
+ * chains is possible (a shared deployer at a matching nonce, or a CREATE2
+ * salt collision) and worth this note so a future reader does not assume a
+ * transcription error and "fix" it back to something wrong.
+ */
+export declare const uniV2Factories: Record<Chains, Hex[]>;
+/** A map of chains to native token symbols */
+export declare const nativeTokenSymbol: Record<Chains, string>;
+/** A map of chains to native token names */
+export declare const nativeTokenName: Record<Chains, string>;
+/** The pathway of a bridge */
+export type Pathway = {
+    from: Hex;
+    to: Hex;
+    destinationRouter: Hex | null;
+    nativeRouter: Hex;
+    validator: Hex;
+    usesExtraParam: boolean;
+    feeManager: 'from' | 'to';
+    toHome: boolean;
+    requiresDelivery: boolean;
+    bridgedNativeAssetOut: Hex;
+    settingOverrides?: Record<Hex, Partial<Pathway>>;
+};
+/** A map of providers to pathways */
+export type DeepPathwayConfig = Record<Provider, Partial<Record<Chains, Partial<Record<Chains, Pathway>>>>>;
+export declare const pathways: DeepPathwayConfig;
+export declare const testnetPathways: DeepPathwayConfig;
+/** Returns the valid bridge keys for the given is prod */
+export declare const validBridgeKeys: (isProd: boolean) => BridgeKey[];
+/**
+ * Whether a chain belongs to the testnet pathway map rather than the mainnet one.
+ * @param chain - the chain to classify
+ * @returns true for Sepolia and PulseChain testnet V4
+ */
+export declare const isTestnetChain: (chain: Chains) => boolean;
+/**
+ * Infers the bridge key from the current key, provider, from chain, and to chain.
+ *
+ * A chain the provider does not serve falls back to the provider's first chain,
+ * so a provider switch lands on a real pathway. That fallback never crosses
+ * between the testnet and mainnet maps: when testnets are off and a requested
+ * chain is a testnet chain, this returns null rather than a mainnet key for a
+ * testnet pair.
+ *
+ * @param options.currentKey - the current bridge key
+ * @param options.provider - the provider
+ * @param options.fromChain - the from chain (defaults to the current key's)
+ * @param options.toChain - the to chain (defaults to the current key's)
+ * @param options.isProd - true leaves testnet pathways out (default false: both maps)
+ * @returns the inferred bridge key, or null when no pathway can honour the request
+ */
+export declare const inferBridgeKey: ({ currentKey, provider, fromChain, toChain, isProd, }: {
+    currentKey: BridgeKey;
+    provider: Provider;
+    fromChain?: Chains;
+    toChain?: Chains;
+    isProd?: boolean;
+}) => BridgeKey | null;
+/**
+ * Returns the pathway for the given bridge key, is prod, and asset in address
+ * @param bridgeKey - the bridge key
+ * @param isProd - whether to use the production pathway
+ * @param assetInAddress - the asset in address
+ * @returns the pathway
+ */
+/**
+ * The pathway group for one provider on one chain, honouring the testnet map.
+ *
+ * Exists because {@link pathway} already knew that testnet pathways live in a
+ * SECOND map and are only in play off production, while other callers reached
+ * straight into `pathways` and therefore could not see a testnet route at all.
+ * That is the sort of knowledge that has to live in one place: duplicated, one
+ * copy silently lags the other, and the symptom is a thrown "no pathway found"
+ * on a route the rest of the application considers perfectly valid.
+ *
+ * @param provider - the bridge provider
+ * @param chain - the chain being bridged FROM
+ * @param isProd - whether this is a production build; testnets are off when true
+ * @returns the group keyed by destination chain, or undefined when unknown
+ */
+export declare const pathwayGroup: (provider: Provider, chain: Chains, isProd: boolean) => Partial<Record<Chains, Pathway>> | undefined;
+export declare const pathway: (bridgeKey: BridgeKey | null, isProd: boolean, assetInAddress?: string | Hex | null | undefined) => Pathway | undefined;
+/**
+ * Returns the default asset in for the given bridge key and is prod
+ * @param bridgeKey - the bridge key
+ * @param isProd - whether to use the production pathway
+ * @returns the default asset in
+ */
+export declare const defaultAssetIn: ($bridgeKey: BridgeKey | null, isProd: boolean) => `0x${string}` | null | undefined;
+/** Which pathway maps a lookup reads. */
+export type PathwayLookupOptions = {
+    /**
+     * true reads the mainnet map alone; false (the default) also reads the
+     * testnet map, which is what every caller did before this option existed.
+     */
+    isProd?: boolean;
+};
+/**
+ * Returns whether the given asset is the native asset for the given bridge key.
+ *
+ * Never throws. A token whose address is not known yet (a {@link TokenOut} for a
+ * not-yet-bridged token), an address that is not a valid address, and a bridge
+ * key with no pathway each answer false.
+ *
+ * @param asset - the asset
+ * @param bridgeKey - the bridge key
+ * @param options - which pathway maps to read; see {@link PathwayLookupOptions}
+ * @returns whether the given asset is the native asset for the given bridge key
+ */
+export declare const isNative: (asset: Token | TokenOut | null, bridgeKey: BridgeKey | null, options?: PathwayLookupOptions) => boolean;
+/**
+ * Returns whether the given asset is unwrappable for the given bridge key.
+ *
+ * Never throws: a missing or malformed address and a bridge key with no
+ * pathway each answer false.
+ *
+ * @param bridgeKey - the bridge key
+ * @param assetIn - the asset in
+ * @param options - which pathway maps to read; see {@link PathwayLookupOptions}
+ * @returns whether the given asset is unwrappable for the given bridge key
+ */
+export declare const isUnwrappable: (bridgeKey: BridgeKey | null, assetIn: {
+    address: string | null;
+} | null, options?: PathwayLookupOptions) => boolean;
+/**
+ * Returns whether the given asset can be unwrapped for the given bridge key
+ * @param bridgeKey - the bridge key
+ * @param assetIn - the asset in
+ * @param options - which pathway maps to read; see {@link PathwayLookupOptions}
+ * @returns boolean
+ */
+export declare const canChangeUnwrap: (bridgeKey: BridgeKey, assetIn: Token | null, options?: PathwayLookupOptions) => boolean;
+export declare const chains: {
+    readonly ethereum: 1;
+    readonly bsc: 56;
+    readonly pulsechain: 369;
+    readonly pulsechainV4: 943;
+    readonly sepolia: 11155111;
+};
+export declare const chainIds: (1 | 56 | 369 | 943 | 11155111)[];
+/** Start blocks aligned with when bridge validators began operating — canonical reference for all ponder indexers in this monorepo. */
+export declare const startBlocks: Record<keyof typeof chains, number>;
+export type ChainId = (typeof chainIds)[number];
+export type Side = 'home' | 'foreign';
+export type MinimalKey = `${ChainId}-${Hex}`;
+export type PathwayInfo = {
+    pair: string;
+    key: string;
+    home: Hex;
+    foreign: Hex;
+};
+export type ProviderHomeChainEntry = Partial<Record<ChainId, PathwayInfo[]>>;
+export type ProviderEntries = Partial<Record<ChainId, ProviderHomeChainEntry>>;
+export type BridgeConfig = Record<Provider, ProviderEntries>;
+export declare const bridgeConfigs: BridgeConfig;
+export declare const HOME_TO_FOREIGN_FEE: `0x${string}`;
+export declare const FOREIGN_TO_HOME_FEE: `0x${string}`;