@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/ton-execution.js

@@ -1,247 +1,7 @@
-import { Cell, beginCell, loadMessage, storeMessage } from '@ton/core';
 /**
- * Executing a deposit on The Open Network, as pure data.
+ * The original name of `@gibs/bridge-sdk/ton`, kept so existing imports work.
  *
- * Relay describes a deposit as a list of internal messages carrying `to`,
- * `value`, `body` and a `bounce` flag. A connected wallet, however, is driven
- * through the TON Connect protocol, whose request shape is different in one way
- * that silently loses money:
- *
- * **TON Connect has no per-message `bounce` field.** A wallet derives whether a
- * message bounces from the FORM OF THE ADDRESS — the bounceable `EQ…` prefix or
- * the non-bounceable `UQ…` one. Passing Relay's address through unchanged while
- * dropping its `bounce: false` therefore sends a deposit to the bounceable form,
- * and the depository bounces the funds straight back to the sender. The transfer
- * looks like it succeeded and the route never fills.
- *
- * {@link buildTonConnectRequest} folds `bounce` into the address so the flag
- * cannot be dropped on the way to a wallet.
- *
- * Kept free of transport and of clock reads so it is fully testable: nothing
- * here signs, fetches, or calls `Date.now`. The caller supplies the deadline and
- * performs the request.
- *
- * The rules encoded here are those of Relay's own wallet adapter, which is the
- * only reference implementation of this mapping.
- */
-/**
- * The TON Connect network identifier for mainnet. Relay bridges only mainnet, so
- * a request is always tagged with this.
- */
-export const tonConnectMainnetNetwork = '-239';
-/** How long a request stays valid by default, in seconds, matching Relay's adapter. */
-export const tonConnectDefaultValidForSeconds = 300;
-/** Address tag byte for the bounceable (`EQ…`) form. */
-const bounceableTag = 0x11;
-/** Address tag byte for the non-bounceable (`UQ…`) form. */
-const nonBounceableTag = 0x51;
-/** Bit set on the tag byte for testnet-only addresses (`kQ…` / `0Q…`). */
-const testnetTagFlag = 0x80;
-/** A friendly address is a 36-byte structure: tag, workchain, hash, checksum. */
-const friendlyAddressByteLength = 36;
-/** An account identifier is always 32 bytes, in every address form. */
-const accountHashByteLength = 32;
-/**
- * Cyclic redundancy check (16-bit, the XModem variant) over an address body.
- * The Open Network appends it to every friendly address, and a re-encoded
- * address whose checksum is not recomputed is rejected by wallets as malformed.
- */
-const checksum = (data) => {
-    let remainder = 0;
-    for (const byte of data) {
-        remainder ^= byte << 8;
-        for (let bit = 0; bit < 8; bit += 1) {
-            remainder =
-                remainder & 0x8000 ? ((remainder << 1) ^ 0x1021) & 0xffff : (remainder << 1) & 0xffff;
-        }
-    }
-    return remainder;
-};
-/** Decodes the url-safe base64 alphabet the friendly address form uses. */
-const decodeBase64Url = (value) => {
-    const standard = value.replaceAll('-', '+').replaceAll('_', '/');
-    const padded = standard.padEnd(Math.ceil(standard.length / 4) * 4, '=');
-    try {
-        const binary = atob(padded);
-        return Uint8Array.from(binary, (character) => character.charCodeAt(0));
-    }
-    catch {
-        return null;
-    }
-};
-/** Encodes bytes back into the url-safe, unpadded base64 form. */
-const encodeBase64Url = (bytes) => {
-    let binary = '';
-    for (const byte of bytes) {
-        binary += String.fromCharCode(byte);
-    }
-    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
-};
-const parseRawAddress = (value) => {
-    const separator = value.indexOf(':');
-    if (separator < 0) {
-        return null;
-    }
-    const workchain = Number(value.slice(0, separator));
-    const hex = value.slice(separator + 1);
-    if (!Number.isInteger(workchain) || hex.length !== accountHashByteLength * 2) {
-        return null;
-    }
-    const hash = new Uint8Array(accountHashByteLength);
-    for (let index = 0; index < accountHashByteLength; index += 1) {
-        const byte = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
-        if (Number.isNaN(byte)) {
-            return null;
-        }
-        hash[index] = byte;
-    }
-    // The raw form carries no network tag, so mainnet is the only safe assumption.
-    return { workchain, hash, testOnly: false };
-};
-const parseFriendlyAddress = (value) => {
-    const bytes = decodeBase64Url(value);
-    if (bytes === null || bytes.length !== friendlyAddressByteLength) {
-        return null;
-    }
-    const body = bytes.subarray(0, friendlyAddressByteLength - 2);
-    // Every index below is in range: the length was checked to be exactly
-    // `friendlyAddressByteLength` above, so the non-null assertions are sound.
-    const stated = (bytes[friendlyAddressByteLength - 2] << 8) | bytes[friendlyAddressByteLength - 1];
-    if (checksum(body) !== stated) {
-        return null;
-    }
-    const tag = bytes[0];
-    const withoutTestFlag = tag & ~testnetTagFlag;
-    if (withoutTestFlag !== bounceableTag && withoutTestFlag !== nonBounceableTag) {
-        return null;
-    }
-    const workchainByte = bytes[1];
-    return {
-        // The masterchain is workchain -1, which travels as the byte 0xff.
-        workchain: workchainByte === 0xff ? -1 : workchainByte,
-        hash: bytes.slice(2, 2 + accountHashByteLength),
-        testOnly: (tag & testnetTagFlag) !== 0,
-    };
-};
-/**
- * Parses either address form The Open Network uses.
- *
- * @param value - a friendly (`EQ…`/`UQ…`) or raw (`0:…`) address
- * @returns the address parts, or null when it is neither form or fails its checksum
- */
-export const parseTonAddress = (value) => value.includes(':') ? parseRawAddress(value) : parseFriendlyAddress(value);
-/**
- * Re-encodes an address into the friendly form matching a bounce setting.
- *
- * This is the whole point of the module: the bounce flag has nowhere else to
- * live in a TON Connect request, so it has to be carried by the address itself.
- *
- * @param address - the address in either form
- * @param options.bounceable - whether the message may bounce back to the sender
- * @returns the friendly address, or null when the input cannot be parsed
- */
-export const encodeTonAddress = (address, { bounceable }) => {
-    const parsed = parseTonAddress(address);
-    if (parsed === null) {
-        return null;
-    }
-    const bytes = new Uint8Array(friendlyAddressByteLength);
-    bytes[0] =
-        (bounceable ? bounceableTag : nonBounceableTag) | (parsed.testOnly ? testnetTagFlag : 0);
-    bytes[1] = parsed.workchain < 0 ? 0xff : parsed.workchain;
-    bytes.set(parsed.hash, 2);
-    const stated = checksum(bytes.subarray(0, friendlyAddressByteLength - 2));
-    bytes[friendlyAddressByteLength - 2] = (stated >> 8) & 0xff;
-    bytes[friendlyAddressByteLength - 1] = stated & 0xff;
-    return encodeBase64Url(bytes);
-};
-/**
- * Builds the TON Connect request for a deposit.
- *
- * @param deposit - the parsed origin deposit
- * @param options.validUntil - unix seconds after which the request expires.
- *   Supplied by the caller rather than read from a clock here so the transform
- *   stays pure; {@link tonConnectDefaultValidForSeconds} is the usual offset.
- * @returns the request, or null when the deposit carries no messages or any
- *   destination address cannot be re-encoded — never a request whose bounce
- *   setting has been silently dropped
- */
-export const buildTonConnectRequest = (deposit, { validUntil }) => {
-    if (deposit.messages.length === 0) {
-        return null;
-    }
-    const messages = [];
-    for (const message of deposit.messages) {
-        const address = encodeTonAddress(message.to, { bounceable: message.bounce });
-        // Refuse rather than fall back to the unencoded address: the fallback is
-        // exactly the bounce-losing behaviour this module exists to prevent.
-        if (address === null) {
-            return null;
-        }
-        messages.push({
-            address,
-            amount: message.value.toString(),
-            ...(message.body ? { payload: message.body } : {}),
-        });
-    }
-    // `messages[0]` is present: the empty case returned null above.
-    const from = deposit.messages[0].from;
-    return {
-        validUntil,
-        network: tonConnectMainnetNetwork,
-        ...(from === null ? {} : { from }),
-        messages,
-    };
-};
-/**
- * Derives the transaction identifier from a wallet's `sendTransaction` response.
- *
- * A wallet answers with a `boc`: the base64 bag-of-cells of the signed
- * external-in message it broadcast — NOT the resulting transaction, and NOT a
- * hash. The identifier explorers and indexers (toncenter, TonAPI) resolve a
- * transaction by is the hash of that external message, but it must be the
- * NORMALIZED hash of TEP-467, not the hash of the bytes the wallet happened to
- * send.
- *
- * The distinction is the whole point, and getting it wrong loses a resume record
- * for real funds. An external-in message can be serialized several equivalent
- * ways — a wallet may or may not include its own `src`, may set a non-zero
- * `import_fee`, may attach a `stateInit`, may store the body inline or as a
- * reference. The raw cell hash changes with each of those wallet-specific
- * choices, so it frequently does NOT match what an indexer keyed the same
- * transaction under. TEP-467 rebuilds the message with those variable fields
- * stripped (`src` to none, `import_fee` to zero, `init` dropped, body forced to a
- * reference) so the hash is stable across wallets and matches the indexers.
- *
- * @param boc - the wallet's base64 `boc` field from `sendTransaction`
- * @returns the 64-character hex normalized hash, or null when the input is not a
- *   parseable external-in message
+ * @deprecated Import from `@gibs/bridge-sdk/ton` for the full TON surface, or
+ * from `@gibs/bridge-sdk/ton-connect` for the helpers that need no TON library.
  */
