@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/cjs/hyperliquid-execution.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHyperliquidAuthorizationRequest = exports.buildHyperliquidAuthorizationTypedData = exports.isHyperliquidExchangeSuccess = exports.buildHyperliquidExchangeRequest = exports.buildHyperliquidTypedData = exports.hyperliquidVerifyingContract = exports.hyperliquidDomainVersion = exports.hyperliquidDomainName = exports.hyperliquidExchangeUrl = void 0;
+const url_1 = require("@gibs/common/url");
+const viem_1 = require("viem");
+const relay_quote_js_1 = require("./relay-quote.js");
+/**
+ * Executing a Hyperliquid deposit, as pure data.
+ *
+ * Hyperliquid is the one origin whose deposit is never broadcast to a chain.
+ * The user signs a typed-data ACTION and that signed action is posted to
+ * Hyperliquid's own exchange API; Relay then observes the transfer and fills the
+ * route. Two details make this impossible to derive from the quote alone, and
+ * both are encoded here rather than rediscovered at a call site:
+ *
+ * 1. Relay's quote supplies `eip712Types`, `eip712PrimaryType` and the action,
+ *    but NOT the signing domain. The domain is fixed by Hyperliquid and is
+ *    reconstructed by {@link buildHyperliquidTypedData}.
+ * 2. Hyperliquid wants the signature split into `r`/`s`/`v` components, not the
+ *    concatenated hex string a wallet returns.
+ *
+ * Kept free of transport so it is fully testable: nothing here signs, fetches,
+ * or reads a clock. The caller supplies the signature and performs the request.
+ *
+ * The shape mirrors Relay's own client, which is the only reference
+ * implementation of this exchange — their public documentation covers the
+ * generic `signature` step but not this action-bearing `transaction` step.
+ */
+/** Where a signed Hyperliquid action is submitted. Hyperliquid's API, not Relay's. */
+exports.hyperliquidExchangeUrl = 'https://api.hyperliquid.xyz/exchange';
+/** The signing domain Hyperliquid requires. Fixed; never supplied by the quote. */
+exports.hyperliquidDomainName = 'HyperliquidSignTransaction';
+/** The signing domain's version. Fixed alongside {@link hyperliquidDomainName}. */
+exports.hyperliquidDomainVersion = '1';
+/**
+ * The domain's `verifyingContract`. Hyperliquid actions are verified off-chain,
+ * so no contract is involved and the field is the all-zero address.
+ */
+exports.hyperliquidVerifyingContract = '0x0000000000000000000000000000000000000000';
+/** The standard typed-data domain type, which the action's type table must include. */
+const eip712DomainType = [
+    { name: 'name', type: 'string' },
+    { name: 'version', type: 'string' },
+    { name: 'chainId', type: 'uint256' },
+    { name: 'verifyingContract', type: 'address' },
+];
+/**
+ * Builds the typed-data payload for a Hyperliquid deposit.
+ *
+ * The message is the action's parameters plus the action `type` and a
+ * `signatureChainId`; the latter is the signing chain in hex and MUST agree
+ * with `domain.chainId`, because Hyperliquid recovers the signer using both.
+ * They are derived from the single `signatureChainId` argument so they cannot
+ * disagree.
+ *
+ * @param deposit - the parsed Hyperliquid origin deposit
+ * @param options.signatureChainId - the chain id the connected wallet signs
+ *   under. Not the Relay origin chain id: it identifies the signing domain, and
+ *   Relay's own client uses the wallet's active chain here.
+ * @returns the payload to sign, whose `message` doubles as the submitted action
+ */
+const buildHyperliquidTypedData = (deposit, { signatureChainId }) => ({
+    domain: {
+        name: exports.hyperliquidDomainName,
+        version: exports.hyperliquidDomainVersion,
+        chainId: signatureChainId,
+        verifyingContract: exports.hyperliquidVerifyingContract,
+    },
+    types: {
+        ...deposit.eip712Types,
+        EIP712Domain: eip712DomainType,
+    },
+    primaryType: deposit.eip712PrimaryType,
+    message: {
+        ...deposit.action.parameters,
+        type: deposit.action.type,
+        signatureChainId: `0x${signatureChainId.toString(16)}`,
+    },
+});
+exports.buildHyperliquidTypedData = buildHyperliquidTypedData;
+/**
+ * Builds the exchange request for an action the user has signed.
+ *
+ * The nonce is read back out of the signed message rather than passed in: it is
+ * covered by the signature, so any independently supplied value could disagree
+ * with what was signed and be rejected.
+ *
+ * @param options.typedData - the payload that was signed
+ * @param options.signature - the wallet's signature over it
+ * @returns the request body, or null when the signed action carries no usable nonce
+ */
+const buildHyperliquidExchangeRequest = ({ typedData, signature, }) => {
+    // Hyperliquid names it `nonce`; the older action shapes name it `time`.
+    const rawNonce = typedData.message.nonce ?? typedData.message.time;
+    if (typeof rawNonce !== 'number' && typeof rawNonce !== 'bigint') {
+        return null;
+    }
+    const { r, s, v, yParity } = (0, viem_1.parseSignature)(signature);
+    return {
+        // The exchange wants the 27/28 form. A signature whose final byte is the
+        // PARITY form (0 or 1) — which some hardware wallets and smart-account flows
+        // produce — parses with `v` absent and the parity carried separately, so
+        // reading `v` alone and defaulting would send recovery value 0: not a value
+        // the exchange accepts, and the deposit dies for those wallets only. The
+        // parity is the same fact in the other encoding, so shift it rather than
+        // guess.
+        signature: { r, s, v: v === undefined ? yParity + 27 : Number(v) },
+        nonce: Number(rawNonce),
+        action: typedData.message,
+    };
+};
+exports.buildHyperliquidExchangeRequest = buildHyperliquidExchangeRequest;
+/**
+ * Whether an exchange response reports success. Hyperliquid answers with HTTP
+ * 200 even for a rejected action, so the body's own status is the only reliable
+ * signal — treating the status code as the outcome would report a failed
+ * transfer as a completed one.
+ *
+ * @param payload - the parsed response body
+ * @returns true only when the body explicitly reports success
+ */
+const isHyperliquidExchangeSuccess = (payload) => {
+    if (typeof payload !== 'object' || payload === null) {
+        return false;
+    }
+    return payload.status === 'ok';
+};
+exports.isHyperliquidExchangeSuccess = isHyperliquidExchangeSuccess;
+/**
+ * The typed-data payload for the authorization that must be completed BEFORE
+ * the action is submitted.
+ *
+ * Relay builds the authorization against a chain it picks when quoting, but the
+ * signature is produced by whichever chain the wallet is actually on. Both the
+ * domain here and `signatureChainId` in {@link buildHyperliquidAuthorizationRequest}
+ * are therefore overridden with the active wallet chain; leaving Relay's value in
+ * place makes the recovered signer disagree with the submitted one and the
+ * authorization is rejected.
+ *
+ * @param authorization - the authorization carried by the deposit
+ * @param options.signatureChainId - the chain id the connected wallet signs under
+ * @returns the payload to sign
+ */
+const buildHyperliquidAuthorizationTypedData = (authorization, { signatureChainId }) => ({
+    domain: {
+        ...authorization.sign.domain,
+        chainId: signatureChainId,
+    },
+    types: authorization.sign.types,
+    primaryType: authorization.sign.primaryType,
+    message: authorization.sign.value,
+});
+exports.buildHyperliquidAuthorizationTypedData = buildHyperliquidAuthorizationTypedData;
+/**
+ * Builds the authorization submission for a signed authorization.
+ *
+ * @param options.authorization - the authorization that was signed
+ * @param options.signature - the wallet's signature over its typed data
+ * @param options.signatureChainId - the chain id the wallet signed under, which
+ *   replaces the value Relay quoted so the body agrees with the signature
+ * @param options.baseUrl - Relay's API root; the step's endpoint is relative
+ * @returns the request to perform, or null when the endpoint is not a usable path
+ */
+const buildHyperliquidAuthorizationRequest = ({ authorization, signature, signatureChainId, baseUrl = relay_quote_js_1.relayApiBaseUrl, }) => {
+    const { endpoint, method, body } = authorization.post;
+    if (!endpoint.startsWith('/')) {
+        return null;
+    }
+    return {
+        url: (0, url_1.buildUrl)(`${baseUrl}${endpoint}`, { signature }),
+        method,
+        body: { ...body, signatureChainId },
+    };
+};
+exports.buildHyperliquidAuthorizationRequest = buildHyperliquidAuthorizationRequest;

