@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/cjs/relay-quote.d.ts

@@ -0,0 +1,301 @@
+import { type Hex } from 'viem';
+import { type ConsolidatedQuote, type ConsolidatedQuoteRequest, type ConsolidatedStatus } from './consolidated-quote.js';
+import type { Ecosystem } from './ecosystems.js';
+/**
+ * Relay (relay.link) as a second consolidated-route quote provider, competing
+ * with LI.FI on price. Relay quotes the same backwards-from-destination route:
+ * deliver exactly `toAmount` of the Ethereum-side token, then run our omnibridge
+ * entry call against it.
+ *
+ * One semantic differs from LI.FI and the difference is load-bearing. Relay has
+ * NO destination-chain fallback address. When the destination call cannot fill,
+ * Relay refunds on the ORIGIN chain to `refundTo`, in the origin currency — the
+ * user ends up back where they started, not holding the Ethereum-side token at
+ * a fallback. We therefore map our `fallbackAddress` onto `refundTo`; a failed
+ * Relay route is recovered on the origin chain, never stranded on Ethereum.
+ */
+/**
+ * Relay's API root. Steps carry RELATIVE post endpoints (`/authorize`), so a
+ * caller completing one has to resolve it against this.
+ */
+export declare const relayApiBaseUrl = "https://api.relay.link";
+/** Relay quote endpoint. Anonymous access works at a 50-requests-per-minute tier. */
+export declare const relayQuoteUrl = "https://api.relay.link/quote/v2";
+/** Relay requests endpoint; filters by origin or destination transaction hash. */
+/**
+ * The request-lookup endpoint, used to poll a route's progress.
+ *
+ * v3 RATHER THAN v2 BECAUSE v2 IS GOING AWAY. Relay began staged rate limiting
+ * of `/requests/v2` on 2026-09-01 and retires it on 2026-11-24, saying so in a
+ * `deprecation` block on every v2 response. v3 REQUIRES `x-api-key` - it
+ * answers 400 without one, where v2 served anonymous callers from a shared
+ * pool - so a caller must send `relayRequestHeaders(yourRelayApiKey)`.
+ */
+export declare const relayRequestsUrl = "https://api.relay.link/requests/v3";
+/**
+ * Builds the headers for a Relay request. `apiKey` is Relay's `x-api-key`
+ * value. This package ships no key: the caller supplies its own (the Gibs
+ * interface keeps its key in `packages/ui/src/lib/config.ts`).
+ * Relay raises the account's rate limit and attributes traffic to it when the
+ * header is present.
+ *
+ * When `apiKey` is absent or an empty string, the returned headers carry NO
+ * `x-api-key` entry at all — not an empty one.
+ *
+ * WHETHER THAT IS SURVIVABLE DEPENDS ENTIRELY ON WHICH ENDPOINT IS BEING CALLED,
+ * and this note used to say only the reassuring half. Measured against the live
+ * service:
+ *
+ *     POST /quote            no key -> 200   routing works anonymously
+ *     GET  /requests/v3      no key -> 400   "headers must have required
+ *                                             property 'x-api-key'"
+ *
+ * So a missing key is a normal operating state for ROUTING — a reader on a
+ * local build or the anonymous InterPlanetary File System deployment still gets
+ * real quotes, and clearing the key disables attribution rather than the
+ * product. It is NOT survivable for STATUS. Every status poll from a keyless
+ * build fails, which means a consolidated record never learns its provider
+ * finished, never records the entry-chain transaction, and never releases from
+ * the pending list. That is not a degraded rate limit; it is the feature not
+ * working at all, silently.
+ */
+export declare const relayRequestHeaders: (apiKey?: string) => Record<string, string>;
+/**
+ * Gibs Finance's own Relay `referrer`, for callers that want to attribute to
+ * Gibs Finance. The request builders do NOT default to it: pass it, or your
+ * own, as `relayReferrer` on the request. Relay reads any `referrer` as "a
+ * referrer was supplied" and then requires an API key, so a default would
+ * break every caller without one.
+ */
+export declare const relayReferrer = "gibs.finance";
+/**
+ * Application fee in basis points charged on Relay routes. Ten basis points is
+ * one tenth of a percent. Sent as `appFees[0].fee` when a payout recipient is
+ * configured; absent entirely when the recipient is missing.
+ */
+export declare const relayReferralFeeBasisPoints = 10n;
+export { relayReferralRecipient } from './referral.js';
+/** Extra gas added to the destination budget to cover a prepended approval call. */
+export declare const relayApprovalGasBuffer = 60000n;
+/**
+ * Relay's chain identifiers and their display names live in `chain-names.ts`
+ * so the route-step normalizer can name a Relay chain without importing this
+ * module, which imports it. Re-exported here because callers reach for them
+ * alongside the rest of the Relay surface.
+ */
+export { relayChainIds, relayChainNames } from './chain-names.js';
+/**
+ * Maps a chain identifier to its virtual-machine ecosystem. Relay's non-Ethereum
+ * pseudo chain identifiers map to their own ecosystem; every other identifier
+ * (every Ethereum Virtual Machine chain) maps to `evm`. Total — never throws.
+ *
+ * Lives here rather than in `ecosystems.ts` because it depends on
+ * `relayChainIds` (defined in this file); the `Ecosystem` import is type-only,
+ * so `ecosystems.ts` stays a dependency-free leaf and no import cycle is formed.
+ *
+ * @param chainId - a chain identifier (an Ethereum chain id, or a Relay pseudo id)
+ * @returns the ecosystem that chain belongs to
+ */
+export declare const ecosystemByChainId: (chainId: number) => Ecosystem;
+/**
+ * Relay's native-currency address strings, used verbatim as `originCurrency`
+ * when the origin pays in the chain's native asset.
+ *
+ * Source: https://api.relay.link/chains.
+ */
+export declare const relayNativeCurrencyAddresses: {
+    /**
+     * Ethereum Virtual Machine native currency (Ether, native gas tokens). The
+     * all-zero address Relay uses across every Ethereum Virtual Machine chain.
+     */
+    readonly ethereumVirtualMachine: "0x0000000000000000000000000000000000000000";
+    /**
+     * Solana native currency (SOL), addressed by the System Program. Nine
+     * decimals.
+     */
+    readonly solana: "11111111111111111111111111111111";
+    /** Bitcoin native currency (BTC). Eight decimals. */
+    readonly bitcoin: "bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8";
+    /** Tron native currency (TRX). Six decimals. */
+    readonly tron: "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb";
+    /**
+     * The Open Network's native currency as Relay reports it: Gram, NOT the
+     * Toncoin gas asset. Nine decimals.
+     */
+    readonly ton: "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c";
+    /**
+     * Hyperliquid's native currency as Relay reports it: USD Coin, NOT the Hype
+     * gas asset, addressed by a sixteen-byte HyperCore token identifier. Eight
+     * decimals. Deliberately NOT the twenty-byte all-zero Ethereum address.
+     */
+    readonly hyperliquid: "0x00000000000000000000000000000000";
+};
+/**
+ * Relay's solving direction for a quote.
+ *
+ * - `EXACT_OUTPUT` — solve BACKWARD to a fixed delivered amount; this is what
+ *   the consolidated route uses, because the omnibridge entry call encodes a
+ *   fixed anchor amount that must arrive exactly.
+ * - `EXACT_INPUT` — solve FORWARD from a fixed input amount; this is what the
+ *   two-phase pre-quote uses to LEARN the delivered anchor amount for a fixed
+ *   user input before building the EXACT_OUTPUT execution quote.
+ */
+export type RelayTradeType = 'EXACT_OUTPUT' | 'EXACT_INPUT';
+/** One destination transaction in a Relay quote request. */
+export type RelayTransaction = {
+    to: Hex;
+    value: string;
+    data: Hex;
+};
+/** The JSON body for `POST /quote/v2` with attached destination calls. */
+export type RelayQuoteRequestBody = {
+    /**
+     * The user's origin-chain address. Typed as `string` because a non-Ethereum
+     * origin (Solana base58, Bitcoin bech32) supplies a non-`Hex` address here.
+     */
+    user: string;
+    originChainId: number;
+    /**
+     * The origin currency address. Typed as `string` because a non-Ethereum
+     * origin's native currency address (Solana System Program, Bitcoin native) is
+     * not `Hex`.
+     */
+    originCurrency: string;
+    destinationChainId: number;
+    /** The Ethereum-side entry-chain token; always an Ethereum Virtual Machine address. */
+    destinationCurrency: Hex;
+    amount: string;
+    tradeType: RelayTradeType;
+    /**
+     * Origin-chain refund address; without it Relay disables automatic refunds.
+     * Typed as `string` because for a non-Ethereum origin the refund lands on the
+     * origin chain and so carries that chain's (non-`Hex`) address.
+     */
+    refundTo: string;
+    /** Omitted unless the request names a `relayReferrer`. */
+    referrer?: string;
+    /**
+     * Where the funds land, for a route that names no transaction to run.
+     *
+     * A route into the omnibridge carries its recipient INSIDE the entry call's
+     * calldata, so this is absent there and Relay delivers to the executor that
+     * performs the call. A direct route has no call, so the recipient has to be
+     * said out loud.
+     */
+    recipient?: Hex;
+    /**
+     * The calls the executor performs on arrival, in order.
+     *
+     * Absent on a direct route. Its presence is what tells Relay this is a
+     * deliver-and-call rather than a plain transfer, so an empty array would be a
+     * different request from an omitted field and must not be sent instead.
+     */
+    txs?: RelayTransaction[];
+    /** Aggregate gas budget across every entry in `txs`. Absent when `txs` is. */
+    txsGasLimit?: number;
+    /** Maximum slippage in basis points (50 means half a percent). */
+    slippageTolerance?: string;
+    /**
+     * Solana fee-payer address that sponsors the deposit transaction's fee. Only
+     * present for a Solana origin; omitted entirely for every other origin.
+     */
+    depositFeePayer?: string;
+    /**
+     * Extra data Relay needs for non-Ethereum deposits. Only the Bitcoin
+     * pay-to-script-hash public key is carried today, and only for a Bitcoin
+     * origin; omitted entirely otherwise.
+     */
+    additionalData?: {
+        /** The Bitcoin pay-to-script-hash public key. */
+        userPublicKey?: string;
+    };
+    /**
+     * Application fees collected by the integrator. Each entry names a payout
+     * recipient and a rate in basis points (as a string). Omitted entirely when
+     * no recipient is configured — Relay rejects a recipient-less fee entry.
+     */
+    appFees?: Array<{
+        recipient: string;
+        fee: string;
+    }>;
+};
+/**
+ * Converts a slippage fraction into the basis-point string Relay expects.
+ *
+ * @param slippage - tolerance as a fraction (0.005 means half a percent)
+ * @returns basis points as a string (0.005 becomes "50")
+ */
+export declare const slippageToBasisPoints: (slippage: number) => string;
+/**
+ * The `referrer` field of a Relay request body, present only when the caller
+ * named one. Relay reads any `referrer`, an empty one included, as "a referrer
+ * was supplied" and then requires an API key, so absence is the safe default.
+ *
+ * @param request - carries the caller's `relayReferrer`, if any
+ * @returns `{ referrer }`, or an empty object
+ */
+export declare const relayReferrerField: (request: {
+    relayReferrer?: string | null;
+}) => {
+    referrer?: string;
+};
+/**
+ * Builds the Relay contract-call quote request from a provider-agnostic
+ * consolidated request. The omnibridge entry call becomes the final `txs`
+ * entry; when it needs an ERC20 allowance (the relayTokens shape, where
+ * `approvalTarget` is set) an `approve` call is prepended so Relay's executor
+ * grants it before relaying.
+ *
+ * @returns the request body, or null when the inputs cannot form a valid call
+ */
+export declare const buildRelayQuoteRequest: (request: ConsolidatedQuoteRequest) => RelayQuoteRequestBody | null;
+/**
+ * Normalizes a Relay `/quote/v2` response into the shared consolidated quote
+ * shape. The origin approval Relay returns as its own step is folded back into
+ * `approvalAddress` so the executor raises it through the same path as LI.FI;
+ * the deposit step becomes the single `originDeposit`.
+ *
+ * @returns the normalized quote, or null when the payload shape is unexpected
+ */
+export declare const parseRelayQuote: (payload: unknown) => ConsolidatedQuote | null;
+/**
+ * Builds the requests-lookup address for a Relay route BY ITS QUOTE
+ * IDENTIFIER.
+ *
+ * IT USED TO ASK BY ORIGIN TRANSACTION HASH, AND THAT RETURNED OTHER PEOPLE'S
+ * TRANSFERS. `/requests/v3` does not accept a `hash` filter: it ignores the
+ * parameter entirely and answers with the twenty most recent requests ACROSS
+ * ALL USERS. Measured, with two different origin hashes a minute apart:
+ *
+ *     ?hash=0x447149ed…  -> 20 requests, first is 8453:0x7d7c3de2… -> 4663:…
+ *     ?hash=0xa650d2d7…  -> the SAME 20 requests, same first entry
+ *
+ * `parseRelayStatus` reads `requests[0]`, so both of this account's transfers
+ * were updated from a stranger's — they took the same entry-chain transaction
+ * hash, and neither was their own. A transfer was reported finished because
+ * somebody else's had finished.
+ *
+ * `id` is the filter v3 actually honours. The same lookup by quote identifier
+ * returns exactly ONE request, and its `inTxs` name the origin transaction the
+ * reader really signed. The caller should assert that correspondence rather
+ * than trust it — see `checkConsolidatedRecord`.
+ */
+export declare const relayStatusUrl: ({ quoteId }: {
+    quoteId: string;
+}) => string;
+/**
+ * Maps a Relay request status onto the provider-agnostic consolidated status.
+ * `success` reports `DONE`/`COMPLETED` because for this route the destination
+ * fill IS our omnibridge entry call; `refund` reports `DONE`/`REFUNDED` because
+ * the user was made whole on the origin chain. Relay never strands funds on
+ * Ethereum, so the partial/stranded status LI.FI can return has no analogue.
+ *
+ * @param payload - a `/requests/v2?hash=` response body
+ * @param options.destinationChainId - the omnibridge entry chain the route
+ *   targeted (Ethereum or Binance Smart Chain); defaults to Ethereum,
+ *   preserving the original single-entry behavior
+ * @returns the normalized status, or null when no matching request is present
+ */
+export declare const parseRelayStatus: (payload: unknown, { destinationChainId }?: {
+    destinationChainId?: number;
+}) => ConsolidatedStatus | null;