@gibs/bridge-sdk 1.13.1 → 1.17.0

package/docs/examples/example-b-token-pulsechain-to-ethereum.ts

@@ -0,0 +1,270 @@
+/**
+ * Example B: an ERC-20 token from PulseChain to Ethereum, with delivery off.
+ *
+ * 1. Read how the token maps across the bridge, and search for the route.
+ * 2. Plan the direct crossing with `shouldDeliver: false`: an exact approval,
+ *    then `relayTokens`.
+ * 3. Poll `fetchTransferStatus` until the crossing is `claimable`.
+ * 4. Read the bridge request with `fetchClaimRecords` and build the claim
+ *    with `buildClaimTransaction`, handling every typed refusal.
+ * 5. Send the claim on Ethereum, then poll until the transfer is delivered.
+ *
+ * Typechecked only (`docs/examples/tsconfig.json` in `@gibs/bridge-sdk`). Never run against mainnet.
+ */
+import { type ClaimRecord, fetchClaimRecords, type TransferStatus } from '@gibs/bridge-indexer';
+import { tokenBridgeInfo } from '@gibs/bridge-sdk/chain-info';
+import { buildClaimTransaction, type ClaimRefusal } from '@gibs/bridge-sdk/claims';
+import { Chains, Providers } from '@gibs/bridge-sdk/config';
+import { planCandidateExecution } from '@gibs/bridge-sdk/execution';
+import type { BridgeKey, Token } from '@gibs/bridge-sdk/types';
+import { searchBridgeRoutes } from '@gibs/quotes/search';
+import type { Hex } from 'viem';
+import {
+  allowanceReaderWith,
+  createClientLookup,
+  type RpcUrlByChainId,
+  requireClientWith,
+  sendPlannedTransactions,
+  sleep,
+  type WalletSigner,
+  waitForTransferStatus,
+} from './shared.js';
+
+const pulsechainChainId = 369;
+
+/** PulseX (PLSX), an ERC-20 token native to PulseChain. */
+const plsx: Token = {
+  chainId: pulsechainChainId,
+  address: '0x95B303987A60C71504D99Aa1b13B4DA07b0790ab',
+  decimals: 18,
+  symbol: 'PLSX',
+  name: 'PulseX',
+  logoURI: null,
+};
+
+const pulsechainToEthereum: BridgeKey = [Providers.PULSECHAIN, Chains.PLS, Chains.ETH];
+
+/** What the example needs from the wallet. */
+export type TokenToEthereumOptions = {
+  readonly signer: WalletSigner;
+  readonly rpcUrlByChainId: RpcUrlByChainId;
+  /** The amount to send, in the token's base units. */
+  readonly amount: bigint;
+  /** Cancels the search and every poll. */
+  readonly signal: AbortSignal;
+};
+
+/** A claim the wallet must not send, and must not retry by waiting. */
+export class ClaimRefusedError extends Error {
+  constructor(readonly refusal: ClaimRefusal) {
+    super(`the claim was refused: ${refusal.reason}`);
+    this.name = 'ClaimRefusedError';
+  }
+}
+
+/**
+ * Reads the one bridge request a crossing transaction started.
+ * `fetchClaimRecords` asks the indexer for exactly the fields a claim reads,
+ * lowercases the hash (the indexer matches hex in lowercase only), and never
+ * reads a relation the indexer leaves null.
+ *
+ * @param options.txHash - the crossing transaction on PulseChain
+ * @param options.signal - cancels the request
+ * @returns the record, in the shape `buildClaimTransaction` takes
+ * @throws on a network or GraphQL failure, or when the transaction started other than one request
+ */
+const readClaimRecord = async (options: {
+  readonly txHash: Hex;
+  readonly signal: AbortSignal;
+}): Promise<ClaimRecord> => {
+  const records = await fetchClaimRecords({
+    source: { chainId: pulsechainChainId, txHash: options.txHash },
+    signal: options.signal,
+  });
+  const [record] = records;
+  if (record === undefined || records.length !== 1) {
+    throw new Error(`expected one bridge request for ${options.txHash}, found ${records.length}`);
+  }
+  return record;
+};
+
+/** What to do with a refused claim. */
+type RefusalAction =
+  | { readonly kind: 'done' }
+  | { readonly kind: 'wait' }
+  | { readonly kind: 'stop'; readonly error: Error };
+
+/**
+ * Decides what each typed refusal means for the wallet. The switch is
+ * exhaustive: a new refusal reason fails the typecheck here.
+ *
+ * @param refusal - the refusal from `buildClaimTransaction`
+ * @returns the action
+ */
+const actionForRefusal = (refusal: ClaimRefusal): RefusalAction => {
+  switch (refusal.reason) {
+    case 'already-delivered':
+      // Somebody executed the release already. Nothing to send.
+      return { kind: 'done' };
+    case 'not-signed-yet':
+      // The validators are still signing. Ask again later.
+      return { kind: 'wait' };
+    case 'signatures-incomplete':
+      // The indexer stored fewer signatures than the bridge needs (see
+      // "Known limits": the submitSignature case). Waiting does not fix it.
+      // Tell the user, and report the transfer to Gibs.
+      return { kind: 'stop', error: new ClaimRefusedError(refusal) };
+    case 'wrong-type':
+      // Not a signature request. The validators execute an affirmation themselves.
+      return { kind: 'stop', error: new ClaimRefusedError(refusal) };
+    case 'malformed-request':
+      // A field is not the shape the indexer documents. Report it.
+      return { kind: 'stop', error: new ClaimRefusedError(refusal) };
+    default: {
+      const unhandled: never = refusal;
+      return { kind: 'stop', error: new Error(`unhandled refusal ${JSON.stringify(unhandled)}`) };
+    }
+  }
+};
+
+/**
+ * Sends an ERC-20 token from PulseChain to Ethereum and claims it there by hand.
+ *
+ * @param options - see {@link TokenToEthereumOptions}
+ * @returns the crossing hash, the claim hash (null when somebody else released it), and the final status
+ */
+export const sendTokenToEthereum = async (
+  options: TokenToEthereumOptions,
+): Promise<{
+  readonly crossingHash: Hex;
+  readonly claimHash: Hex | null;
+  readonly finalStatus: TransferStatus;
+}> => {
+  const { signer, signal } = options;
+  const clientForChain = createClientLookup(options.rpcUrlByChainId);
+  const requireClient = requireClientWith(clientForChain);
+  const pulsechainClient = requireClient(pulsechainChainId);
+  const ethereumClient = requireClient(Number(Chains.ETH));
+
+  // 1. How PLSX maps onto Ethereum. A null `assetOutAddress` means the token
+  //    has not crossed before; the first transfer creates it. The search needs
+  //    a destination address, so this example stops there.
+  const assetLink = await tokenBridgeInfo({
+    bridgeKey: pulsechainToEthereum,
+    assetIn: plsx,
+    isProd: true,
+    fromChainClient: pulsechainClient,
+    toChainClient: ethereumClient,
+  });
+  if (assetLink === null || assetLink.assetOutAddress === null) {
+    throw new Error('PLSX has no bridged address on Ethereum yet');
+  }
+
+  const search = await searchBridgeRoutes({
+    origin: {
+      chainId: pulsechainChainId,
+      token: plsx,
+      amount: options.amount,
+      account: signer.address,
+    },
+    destination: {
+      chainId: Number(Chains.ETH),
+      token: { address: assetLink.assetOutAddress, decimals: plsx.decimals, symbol: plsx.symbol },
+      recipient: signer.address,
+    },
+    clientForChain,
+    fetch: (input, init) => globalThis.fetch(input, init),
+    signal,
+  });
+
+  // The direct crossing: one section, one omnibridge hop.
+  const crossing = search.routes.find(
+    ({ plan }) =>
+      plan.signatures.length === 1 && plan.hops[0]?.edge.carrier === Providers.PULSECHAIN,
+  );
+  if (crossing === undefined)
+    throw new Error('the search served no direct crossing for this token');
+
+  // 2. Plan it. Delivery is off: nobody is paid to release it on Ethereum, so
+  //    the user claims it there and pays the Ethereum gas.
+  const plan = await planCandidateExecution({
+    candidate: crossing.candidate,
+    account: signer.address,
+    readAllowance: allowanceReaderWith(requireClient),
+    resolveToken: search.resolveToken,
+    sections: [
+      {
+        amountIn: options.amount,
+        recipient: signer.address,
+        omnibridge: { isProd: true, assetLink, delivery: { shouldDeliver: false }, unwrap: false },
+      },
+    ],
+  });
+  if (plan.kind === 'refused') throw new Error(`cannot plan the crossing: ${plan.refusal.reason}`);
+  // plan.transactions is [approve (when the allowance is short), bridge], both on PulseChain.
+
+  const sent = await sendPlannedTransactions({
+    transactions: plan.transactions,
+    signer,
+    requireClient,
+    // Every transaction is on PulseChain, so this is never called.
+    waitForArrival: async () => {},
+  });
+  const bridge = sent.find(({ transaction }) => transaction.kind === 'bridge');
+  if (bridge === undefined) throw new Error('the plan held no bridge transaction');
+  const source = { chainId: pulsechainChainId, txHash: bridge.hash } as const;
+  const statusOptions = { signal, originClient: pulsechainClient } as const;
+
+  // 3. Wait until the validators have signed. `claimable` is true in both
+  //    ready states. `delivered` means somebody released it already.
+  const ready = await waitForTransferStatus({
+    source,
+    statusOptions,
+    isDone: (status) => status.claimable || status.state === 'delivered',
+    intervalMs: 30_000,
+  });
+  if (ready.state === 'delivered')
+    return { crossingHash: bridge.hash, claimHash: null, finalStatus: ready };
+
+  // 4. Build the claim from the indexer's record. Retry only on `not-signed-yet`.
+  for (;;) {
+    const request = await readClaimRecord({ txHash: bridge.hash, signal });
+    // Delivery was off, so the claim goes straight to the destination bridge and pays no tip.
+    const claim = buildClaimTransaction({ request, via: { kind: 'direct' } });
+    if (claim.kind === 'refused') {
+      const action = actionForRefusal(claim.refusal);
+      if (action.kind === 'stop') throw action.error;
+      if (action.kind === 'done') {
+        const finalStatus = await waitForTransferStatus({
+          source,
+          statusOptions,
+          isDone: (status) => status.state === 'delivered',
+          intervalMs: 15_000,
+        });
+        return { crossingHash: bridge.hash, claimHash: null, finalStatus };
+      }
+      await sleep(30_000, signal);
+      continue;
+    }
+
+    // 5. Send the claim on Ethereum (`claim.transaction.chainId` is 1).
+    const [claimSent] = await sendPlannedTransactions({
+      transactions: [claim.transaction],
+      signer,
+      requireClient,
+      waitForArrival: async () => {},
+    });
+    if (claimSent === undefined) throw new Error('the claim was not sent');
+    const receipt = await requireClient(claim.transaction.chainId).waitForTransactionReceipt({
+      hash: claimSent.hash,
+    });
+    if (receipt.status !== 'success') throw new Error(`the claim ${claimSent.hash} reverted`);
+    const finalStatus = await waitForTransferStatus({
+      source,
+      statusOptions,
+      isDone: (status) => status.state === 'delivered',
+      intervalMs: 15_000,
+    });
+    return { crossingHash: bridge.hash, claimHash: claimSent.hash, finalStatus };
+  }
+};

