@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/chain-info.js

@@ -0,0 +1,410 @@
+import { multicallRead } from '@gibs/common/multicall';
+import * as _ from 'lodash-es';
+import { encodeFunctionData, getContract, multicall3Abi, zeroAddress, } from 'viem';
+import * as abis from './abis.js';
+import { chainsMetadata } from './chains.js';
+import { nativeAssetOut, pathway, toChain, uniV2Routers, } from './config.js';
+/** Cache key for the links memoize: one entry per (chain, bridge, token) triple. */
+const linksCacheKey = ({ chainId, target, address, }) => `${chainId}-${target}-${address}`.toLowerCase();
+/**
+ * Whether a {@link links} answer says the token has no mapping on this bridge
+ * yet. That answer is temporary: the first transfer of the token creates the
+ * mapping, so it must not be cached.
+ * @param pair - the bridged and native addresses the mediator returned
+ * @returns true when both are the zero address
+ */
+const isUnmappedAnswer = ([bridged, native]) => bridged === zeroAddress && native === zeroAddress;
+/**
+ * Returns the bridged token address and native token address that a mediator
+ * holds for one token.
+ *
+ * A non-zero answer is cached for the life of the process: a mediator never
+ * changes a mapping once the first transfer creates it. A failed read, and a
+ * `[zero, zero]` answer (the token is not bridged yet), are not cached, so the
+ * next call reads the chain again. Call {@link clearChainInfoCaches} to drop
+ * every cached answer.
+ *
+ * @param inputs.chainId - the chain id being targeted
+ * @param inputs.target - the mediator to ask
+ * @param inputs.address - the token address
+ * @param inputs.client - a client for that chain
+ * @returns the bridged token address and native token address
+ */
+// The annotation is required, not stylistic: `@types/lodash-es` re-exports its
+// `MemoizedFunction` type from a nested `@types/lodash` that a generated
+// declaration file cannot name (TS2742). The body reaches for `links.cache` to
+// evict an answer, so the cache surface is spelled out to the extent this file
+// uses it.
+export const links = _.memoize(async (inputs) => {
+    const { chainId, target, address, client } = inputs;
+    const evict = () => links.cache.delete(linksCacheKey(inputs));
+    const pair = await multicallRead({
+        client,
+        chain: chainsMetadata[toChain(chainId)],
+        abi: abis.inputBridge,
+        target,
+        calls: [
+            { functionName: 'bridgedTokenAddress', args: [address] },
+            { functionName: 'nativeTokenAddress', args: [address] },
+        ],
+    }).catch((error) => {
+        // a transient read failure must not poison the cache for the session
+        evict();
+        throw error;
+    });
+    if (isUnmappedAnswer(pair)) {
+        // the token may be bridged a minute from now; ask again next time
+        evict();
+    }
+    return pair;
+}, linksCacheKey);
+/**
+ * Drops every answer this module has cached, so the next read goes to the chain.
+ *
+ * Use it after a token's first transfer, in a long-running process that wants
+ * a fresh view, or between tests.
+ */
+export const clearChainInfoCaches = () => {
+    // lodash types mark `clear` optional; the default MapCache always has it
+    links.cache.clear?.();
+};
+/**
+ * Returns the token bridge info for the given bridge key, asset in, is prod, from chain client, and to chain client
+ * @param bridgeKey - the bridge key
+ * @param assetIn - the asset in
+ * @param isProd - whether to use the production pathway
+ * @param fromChainClient - the from chain client
+ * @param toChainClient - the to chain client
+ * @returns the token bridge info
+ */
+export const tokenBridgeInfo = async ({ bridgeKey, assetIn, isProd, fromChainClient, toChainClient, }) => {
+    const bridgePathway = pathway(bridgeKey, isProd, assetIn?.address);
+    if (!assetIn || !bridgePathway) {
+        return null;
+    }
+    const [, fromChain, toChain] = bridgeKey;
+    const assetInAddress = assetIn.address === zeroAddress ? nativeAssetOut[fromChain] : assetIn.address;
+    const [toMappings, fromMappings] = await Promise.all([
+        links({
+            chainId: Number(toChain),
+            target: bridgePathway.to,
+            address: assetInAddress,
+            client: toChainClient,
+        }),
+        links({
+            chainId: Number(fromChain),
+            target: bridgePathway.from,
+            address: assetInAddress,
+            client: fromChainClient,
+        }),
+    ]);
+    const [toBridged, toNative] = toMappings;
+    if (toBridged !== zeroAddress) {
+        return {
+            originationChainId: fromChain,
+            assetInAddress: assetInAddress,
+            assetOutAddress: toBridged,
+            toHome: {
+                home: toBridged,
+                foreign: assetInAddress,
+            },
+        };
+    }
+    if (toNative !== zeroAddress) {
+        return {
+            originationChainId: toChain,
+            assetInAddress: assetInAddress,
+            assetOutAddress: toNative,
+            toForeign: {
+                home: toNative,
+                foreign: assetInAddress,
+            },
+        };
+    }
+    const [fromBridged, fromNative] = fromMappings;
+    if (fromNative !== zeroAddress) {
+        return {
+            originationChainId: toChain,
+            assetInAddress: assetInAddress,
+            assetOutAddress: fromNative,
+            toHome: {
+                home: assetInAddress,
+                foreign: fromNative,
+            },
+        };
+    }
+    if (fromBridged !== zeroAddress) {
+        return {
+            originationChainId: fromChain,
+            assetInAddress: assetInAddress,
+            assetOutAddress: fromBridged,
+            toForeign: {
+                foreign: fromBridged,
+                home: assetInAddress,
+            },
+        };
+    }
+    // the token has not been bridged yet
+    return {
+        originationChainId: toChain,
+        assetInAddress: assetInAddress,
+        assetOutAddress: null,
+        ...(bridgePathway.toHome
+            ? {
+                toHome: {
+                    foreign: assetInAddress,
+                    home: null,
+                },
+            }
+            : {
+                toForeign: {
+                    foreign: null,
+                    home: assetInAddress,
+                },
+            }),
+    };
+};
+/**
+ * Check the prices that each router offers for the given paths
+ * @param assetInAddress the address of the asset going into the bridge
+ * @param oneTokenInt the number of tokens to push into the bridge (before fees)
+ * @param chain the chain of the asset going into the bridge
+ * @param bridgeKey the bridge key
+ * @param blockNumber the block number to use for the price
+ * @param paths the paths to check
+ * @returns the prices as bigint for each path, hex whenever the price is not available
+ */
+const readAmountOut = ({ amountIn, chain, paths, client, uniV2Router, }) => {
+    return multicallRead({
+        chain: chainsMetadata[chain],
+        client,
+        abi: abis.univ2Router,
+        // pulsex router
+        calls: _.flatMap(uniV2Router ? [uniV2Router] : uniV2Routers[chain], (target) => paths.map((path) => ({
+            functionName: 'getAmountsOut',
+            allowFailure: true,
+            args: [amountIn, path],
+            target,
+        }))),
+    });
+};
+/**
+ * Fetch the price corrective for the given bridge key, asset out, measurement token, from chain client, to chain client, asset link, amount in, and is prod
+ * @param bridgeKeyPartner - the bridge key partner
+ * @param assetOut - the asset out
+ * @param measurementToken - the measurement token
+ * @param fromChainClient - the from chain client
+ * @param toChainClient - the to chain client
+ * @param assetLink - the asset link
+ * @param amountIn - the amount in
+ * @param isProd - whether to use the production pathway
+ * @returns the price corrective
+ */
+export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementToken, fromChainClient, toChainClient, assetLink, amountIn, isProd, }) => {
+    return {
+        getPaymentToken: async () => {
+            // fetch the token bridge info for the token that is about to be spent by the delivery service
+            return await tokenBridgeInfo({
+                bridgeKey: bridgeKeyPartner,
+                assetIn: {
+                    ...assetOut,
+                    address: measurementToken,
+                },
+                isProd,
+                // clients are reversed here because we are actually fetching the
+                // tokens going the opposite direction to the provided bridge key
+                fromChainClient: toChainClient,
+                toChainClient: fromChainClient,
+            });
+        },
+        getSwapResults: async ({ paymentTokenResult, chain, uniV2Router, client, }) => {
+            return await Promise.all([
+                readAmountOut({
+                    amountIn,
+                    chain,
+                    uniV2Router,
+                    client,
+                    paths: [
+                        // check the direct route
+                        [assetLink.assetInAddress, paymentTokenResult.assetOutAddress],
+                        // might have heavier liquidity going through the native asset on the home side
+                        [assetLink.assetInAddress, nativeAssetOut[chain], paymentTokenResult.assetOutAddress],
+                    ],
+                }),
+                readAmountOut({
+                    amountIn,
+                    chain,
+                    uniV2Router,
+                    client,
+                    paths: [[assetOut.address, measurementToken]],
+                    // only the direct route is available.
+                    // might be able to create a whitelist for this at some point
+                }),
+            ]);
+        },
+        reduceResults: ({ results, oneToken, }) => {
+            const outputFromRouter = (result) => {
+                if (_.isString(result)) {
+                    // the router failed to return a result
+                    return 0n;
+                }
+                if (!result.length) {
+                    // the router returned an empty result
+                    return 0n;
+                }
+                // the last element is the amount of the output token
+                const last = result[result.length - 1];
+                return (last * oneToken) / amountIn;
+            };
+            const max = (amountsOut) => {
+                return _.compact(amountsOut).reduce((max, current) => (max < current ? current : max), 0n);
+            };
+            // could do with a refactor to unify the results
+            const [outputs, inputs] = results;
+            const outputAmounts = outputs.map(outputFromRouter);
+            const inputAmounts = inputs.map(outputFromRouter);
+            const outputToken = max(outputAmounts);
+            const inputToken = max(inputAmounts);
+            const result = outputToken && outputToken > 0n
+                ? inputToken && inputToken > outputToken && inputToken / outputToken === 1n
+                    ? inputToken
+                    : outputToken
+                : inputToken;
+            return result;
+        },
+    };
+};
+/**
+ * Read the smallest amount the bridge will accept for this asset on this pathway.
+ *
+ * THE ENTRY MEDIATOR DECIDES, so this always reads `pathway.from` on the chain
+ * the funds leave. `feeManager` says which side prices the transfer; it has
+ * never said which side validates the amount, and using it for both is what
+ * produced the defect this replaces.
+ *
+ * Both mediators keep a `minPerTx` under the same name, and for a token that
+ * originates on the entry chain the two sides usually hold the same number. That
+ * agreement is a coincidence of configuration - each side is separately
+ * governed, and both happen to apply one blanket default. It breaks outright for
+ * a token that originates on the far side, because the two mediators key their
+ * limits by different addresses. Wrapped Pulse entering from Ethereum is the
+ * live case: the entry mediator enforces 50,000, and the destination mediator
+ * answers 0 for that same address because it files that token under its
+ * PulseChain address instead. Reading the destination got both the chain and the
+ * token key wrong, and reported no floor where a real one stood.
+ * @param assetIn - the asset the sender holds, on the chain it leaves from
+ * @param pathway - the pathway, with any per-asset overrides already applied
+ * @param fromPublicClient - a client for the chain the funds leave
+ * @returns the smallest amount the entry mediator will accept
+ */
+export const minBridgeAmountIn = async ({ assetIn, pathway, fromPublicClient, }) => fromPublicClient.readContract({
+    abi: abis.inputBridge,
+    functionName: 'minPerTx',
+    args: [assetIn.address],
+    address: pathway.from,
+});
+/** get the symbol of the native asset, unwrap it if it needs to be */
+export const nativeSymbol = (asset, unwrap = false) => {
+    return asset
+        ? unwrap && asset.address === nativeAssetOut[toChain(asset.chainId)]
+            ? asset.symbol.slice(1)
+            : asset.symbol
+        : '';
+};
+/**
+ * Returns the Multicall3 contract for the client's chain.
+ * @param client - a client whose `chain` is one of {@link chainsMetadata}'s chains
+ * @returns the Multicall3 contract instance
+ * @throws when the client carries no chain, or the chain has no Multicall3 address
+ */
+export const chainMulticall = (client) => {
+    const chainId = client.chain?.id;
+    if (chainId === undefined) {
+        throw new Error('chainMulticall: the client has no chain configured');
+    }
+    const address = chainsMetadata[toChain(chainId)]?.contracts?.multicall3?.address;
+    if (!address) {
+        throw new Error(`chainMulticall: no Multicall3 address known for chain ${chainId}`);
+    }
+    return getContract({ abi: multicall3Abi, client, address });
+};
+/**
+ * Load the bridge fees for the given pathway, from chain client, and to chain client
+ * @param pathway - the pathway
+ * @param fromChainClient - the from chain client
+ * @param toChainClient - the to chain client
+ * @returns the bridge fees
+ */
+export const loadBridgeFees = async ({ pathway, fromChainClient, toChainClient, }) => {
+    const multicall = pathway.feeManager === 'from' ? chainMulticall(fromChainClient) : chainMulticall(toChainClient);
+    const [feeManagerResponse] = await multicall.read.aggregate3([
+        [
+            {
+                allowFailure: false,
+                target: pathway[pathway.feeManager],
+                callData: encodeFunctionData({
+                    abi: abis.inputBridge,
+                    functionName: 'feeManager',
+                }),
+            },
+        ],
+    ]);
+    const { success, returnData } = feeManagerResponse;
+    if (!success) {
+        throw new Error('unable to load feeManager');
+    }
+    if (returnData === '0x') {
+        throw new Error('unable to read feeManager');
+    }
+    const feeManager = (returnData.startsWith('0x000000000000000000000000')
+        ? `0x${returnData.slice(26)}`
+        : `0x${returnData.slice(-40)}`);
+    const [keyH2F, keyF2H] = await multicall.read.aggregate3([
+        [
+            {
+                allowFailure: false,
+                target: feeManager,
+                callData: encodeFunctionData({
+                    abi: abis.feeManager,
+                    functionName: 'HOME_TO_FOREIGN_FEE',
+                }),
+            },
+            {
+                allowFailure: false,
+                target: feeManager,
+                callData: encodeFunctionData({
+                    abi: abis.feeManager,
+                    functionName: 'FOREIGN_TO_HOME_FEE',
+                }),
+            },
+        ],
+    ]);
+    const [feeH2F, feeF2H] = await multicall.read.aggregate3([
+        [
+            {
+                allowFailure: false,
+                target: feeManager,
+                callData: encodeFunctionData({
+                    abi: abis.feeManager,
+                    functionName: 'getFee',
+                    args: [keyH2F.returnData, zeroAddress],
+                }),
+            },
+            {
+                allowFailure: false,
+                target: feeManager,
+                callData: encodeFunctionData({
+                    abi: abis.feeManager,
+                    functionName: 'getFee',
+                    args: [keyF2H.returnData, zeroAddress],
+                }),
+            },
+        ],
+    ]);
+    const setting = {
+        feeManager,
+        feeH2F: BigInt(feeH2F.returnData),
+        feeF2H: BigInt(feeF2H.returnData),
+    };
+    return setting;
+};

