@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/near-intents.js

@@ -0,0 +1,1055 @@
+import { arbitrum, avalanche, base, bsc, gnosis, mainnet, optimism, polygon, scroll, } from 'viem/chains';
+import { encodeFunctionData, erc20Abi, isAddress } from 'viem';
+import { depositAddressChainIds, isDepositAddressChain, relayChainIds, } from './chain-names.js';
+import { isNativeAsset, isValidAddressIn, sameAddress } from './ecosystems.js';
+import { ecosystemByChainId } from './relay-quote.js';
+import { resolveAttribution } from './referral.js';
+/**
+ * NEAR Intents, through its "one click" quoting service.
+ *
+ * THIS PROVIDER CANNOT EXECUTE ON THE DESTINATION CHAIN, AND IS REGISTERED
+ * ANYWAY. Read both halves of that before changing anything here.
+ *
+ * The service validates its request body against a closed property list and
+ * answers `property destinationCall should not exist` for every name a call
+ * could travel under — `destinationCall`, `calldata`, `msg`, `txs`, `hook`,
+ * `action`, `postSwapAction`. The only thing nameable on the destination side
+ * is an address: `recipient`, with a `recipientType` of `DESTINATION_CHAIN`,
+ * `INTENTS` or `CONFIDENTIAL_INTENTS`. That is measured, not inferred from
+ * silence. `docs/near-intents-capability-survey.md` holds the evidence.
+ *
+ * DELIVERING TO THE MEDIATOR INSTEAD IS NOT A WAY AROUND IT, and the reason is
+ * structural rather than a matter of configuration. The service will happily
+ * deliver to a contract — a quote naming a well-known router as `recipient` is
+ * accepted. But every omnibridge entry point learns WHO THE READER IS from a
+ * data field: `transferAndCall` carries the recipient in its third argument,
+ * `relayTokens` in its second, `wrapAndRelayTokens` in its first. A plain
+ * token transfer has no data field. So a bare arrival cannot name a recipient,
+ * which means it can only ever credit the sender — the solver — or nobody at
+ * all. Do not attempt it.
+ *
+ * SO THE ROUTE TAKES TWO SIGNATURES, and the interface says so on the route
+ * strip rather than in a tooltip. The reader signs the origin transfer; NEAR
+ * Intents lands the anchor token in THEIR OWN WALLET on the entry chain; then
+ * they sign the ordinary bridge leg themselves. `near-intents-route.ts` builds
+ * that shape, and `executesDestinationCalls: false` on the descriptor is what
+ * keeps this provider out of the single-signature machinery, including the
+ * entry-anchor pre-quote — that phase feeds an exact-output target to the
+ * providers that DO execute, and a target only a non-executing provider can
+ * reach is a target nobody can fill.
+ *
+ * TWO SIZE FLOORS MAKE THIS A ROUTING RULE, NOT A FOOTNOTE. Binance Smart
+ * Chain — one of the two omnibridge entry chains — refuses any transfer worth
+ * one thousand United States dollars or less, in either direction, and Polygon
+ * and Tron carry floors of their own. The service imposed these on 2026-09-09
+ * and calls them temporary. Only asking reveals them, so a route has to be
+ * WITHDRAWN on a refusal rather than left to fail: see
+ * {@link NearIntentsQuoteRefusal} and `near-intents-route.ts`.
+ */
+/** Base address for the NEAR Intents one-click service. */
+export const nearIntentsApiBaseUrl = 'https://1click.chaindefuser.com';
+/** Quote endpoint. Verified live: no key required, and a key-less request is answered in full. */
+export const nearIntentsQuoteUrl = `${nearIntentsApiBaseUrl}/v0/quote`;
+/** The list of assets the service can carry, keyed by its own asset identifiers. */
+export const nearIntentsTokensUrl = `${nearIntentsApiBaseUrl}/v0/tokens`;
+/**
+ * Optional notification that the reader's deposit has been sent. The service
+ * detects the deposit on its own; telling it the transaction hash only makes
+ * the detection faster. Takes `{ txHash, depositAddress }`.
+ */
+export const nearIntentsDepositSubmitUrl = `${nearIntentsApiBaseUrl}/v0/deposit/submit`;
+/**
+ * What a key-less request costs, in basis points of the input amount.
+ *
+ * NOT A FEE THIS CODE CHARGES OR CAN DECLINE. The service inserts it into the
+ * echoed request as an `appFees` entry payable to its own account whenever no
+ * key is presented, so a reader on a key-less route pays a quarter of a percent
+ * that no part of this repository asked for. It is named here so the parser can
+ * surface it as a charge rather than let it disappear into the delivered
+ * amount. A partner key reduces it; obtaining one is an owner decision.
+ */
+export const nearIntentsUnauthenticatedFeeBasisPoints = 25;
+/**
+ * What a partner-key request costs instead, in basis points of the input
+ * amount, for an ordinary (non-stablecoin) pair.
+ *
+ * Read from the service's own current documentation on 2026-09-18:
+ * `docs.near-intents.org/integration/distribution-channels/1click-api/authentication`.
+ * See `docs/near-intents-partner-key.md` for the full process of obtaining a
+ * key and what else changes once one is configured.
+ */
+export const nearIntentsAuthenticatedFeeBasisPoints = 20;
+/**
+ * What a partner-key request costs on a stablecoin pair or a same-asset
+ * multi-chain route, in basis points of the input amount.
+ *
+ * Read from the same page as {@link nearIntentsAuthenticatedFeeBasisPoints} on
+ * 2026-09-18. Kept as its own constant rather than a special case of the other
+ * one because the service documents it as a distinct figure for a distinct
+ * class of route, not a discount computed from the ordinary rate.
+ */
+export const nearIntentsAuthenticatedStablecoinFeeBasisPoints = 1;
+/**
+ * Builds the status-poll address for one quote.
+ *
+ * The deposit address IS the lookup key here, unlike every other provider in
+ * this repository, which key by a request identifier. Each quote is issued its
+ * own deposit address, so the two are one and the same fact — see
+ * {@link parseNearIntentsQuote}, which puts the deposit address in `quoteId`
+ * for exactly this reason.
+ *
+ * @param options.quoteId - the quote's deposit address
+ * @returns the fully-formed status address
+ */
+export const nearIntentsStatusUrl = ({ quoteId }) => {
+    const url = new URL(`${nearIntentsApiBaseUrl}/v0/status`);
+    url.searchParams.set('depositAddress', quoteId);
+    return url.toString();
+};
+/**
+ * What this repository calls itself when it asks the one-click service.
+ *
+ * SENT BECAUSE THE SERVICE REFUSES SOME CALLERS BY NAME, and until now the
+ * name was whatever the runtime happened to supply. The service sits behind
+ * Cloudflare, which answers a refused caller with HTTP 403 and a body reading
+ * `error code: 1010` — a page, not a quote, so a parser sees a shape it cannot
+ * read and the whole provider looks like an outage.
+ *
+ * MEASURED against the live quote endpoint on 2026-09-21, one identical body,
+ * one header changed:
+ *
+ * | user agent                | answer |
+ * | ------------------------- | ------ |
+ * | none (Node 26 default)    | 201    |
+ * | `undici`                  | 201    |
+ * | `node`                    | 201    |
+ * | `curl/8.7.1`              | 201    |
+ * | `python-requests/2.32`    | 201    |
+ * | `Python-urllib/3.14`      | 403    |
+ * | this value                | 201    |
+ *
+ * So nothing is blocked today. The point is that whether we are blocked was
+ * being decided by a list we do not control, matched against a string we never
+ * chose — and a runtime upgrade could change that string without anyone here
+ * touching a line. Naming ourselves fixes the input to that decision.
+ *
+ * A BROWSER IGNORES THIS, and that is fine. `User-Agent` is a forbidden header
+ * name for `fetch`, so the browser drops it silently and sends its own. The
+ * value therefore governs Node alone: the live test harness, the deposit
+ * poller, and any script written later.
+ */
+export const nearIntentsUserAgent = 'gibs-bridge/1.0 (+https://gibs.finance)';
+/**
+ * Request headers for the one-click service.
+ *
+ * THE KEY IS A JSON WEB TOKEN, NOT A PLAIN IDENTIFIER LIKE RELAY'S. The
+ * service's own documentation accepts it as `Authorization: Bearer` as well as
+ * `X-API-Key`, calls it a "JWT token" throughout, and tells an integrator to
+ * "store your JWT token securely and never commit it to version control. Use
+ * environment variables or secure secret management systems." Relay's
+ * documentation says none of that about its key. `X-API-Key` is the form sent
+ * here because the service accepts it and it matches the header name Relay
+ * already uses, so one code path serves both — but the caller of this
+ * function decides where the value comes from, and that decision is where the
+ * secrecy question has to be answered. See `packages/ui/src/lib/config.ts`
+ * and `docs/near-intents-partner-key.md`.
+ *
+ * THE DEFAULT `User-Agent` NAMES GIBS FINANCE, AND THAT COSTS A CALLER
+ * NOTHING: it carries no key and no rate-limit budget, and a browser drops it.
+ * Pass `options.userAgent` to name yourself instead, or `null` to send none and
+ * let the runtime use its own.
+ *
+ * @param apiKey - a partner key, when one is configured
+ * @param options - `userAgent`: your own value, or `null` for none (defaults to {@link nearIntentsUserAgent})
+ * @returns the headers, carrying the key only when there is one to carry
+ */
+export const nearIntentsRequestHeaders = (apiKey, options = {}) => {
+    const userAgent = resolveAttribution(options.userAgent, nearIntentsUserAgent);
+    return {
+        'Content-Type': 'application/json',
+        ...(userAgent === undefined ? {} : { 'User-Agent': userAgent }),
+        ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+    };
+};
+/**
+ * This repository's chain identifiers, keyed by the service's short chain name.
+ *
+ * The Ethereum-virtual-machine entries are read from viem rather than written
+ * down, because a chain identifier typed from memory is a hypothesis that every
+ * later reader will trust — and a wrong one here does not fail loudly, it
+ * simply quotes a different chain's token.
+ *
+ * The non-Ethereum entries are this repository's own identifiers for those
+ * families, which are Relay's numbers (see {@link relayChainIds}); the service
+ * uses short names and has no numeric identifier of its own to reconcile with.
+ *
+ * DELIBERATELY SHORTER THAN THE SERVICE'S CHAIN LIST. The service names about
+ * thirty-five chains. Only the ones this bridge can actually originate from or
+ * enter are listed, because an unlisted chain resolves to no asset and
+ * therefore to no route, which is the honest outcome, whereas a guessed
+ * identifier resolves to a route on the wrong chain.
+ */
+export const chainIdByNearIntentsChain = new Map([
+    ['eth', mainnet.id],
+    ['bsc', bsc.id],
+    ['base', base.id],
+    ['arb', arbitrum.id],
+    ['op', optimism.id],
+    ['pol', polygon.id],
+    ['avax', avalanche.id],
+    ['gnosis', gnosis.id],
+    ['scroll', scroll.id],
+    ['sol', relayChainIds.solana],
+    ['btc', relayChainIds.bitcoin],
+    ['tron', relayChainIds.tron],
+    ['ton', relayChainIds.ton],
+    ['hypercore', relayChainIds.hyperliquid],
+    // THE ONE ENTRY WITH NO WALLET BEHIND IT. Zcash is not a Relay chain and not
+    // a LI.FI chain; this repository names it itself, in `chain-names.ts`, so
+    // that a route from it can be priced and drawn. The reader pays the address
+    // this service issues, by hand, from wherever they hold the coin.
+    ['zec', depositAddressChainIds.zcash],
+]);
+const asRecord = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    return value;
+};
+/**
+ * Reads `GET /v0/tokens` into the asset records the identifier lookup needs.
+ *
+ * An entry missing any field the lookup reads is dropped rather than patched
+ * with a default: an asset whose decimals were invented would price every
+ * amount wrong by orders of magnitude, and an asset whose identifier is
+ * missing cannot be quoted at all.
+ *
+ * @param payload - the raw JSON body from `GET /v0/tokens`
+ * @returns every readable asset, in the order the service listed them
+ */
+export const parseNearIntentsTokens = (payload) => {
+    if (!Array.isArray(payload)) {
+        return [];
+    }
+    const assets = [];
+    for (const entry of payload) {
+        const record = asRecord(entry);
+        if (!record) {
+            continue;
+        }
+        const { assetId, blockchain, symbol, decimals, contractAddress, price, priceUpdatedAt } = record;
+        if (typeof assetId !== 'string' || typeof blockchain !== 'string') {
+            continue;
+        }
+        if (typeof symbol !== 'string' || typeof decimals !== 'number') {
+            continue;
+        }
+        assets.push({
+            assetId,
+            blockchain,
+            symbol,
+            decimals,
+            contractAddress: typeof contractAddress === 'string' ? contractAddress : null,
+            price: typeof price === 'number' && Number.isFinite(price) ? price : null,
+            priceUpdatedAt: typeof priceUpdatedAt === 'string' ? priceUpdatedAt : null,
+        });
+    }
+    return assets;
+};
+/**
+ * Finds the service's identifier for one token on one chain.
+ *
+ * THE IDENTIFIER CANNOT BE CONSTRUCTED, ONLY LOOKED UP. It reads like a
+ * pattern — a chain name, the token's address, a fixed suffix — and for an
+ * Ethereum-virtual-machine token it currently is one. It is not one for the
+ * other families: Solana's USD Coin carries a hexadecimal handle that is
+ * nothing like its base58 mint. Building the string from its parts therefore
+ * produces an identifier that is well-formed and refers to nothing, so the
+ * asset list is the only source.
+ *
+ * @param options.assets - the parsed asset list
+ * @param options.chainId - this repository's identifier for the chain
+ * @param options.tokenAddress - the token's address on that chain
+ * @param options.ecosystem - the chain's virtual-machine family, which decides
+ *   whether the native-coin test and the address comparison are meaningful
+ * @returns the matching asset, or null when the service does not carry it
+ */
+export const findNearIntentsAsset = ({ assets, chainId, tokenAddress, ecosystem, }) => {
+    const onChain = assets.filter((asset) => chainIdByNearIntentsChain.get(asset.blockchain) === chainId);
+    if (onChain.length === 0) {
+        return null;
+    }
+    if (isNativeAsset(tokenAddress, ecosystem)) {
+        return onChain.find((asset) => asset.contractAddress === null) ?? null;
+    }
+    // Only an Ethereum-virtual-machine chain reports a token's real address here,
+    // so a match on any other family would be a coincidence of hexadecimal.
+    if (ecosystem !== 'evm') {
+        return null;
+    }
+    const match = onChain.find((asset) => asset.contractAddress !== null && sameAddress(asset.contractAddress, tokenAddress, 'evm'));
+    return match ?? null;
+};
+/**
+ * How far ahead the requested refund deadline is set, in milliseconds.
+ *
+ * WHAT IS SENT, NOT WHAT COMES BACK. The service does not honour this value: it
+ * returns a `deadline` of exactly three days after the one asked for, and
+ * returns `timeWhenInactive` equal to that same instant rather than to the
+ * earlier moment the documentation describes. Both are visible in the checked-in
+ * capture — asked 2026-09-17T23:49:52.805Z, answered 2026-09-20T23:49:52.805Z.
+ *
+ * So anything that needs the real clock must read `quote.deadline` off the
+ * answer. Reading `quoteRequest.deadline` back gives this number, which is the
+ * request echoed, not a commitment; and treating `deadline` and
+ * `timeWhenInactive` as two milestones reads a distinction the service is not
+ * currently making.
+ */
+const defaultDeadlineMilliseconds = 30 * 60 * 1000;
+/**
+ * Slippage THIS MODULE sends when the caller states none, in basis points.
+ *
+ * Not a default the service holds. `slippageTolerance` is a required property —
+ * the service rejects a request without it — so there is no "leave it to them"
+ * option here as there is with the other providers, and one percent is a value
+ * chosen on this side.
+ */
+const defaultSlippageBasisPoints = 100;
+/**
+ * Converts a slippage fraction into the basis points the service expects.
+ *
+ * @param slippage - tolerance as a fraction (0.005 means half a percent)
+ * @returns basis points (0.005 becomes 50)
+ */
+export const slippageToNearIntentsBasisPoints = (slippage) => Math.round(slippage * 10_000);
+/**
+ * Reads the build inputs out of the shared provider context.
+ *
+ * Returns null when the asset list is absent, and that is not a defensive
+ * check — without the list no asset identifier can be resolved, so there is no
+ * request to form. Answering null leaves the route to the providers that can
+ * express it, which is the same thing every other builder here does when it
+ * cannot express a request.
+ */
+const buildOptionsFrom = (context, { dry }) => {
+    const assets = context?.nearIntentsAssets;
+    if (assets === undefined || assets.length === 0) {
+        return null;
+    }
+    return { assets, now: context?.now ?? new Date(), referral: context?.referral, dry };
+};
+/**
+ * Where a refund goes, and it is a different answer for a chain the reader
+ * cannot sign on.
+ *
+ * THE ORDINARY CASE. A refund lands back on the ORIGIN chain, at the reader's
+ * own origin-chain address — never the delivery address, which could not
+ * receive one there.
+ *
+ * THE PAY-BY-HAND CASE, WHICH IS THE WHOLE REASON THIS FLOW IS POSSIBLE. A
+ * reader with no Zcash wallet has no Zcash address to refund to, and
+ * `refundType` offers no destination-chain option: the three values are
+ * `ORIGIN_CHAIN`, `INTENTS` and `CONFIDENTIAL_INTENTS`. `INTENTS` credits the
+ * refund to a ledger row inside the settlement contract `intents.near`, and the
+ * row may be named for the reader's own Ethereum address, which the same
+ * Ethereum key controls. So the reader types nothing, and the refund fee falls
+ * from 32,000 base units to zero: crediting a balance inside a contract needs
+ * no Zcash transaction. `docs/near-implicit-account-refunds.md` checks the
+ * claim at the protocol level.
+ *
+ * TWO TRAPS, BOTH MEASURED, BOTH CAPABLE OF COSTING SOMEBODY THEIR MONEY.
+ *
+ * FIRST, LOWER CASE IS NOT COSMETIC. The account name must be lower case. The
+ * same address in its checksummed spelling is refused outright with `refundTo
+ * is not valid` — the capture is
+ * `__fixtures__/near-intents/quote-error-zcash-refund-mixed-case.json`.
+ *
+ * SECOND, ACCEPTANCE PROVES NOTHING. On the intents path the service checks
+ * only that the string looks like a NEAR account name — the literal
+ * `not-an-address-at-all` quotes happily. A wrong value therefore passes
+ * quoting and is discovered only when a swap is refunded to nobody. That is
+ * why this reads `connectedEthereumAccount`, whose contract is that it comes
+ * from the wallet connection, and why it builds nothing when that is absent
+ * or is not an Ethereum address.
+ *
+ * @param options.fromChainId - the origin chain
+ * @param options.fromAddress - the reader's address on the origin chain
+ * @param options.connectedEthereumAccount - the reader's connected Ethereum account
+ * @returns the two refund properties, or null when a pay-by-hand route has no
+ *   connected Ethereum account to name
+ */
+const refundFields = ({ fromChainId, fromAddress, connectedEthereumAccount, }) => {
+    if (!isDepositAddressChain(fromChainId)) {
+        return { refundTo: fromAddress, refundType: 'ORIGIN_CHAIN' };
+    }
+    if (connectedEthereumAccount === undefined || !isAddress(connectedEthereumAccount)) {
+        return null;
+    }
+    return { refundTo: connectedEthereumAccount.toLowerCase(), refundType: 'INTENTS' };
+};
+/**
+ * The smallest Zcash deposit that can actually be credited, in base units:
+ * 0.01 Zcash.
+ *
+ * THE LARGER OF TWO FIGURES THAT DISAGREE. The quoting service prices a Zcash
+ * input down to about two cents — the smaller floor, read live from its
+ * refusal by {@link parseNearIntentsQuoteRefusal}. But Zcash crosses on the
+ * Proof of Authority bridge, not the Omni Bridge, and that bridge publishes
+ * `min_deposit_amount: 1000000` for native Zcash. A quote between the two is
+ * priced by one surface and below the other's floor, so it takes the money and
+ * stalls — and the published stuck-deposit recovery flow is written for the
+ * Omni Bridge, so it does not cover Zcash. Measured 2026-09-21; see
+ * `docs/near-intents-capability-survey.md`.
+ */
+export const zcashWorkingFloorBaseUnits = 1000000n;
+/**
+ * The working floor for each chain a reader pays by hand, in base units of
+ * that chain's native asset, one entry per member of {@link DepositAddressChain}.
+ * Typed on the union rather than on `number` so a pay-by-hand chain added to
+ * {@link depositAddressChainIds} without a floor here is a compile error.
+ */
+const workingFloorBaseUnitsByChain = {
+    zcash: zcashWorkingFloorBaseUnits,
+};
+/** {@link workingFloorBaseUnitsByChain}, keyed by chain id for lookup. */
+const workingFloorByChainId = new Map(Object.keys(depositAddressChainIds).map((chain) => [
+    depositAddressChainIds[chain],
+    workingFloorBaseUnitsByChain[chain],
+]));
+/**
+ * The working floor for a pay-by-hand chain, in base units, or null when the
+ * chain has none registered.
+ *
+ * EXPORTED SO A SCREEN NEVER KEEPS ITS OWN COPY. {@link isBelowWorkingFloor} is
+ * the decision this library enforces when quoting; this is the SAME table,
+ * exposed so a payment screen can PRINT the figure it refuses under instead of
+ * hand-copying the table — a copy that would silently disagree with quoting
+ * the moment a second pay-by-hand chain gets a floor here and not there.
+ *
+ * @param chainId - the origin chain
+ * @returns the floor in base units, or null when the chain has none
+ */
+export const workingFloorFor = (chainId) => workingFloorByChainId.get(chainId) ?? null;
+/**
+ * Whether an amount is below the floor a deposit on this chain can actually
+ * be credited at.
+ *
+ * ASK IT BEFORE ASKING FOR A LIVE QUOTE. The quote request builder already
+ * declines such an amount, so no deposit address is ever issued for money that
+ * would stall. This predicate lets a surface say WHY there is no route, and
+ * what size would work.
+ *
+ * @param options.chainId - the origin chain
+ * @param options.amount - the input, in base units of the origin asset
+ * @returns whether the amount is below that chain's working floor
+ */
+export const isBelowWorkingFloor = ({ chainId, amount, }) => {
+    const floor = workingFloorByChainId.get(chainId);
+    return floor !== undefined && amount < floor;
+};
+/**
+ * Builds the request body every quote and pre-quote shares.
+ *
+ * THE ORIGIN ECOSYSTEM IS DERIVED FROM THE CHAIN ID, NOT ACCEPTED AS AN
+ * ARGUMENT. It used to be read off the request's own `originVmType` while the
+ * pay-by-hand `swapType` decision two lines below read `fromChainId` through
+ * {@link isDepositAddressChain} — two signals that a caller could set to
+ * disagree, most easily by simply leaving `originVmType` unset on a
+ * deposit-address request. `near-intents.test.ts` certified exactly that
+ * contradiction as a valid Zcash request before this was fixed. Deriving both
+ * decisions from the same chain id, in the same function, makes the
+ * disagreement impossible to construct rather than merely unlikely.
+ */
+const buildBody = ({ fromChainId, fromTokenAddress, fromAddress, connectedEthereumAccount, toChainId, toTokenAddress, recipient, amount, swapType, slippage, options, }) => {
+    if (amount <= 0n) {
+        return null;
+    }
+    if (isBelowWorkingFloor({ chainId: fromChainId, amount })) {
+        return null;
+    }
+    const originAsset = findNearIntentsAsset({
+        assets: options.assets,
+        chainId: fromChainId,
+        tokenAddress: fromTokenAddress,
+        ecosystem: ecosystemByChainId(fromChainId),
+    });
+    if (originAsset === null) {
+        return null;
+    }
+    // The delivered side of every route this module can express lands on an
+    // entry chain, which is always an Ethereum Virtual Machine chain.
+    const destinationAsset = findNearIntentsAsset({
+        assets: options.assets,
+        chainId: toChainId,
+        tokenAddress: toTokenAddress,
+        ecosystem: 'evm',
+    });
+    if (destinationAsset === null) {
+        return null;
+    }
+    const refund = refundFields({ fromChainId, fromAddress, connectedEthereumAccount });
+    if (refund === null) {
+        return null;
+    }
+    return {
+        dry: options.dry,
+        // A reader paying by hand gets the flexible band; a reader whose wallet
+        // composes the transfer to the exact base unit does not need one.
+        swapType: isDepositAddressChain(fromChainId) ? 'FLEX_INPUT' : swapType,
+        slippageTolerance: slippage === undefined
+            ? defaultSlippageBasisPoints
+            : slippageToNearIntentsBasisPoints(slippage),
+        originAsset: originAsset.assetId,
+        depositType: 'ORIGIN_CHAIN',
+        destinationAsset: destinationAsset.assetId,
+        amount: amount.toString(),
+        ...refund,
+        recipient,
+        recipientType: 'DESTINATION_CHAIN',
+        deadline: new Date(options.now.getTime() + defaultDeadlineMilliseconds).toISOString(),
+        ...(options.referral === undefined ? {} : { referral: options.referral }),
+    };
+};
+/**
+ * Builds the forward-solving origin-to-anchor pre-quote body.
+ *
+ * READ THE HEAD OF THIS MODULE BEFORE CALLING THIS FROM THE ROUTER. The
+ * entry-anchor pre-quote takes the largest delivered amount across providers
+ * and hands it to the providers that execute, so a pre-quote from a provider
+ * that cannot execute raises a target nobody can reach. This builder exists
+ * because the request shape is real and testable, not because that wiring is
+ * wanted.
+ *
+ * @param request - the provider-agnostic pre-quote request
+ * @param options - the asset list, the clock, and the referral tag
+ * @returns the request body, or null when the service carries neither asset or
+ *   the amount is not positive
+ */
+export const buildNearIntentsPreQuoteRequest = (request, context) => {
+    // A pre-quote prices a route it will never execute, so it must not reserve a
+    // deposit address; asking dry also keeps it out of the service's records.
+    const options = buildOptionsFrom(context, { dry: true });
+    if (options === null) {
+        return null;
+    }
+    const recipient = request.recipient ?? request.fromAddress;
+    return buildBody({
+        fromChainId: request.fromChainId,
+        fromTokenAddress: request.fromTokenAddress,
+        fromAddress: request.fromAddress,
+        // A pre-quote carries no connected account, so a pay-by-hand origin builds
+        // no pre-quote. None is wanted: this provider never bids in the pre-quote.
+        connectedEthereumAccount: undefined,
+        toChainId: request.toChainId,
+        toTokenAddress: request.toTokenAddress,
+        recipient,
+        amount: request.amount,
+        swapType: 'EXACT_INPUT',
+        slippage: request.slippage,
+        options: { ...options, dry: true },
+    });
+};
+/**
+ * Builds the execution quote body for a crossing with nothing to run on arrival.
+ *
+ * REFUSES ANY REQUEST CARRYING A DESTINATION CALL, and that refusal is the
+ * whole point of it. The service has no field a call can travel in, so a
+ * request built without the call would look like a valid quote for the same
+ * route and would deliver the reader's funds to an address instead of into the
+ * omnibridge — a silent, funds-affecting difference. Returning null leaves that
+ * route to the providers that execute.
+ *
+ * @param request - the provider-agnostic consolidated request
+ * @param context - carries the asset list, the clock and the referral tag
+ * @param options.dry - price only, reserving nothing. What a route ON DISPLAY
+ *   must ask; a live quote reserves a deposit address for three days, so it is
+ *   asked only when the reader commits. See `UnreservedDeposit`.
+ * @returns the request body, or null when the route needs a destination call,
+ *   names no input amount, or the service carries neither asset
+ */
+export const buildNearIntentsQuoteRequest = (request, context, { dry = false } = {}) => {
+    if (request.destinationCall !== undefined) {
+        return null;
+    }
+    const { fromAmount, toChainId } = request;
+    if (fromAmount === undefined || toChainId === undefined) {
+        return null;
+    }
+    const options = buildOptionsFrom(context, { dry });
+    if (options === null) {
+        return null;
+    }
+    return buildBody({
+        fromChainId: request.fromChainId,
+        fromTokenAddress: request.fromTokenAddress,
+        fromAddress: request.fromAddress,
+        connectedEthereumAccount: request.connectedEthereumAccount,
+        toChainId,
+        toTokenAddress: request.toTokenAddress,
+        recipient: request.recipient,
+        amount: fromAmount,
+        swapType: 'EXACT_INPUT',
+        slippage: request.slippage,
+        options: { ...options, dry },
+    });
+};
+const parseAmount = (value) => {
+    if (typeof value !== 'string' || value === '') {
+        return null;
+    }
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Parses a quote response into the delivered amounts a pre-quote reports.
+ *
+ * `amountOut` is the expected delivery and `minAmountOut` the guaranteed floor
+ * after slippage, which is the same pair the other providers' pre-quote parsers
+ * produce, so the three rank on like figures.
+ *
+ * @param payload - the raw JSON body from `POST /v0/quote`
+ * @returns the delivered amounts, or null when the payload is an error or
+ *   otherwise not a quote
+ */
+export const parseNearIntentsPreQuote = (payload) => {
+    const quote = asRecord(asRecord(payload)?.quote);
+    if (!quote) {
+        return null;
+    }
+    const expectedAmount = parseAmount(quote.amountOut);
+    if (expectedAmount === null) {
+        return null;
+    }
+    const minimumAmount = parseAmount(quote.minAmountOut);
+    return { expectedAmount, minimumAmount: minimumAmount ?? expectedAmount };
+};
+/**
+ * Builds the transfer the reader signs to fund a quote.
+ *
+ * THE SERVICE RETURNS NO TRANSACTION, ONLY AN ADDRESS. Every other provider in
+ * this repository hands back a signable payload; this one hands back a deposit
+ * address and watches the chain for an ordinary transfer into it. So the origin
+ * deposit is CONSTRUCTED here from the request, not read off the response, and
+ * the response alone is not enough to produce one.
+ *
+ * There is never an approval. Nothing pulls from the reader's account — they
+ * send — so a spender allowance has nothing to authorize.
+ *
+ * @param options.depositAddress - the address the quote reserved
+ * @param options.amount - the input amount, in the origin token's base units
+ * @param options.request - the request the quote answered
+ * @returns the Ethereum deposit, or null for an origin family this cannot build
+ */
+const nearIntentsOriginDeposit = ({ depositAddress, amount, request, }) => {
+    // Only Ethereum-virtual-machine origins are built. The other families need a
+    // transfer composed in that family's own encoding — a Solana instruction, a
+    // Bitcoin transaction — and no signer in this repository accepts a transfer
+    // this module composed. Returning null declines the route rather than
+    // handing a wallet a payload meant for a different chain.
+    //
+    // Derived from the chain id, never from the request's own `originVmType` —
+    // see the note on {@link buildBody}, which fixes the same signal for the
+    // same reason.
+    if (ecosystemByChainId(request.fromChainId) !== 'evm') {
+        return null;
+    }
+    if (!depositAddress.startsWith('0x')) {
+        return null;
+    }
+    const chainId = request.fromChainId;
+    if (isNativeAsset(request.fromTokenAddress, 'evm')) {
+        return {
+            ecosystem: 'evm',
+            to: depositAddress,
+            data: '0x',
+            value: amount,
+            chainId,
+            gasLimit: null,
+        };
+    }
+    return {
+        ecosystem: 'evm',
+        to: request.fromTokenAddress,
+        data: encodeFunctionData({
+            abi: erc20Abi,
+            functionName: 'transfer',
+            args: [depositAddress, amount],
+        }),
+        value: 0n,
+        chainId,
+        gasLimit: null,
+    };
+};
+/**
+ * Builds the deposit for a chain the reader pays by hand: an address, an
+ * amount, a tolerance and a clock, and nothing to sign.
+ *
+ * EVERY FIELD IS READ OFF THE LIVE ANSWER, and each one refuses rather than
+ * defaults, because a wrong figure here is shown to a person who then sends
+ * money by hand:
+ *
+ * - the address must be a well-formed address ON THE ORIGIN CHAIN. An answer
+ *   that issued an Ethereum-shaped address for a Zcash route is not a Zcash
+ *   deposit, whatever else it says.
+ * - the displayed minimum is the LARGER of two floors, never `minAmountIn`
+ *   alone. `minAmountIn` is the service's flexible-input floor, priced about
+ *   one percent under the quoted amount; {@link isBelowWorkingFloor} is the
+ *   bridge's own floor, which does not move with the quote and can sit above
+ *   `minAmountIn` for a small Zcash amount. A reader told to send the smaller
+ *   figure sends a deposit the bridge will not credit, and it stalls with no
+ *   published recovery — see {@link zcashWorkingFloorBaseUnits}. The combined
+ *   minimum still may not exceed the quoted amount; one that did would tell
+ *   the reader to send more than asked, so that is refused rather than shown.
+ * - `deadline` is the answer's own. The request's echoed deadline is ignored
+ *   by the service, which substitutes one three days out — see
+ *   {@link defaultDeadlineMilliseconds}.
+ *
+ * @param options.quote - the `quote` record of a live answer
+ * @param options.depositAddress - the address that answer issued
+ * @param options.amount - the quoted input, in base units of the origin asset
+ * @param options.chainId - the origin chain
+ * @param options.decimals - the origin asset's decimal places
+ * @returns the deposit, or null when any field is missing or malformed
+ */
+const depositAddressOriginDeposit = ({ quote, depositAddress, amount, chainId, decimals, }) => {
+    if (!isValidAddressIn(depositAddress, ecosystemByChainId(chainId))) {
+        return null;
+    }
+    const flexibleInputFloor = parseAmount(quote.minAmountIn);
+    if (flexibleInputFloor === null || flexibleInputFloor <= 0n) {
+        return null;
+    }
+    const bridgeWorkingFloor = workingFloorByChainId.get(chainId) ?? 0n;
+    const minimumAmount = flexibleInputFloor > bridgeWorkingFloor ? flexibleInputFloor : bridgeWorkingFloor;
+    if (minimumAmount > amount) {
+        return null;
+    }
+    const expiresAtMs = typeof quote.deadline === 'string' ? Date.parse(quote.deadline) : Number.NaN;
+    if (Number.isNaN(expiresAtMs)) {
+        return null;
+    }
+    return {
+        kind: 'deposit-address',
+        chainId,
+        depositAddress,
+        amount,
+        minimumAmount,
+        decimals,
+        expiresAtMs,
+    };
+};
+/**
+ * Reads what the route charges.
+ *
+ * TWO OF THE THREE NUMBERS THE SERVICE REPORTS ARE COSTS, AND ONE IS NOT.
+ * `withdrawFee` is taken out of the delivered amount on every successful route,
+ * and the key-less surcharge in the echoed `appFees` is taken out of the input,
+ * so both are real. `refundFee` is charged ONLY when a swap is refunded — it is
+ * the price of a route that did not happen — so counting it would overstate
+ * what a completed crossing costs, and it is deliberately left out.
+ */
+const nearIntentsQuoteFees = ({ quote, quoteRequest, originToken, destinationToken, }) => {
+    const fees = [];
+    const withdrawFee = parseAmount(quote.withdrawFee);
+    if (withdrawFee !== null && withdrawFee > 0n) {
+        fees.push({
+            kind: 'service',
+            label: 'Withdrawal fee',
+            amount: withdrawFee,
+            token: destinationToken,
+            amountUsd: null,
+            // Taken out of what is delivered rather than added to what is sent, so
+            // the reader never pays it on top.
+            includedInFromAmount: true,
+        });
+    }
+    const amountIn = parseAmount(quote.amountIn);
+    const appFees = quoteRequest?.appFees;
+    if (amountIn === null || !Array.isArray(appFees)) {
+        return fees;
+    }
+    for (const entry of appFees) {
+        const basisPoints = asRecord(entry)?.fee;
+        if (typeof basisPoints !== 'number' || basisPoints <= 0) {
+            continue;
+        }
+        fees.push({
+            kind: 'service',
+            label: 'NEAR Intents platform fee',
+            amount: (amountIn * BigInt(Math.round(basisPoints))) / 10000n,
+            token: originToken,
+            amountUsd: null,
+            includedInFromAmount: true,
+        });
+    }
+    return fees;
+};
+/**
+ * Normalizes a quote response into the shared consolidated quote shape.
+ *
+ * READS THE REQUEST AS WELL AS THE RESPONSE, unlike every other parser here,
+ * and it has to: the response names a deposit address and no transaction, so
+ * the origin chain, the origin token and the ecosystem — everything needed to
+ * build the transfer the reader signs — exist only on the request. That is why
+ * {@link ProviderQuoteContext} carries a request at all.
+ *
+ * A DRY QUOTE IS REFUSED. It carries prices and no deposit address, so it can
+ * never be executed, and a quote that cannot be executed must not be returned
+ * as one.
+ *
+ * @param payload - the raw JSON body from `POST /v0/quote`
+ * @param context - carries the request this answers and both tokens' metadata
+ * @returns the normalized quote, or null when the payload cannot produce one
+ */
+/**
+ * The parts of an answer every NEAR Intents quote needs, reserved or not.
+ *
+ * @returns the pieces, or null when the context or the body is unusable
+ */
+const quoteEssentials = (payload, context) => {
+    const request = context?.request;
+    const originToken = context?.originToken;
+    const destinationToken = context?.destinationToken;
+    // Without the request there is no chain and no token to compose a transfer
+    // from, so there is no quote to return — the same answer as a malformed body.
+    if (request === undefined || originToken === undefined || destinationToken === undefined) {
+        return null;
+    }
+    const body = asRecord(payload);
+    const quote = asRecord(body?.quote);
+    if (!quote) {
+        return null;
+    }
+    const fromAmount = parseAmount(quote.amountIn);
+    if (fromAmount === null) {
+        return null;
+    }
+    if (typeof quote.timeEstimate !== 'number') {
+        return null;
+    }
+    return { request, originToken, destinationToken, body, quote, fromAmount, timeEstimate: quote.timeEstimate };
+};
+/**
+ * Assembles the shared quote shape around a deposit.
+ *
+ * @returns the normalized quote
+ */
+const nearIntentsQuoteShape = ({ essentials: { body, quote, fromAmount, timeEstimate, originToken, destinationToken }, quoteId, originDeposit, }) => {
+    const toAmount = parseAmount(quote.amountOut);
+    return {
+        provider: 'near-intents',
+        quoteId,
+        tool: 'near-intents',
+        toolName: 'NEAR Intents',
+        fromAmount,
+        ...(toAmount === null ? {} : { toAmount }),
+        fromAmountUsd: typeof quote.amountInUsd === 'string' ? quote.amountInUsd : null,
+        ...(typeof quote.amountOutUsd === 'string' ? { toAmountUsd: quote.amountOutUsd } : {}),
+        // Nothing pulls from the reader's account, so no spender is ever approved.
+        approvalAddress: null,
+        executionDurationSeconds: timeEstimate,
+        // The service reports no per-leg breakdown, only the two ends of the trade.
+        steps: [],
+        originDeposit,
+        fees: nearIntentsQuoteFees({
+            quote,
+            quoteRequest: asRecord(body?.quoteRequest),
+            originToken,
+            destinationToken,
+        }),
+    };
+};
+/**
+ * Normalizes a DRY answer into a quote that can be drawn and not paid.
+ *
+ * Same figures, fees and timing as a live quote; its deposit is
+ * {@link UnreservedDeposit} and its `quoteId` is empty, because a dry answer
+ * reserves no address and the address is a quote's identity. A caller that
+ * reaches the commit asks live with `buildNearIntentsQuoteRequest(…, { dry:
+ * false })` and pays that answer instead.
+ *
+ * @param payload - the raw JSON body of a `dry: true` quote
+ * @param context - the same context the live parser reads
+ * @returns the priced quote, or null when the body is not a quote
+ */
+export const parseNearIntentsPriceQuote = (payload, context) => {
+    const essentials = quoteEssentials(payload, context);
+    if (essentials === null) {
+        return null;
+    }
+    return nearIntentsQuoteShape({
+        essentials,
+        quoteId: '',
+        originDeposit: { kind: 'unreserved', chainId: essentials.request.fromChainId },
+    });
+};
+export const parseNearIntentsQuote = (payload, context) => {
+    const essentials = quoteEssentials(payload, context);
+    if (essentials === null) {
+        return null;
+    }
+    const { request, originToken, quote, fromAmount } = essentials;
+    const depositAddress = quote.depositAddress;
+    if (typeof depositAddress !== 'string' || depositAddress === '') {
+        return null;
+    }
+    const originDeposit = isDepositAddressChain(request.fromChainId)
+        ? depositAddressOriginDeposit({
+            quote,
+            depositAddress,
+            amount: fromAmount,
+            chainId: request.fromChainId,
+            decimals: originToken.decimals,
+        })
+        : nearIntentsOriginDeposit({ depositAddress, amount: fromAmount, request });
+    if (originDeposit === null) {
+        return null;
+    }
+    // The deposit address is this quote's identity: the service issues a fresh
+    // one per quote and the status endpoint is keyed by it. See
+    // {@link nearIntentsStatusUrl}.
+    return nearIntentsQuoteShape({ essentials, quoteId: depositAddress, originDeposit });
+};
+// "Temporary swap limits: minimum swap amount is $1,000" — thousands separators
+// and all. Captured live against Binance Smart Chain, Polygon and Tron.
+const chainMinimumPattern = /minimum swap amount is \$([\d,]+(?:\.\d+)?)/;
+// "Amount is too low for bridge, try at least 303824" — base units of the
+// origin asset, quoted live and different on consecutive requests.
+const bridgeMinimumPattern = /try at least (\d+)/;
+/**
+ * Reads why a quote request was declined.
+ *
+ * WORTH READING RATHER THAN TREATING AS A FAILURE. A route below one of these
+ * floors is not a fault to retry — it is a route this provider will never
+ * carry at that size, so a router can drop the provider from the competition
+ * and a surface can say what size would work. Left as a bare rejection, the
+ * same route simply produces a slower answer with one fewer bidder and nothing
+ * on screen to explain it.
+ *
+ * @param payload - the raw JSON body of a declined `POST /v0/quote`
+ * @returns the refusal, or null when the body carries no message to read
+ */
+export const parseNearIntentsQuoteRefusal = (payload) => {
+    const message = asRecord(payload)?.message;
+    if (typeof message !== 'string') {
+        return null;
+    }
+    const chainMinimum = chainMinimumPattern.exec(message);
+    if (chainMinimum?.[1] !== undefined) {
+        return { reason: 'belowChainMinimum', minimumUsd: Number(chainMinimum[1].replaceAll(',', '')) };
+    }
+    const bridgeMinimum = bridgeMinimumPattern.exec(message);
+    if (bridgeMinimum?.[1] !== undefined) {
+        return { reason: 'belowBridgeMinimum', minimumAmount: BigInt(bridgeMinimum[1]) };
+    }
+    if (message.includes('No liquidity available')) {
+        return { reason: 'noLiquidity' };
+    }
+    return { reason: 'other' };
+};
+/**
+ * The lifecycle states the status endpoint reports. `SUCCESS`, `REFUNDED` and
+ * `FAILED` are terminal; the rest are still in flight.
+ */
+const nearIntentsInFlightStatuses = [
+    'KNOWN_DEPOSIT_TX',
+    'PENDING_DEPOSIT',
+    'INCOMPLETE_DEPOSIT',
+    'PROCESSING',
+];
+const isEthereumTransactionHash = (value) => typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value);
+/**
+ * Finds the destination-chain transaction hash, which is what hands a route
+ * over from provider polling to the omnibridge indexer.
+ *
+ * The hashes arrive as records carrying a `hash` and an explorer address, and
+ * the destination chain may not be an Ethereum one, so anything that is not a
+ * full thirty-two-byte hash collapses to null rather than being passed on as
+ * though it were a transaction.
+ */
+const destinationTransactionHash = (swapDetails) => {
+    const hashes = swapDetails?.destinationChainTxHashes;
+    if (!Array.isArray(hashes)) {
+        return null;
+    }
+    for (const entry of hashes) {
+        const hash = asRecord(entry)?.hash;
+        if (isEthereumTransactionHash(hash)) {
+            return hash;
+        }
+    }
+    return null;
+};
+/**
+ * Where a refund was credited, when it went into an account inside NEAR
+ * Intents rather than back to the origin chain.
+ *
+ * READ FROM THE PROVIDER'S OWN ECHO OF THE REQUEST. The status response carries
+ * the quote request it answered, so the refund's account, type and asset come
+ * from what the provider says it did — not from a guess on our side about
+ * which asset a chain's refund would be in. The amount is the provider's own
+ * `refundedAmount`.
+ *
+ * NULL FOR AN `ORIGIN_CHAIN` REFUND, which lands back in the reader's own
+ * origin wallet and needs nothing from them, and null whenever any field is
+ * missing: a refund step that names the wrong account or asset would send the
+ * reader looking in the wrong place.
+ *
+ * @param body - the whole status response
+ * @param swapDetails - its `swapDetails` record
+ * @returns the account refund, or null
+ */
+const intentsAccountRefund = (body, swapDetails) => {
+    const request = asRecord(asRecord(body?.quoteResponse)?.quoteRequest);
+    if (request?.refundType !== 'INTENTS') {
+        return null;
+    }
+    const { refundTo, originAsset } = request;
+    const refundedAmount = swapDetails?.refundedAmount;
+    if (typeof refundTo !== 'string' || typeof originAsset !== 'string') {
+        return null;
+    }
+    if (typeof refundedAmount !== 'string' || !/^\d+$/.test(refundedAmount)) {
+        return null;
+    }
+    return { account: refundTo.toLowerCase(), assetId: originAsset, baseUnits: refundedAmount };
+};
+/**
+ * Normalizes a `GET /v0/status` response.
+ *
+ * @param payload - the raw JSON body
+ * @returns the normalized status, or null when the payload names no status
+ */
+export const parseNearIntentsStatus = (payload) => {
+    const body = asRecord(payload);
+    const status = body?.status;
+    if (typeof status !== 'string') {
+        return null;
+    }
+    const swapDetails = asRecord(body?.swapDetails);
+    const receivingTxHash = destinationTransactionHash(swapDetails);
+    if (status === 'SUCCESS') {
+        return { status: 'DONE', substatus: 'COMPLETED', receivingTxHash };
+    }
+    if (status === 'REFUNDED') {
+        return {
+            status: 'DONE',
+            substatus: 'REFUNDED',
+            receivingTxHash: null,
+            refund: intentsAccountRefund(body, swapDetails),
+        };
+    }
+    if (status === 'FAILED') {
+        return { status: 'FAILED', substatus: status, receivingTxHash: null };
+    }
+    if (nearIntentsInFlightStatuses.some((inFlight) => inFlight === status)) {
+        return { status: 'PENDING', substatus: status, receivingTxHash };
+    }
+    // An unrecognized state is treated as still settling rather than terminal, so
+    // a new state the service adds never reads as a completed transfer.
+    return { status: 'NOT_FOUND', substatus: status, receivingTxHash };
+};