-export const tonExternalMessageHash = (boc) => {
-    try {
-        const message = loadMessage(Cell.fromBase64(boc).beginParse());
-        // Only an external-in message has a normalized form; an internal message or
-        // a bare cell is not the wallet's broadcast envelope and cannot be keyed.
-        if (message.info.type !== 'external-in') {
-            return null;
-        }
-        const normalized = {
-            ...message,
-            // Dropped by TEP-467 so a wallet-attached stateInit does not move the hash.
-            init: null,
-            // `src` to addr_none (undefined) and the fee to zero: both are the sender's
-            // to choose and neither is part of what identifies the message.
-            info: { ...message.info, src: undefined, importFee: 0n },
-        };
-        // `forceRef` stores the body as a reference, as the normalized form requires.
-        return beginCell()
-            .store(storeMessage(normalized, { forceRef: true }))
-            .endCell()
-            .hash()
-            .toString('hex');
-    }
-    catch {
-        // A malformed base64 payload or a cell tree that is not a message at all.
-        return null;
-    }
-};
+export * from './ton.js';

package/dist/ton.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Everything the bridge SDK offers for The Open Network, in one entry point.
+ *
+ * It re-exports the pure TON Connect helpers from `./ton-connect.js` and adds
+ * {@link tonExternalMessageHash}, the only helper that needs `@ton/core`.
+ *
+ * Kept apart from the root entry point on purpose. `@ton/core` uses Node's
+ * `Buffer`, and its `@ton/crypto` dependency resolves, under React Native, to a
+ * build that requires `expo-crypto`. An application that bridges only between
+ * Ethereum-style chains never imports this file, so it never pays for either.
+ */
+export * from './ton-connect.js';
+/**
+ * Derives the transaction identifier from a wallet's `sendTransaction` response.
+ *
+ * A wallet answers with a `boc`: the base64 bag-of-cells of the signed
+ * external-in message it broadcast — NOT the resulting transaction, and NOT a
+ * hash. The identifier explorers and indexers (toncenter, TonAPI) resolve a
+ * transaction by is the hash of that external message, but it must be the
+ * NORMALIZED hash of TEP-467, not the hash of the bytes the wallet happened to
+ * send.
+ *
+ * The distinction is the whole point, and getting it wrong loses a resume record
+ * for real funds. An external-in message can be serialized several equivalent
+ * ways — a wallet may or may not include its own `src`, may set a non-zero
+ * `import_fee`, may attach a `stateInit`, may store the body inline or as a
+ * reference. The raw cell hash changes with each of those wallet-specific
+ * choices, so it frequently does NOT match what an indexer keyed the same
+ * transaction under. TEP-467 rebuilds the message with those variable fields
+ * stripped (`src` to none, `import_fee` to zero, `init` dropped, body forced to a
+ * reference) so the hash is stable across wallets and matches the indexers.
+ *
+ * @param boc - the wallet's base64 `boc` field from `sendTransaction`
+ * @returns the 64-character hex normalized hash, or null when the input is not a
+ *   parseable external-in message
+ */
+export declare const tonExternalMessageHash: (boc: string) => string | null;