package/dist/chain-names.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Chain identifiers and their human-readable display names, in one place.
+ *
+ * This module exists to break an import cycle. `relay-quote.ts` imports the
+ * step normalizers from `route-steps.ts`, and `route-steps.ts` needs to name
+ * Relay's non-Ethereum chains when it labels a leg. Holding the shared lookup
+ * here lets both import it without either importing the other.
+ *
+ * Names are spelled out in full — these strings are shown to someone choosing
+ * where their funds leave from, so "The Open Network", never "TON".
+ */
+/**
+ * Relay's numeric chain identifiers for the non-Ethereum-Virtual-Machine origin
+ * chains this bridge supports. These are Relay's OWN identifiers, distinct from
+ * any native chain id, and are required verbatim as the request's
+ * `originChainId`.
+ *
+ * Source: https://api.relay.link/chains, where each entry's `vmType` names the
+ * ecosystem and each is reported `depositEnabled`.
+ */
+export declare const relayChainIds: {
+    /** Relay's chain id for Solana mainnet (virtual-machine type `svm`). */
+    readonly solana: 792703809;
+    /**
+     * Relay's chain id for Eclipse (virtual-machine type `svm`) — a SECOND chain
+     * in the Solana ecosystem, sharing Solana's address encoding, deposit shape
+     * and native-asset sentinel while being a different network with a different
+     * native asset (Ether, not Sol).
+     *
+     * Quotable, but see the guard in the interface's Solana signer: sharing an
+     * ecosystem means sharing a wallet adapter, and that adapter is bound to ONE
+     * Solana network at a time. A deposit for this chain must never be signed
+     * against a connection pointed at Solana.
+     */
+    readonly eclipse: 9286185;
+    /** Relay's chain id for Bitcoin mainnet (virtual-machine type `bvm`). */
+    readonly bitcoin: 8253038;
+    /** Relay's chain id for Tron mainnet (virtual-machine type `tvm`). */
+    readonly tron: 728126428;
+    /** Relay's chain id for The Open Network (virtual-machine type `tonvm`). */
+    readonly ton: 224235520;
+    /**
+     * Relay's chain id for Hyperliquid (virtual-machine type `hypevm`).
+     *
+     * BEWARE: 1337 is also the default chain id of a local Ganache development
+     * node, so this is the one Relay identifier that can collide with a real
+     * Ethereum Virtual Machine chain a developer might be running. Treating a
+     * local test chain as Hyperliquid would route it down the HyperCore deposit
+     * path, so never feed a local development chain id through
+     * `ecosystemByChainId`.
+     */
+    readonly hyperliquid: 1337;
+};
+/**
+ * Chain identifiers for origin chains a reader PAYS BY HAND.
+ *
+ * WHAT MAKES THESE DIFFERENT FROM EVERY OTHER CHAIN HERE. Every identifier
+ * above names a chain this interface can connect a wallet to and sign on.
+ * These name chains it cannot. There is no connector, no signer and no
+ * transaction: the provider issues an address, the reader sends an ordinary
+ * transfer to it from any wallet or any exchange, and the provider's own
+ * watcher reports the arrival. The chain identifier exists so the route layer
+ * can NAME the chain, price it and draw it — nothing more.
+ *
+ * THE NUMBERS ARE DERIVED, NOT INVENTED, and the derivation is written down
+ * because a chain identifier typed from memory is a hypothesis every later
+ * reader will trust. Each is the chain's registered SLIP-0044 coin type with
+ * the hardened bit set, exactly as a BIP-44 derivation path writes it:
+ * `0x80000000 + coinType`. That puts them above every chain identifier in
+ * public use, so one can never collide with a real Ethereum chain and be
+ * mistaken for one — which is the failure that matters, because an Ethereum
+ * chain has a wallet and would be handed a payload to sign.
+ *
+ * They are LOCAL identifiers and never travel on a wire. NEAR Intents names
+ * Zcash `zec`; `chainIdByNearIntentsChain` is where the two are reconciled.
+ */
+export declare const depositAddressChainIds: {
+    /** Zcash mainnet. SLIP-0044 coin type 133, hardened: 0x80000000 + 133. */
+    readonly zcash: 2147483781;
+};
+/**
+ * One member per pay-by-hand origin chain — the union every table keyed by a
+ * pay-by-hand chain must be typed against.
+ *
+ * WHY THIS UNION, NOT `number`. `DepositAddressDeposit`'s own doc says the same
+ * shape will serve Zcash, Dogecoin, Litecoin and the XRP Ledger alike, so a
+ * second member is coming. A table typed `Record<number, X>` or
+ * `Map<number, X>` accepts a member of {@link depositAddressChainIds} being
+ * missing silently; a table typed `Record<DepositAddressChain, X>` cannot
+ * compile until every member has an entry. The dangerous table this protects
+ * is the ecosystem lookup in `relay-quote.ts`: a miss there makes a pay-by-hand
+ * chain read as an Ethereum chain, which has a wallet, a signer and a
+ * transaction.
+ */
+export type DepositAddressChain = keyof typeof depositAddressChainIds;
+/**
+ * Whether a chain identifier names a chain this interface CANNOT SIGN ON.
+ *
+ * The one predicate every surface asks before offering a wallet. A chain that
+ * answers true has no connector, so anything that would connect, switch
+ * networks, estimate gas or compose a transaction for it is wrong — the reader
+ * is shown an address to pay instead.
+ *
+ * @param chainId - a chain identifier
+ * @returns whether the reader pays this chain by hand
+ */
+export declare const isDepositAddressChain: (chainId: number) => boolean;
+/**
+ * Display names for Relay's non-Ethereum origin chains.
+ *
+ * An ecosystem label is NOT a chain name, and using one as a name is actively
+ * wrong: `svm` holds both Solana and Eclipse, so labelling by ecosystem renders
+ * Eclipse as "Solana" — a different network, shown to someone choosing where
+ * their funds leave from. Keyed by chain id for exactly that reason.
+ */
+export declare const relayChainNames: Map<number, string>;
+/**
+ * Registers display names for chains this module does not know about.
+ *
+ * Call once during startup, before anything renders. Entries are merged, and a
+ * name declared in `virtualMachineChainNames` above WINS over a registered one:
+ * the local table is deliberate ("Binance Smart Chain", not the registry's
+ * "BNB Smart Chain"), and a registry that happens to disagree must not quietly
+ * rename a chain the product has already named.
+ *
+ * @param entries - chain id and display name pairs
+ */
+export declare const registerChainNames: (entries: Iterable<readonly [number, string]>) => void;
+/**
+ * Returns a human-readable chain name for the given chain id, covering both
+ * Ethereum-Virtual-Machine chains and Relay's non-Ethereum pseudo identifiers.
+ *
+ * Falls back to the numeric id stringified when the chain is not known — better
+ * to show "chain 999" than to silently drop the leg that traverses it.
+ *
+ * @param chainId - a decimal chain id, Relay's identifier included
+ * @returns the display name, or `chain <id>` when unknown
+ */
+export declare const chainDisplayName: (chainId: number) => string;
+/**
+ * The name this module KNOWS for a chain, or null when it knows none.
+ *
+ * Same lookup as {@link chainDisplayName} without the placeholder, so a caller
+ * with a better fallback of its own can reach one. {@link chainDisplayName} is
+ * defined in terms of this, which is the point: the two can never disagree
+ * about which chains are known.
+ *
+ * WHY A CALLER WOULD WANT THIS. The network chips in the token picker have a
+ * second name to fall back on — the aggregator's own chain list, which reaches
+ * chains this registry has never been told about and says "Unknown network"
+ * rather than printing a bare number. Choosing between the two used to be done
+ * by comparing `chainDisplayName`'s answer against the literal string
+ * `chain <id>`, which is a caller reaching into another function's fallback
+ * format: rename the placeholder here and that comparison quietly stops
+ * matching, leaving every unknown chain labelled with its number.
+ *
+ * @param chainId - a decimal chain id, Relay's identifiers included
+ * @returns the display name, or null when the chain is not known here
+ */
+export declare const knownChainName: (chainId: number) => string | null;