package/dist/cjs/image-links.d.ts

@@ -0,0 +1,117 @@
+import { type DepositAddressChain } from './chain-names.js';
+/**
+ * Sets the image root for the bridge
+ * @param root - the root
+ */
+export declare const setImageRoot: (root: string) => void;
+/**
+ * Returns the image root for the bridge
+ * @returns the image root
+ */
+export declare const getImageRoot: () => string;
+/** The minimal token info */
+interface MinimalTokenInfo {
+    chainId: number;
+    address: string;
+    logoURI?: string | null;
+}
+/**
+ * Returns the list image for the given path
+ * @param path - the path
+ * @returns the list image
+ */
+export declare const list: (path: string) => string;
+/**
+ * Returns the network image for the given chain id
+ * @param chainId - the chain id
+ * @returns the network image
+ */
+export declare const network: (chainId: number) => string;
+/**
+ * gib.show's own key for a chain this package can only name by a LOCAL,
+ * INVENTED identifier — a pay-by-hand origin (see `depositAddressChainIds`)
+ * rather than a real chain id gib.show's numeric endpoint recognizes.
+ * `network(chainId)` 404s for one of these, and the browser draws that 404 as
+ * a broken image on every chain badge and route mark drawn through it.
+ *
+ * Every route producer that draws a chain badge for a token needs this, not
+ * only the deposit-address ones: a route can START on a deposit-address chain
+ * and cross through ordinary Ethereum-Virtual-Machine chains after, so the
+ * predicate has to run on every chain id a route touches, not only the one
+ * the reader picked. Kept beside `network` rather than in the client that also
+ * resolves Relay's pseudo chains (`@gibs/bridge-client/image`'s
+ * `chainLogoUrl`) because that client sits ABOVE this package — it imports
+ * FROM `bridge-sdk` — so this package importing back from it would be a
+ * cycle. `chainLogoUrl` still adds a Relay-icon fallback for chains gib.show
+ * does not carry at ALL (Eclipse, Hyperliquid); this table is only the
+ * chains gib.show DOES carry, under a key other than their numeric id.
+ *
+ * EXPORTED, and this is the ONLY place a pay-by-hand chain's gib.show key is
+ * declared. `@gibs/bridge-client`'s `image.ts` used to hard-code its own copy
+ * of the same `zcash → 'bip122-133'` entry; it now spreads this map into its
+ * own icon table instead, because the dependency runs one way — the client
+ * already imports from this package — so there was never a cycle stopping it.
+ */
+export declare const pseudoChainGibShowIdentifierByChain: Record<DepositAddressChain, string>;
+/** {@link pseudoChainGibShowIdentifierByChain}, keyed by chain id for lookup. */
+export declare const pseudoChainGibShowIdentifier: Readonly<Record<number, string>>;
+/**
+ * The network image for a chain id, honouring a pseudo chain's own gib.show
+ * key when its numeric id is not one gib.show's `/image/<id>` endpoint knows.
+ *
+ * @param chainId - the chain id, a deposit-address chain's local identifier included
+ * @returns a working network/chain-badge image url
+ */
+export declare const networkOrPseudo: (chainId: number) => string;
+/**
+ * Returns the image url for the given token info.
+ *
+ * The gas token is asked for by BOTH of its keys, because the service keys it
+ * two ways and each chain carries only one of them. `<chain>/<zero address>` is
+ * a dedicated picture — Ethereum's ether diamond, PulseChain's mark — and
+ * Binance Smart Chain has none, so asking for it there returns a 404 the browser
+ * draws as a broken image. The empty-address form `<chain>/` is the chain's own
+ * mark, which every chain has.
+ *
+ * The order is NOT interchangeable. The service serves the first source that
+ * resolves, so a chain with a dedicated picture keeps it; reversed, Ethereum
+ * would show the network logo where the ether logo belongs (the two are
+ * genuinely different files). The pair is for the gas token alone: pairing an
+ * ordinary contract address with the chain mark would hide a missing token logo
+ * behind the network's, showing the wrong token rather than an honest fallback.
+ *
+ * @param t - the token info
+ * @returns the image url
+ */
+export declare const image: (t: MinimalTokenInfo) => string;
+/**
+ * {@link image}, but falling back to the token's own CHAIN mark rather than
+ * throwing or asking the service for a picture that was never going to exist,
+ * when the token carries no address a picture can be resolved from yet.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM `image`. A route producer can reach the
+ * moment it draws a DELIVERED token's picture before that token's exact
+ * on-chain address is known — a not-yet-bridged token's `assetOutAddress` is
+ * documented to arrive `null` (see the repository's own "Not-Yet-Bridged
+ * Tokens" gotcha), and a deferred crossing's landing token is exactly this
+ * case: the reader has not yet signed the leg that would settle it. `image`
+ * either throws (`getAddress` refuses a malformed or empty string) or, for a
+ * caller that swallows the throw, silently draws nothing — the same "blank
+ * disc" defect the carrier marks were fixed for, one token lower. The chain's
+ * own mark is a real, recognisable picture that is honest about what is
+ * known: THIS chain, a token not yet resolved on it — the same trade
+ * `trackerView.ts`'s `depositAddressChainLogoFallback` already makes for a
+ * pay-by-hand ORIGIN with no address of its own.
+ *
+ * @param t - the token to draw
+ * @returns the token's own picture, or its chain's mark when the token's
+ *   address cannot be resolved into one
+ */
+export declare const tokenImageOrChainFallback: (t: MinimalTokenInfo) => string;
+/**
+ * Returns a url that will lookup all sources for the given array
+ * @param sources - the sources
+ * @returns the images
+ */
+export declare const images: (sources: string[]) => string;
+export {};