package/docs/examples/shared.ts

@@ -0,0 +1,261 @@
+/**
+ * Helpers both wallet examples share: the signer the examples expect, one viem
+ * client per chain from the wallet's own RPC endpoints, an allowance reader,
+ * a sender that honours `waitForReceipt`, and a status poller.
+ *
+ * The packages do not depend on web3.js, so the signer is a small
+ * interface. A web3.js v4 adapter for it is shown in a comment below.
+ *
+ * These files are typechecked only. They are never run against a live chain.
+ */
+import {
+  type FetchTransferStatusOptions,
+  fetchTransferStatus,
+  type TransferSource,
+  type TransferStatus,
+} from '@gibs/bridge-indexer';
+import type { AllowanceReader, PlannedTx } from '@gibs/bridge-sdk/execution';
+import { type Chain, createPublicClient, erc20Abi, type Hex, http, type PublicClient, zeroAddress } from 'viem';
+import { mainnet, pulsechain } from 'viem/chains';
+
+/** One transaction for the wallet to sign and broadcast. */
+export type WalletTransactionRequest = {
+  readonly chainId: number;
+  readonly from: Hex;
+  readonly to: Hex;
+  readonly data: Hex;
+  readonly value: bigint;
+  /** Set only when the plan names a gas limit. Otherwise the wallet estimates it. */
+  readonly gas?: bigint;
+};
+
+/**
+ * The signer the examples expect. It broadcasts one transaction on the chain
+ * the request names and resolves with the transaction hash, before the
+ * transaction is mined. The examples wait for receipts themselves, through
+ * the viem clients, only where the plan says `waitForReceipt`.
+ *
+ * A web3.js v4 adapter, with one `Web3` instance per chain:
+ *
+ * ```ts
+ * import { Web3 } from 'web3';
+ *
+ * const web3ByChainId = new Map<number, Web3>([[1, ethereumWeb3], [369, pulsechainWeb3]]);
+ * const signer: WalletSigner = {
+ *   address: account,
+ *   sendTransaction: (request) =>
+ *     new Promise((resolve, reject) => {
+ *       const web3 = web3ByChainId.get(request.chainId);
+ *       if (web3 === undefined) return reject(new Error(`no web3 for chain ${request.chainId}`));
+ *       // web3.eth.sendTransaction returns a PromiEvent. Awaiting it resolves
+ *       // with the mined receipt; the 'transactionHash' event fires first.
+ *       web3.eth
+ *         .sendTransaction({
+ *           from: request.from,
+ *           to: request.to,
+ *           data: request.data,
+ *           value: request.value,
+ *           ...(request.gas === undefined ? {} : { gas: request.gas }),
+ *         })
+ *         .on('transactionHash', (hash) => resolve(hash as Hex))
+ *         .on('error', reject);
+ *     }),
+ * };
+ * ```
+ */
+export type WalletSigner = {
+  readonly address: Hex;
+  readonly sendTransaction: (request: WalletTransactionRequest) => Promise<Hex>;
+};
+
+/** The wallet's own RPC endpoint for each chain it supports, by decimal chain id. */
+export type RpcUrlByChainId = ReadonlyMap<number, string>;
+
+/** The chains these examples touch. A real wallet lists every chain it supports. */
+const viemChainById: ReadonlyMap<number, Chain> = new Map<number, Chain>([
+  [mainnet.id, mainnet],
+  [pulsechain.id, pulsechain],
+]);
+
+/**
+ * Builds one viem public client per chain, from the wallet's own endpoints.
+ * Never the demo endpoints (`demoRpcUrls` in `@gibs/bridge-sdk/chains`).
+ *
+ * @param rpcUrlByChainId - the wallet's endpoint for each chain
+ * @returns a lookup that answers null for a chain the wallet has no endpoint for
+ */
+export const createClientLookup = (
+  rpcUrlByChainId: RpcUrlByChainId,
+): ((chainId: number) => PublicClient | null) => {
+  const clients = new Map<number, PublicClient>();
+  for (const [chainId, url] of rpcUrlByChainId) {
+    const chain = viemChainById.get(chainId);
+    if (chain === undefined) continue;
+    clients.set(chainId, createPublicClient({ chain, transport: http(url) }));
+  }
+  return (chainId) => clients.get(chainId) ?? null;
+};
+
+/**
+ * Wraps a client lookup so that a missing chain fails fast with a clear message.
+ *
+ * @param clientForChain - the lookup from {@link createClientLookup}
+ * @returns a lookup that throws for a chain with no client
+ */
+export const requireClientWith =
+  (clientForChain: (chainId: number) => PublicClient | null) =>
+  (chainId: number): PublicClient => {
+    const client = clientForChain(chainId);
+    if (client === null) throw new Error(`the wallet has no RPC endpoint for chain ${chainId}`);
+    return client;
+  };
+
+/**
+ * An allowance reader for `planCandidateExecution`, on the wallet's own clients.
+ *
+ * @param requireClient - see {@link requireClientWith}
+ * @returns the reader
+ */
+export const allowanceReaderWith =
+  (requireClient: (chainId: number) => PublicClient): AllowanceReader =>
+  (chainId, token, owner, spender) =>
+    requireClient(chainId).readContract({
+      address: token,
+      abi: erc20Abi,
+      functionName: 'allowance',
+      args: [owner, spender],
+    });
+
+/**
+ * Reads what an account holds of one token, or of the native coin when the
+ * token is the zero address. The examples read it before and after a
+ * crossing, so a later section spends what actually arrived.
+ *
+ * @param options.client - a client on the token's chain
+ * @param options.token - the token, or the zero address for the native coin
+ * @param options.owner - the account
+ * @returns the balance, in the token's base units
+ */
+export const readBalance = (options: {
+  readonly client: PublicClient;
+  readonly token: string;
+  readonly owner: Hex;
+}): Promise<bigint> => {
+  const { client, token, owner } = options;
+  if (token.toLowerCase() === zeroAddress) return client.getBalance({ address: owner });
+  return client.readContract({ address: token as Hex, abi: erc20Abi, functionName: 'balanceOf', args: [owner] });
+};
+
+/** One transaction the sender broadcast, with its hash. */
+export type SentTransaction = { readonly transaction: PlannedTx; readonly hash: Hex };
+
+/**
+ * Sends a plan's transactions in order.
+ *
+ * - It waits for a receipt only where the plan sets `waitForReceipt`.
+ * - A receipt is not arrival. When the next transaction is on another chain,
+ *   it calls `waitForArrival` with the transaction that started the crossing,
+ *   and sends nothing more until that resolves.
+ *
+ * @param options.transactions - the plan's transactions, in plan order
+ * @param options.signer - the wallet's signer
+ * @param options.requireClient - see {@link requireClientWith}
+ * @param options.waitForArrival - resolves once the crossing's funds arrived on the next chain
+ * @returns every transaction sent, with its hash, in order
+ * @throws when a receipt reports a revert
+ */
+export const sendPlannedTransactions = async (options: {
+  readonly transactions: readonly PlannedTx[];
+  readonly signer: WalletSigner;
+  readonly requireClient: (chainId: number) => PublicClient;
+  readonly waitForArrival: (crossing: SentTransaction) => Promise<void>;
+}): Promise<readonly SentTransaction[]> => {
+  const { transactions, signer, requireClient, waitForArrival } = options;
+  const sent: SentTransaction[] = [];
+  for (const [index, transaction] of transactions.entries()) {
+    const hash = await signer.sendTransaction({
+      chainId: transaction.chainId,
+      from: signer.address,
+      to: transaction.to,
+      data: transaction.data,
+      value: transaction.value,
+      ...(transaction.gasLimit === null ? {} : { gas: transaction.gasLimit }),
+    });
+    sent.push({ transaction, hash });
+    if (!transaction.waitForReceipt) continue;
+    const receipt = await requireClient(transaction.chainId).waitForTransactionReceipt({ hash });
+    if (receipt.status !== 'success') {
+      throw new Error(
+        `${transaction.kind} transaction ${hash} reverted on chain ${transaction.chainId}`,
+      );
+    }
+    const next = transactions[index + 1];
+    if (next !== undefined && next.chainId !== transaction.chainId) {
+      await waitForArrival({ transaction, hash });
+    }
+  }
+  return sent;
+};
+
+/**
+ * Waits for a time, or rejects when the signal fires.
+ *
+ * @param milliseconds - how long to wait
+ * @param signal - cancels the wait
+ */
+export const sleep = (milliseconds: number, signal?: AbortSignal): Promise<void> =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+
+/** A transfer that ended badly. Waiting longer does not change it. */
+export class TransferEndedError extends Error {
+  constructor(readonly status: TransferStatus) {
+    super(`the transfer ended as ${status.state}`);
+    this.name = 'TransferEndedError';
+  }
+}
+
+/**
+ * Polls `fetchTransferStatus` until `isDone` accepts an answer.
+ *
+ * @param options.source - the transaction that started the transfer
+ * @param options.statusOptions - passed through to `fetchTransferStatus`
+ * @param options.isDone - true for the answer the caller waits for
+ * @param options.intervalMs - the pause between polls
+ * @returns the first answer `isDone` accepts
+ * @throws {TransferEndedError} on `failed` or `stranded`
+ */
+export const waitForTransferStatus = async (options: {
+  readonly source: TransferSource;
+  readonly statusOptions: FetchTransferStatusOptions;
+  readonly isDone: (status: TransferStatus) => boolean;
+  readonly intervalMs: number;
+}): Promise<TransferStatus> => {
+  const { source, statusOptions, isDone, intervalMs } = options;
+  for (;;) {
+    const status = await fetchTransferStatus(source, statusOptions);
+    if (status.state === 'failed' || status.state === 'stranded')
+      throw new TransferEndedError(status);
+    if (isDone(status)) return status;
+    await sleep(intervalMs, statusOptions.signal);
+  }
+};
+
+/**
+ * The unix-seconds deadline a PulseX swap carries, `seconds` from now.
+ *
+ * @param seconds - how long the swap stays valid
+ * @returns the deadline
+ */
+export const deadlineIn = (seconds: number): bigint =>
+  BigInt(Math.floor(Date.now() / 1000) + seconds);

package/docs/examples/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "types": []
+  },
+  "include": ["*.ts"]
+}