@gibs/bridge-sdk 1.19.0 → 1.20.0

package/dist/near-intents.js

@@ -5,163 +5,17 @@ import { depositAddressChainIds, isDepositAddressChain, relayChainIds, } from '.
 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 }) => {
     return buildUrl(`${nearIntentsApiBaseUrl}/v0/status`, { depositAddress: quoteId });
 };
-/**
- * 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 {
@@ -170,24 +24,6 @@ export const nearIntentsRequestHeaders = (apiKey, options = {}) => {
         ...(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],
@@ -203,10 +39,6 @@ export const chainIdByNearIntentsChain = new Map([
     ['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) => {
@@ -215,17 +47,6 @@ const asRecord = (value) => {
     }
     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 [];
@@ -255,24 +76,6 @@ export const parseNearIntentsTokens = (payload) => {
     }
     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) {
@@ -281,55 +84,15 @@ export const findNearIntentsAsset = ({ assets, chainId, tokenAddress, ecosystem,
     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) {
@@ -337,46 +100,6 @@ const buildOptionsFrom = (context, { dry }) => {
     }
     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' };
@@ -386,79 +109,19 @@ const refundFields = ({ fromChainId, fromAddress, connectedEthereumAccount, }) =
     }
     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;
@@ -475,8 +138,6 @@ const buildBody = ({ fromChainId, fromTokenAddress, fromAddress, connectedEthere
     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,
@@ -492,8 +153,6 @@ const buildBody = ({ fromChainId, fromTokenAddress, fromAddress, connectedEthere
     }
     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
@@ -509,24 +168,7 @@ const buildBody = ({ fromChainId, fromTokenAddress, fromAddress, connectedEthere
         ...(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;
@@ -536,8 +178,6 @@ export const buildNearIntentsPreQuoteRequest = (request, context) => {
         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,
@@ -548,24 +188,6 @@ export const buildNearIntentsPreQuoteRequest = (request, context) => {
         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;
@@ -603,17 +225,6 @@ const parseAmount = (value) => {
         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) {
@@ -626,33 +237,7 @@ export const parseNearIntentsPreQuote = (payload) => {
     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;
     }
@@ -683,37 +268,6 @@ const nearIntentsOriginDeposit = ({ depositAddress, amount, request, }) => {
         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;
@@ -741,16 +295,6 @@ const depositAddressOriginDeposit = ({ quote, depositAddress, amount, chainId, d
         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);
@@ -761,8 +305,6 @@ const nearIntentsQuoteFees = ({ quote, quoteRequest, originToken, destinationTok
             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,
         });
     }
@@ -787,34 +329,10 @@ const nearIntentsQuoteFees = ({ quote, quoteRequest, originToken, destinationTok
     }
     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;
     }
@@ -832,11 +350,6 @@ const quoteEssentials = (payload, context) => {
     }
     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 {
@@ -848,10 +361,8 @@ const nearIntentsQuoteShape = ({ essentials: { body, quote, fromAmount, timeEsti
         ...(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({
@@ -862,19 +373,6 @@ const nearIntentsQuoteShape = ({ essentials: { body, quote, fromAmount, timeEsti
         }),
     };
 };
-/**
- * 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) {
@@ -908,30 +406,10 @@ export const parseNearIntentsQuote = (payload, context) => {
     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') {
@@ -950,10 +428,6 @@ export const parseNearIntentsQuoteRefusal = (payload) => {
     }
     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',
@@ -961,15 +435,6 @@ const nearIntentsInFlightStatuses = [
     '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)) {
@@ -983,25 +448,6 @@ const destinationTransactionHash = (swapDetails) => {
     }
     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') {
@@ -1017,12 +463,6 @@ const intentsAccountRefund = (body, swapDetails) => {
     }
     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;
@@ -1048,7 +488,5 @@ export const parseNearIntentsStatus = (payload) => {
     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 };
 };