package/dist/cjs/image-links.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.images = exports.tokenImageOrChainFallback = exports.image = exports.networkOrPseudo = exports.pseudoChainGibShowIdentifier = exports.pseudoChainGibShowIdentifierByChain = exports.network = exports.list = exports.getImageRoot = exports.setImageRoot = void 0;
+const viem_1 = require("viem");
+const chain_names_js_1 = require("./chain-names.js");
+const ecosystems_js_1 = require("./ecosystems.js");
+let imageRoot = 'https://gib.show';
+/**
+ * Sets the image root for the bridge
+ * @param root - the root
+ */
+const setImageRoot = (root) => {
+    imageRoot = root;
+};
+exports.setImageRoot = setImageRoot;
+/**
+ * Returns the image root for the bridge
+ * @returns the image root
+ */
+const getImageRoot = () => imageRoot;
+exports.getImageRoot = getImageRoot;
+/**
+ * Returns the list image for the given path
+ * @param path - the path
+ * @returns the list image
+ */
+const list = (path) => {
+    return `${imageRoot}/list${path}`;
+};
+exports.list = list;
+/**
+ * Returns the network image for the given chain id
+ * @param chainId - the chain id
+ * @returns the network image
+ */
+const network = (chainId) => `${imageRoot}/image/${Number(chainId)}`;
+exports.network = network;
+/**
+ * gib.show's own key for a chain this package can only name by a LOCAL,
+ * INVENTED identifier — a pay-by-hand origin (see `depositAddressChainIds`)
+ * rather than a real chain id gib.show's numeric endpoint recognizes.
+ * `network(chainId)` 404s for one of these, and the browser draws that 404 as
+ * a broken image on every chain badge and route mark drawn through it.
+ *
+ * Every route producer that draws a chain badge for a token needs this, not
+ * only the deposit-address ones: a route can START on a deposit-address chain
+ * and cross through ordinary Ethereum-Virtual-Machine chains after, so the
+ * predicate has to run on every chain id a route touches, not only the one
+ * the reader picked. Kept beside `network` rather than in the client that also
+ * resolves Relay's pseudo chains (`@gibs/bridge-client/image`'s
+ * `chainLogoUrl`) because that client sits ABOVE this package — it imports
+ * FROM `bridge-sdk` — so this package importing back from it would be a
+ * cycle. `chainLogoUrl` still adds a Relay-icon fallback for chains gib.show
+ * does not carry at ALL (Eclipse, Hyperliquid); this table is only the
+ * chains gib.show DOES carry, under a key other than their numeric id.
+ *
+ * EXPORTED, and this is the ONLY place a pay-by-hand chain's gib.show key is
+ * declared. `@gibs/bridge-client`'s `image.ts` used to hard-code its own copy
+ * of the same `zcash → 'bip122-133'` entry; it now spreads this map into its
+ * own icon table instead, because the dependency runs one way — the client
+ * already imports from this package — so there was never a cycle stopping it.
+ */
+exports.pseudoChainGibShowIdentifierByChain = {
+    zcash: 'bip122-133',
+};
+/** {@link pseudoChainGibShowIdentifierByChain}, keyed by chain id for lookup. */
+exports.pseudoChainGibShowIdentifier = Object.fromEntries(Object.keys(chain_names_js_1.depositAddressChainIds).map((chain) => [
+    chain_names_js_1.depositAddressChainIds[chain],
+    exports.pseudoChainGibShowIdentifierByChain[chain],
+]));
+/**
+ * The network image for a chain id, honouring a pseudo chain's own gib.show
+ * key when its numeric id is not one gib.show's `/image/<id>` endpoint knows.
+ *
+ * @param chainId - the chain id, a deposit-address chain's local identifier included
+ * @returns a working network/chain-badge image url
+ */
+const networkOrPseudo = (chainId) => {
+    const identifier = exports.pseudoChainGibShowIdentifier[chainId];
+    return identifier !== undefined ? `${imageRoot}/image/${identifier}` : (0, exports.network)(chainId);
+};
+exports.networkOrPseudo = networkOrPseudo;
+/**
+ * Returns the image url for the given token info.
+ *
+ * The gas token is asked for by BOTH of its keys, because the service keys it
+ * two ways and each chain carries only one of them. `<chain>/<zero address>` is
+ * a dedicated picture — Ethereum's ether diamond, PulseChain's mark — and
+ * Binance Smart Chain has none, so asking for it there returns a 404 the browser
+ * draws as a broken image. The empty-address form `<chain>/` is the chain's own
+ * mark, which every chain has.
+ *
+ * The order is NOT interchangeable. The service serves the first source that
+ * resolves, so a chain with a dedicated picture keeps it; reversed, Ethereum
+ * would show the network logo where the ether logo belongs (the two are
+ * genuinely different files). The pair is for the gas token alone: pairing an
+ * ordinary contract address with the chain mark would hide a missing token logo
+ * behind the network's, showing the wrong token rather than an honest fallback.
+ *
+ * @param t - the token info
+ * @returns the image url
+ */
+const image = (t) => {
+    if (t.logoURI)
+        return t.logoURI;
+    if ((0, ecosystems_js_1.isNativeAsset)(t.address, 'evm')) {
+        return (0, exports.images)([`${Number(t.chainId)}/${viem_1.zeroAddress}`, `${Number(t.chainId)}/`]);
+    }
+    return `${(0, exports.network)(t.chainId)}/${(0, viem_1.getAddress)(t.address)}`;
+};
+exports.image = image;
+/**
+ * Whether `address` is a real Ethereum-Virtual-Machine address {@link image}
+ * can ask the service about — the zero address included, since that is
+ * {@link isNativeAsset}'s own case and {@link image} handles it without
+ * `getAddress` ever running.
+ *
+ * @param address - the address to check
+ * @returns true when `getAddress` can checksum it without throwing
+ */
+const isResolvableEvmAddress = (address) => /^0x[0-9a-fA-F]{40}$/.test(address);
+/**
+ * {@link image}, but falling back to the token's own CHAIN mark rather than
+ * throwing or asking the service for a picture that was never going to exist,
+ * when the token carries no address a picture can be resolved from yet.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM `image`. A route producer can reach the
+ * moment it draws a DELIVERED token's picture before that token's exact
+ * on-chain address is known — a not-yet-bridged token's `assetOutAddress` is
+ * documented to arrive `null` (see the repository's own "Not-Yet-Bridged
+ * Tokens" gotcha), and a deferred crossing's landing token is exactly this
+ * case: the reader has not yet signed the leg that would settle it. `image`
+ * either throws (`getAddress` refuses a malformed or empty string) or, for a
+ * caller that swallows the throw, silently draws nothing — the same "blank
+ * disc" defect the carrier marks were fixed for, one token lower. The chain's
+ * own mark is a real, recognisable picture that is honest about what is
+ * known: THIS chain, a token not yet resolved on it — the same trade
+ * `trackerView.ts`'s `depositAddressChainLogoFallback` already makes for a
+ * pay-by-hand ORIGIN with no address of its own.
+ *
+ * @param t - the token to draw
+ * @returns the token's own picture, or its chain's mark when the token's
+ *   address cannot be resolved into one
+ */
+const tokenImageOrChainFallback = (t) => isResolvableEvmAddress(t.address) ? (0, exports.image)(t) : (0, exports.networkOrPseudo)(t.chainId);
+exports.tokenImageOrChainFallback = tokenImageOrChainFallback;
+/**
+ * Returns a url that will lookup all sources for the given array
+ * @param sources - the sources
+ * @returns the images
+ */
+const images = (sources) => `${imageRoot}/image/?${sources.map((s) => `i=${s}`).join('&')}`;
+exports.images = images;