package/dist/ton.js

@@ -0,0 +1,65 @@
+import { Cell, beginCell, loadMessage, storeMessage } from '@ton/core';
+/**
+ * Everything the bridge SDK offers for The Open Network, in one entry point.
+ *
+ * It re-exports the pure TON Connect helpers from `./ton-connect.js` and adds
+ * {@link tonExternalMessageHash}, the only helper that needs `@ton/core`.
+ *
+ * Kept apart from the root entry point on purpose. `@ton/core` uses Node's
+ * `Buffer`, and its `@ton/crypto` dependency resolves, under React Native, to a
+ * build that requires `expo-crypto`. An application that bridges only between
+ * Ethereum-style chains never imports this file, so it never pays for either.
+ */
+export * from './ton-connect.js';
+/**
+ * Derives the transaction identifier from a wallet's `sendTransaction` response.
+ *
+ * A wallet answers with a `boc`: the base64 bag-of-cells of the signed
+ * external-in message it broadcast — NOT the resulting transaction, and NOT a
+ * hash. The identifier explorers and indexers (toncenter, TonAPI) resolve a
+ * transaction by is the hash of that external message, but it must be the
+ * NORMALIZED hash of TEP-467, not the hash of the bytes the wallet happened to
+ * send.
+ *
+ * The distinction is the whole point, and getting it wrong loses a resume record
+ * for real funds. An external-in message can be serialized several equivalent
+ * ways — a wallet may or may not include its own `src`, may set a non-zero
+ * `import_fee`, may attach a `stateInit`, may store the body inline or as a
+ * reference. The raw cell hash changes with each of those wallet-specific
+ * choices, so it frequently does NOT match what an indexer keyed the same
+ * transaction under. TEP-467 rebuilds the message with those variable fields
+ * stripped (`src` to none, `import_fee` to zero, `init` dropped, body forced to a
+ * reference) so the hash is stable across wallets and matches the indexers.
+ *
+ * @param boc - the wallet's base64 `boc` field from `sendTransaction`
+ * @returns the 64-character hex normalized hash, or null when the input is not a
+ *   parseable external-in message
+ */
+export const tonExternalMessageHash = (boc) => {
+    try {
+        const message = loadMessage(Cell.fromBase64(boc).beginParse());
+        // Only an external-in message has a normalized form; an internal message or
+        // a bare cell is not the wallet's broadcast envelope and cannot be keyed.
+        if (message.info.type !== 'external-in') {
+            return null;
+        }
+        const normalized = {
+            ...message,
+            // Dropped by TEP-467 so a wallet-attached stateInit does not move the hash.
+            init: null,
+            // `src` to addr_none (undefined) and the fee to zero: both are the sender's
+            // to choose and neither is part of what identifies the message.
+            info: { ...message.info, src: undefined, importFee: 0n },
+        };
+        // `forceRef` stores the body as a reference, as the normalized form requires.
+        return beginCell()
+            .store(storeMessage(normalized, { forceRef: true }))
+            .endCell()
+            .hash()
+            .toString('hex');
+    }
+    catch {
+        // A malformed base64 payload or a cell tree that is not a message at all.
+        return null;
+    }
+};

package/docs/examples/example-a-ether-to-pulse.ts

@@ -0,0 +1,300 @@
+/**
+ * Example A: ETH on Ethereum to PLS on PulseChain.
+ *
+ * 1. Build viem clients from the wallet's own RPC endpoints.
+ * 2. Search with `searchBridgeRoutes` and pick the best served route.
+ * 3. Plan ONE section at a time with `planCandidateExecution`
+ *    (`firstSectionIndex`), so a later section spends what actually arrived,
+ *    with a fresh swap floor and deadline, or a fresh aggregator quote.
+ * 4. Send each section's transactions, honouring `waitForReceipt`, and wait
+ *    for the crossing to arrive before planning the next section.
+ * 5. Poll `fetchTransferStatus` until the last crossing is delivered.
+ *
+ * Typechecked only (`docs/examples/tsconfig.json` in `@gibs/bridge-sdk`). Never run against mainnet.
+ */
+import type { AggregatorStatusSource, FetchTransferStatusOptions } from '@gibs/bridge-indexer';
+import { tokenBridgeInfo } from '@gibs/bridge-sdk/chain-info';
+import { type Provider, Providers, toChain } from '@gibs/bridge-sdk/config';
+import type { ConsolidatedQuote } from '@gibs/bridge-sdk/consolidated-quote';
+import {
+  type CandidateExecutionPlan,
+  planCandidateExecution,
+  readPulseXSectionQuote,
+  type SectionExecutionInputs,
+} from '@gibs/bridge-sdk/execution';
+import type { PlannedHop, ResolveNodeToken, RoutePlan } from '@gibs/bridge-sdk/routing';
+import { fetchLiveSectionQuote, type ServedBridgeRoute, searchBridgeRoutes } from '@gibs/quotes/search';
+import { type Hex, type PublicClient, zeroAddress } from 'viem';
+import {
+  allowanceReaderWith,
+  createClientLookup,
+  deadlineIn,
+  type RpcUrlByChainId,
+  readBalance,
+  requireClientWith,
+  type SentTransaction,
+  sendPlannedTransactions,
+  type WalletSigner,
+  waitForTransferStatus,
+} from './shared.js';
+
+const ethereumChainId = 1;
+const pulsechainChainId = 369;
+
+/** What the example needs from the wallet. */
+export type EtherToPulseOptions = {
+  readonly signer: WalletSigner;
+  readonly rpcUrlByChainId: RpcUrlByChainId;
+  /** The ether to send, in wei. */
+  readonly amountWei: bigint;
+  /** Cancels the search, every live quote and every status poll. */
+  readonly signal: AbortSignal;
+  /** The wallet's own LI.FI key, sent only as the `x-lifi-api-key` header. Leave it out to use LI.FI's keyless tier. */
+  readonly lifiApiKey?: string;
+  /** The wallet's own Relay key, sent only as a header. Leave it out to use Relay's anonymous tier. */
+  readonly relayApiKey?: string;
+};
+
+const omnibridgeCarriers: ReadonlySet<string> = new Set(Object.values(Providers));
+
+const isOmnibridgeCarrier = (carrier: string): carrier is Provider =>
+  omnibridgeCarriers.has(carrier);
+
+/** A plan's sections, one per signature, each as its hops. */
+const sectionsOf = (plan: RoutePlan): readonly (readonly PlannedHop[])[] =>
+  plan.signatures.map((group) => group.flatMap((hopIndex) => plan.hops[hopIndex] ?? []));
+
+/** Where `fetchTransferStatus` asks about an aggregator's leg. */
+const aggregatorSourceOf = (
+  quote: ConsolidatedQuote,
+  relayApiKey: string | undefined,
+): AggregatorStatusSource => {
+  if (quote.provider === 'lifi') return { provider: 'lifi' };
+  if (quote.provider === 'relay') {
+    return {
+      provider: 'relay',
+      requestId: quote.quoteId,
+      ...(relayApiKey === undefined ? {} : { apiKey: relayApiKey }),
+    };
+  }
+  return { provider: 'near-intents', depositAddress: quote.quoteId };
+};
+
+/** One section's inputs, and the live quote it signs when an aggregator carries it. */
+type SectionPlanInputs = {
+  readonly inputs: SectionExecutionInputs;
+  readonly liveQuote: ConsolidatedQuote | null;
+};
+
+/**
+ * Builds the inputs for ONE section, from what it spends NOW: the typed
+ * amount for the first section, what actually arrived for a later one.
+ */
+const buildSectionInputs = async (options: {
+  readonly served: ServedBridgeRoute;
+  readonly sectionIndex: number;
+  readonly hops: readonly PlannedHop[];
+  readonly amountIn: bigint;
+  readonly resolveToken: ResolveNodeToken;
+  readonly account: Hex;
+  readonly requireClient: (chainId: number) => PublicClient;
+  readonly clientForChain: (chainId: number) => PublicClient | null;
+  readonly signal: AbortSignal;
+  readonly lifiApiKey: string | undefined;
+  readonly relayApiKey: string | undefined;
+}): Promise<SectionPlanInputs> => {
+  const { served, sectionIndex, hops, amountIn, resolveToken, account, requireClient } = options;
+  const firstHop = hops[0];
+  if (firstHop === undefined) throw new Error(`section ${sectionIndex} has no hops`);
+  // Every section delivers to the signer; this example sends to the signer too.
+  const recipient = account;
+  const { carrier, from, to } = firstHop.edge;
+
+  if (isOmnibridgeCarrier(carrier)) {
+    // How the token maps across the bridge. Native ether reads the wrapped-ether mapping.
+    const assetLink = await tokenBridgeInfo({
+      bridgeKey: [carrier, toChain(from.chainId), toChain(to.chainId)],
+      assetIn: resolveToken(from),
+      isProd: true,
+      fromChainClient: requireClient(from.chainId),
+      toChainClient: requireClient(to.chainId),
+    });
+    if (assetLink === null)
+      throw new Error(`no omnibridge mapping for ${from.address} on chain ${from.chainId}`);
+    // The explicit delivery choice. Entering PulseChain, the bridge itself
+    // executes the crossing, so `shouldDeliver: false` is the only accepted
+    // choice here. Leaving PulseChain, see Example B.
+    const omnibridge = { isProd: true, assetLink, delivery: { shouldDeliver: false }, unwrap: false } as const;
+    return { inputs: { amountIn, recipient, omnibridge }, liveQuote: null };
+  }
+  if (carrier === 'PulseX') {
+    // A FRESH QUOTE, read now along the exact path the swap signs, for the
+    // amount that actually arrived. The floor is one percent below it, and the
+    // deadline starts now, not before the crossing.
+    const quotedAmountOut = await readPulseXSectionQuote({
+      hop: firstHop,
+      amountIn,
+      client: requireClient(from.chainId),
+    });
+    if (quotedAmountOut === null) throw new Error(`section ${sectionIndex}: PulseX gave no quote`);
+    return {
+      inputs: { amountIn, recipient, swap: { slippageBasisPoints: 100n, deadline: deadlineIn(20 * 60), quotedAmountOut } },
+      liveQuote: null,
+    };
+  }
+  if (carrier === 'wrap') return { inputs: { amountIn, recipient }, liveQuote: null };
+  // Any other carrier is an aggregator. It signs only a LIVE quote, asked now
+  // for this wallet, this recipient and this amount.
+  const live = await fetchLiveSectionQuote({
+    plan: served.plan,
+    sectionIndex,
+    resolveToken,
+    amountIn,
+    account,
+    recipient,
+    clientForChain: options.clientForChain,
+    fetch: (input, init) => globalThis.fetch(input, init),
+    signal: options.signal,
+    keys: {
+      ...(options.lifiApiKey === undefined ? {} : { lifiApiKey: options.lifiApiKey }),
+      ...(options.relayApiKey === undefined ? {} : { relayApiKey: options.relayApiKey }),
+    },
+    nearIntentsUserAgent: 'your-wallet/1.0',
+  });
+  if (live.kind !== 'quoted') throw new Error(`section ${sectionIndex}: no live quote (${live.kind})`);
+  return { inputs: { amountIn, recipient, aggregator: { quote: live.quote, request: live.request } }, liveQuote: live.quote };
+};
+
+/** Turns a refused plan into an error a person can act on. */
+const assertPlanned = (
+  plan: CandidateExecutionPlan,
+): Extract<CandidateExecutionPlan, { kind: 'planned' }> => {
+  if (plan.kind === 'planned') return plan;
+  throw new Error(
+    `section ${plan.sectionIndex} cannot be planned: ${JSON.stringify(plan.refusal, (_key, value) => (typeof value === 'bigint' ? value.toString() : value))}`,
+  );
+};
+
+/**
+ * Sends ether from Ethereum and delivers Pulse on PulseChain.
+ *
+ * @param options - see {@link EtherToPulseOptions}
+ * @returns the transactions sent, and the final status of the last crossing
+ */
+export const sendEtherToPulse = async (options: EtherToPulseOptions) => {
+  const { signer, signal } = options;
+  const clientForChain = createClientLookup(options.rpcUrlByChainId);
+  const requireClient = requireClientWith(clientForChain);
+
+  // 1. Search. No attribution and no fee: the wallet names none here.
+  const search = await searchBridgeRoutes({
+    origin: {
+      chainId: ethereumChainId,
+      token: { address: zeroAddress, decimals: 18, symbol: 'ETH' },
+      amount: options.amountWei,
+      account: signer.address,
+    },
+    destination: {
+      chainId: pulsechainChainId,
+      token: { address: zeroAddress, decimals: 18, symbol: 'PLS' },
+      recipient: signer.address,
+    },
+    clientForChain,
+    fetch: (input, init) => globalThis.fetch(input, init),
+    signal,
+    timeouts: { requestMs: 15_000, searchMs: 60_000 },
+    ...(options.lifiApiKey === undefined ? {} : { lifiApiKey: options.lifiApiKey }),
+    ...(options.relayApiKey === undefined ? {} : { relayApiKey: options.relayApiKey }),
+    nearIntentsUserAgent: 'your-wallet/1.0',
+  });
+
+  // 2. Pick a route. `routes` is best first, one per provider.
+  const served = search.routes[0];
+  if (served === undefined) {
+    const why =
+      search.priceImpactRefusal === null ? `${search.refusals.length} refusals` : 'price impact';
+    throw new Error(`no route can be served (${why})`);
+  }
+  const hopsBySection = sectionsOf(served.plan);
+
+  const statusOptionsFor = (
+    crossing: SentTransaction,
+    liveQuote: ConsolidatedQuote | null,
+  ): FetchTransferStatusOptions => ({
+    signal,
+    originClient: requireClient(crossing.transaction.chainId),
+    ...(liveQuote === null ? {} : { aggregator: aggregatorSourceOf(liveQuote, options.relayApiKey) }),
+  });
+  const waitForDelivered = (crossing: SentTransaction, liveQuote: ConsolidatedQuote | null) =>
+    waitForTransferStatus({
+      source: { chainId: crossing.transaction.chainId, txHash: crossing.hash },
+      statusOptions: statusOptionsFor(crossing, liveQuote),
+      isDone: (status) => status.state === 'delivered',
+      intervalMs: 15_000,
+    });
+
+  // 3 and 4. One section at a time. The first spends the typed amount; each
+  //    later one spends what actually arrived from the one before it.
+  const sent: SentTransaction[] = [];
+  let amountIn = options.amountWei;
+  for (const [sectionIndex, hops] of hopsBySection.entries()) {
+    const { inputs, liveQuote } = await buildSectionInputs({
+      served,
+      sectionIndex,
+      hops,
+      amountIn,
+      resolveToken: search.resolveToken,
+      account: signer.address,
+      requireClient,
+      clientForChain,
+      signal,
+      lifiApiKey: options.lifiApiKey,
+      relayApiKey: options.relayApiKey,
+    });
+    const plan = assertPlanned(
+      await planCandidateExecution({
+        candidate: served.candidate,
+        account: signer.address,
+        readAllowance: allowanceReaderWith(requireClient),
+        resolveToken: search.resolveToken,
+        firstSectionIndex: sectionIndex,
+        sections: [inputs],
+      }),
+    );
+    // Show `plan.deliveries` and every fee before the user signs. See "Fees and attribution".
+
+    // What the next section will spend arrives on its own chain. Read the
+    // balance there before this section runs, and again once it arrived.
+    const nextHop = hopsBySection[sectionIndex + 1]?.[0];
+    const nextToken = nextHop === undefined ? null : search.resolveToken(nextHop.edge.from);
+    const readNextBalance = () =>
+      nextToken === null
+        ? Promise.resolve(0n)
+        : readBalance({ client: requireClient(nextToken.chainId), token: nextToken.address, owner: signer.address });
+    const balanceBefore = await readNextBalance();
+
+    // Every transaction of one section is on one chain.
+    const sectionSent = await sendPlannedTransactions({
+      transactions: plan.transactions,
+      signer,
+      requireClient,
+      waitForArrival: async () => {},
+    });
+    sent.push(...sectionSent);
+    const last = sectionSent.at(-1);
+    if (last === undefined) throw new Error(`section ${sectionIndex} planned no transactions`);
+    const receipt = await requireClient(last.transaction.chainId).waitForTransactionReceipt({ hash: last.hash });
+    if (receipt.status !== 'success') throw new Error(`the transaction ${last.hash} reverted`);
+
+    const crossesChains = last.transaction.kind === 'bridge';
+    // 5. The route ends with this section. A crossing is done when delivered;
+    //    a swap is done when its receipt succeeds.
+    if (nextToken === null) {
+      return { sent, finalStatus: crossesChains ? await waitForDelivered(last, liveQuote) : null };
+    }
+    if (crossesChains) await waitForDelivered(last, liveQuote);
+    amountIn = (await readNextBalance()) - balanceBefore;
+    if (amountIn <= 0n) throw new Error(`nothing arrived for section ${sectionIndex + 1}`);
+  }
+  throw new Error('the route had no sections');
+};