package/dist/cjs/index.d.ts

@@ -0,0 +1,23 @@
+export * from './abis.js';
+export * from './bridge-limits.js';
+export * from './chain-info.js';
+export * from './chains.js';
+export * from './config.js';
+export * from './consolidated-quote.js';
+export * from './relay-quote.js';
+export * from './relay-currencies.js';
+export * from './destination-calldata.js';
+export * from './ecosystems.js';
+export * from './fee-type.js';
+export * from './image-links.js';
+export * from './lifi-execution-guard.js';
+export * from './origin-deposit.js';
+export * from './providers.js';
+export * from './referral.js';
+export * from './route-steps.js';
+export * from './routing/index.js';
+export * from './settings.js';
+export * from './types.js';
+export * from './claims.js';
+export * from './execution.js';
+export * from './relay-depository.js';

package/dist/cjs/index.js

@@ -0,0 +1,39 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./abis.js"), exports);
+__exportStar(require("./bridge-limits.js"), exports);
+__exportStar(require("./chain-info.js"), exports);
+__exportStar(require("./chains.js"), exports);
+__exportStar(require("./config.js"), exports);
+__exportStar(require("./consolidated-quote.js"), exports);
+__exportStar(require("./relay-quote.js"), exports);
+__exportStar(require("./relay-currencies.js"), exports);
+__exportStar(require("./destination-calldata.js"), exports);
+__exportStar(require("./ecosystems.js"), exports);
+__exportStar(require("./fee-type.js"), exports);
+__exportStar(require("./image-links.js"), exports);
+__exportStar(require("./lifi-execution-guard.js"), exports);
+__exportStar(require("./origin-deposit.js"), exports);
+__exportStar(require("./providers.js"), exports);
+__exportStar(require("./referral.js"), exports);
+__exportStar(require("./route-steps.js"), exports);
+__exportStar(require("./routing/index.js"), exports);
+__exportStar(require("./settings.js"), exports);
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./claims.js"), exports);
+__exportStar(require("./execution.js"), exports);
+__exportStar(require("./relay-depository.js"), exports);