@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/cjs/tron-execution.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBroadcastResponse = exports.readTriggerSmartContractResponse = exports.tronErrorMessage = exports.buildTriggerSmartContractRequest = exports.isSameTronAccount = exports.normalizeTronHexAddress = exports.maximumTronFeeLimitSun = exports.defaultTronFeeLimitSun = exports.tronTriggerSmartContractPath = void 0;
+/**
+ * Executing a deposit on Tron, as pure data.
+ *
+ * Relay does not return a broadcastable Tron transaction. It returns the
+ * *parameters* of a `TriggerSmartContract` call — owner, contract, call value
+ * and calldata — and nothing else. A Tron transaction additionally needs a
+ * reference block, an expiration and a fee limit, none of which Relay supplies.
+ * Those are produced by asking a full node to build the transaction, which is
+ * what {@link buildTriggerSmartContractRequest} constructs the body for. The
+ * node answers with an UNSIGNED transaction; the wallet signs it and a second
+ * call broadcasts it.
+ *
+ * Three details of that exchange lose money or mislead if handled naively:
+ *
+ * **The `visible` flag defaults to true.** A node reads addresses as base58
+ * unless told otherwise, but Relay returns them as hex with Tron's `41` prefix.
+ * Omitting the flag therefore hands base58-parsing a hex string. The request
+ * built here always states `visible: false` rather than relying on a default
+ * that is the opposite of what the payload contains.
+ *
+ * **`fee_limit` is required and Relay omits it.** It caps the energy the caller
+ * will pay for. Set too low, the call runs out of energy, reverts, and the
+ * energy already burned is NOT refunded — the deposit fails and costs the user
+ * anyway.
+ *
+ * **A rejected call still answers HTTP 200**, with the reason hex-encoded in
+ * `result.message`. Reading the status code alone reports a failed deposit as a
+ * success, and printing the message unmodified shows the user a wall of hex.
+ * {@link tronErrorMessage} decodes it.
+ *
+ * Kept free of transport and of clock reads so it is fully testable: nothing
+ * here signs, fetches, or calls `Date.now`. The caller performs the requests.
+ */
+/** Path of the full-node endpoint that builds an unsigned contract call. */
+exports.tronTriggerSmartContractPath = '/wallet/triggersmartcontract';
+/**
+ * The fee limit used when a caller states none, in sun (1 TRX = 1,000,000 sun).
+ *
+ * Thirty TRX, matching Relay's own wallet adapter, which is the only reference
+ * implementation of this deposit path. It is an upper bound rather than a
+ * charge: unused energy is not taken, so the cost of setting it generously is
+ * only that the wallet shows a larger worst case.
+ */
+exports.defaultTronFeeLimitSun = 30_000_000;
+/**
+ * The largest fee limit a node accepts, in sun — 15,000 TRX. Documented as a
+ * hard protocol cap, so a request above it is rejected outright rather than
+ * clamped.
+ */
+exports.maximumTronFeeLimitSun = 15_000_000_000;
+/**
+ * Tron's `41` address prefix, the hex form's equivalent of the base58 `T`.
+ */
+const tronHexAddressPrefix = '41';
+/** A hex address is the prefix byte plus a twenty-byte account identifier. */
+const tronHexAddressLength = 42;
+/**
+ * Normalizes a Tron hex address for comparison.
+ *
+ * Wallets and quotes disagree on casing, and Relay's payload is not guaranteed
+ * to match what a wallet reports even when both name the same account.
+ *
+ * @param value - an address in Tron's `41`-prefixed hex form, in any casing,
+ *   optionally written with a `0x` prefix
+ * @returns the lowercase `41` form, or null when the value is not that form
+ */
+const normalizeTronHexAddress = (value) => {
+    const withoutPrefix = value.trim().replace(/^0x/i, '').toLowerCase();
+    if (withoutPrefix.length !== tronHexAddressLength) {
+        return null;
+    }
+    if (!withoutPrefix.startsWith(tronHexAddressPrefix)) {
+        return null;
+    }
+    return /^[0-9a-f]+$/.test(withoutPrefix) ? withoutPrefix : null;
+};
+exports.normalizeTronHexAddress = normalizeTronHexAddress;
+/**
+ * Whether two Tron hex addresses name the same account.
+ *
+ * Used to check a deposit's owner against the connected wallet before signing.
+ * A mismatch means the quote was built for a different account, and signing it
+ * would spend from an account the user did not choose — or simply fail after
+ * the user has already approved.
+ *
+ * @param left - an address in Tron's `41`-prefixed hex form
+ * @param right - an address in the same form
+ * @returns true only when both parse and name the same account
+ */
+const isSameTronAccount = (left, right) => {
+    const normalizedLeft = (0, exports.normalizeTronHexAddress)(left);
+    const normalizedRight = (0, exports.normalizeTronHexAddress)(right);
+    return normalizedLeft !== null && normalizedLeft === normalizedRight;
+};
+exports.isSameTronAccount = isSameTronAccount;
+/**
+ * Strips the `0x` prefix Tron calldata never carries.
+ *
+ * Relay documents this field as bare hex, but its own adapter strips the prefix
+ * defensively, and a prefixed value is parsed by a node as calldata beginning
+ * with the bytes `0x` rather than being rejected — a silently wrong call.
+ */
+const bareHex = (value) => value.replace(/^0x/i, '').toLowerCase();
+/**
+ * Whether a numeric amount survives the trip through JSON as an exact integer.
+ *
+ * Sun amounts are 64-bit on the wire but JSON carries them as doubles, so a
+ * large enough value would be silently rounded — into a different amount of
+ * money than the one that was quoted.
+ */
+const isExactInteger = (value) => value >= 0n && value <= BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * Builds the body that asks a full node to construct the unsigned deposit.
+ *
+ * @param deposit - the parsed origin deposit
+ * @param options.feeLimitSun - the energy spending cap in sun; defaults to
+ *   {@link defaultTronFeeLimitSun}
+ * @returns the request body, or null when the deposit names an address that is
+ *   not Tron hex, carries a call value that cannot be represented exactly, or
+ *   the fee limit is outside what a node accepts — never a body that would be
+ *   built against a default `visible` the payload contradicts
+ */
+const buildTriggerSmartContractRequest = (deposit, { feeLimitSun = exports.defaultTronFeeLimitSun } = {}) => {
+    const ownerAddress = (0, exports.normalizeTronHexAddress)(deposit.ownerAddress);
+    const contractAddress = (0, exports.normalizeTronHexAddress)(deposit.contractAddress);
+    if (ownerAddress === null || contractAddress === null) {
+        return null;
+    }
+    if (!isExactInteger(deposit.callValue)) {
+        return null;
+    }
+    if (!Number.isInteger(feeLimitSun) || feeLimitSun <= 0 || feeLimitSun > exports.maximumTronFeeLimitSun) {
+        return null;
+    }
+    return {
+        owner_address: ownerAddress,
+        contract_address: contractAddress,
+        data: bareHex(deposit.data),
+        call_value: Number(deposit.callValue),
+        fee_limit: feeLimitSun,
+        visible: false,
+    };
+};
+exports.buildTriggerSmartContractRequest = buildTriggerSmartContractRequest;
+/**
+ * Decodes a node's hex-encoded failure message.
+ *
+ * A node reports why it refused a call in `result.message`, hex-encoded — the
+ * bytes `4e6f20636f6e7472616374…` rather than "No contract or not a valid smart
+ * contract". Broadcast failures report plain text in the same field, so both
+ * are handled and a value that is not hex is passed through unchanged.
+ */
+const decodeTronMessage = (value) => {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || trimmed.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(trimmed)) {
+        return trimmed;
+    }
+    let decoded = '';
+    for (let index = 0; index < trimmed.length; index += 2) {
+        decoded += String.fromCharCode(Number.parseInt(trimmed.slice(index, index + 2), 16));
+    }
+    // A hex string that decodes to control characters was a number, not a
+    // message — return the original rather than a string of unprintable bytes.
+    return /^[\x20-\x7e]*$/.test(decoded) ? decoded : trimmed;
+};
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+/**
+ * Extracts a node's failure reason from either endpoint's response.
+ *
+ * @param payload - the parsed response body
+ * @returns the decoded message, or null when the response reports no failure
+ */
+const tronErrorMessage = (payload) => {
+    const body = asRecord(payload);
+    if (body === null) {
+        return null;
+    }
+    // The build endpoint nests its outcome under `result`; the broadcast endpoint
+    // reports at the top level.
+    const nested = asRecord(body.result);
+    const message = nested?.message ?? body.message;
+    if (typeof message !== 'string') {
+        return null;
+    }
+    const decoded = decodeTronMessage(message);
+    return decoded.length === 0 ? null : decoded;
+};
+exports.tronErrorMessage = tronErrorMessage;
+/**
+ * Reads the unsigned transaction out of a build response.
+ *
+ * The response carries the transaction at the top level alongside a `result`
+ * object stating whether the build succeeded, so the presence of a `txID` is
+ * not on its own evidence of success.
+ *
+ * @param payload - the parsed `/wallet/triggersmartcontract` response
+ * @returns the unsigned transaction to hand a wallet, or null when the node
+ *   refused the call
+ */
+const readTriggerSmartContractResponse = (payload) => {
+    const body = asRecord(payload);
+    if (body === null) {
+        return null;
+    }
+    const outcome = asRecord(body.result);
+    if (outcome === null || outcome.result !== true) {
+        return null;
+    }
+    const transaction = asRecord(body.transaction);
+    if (transaction === null || typeof transaction.txID !== 'string') {
+        return null;
+    }
+    return transaction;
+};
+exports.readTriggerSmartContractResponse = readTriggerSmartContractResponse;
+/**
+ * Reads the transaction identifier out of a broadcast response.
+ *
+ * GOTCHA: a rejected broadcast answers HTTP 200, and `result` is OMITTED rather
+ * than set to false. Testing `result === false` therefore never fires, and
+ * trusting the status code records a deposit that never entered a block. Only
+ * an explicit `result: true` is accepted here.
+ *
+ * The identifier is read from `txid` where a node reports it, falling back to
+ * the echoed transaction's `txID`. The two spellings differ by casing and by
+ * position: a node answers `txid`, while a wallet library that echoes the
+ * transaction it broadcast carries `txID` inside it. Accepting only the first
+ * would report an accepted broadcast as a failure whenever the caller is one of
+ * those libraries.
+ *
+ * @param payload - the parsed `/wallet/broadcasttransaction` response
+ * @returns the transaction identifier, or null when the broadcast was refused
+ */
+const readBroadcastResponse = (payload) => {
+    const body = asRecord(payload);
+    if (body === null || body.result !== true) {
+        return null;
+    }
+    const echoed = asRecord(body.transaction);
+    const identifier = body.txid ?? echoed?.txID;
+    return typeof identifier === 'string' && identifier.length > 0 ? identifier : null;
+};
+exports.readBroadcastResponse = readBroadcastResponse;

package/dist/cjs/types.d.ts

@@ -0,0 +1,51 @@
+import type { Chain, Hex } from 'viem';
+import type { Chains, Provider } from './config.js';
+export type { RouteStep, RouteStepKind } from './route-steps.js';
+/** The per network bridge link */
+export type PerNetworkBridgeLink = {
+    tokenAddress: Hex;
+};
+/** The extensions for a token */
+export type Extensions = {
+    wrapped?: {
+        address: Hex;
+    };
+    bridgeInfo?: Record<number, PerNetworkBridgeLink>;
+};
+/** The metadata for a token */
+export type TokenMetadata = {
+    name: string;
+    symbol: string;
+    decimals: number;
+};
+/** The token for a given asset */
+export type Token = TokenMetadata & {
+    address: string;
+    chainId: number;
+    logoURI: string | null;
+    extensions?: Extensions;
+    /**
+     * Spot USD price as a decimal string, when a price source provides one inline
+     * (e.g. the LI.FI `/tokens` response). Absent/null for tokens from sources
+     * that carry no price (e.g. the dapp image lists).
+     */
+    priceUSD?: string | null;
+};
+/** The token out for a given asset */
+export type TokenOut = Omit<Token, 'address'> & {
+    address: string | null;
+};
+/** The token list for a given asset */
+export type TokenList = {
+    tokens: Token[];
+};
+/** The bridge key for a given provider, from chain, and to chain */
+export type BridgeKey = [Provider, Chains, Chains];
+/** The visual chain for a given chain */
+export type VisualChain = Chain & {
+    chainId: Chains;
+    logoURI: string;
+    alt: string;
+};
+/** The metadata for a chain */
+export type ChainsMetadata = Record<Chains, VisualChain>;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/claims.d.ts

@@ -0,0 +1,198 @@
+import { type Hex } from 'viem';
+import type { PlannedTx } from './execution.js';
+/**
+ * MANUAL CLAIMS. A home-to-foreign crossing (PulseChain to Ethereum, for
+ * example) ends with a release on the destination chain. When nobody delivers
+ * it, the reader claims it by hand: they send the validators' signatures and
+ * the encoded message to the destination bridge. This module builds that
+ * transaction from the bridge indexer's `UserRequest` record.
+ *
+ * THE INDEXER ASSUMPTION. The indexer collects the signatures in
+ * `handleSignedFor` (`packages/indexer/src/index.ts`, the handler for
+ * `HomeAMB:SignedForUserRequest` and `HomeAMB:SignedForAffirmation`). It does
+ * not read the signature from the event. It decodes the TRANSACTION's own
+ * input as `submitSignature(bytes signature, bytes message)`. That works only
+ * when a validator sends `submitSignature` straight to the home bridge from
+ * its own account.
+ *
+ * When a validator signs some other way (through a multisig wallet, a proxy,
+ * a batching contract, or any call whose top-level input is not
+ * `submitSignature`), the decode fails and the handler drops that signature.
+ * It still counts it: `confirmedSignatures` goes up by one, but `signatures`
+ * stays one short. `finishedSigning` does NOT stay false. The separate
+ * `HomeAMB:CollectedSignatures` event sets it to true regardless. So the
+ * record says "signed" while it holds too few signatures, and a claim built
+ * from it reverts on the destination bridge, which checks the count against
+ * its required-signature threshold. {@link buildClaimTransaction} refuses
+ * that record with `signatures-incomplete` rather than build a claim that
+ * cannot succeed.
+ */
+/** A signature split into the three parts the destination bridge reads, each as hex without a `0x` prefix. */
+export type SignatureParts = {
+    readonly v: string;
+    readonly r: string;
+    readonly s: string;
+};
+/**
+ * Splits one 65-byte validator signature into its `v`, `r` and `s` parts.
+ *
+ * @param rawSignature - the signature as the indexer stores it, with or without a `0x` prefix
+ * @returns the three parts, hex without prefixes
+ */
+export declare const signatureToVRS: (rawSignature: string) => SignatureParts;
+/**
+ * Packs signatures in the layout the bridge's `executeSignatures` reads: one
+ * count byte, then every `v`, then every `r`, then every `s`.
+ *
+ * @param signatures - the split signatures, in the order the validators signed
+ * @returns the packed signatures as one hex string
+ */
+export declare const packSignatures: (signatures: readonly SignatureParts[]) => Hex;
+/**
+ * The calldata for a release that pays no delivery tip: a direct call to the
+ * destination bridge.
+ *
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for `safeExecuteSignaturesWithAutoGasLimit`
+ */
+export declare const encodeReleaseWithoutTipData: ({ encodedData, encodedSignatures, }: {
+    encodedData: Hex;
+    encodedSignatures: Hex;
+}) => Hex;
+/**
+ * The calldata for a release sent through the pathway's destination output
+ * router, the path a fee-director (delivery) request uses.
+ *
+ * @param options.validator - the pathway's validator contract
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for the router's `safeExecuteSignaturesWithAutoGasLimit`
+ */
+export declare const encodeReleaseToRouterData: ({ validator, encodedData, encodedSignatures, }: {
+    validator: Hex;
+    encodedData: Hex;
+    encodedSignatures: Hex;
+}) => Hex;
+/**
+ * Where a claim is sent.
+ *
+ * - `direct` sends it to the destination bridge and pays no delivery tip.
+ * - `router` sends it through the pathway's destination output router, which
+ *   pays the tip a fee-director request carries. Read both addresses from the
+ *   pathway (`pathway(bridgeKey)`'s `destinationRouter` and `validator`).
+ */
+export type ClaimRoute = {
+    readonly kind: 'direct';
+} | {
+    readonly kind: 'router';
+    readonly destinationRouter: Hex;
+    readonly validator: Hex;
+};
+/**
+ * The one place a claim's target and calldata come from. The interface's
+ * release hook and {@link buildClaimTransaction} both call it.
+ *
+ * @param options.encodedData - the bridge message
+ * @param options.signatures - the raw validator signatures, in signing order
+ * @param options.destinationAmbAddress - the destination bridge, used by the `direct` route
+ * @param options.via - which contract receives the claim
+ * @returns the target contract and the calldata
+ */
+export declare const claimCall: ({ encodedData, signatures, destinationAmbAddress, via, }: {
+    readonly encodedData: Hex;
+    readonly signatures: readonly string[];
+    readonly destinationAmbAddress: Hex;
+    readonly via: ClaimRoute;
+}) => {
+    readonly to: Hex;
+    readonly data: Hex;
+};
+/**
+ * The bridge indexer's `UserRequest` fields a claim reads. The names match the
+ * indexer's GraphQL type, so a caller passes the record it fetched as it is.
+ * The indexer sends its big-integer scalars as decimal strings, so the counts
+ * and the chain id accept a string as well.
+ */
+export type ClaimableUserRequest = {
+    /** `'signature'` for a home-to-foreign request. Only those are claimed by hand. */
+    readonly type: string;
+    readonly encodedData: string;
+    /** The JSON list of raw validator signatures, or null on a request type that collects none. */
+    readonly signatures?: unknown;
+    /** How many `SignedFor` events the indexer counted for this request. */
+    readonly confirmedSignatures: bigint | number | string;
+    /**
+     * The bridge's required-signature threshold in force for this request, as
+     * the indexer links it. When absent, the builder demands every counted
+     * signature, which is stricter than the bridge.
+     */
+    readonly requiredSignatures?: {
+        readonly value: bigint | number | string;
+    } | null;
+    readonly destinationAmbAddress: string;
+    readonly destinationChainId: bigint | number | string;
+    /** True once the indexer saw `CollectedSignatures` (or the delivery itself). */
+    readonly finishedSigning: boolean;
+    /** True once the release executed on the destination chain. */
+    readonly delivered: boolean;
+};
+/**
+ * Why a request cannot be claimed. Each case names a different action for the
+ * reader:
+ *
+ * - `wrong-type` — not a signature request. An affirmation request is
+ *   executed by the validators themselves; there is nothing to claim.
+ * - `already-delivered` — the release already executed. A claim would revert.
+ * - `not-signed-yet` — the validators have not finished signing. Wait.
+ * - `signatures-incomplete` — the indexer stored fewer signatures than the
+ *   bridge needs (the threshold, or every counted signature when the request
+ *   carries no threshold). See this module's note on the `submitSignature`
+ *   assumption. Waiting does not fix this one.
+ * - `malformed-request` — a field is not the shape the indexer documents.
+ */
+export type ClaimRefusal = {
+    readonly reason: 'wrong-type';
+    readonly type: string;
+} | {
+    readonly reason: 'already-delivered';
+} | {
+    readonly reason: 'not-signed-yet';
+} | {
+    readonly reason: 'signatures-incomplete';
+    readonly stored: number;
+    readonly needed: number;
+} | {
+    readonly reason: 'malformed-request';
+    readonly field: string;
+};
+/** A claim transaction, or the typed reason none can be built. */
+export type ClaimPlan = {
+    readonly kind: 'claim';
+    readonly transaction: PlannedTx;
+} | {
+    readonly kind: 'refused';
+    readonly refusal: ClaimRefusal;
+};
+/**
+ * Builds the manual-claim transaction for one bridge request, or refuses with
+ * a typed reason.
+ *
+ * The checks run in this order: request type, delivery, signing, then the
+ * stored signature count. A delivered request is refused before the signing
+ * check, because delivery also sets `finishedSigning`.
+ *
+ * ASSUMPTION: the signatures are only complete when every validator sent
+ * `submitSignature` directly to the home bridge. The indexer drops a
+ * signature sent any other way; see this module's head note. This builder
+ * catches the drop by comparing the stored list with the required-signature
+ * threshold, or with `confirmedSignatures` when the record carries no threshold.
+ *
+ * @param options.request - the indexer's `UserRequest` record
+ * @param options.via - the claim target; see {@link ClaimRoute}
+ * @returns a `claim` plan whose transaction runs on the destination chain, or a refusal
+ */
+export declare const buildClaimTransaction: ({ request, via, }: {
+    readonly request: ClaimableUserRequest;
+    readonly via: ClaimRoute;
+}) => ClaimPlan;

package/dist/claims.js

@@ -0,0 +1,140 @@
+import { encodeFunctionData, isHex, numberToHex } from 'viem';
+import * as abis from './abis.js';
+const strip0x = (input) => input.replace(/^0x/, '');
+/**
+ * Splits one 65-byte validator signature into its `v`, `r` and `s` parts.
+ *
+ * @param rawSignature - the signature as the indexer stores it, with or without a `0x` prefix
+ * @returns the three parts, hex without prefixes
+ */
+export const signatureToVRS = (rawSignature) => {
+    const signature = strip0x(rawSignature);
+    const word = 32;
+    const word2 = word * 2;
+    const word4 = word2 * 2;
+    const r = signature.slice(0, word2);
+    const s = signature.slice(word2, word4);
+    const v = signature.slice(word4);
+    return { v, r, s };
+};
+/**
+ * Packs signatures in the layout the bridge's `executeSignatures` reads: one
+ * count byte, then every `v`, then every `r`, then every `s`.
+ *
+ * @param signatures - the split signatures, in the order the validators signed
+ * @returns the packed signatures as one hex string
+ */
+export const packSignatures = (signatures) => {
+    const length = strip0x(numberToHex(signatures.length));
+    const countByte = length.length === 1 ? `0${length}` : length;
+    const v = signatures.map((signature) => signature.v).join('');
+    const r = signatures.map((signature) => signature.r).join('');
+    const s = signatures.map((signature) => signature.s).join('');
+    return `0x${countByte}${v}${r}${s}`;
+};
+/**
+ * The calldata for a release that pays no delivery tip: a direct call to the
+ * destination bridge.
+ *
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for `safeExecuteSignaturesWithAutoGasLimit`
+ */
+export const encodeReleaseWithoutTipData = ({ encodedData, encodedSignatures, }) => encodeFunctionData({
+    abi: abis.relayTokensDirect,
+    functionName: 'safeExecuteSignaturesWithAutoGasLimit',
+    args: [encodedData, encodedSignatures],
+});
+/**
+ * The calldata for a release sent through the pathway's destination output
+ * router, the path a fee-director (delivery) request uses.
+ *
+ * @param options.validator - the pathway's validator contract
+ * @param options.encodedData - the bridge message, `UserRequest.encodedData`
+ * @param options.encodedSignatures - the output of {@link packSignatures}
+ * @returns the calldata for the router's `safeExecuteSignaturesWithAutoGasLimit`
+ */
+export const encodeReleaseToRouterData = ({ validator, encodedData, encodedSignatures, }) => encodeFunctionData({
+    abi: abis.outputRouter,
+    functionName: 'safeExecuteSignaturesWithAutoGasLimit',
+    args: [validator, encodedData, encodedSignatures],
+});
+/**
+ * The one place a claim's target and calldata come from. The interface's
+ * release hook and {@link buildClaimTransaction} both call it.
+ *
+ * @param options.encodedData - the bridge message
+ * @param options.signatures - the raw validator signatures, in signing order
+ * @param options.destinationAmbAddress - the destination bridge, used by the `direct` route
+ * @param options.via - which contract receives the claim
+ * @returns the target contract and the calldata
+ */
+export const claimCall = ({ encodedData, signatures, destinationAmbAddress, via, }) => {
+    const encodedSignatures = packSignatures(signatures.map(signatureToVRS));
+    if (via.kind === 'router') {
+        return {
+            to: via.destinationRouter,
+            data: encodeReleaseToRouterData({ validator: via.validator, encodedData, encodedSignatures }),
+        };
+    }
+    return { to: destinationAmbAddress, data: encodeReleaseWithoutTipData({ encodedData, encodedSignatures }) };
+};
+const isSignatureList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && isHex(entry));
+const refused = (refusal) => ({ kind: 'refused', refusal });
+/**
+ * Builds the manual-claim transaction for one bridge request, or refuses with
+ * a typed reason.
+ *
+ * The checks run in this order: request type, delivery, signing, then the
+ * stored signature count. A delivered request is refused before the signing
+ * check, because delivery also sets `finishedSigning`.
+ *
+ * ASSUMPTION: the signatures are only complete when every validator sent
+ * `submitSignature` directly to the home bridge. The indexer drops a
+ * signature sent any other way; see this module's head note. This builder
+ * catches the drop by comparing the stored list with the required-signature
+ * threshold, or with `confirmedSignatures` when the record carries no threshold.
+ *
+ * @param options.request - the indexer's `UserRequest` record
+ * @param options.via - the claim target; see {@link ClaimRoute}
+ * @returns a `claim` plan whose transaction runs on the destination chain, or a refusal
+ */
+export const buildClaimTransaction = ({ request, via, }) => {
+    if (request.type !== 'signature')
+        return refused({ reason: 'wrong-type', type: request.type });
+    if (request.delivered)
+        return refused({ reason: 'already-delivered' });
+    if (!request.finishedSigning)
+        return refused({ reason: 'not-signed-yet' });
+    if (!isSignatureList(request.signatures))
+        return refused({ reason: 'malformed-request', field: 'signatures' });
+    if (!isHex(request.encodedData))
+        return refused({ reason: 'malformed-request', field: 'encodedData' });
+    if (!isHex(request.destinationAmbAddress)) {
+        return refused({ reason: 'malformed-request', field: 'destinationAmbAddress' });
+    }
+    const needed = Number(request.requiredSignatures?.value ?? request.confirmedSignatures);
+    const stored = request.signatures.length;
+    if (stored < needed)
+        return refused({ reason: 'signatures-incomplete', stored, needed });
+    const { to, data } = claimCall({
+        encodedData: request.encodedData,
+        signatures: request.signatures,
+        destinationAmbAddress: request.destinationAmbAddress,
+        via,
+    });
+    return {
+        kind: 'claim',
+        transaction: {
+            chainId: Number(request.destinationChainId),
+            kind: 'claim',
+            to,
+            data,
+            value: 0n,
+            // The calldata itself asks the bridge to pick its own gas limit
+            // (`safeExecuteSignaturesWithAutoGasLimit`); the wallet estimates the rest.
+            gasLimit: null,
+            waitForReceipt: false,
+        },
+    };
+};

package/dist/config.d.ts

@@ -33,6 +33,30 @@ export declare const Providers: {
 export type Provider = (typeof Providers)[keyof typeof Providers];
 /** A map of chains to native asset out addresses */
 export declare const nativeAssetOut: Record<Chains, Hex>;
+/**
+ * Four PulseChain mainnet tokens that no other constant in this package
+ * names. The PulseX carrier routes swaps through them
+ * (`routing/carriers/pulsex-paths.ts`), and the interface builds its
+ * PulseChain hub nodes from the two stablecoins.
+ *
+ * Each address was already in the repository before it moved here: USDC and
+ * USDT from the interface's `HUB_STABLECOIN_ADDRESSES`
+ * (`packages/ui/src/lib/state/useRouteSearch.ts`), PLSX and HEX from
+ * `scripts/route-parity-corpus.ts`. Each one was read on chain again on
+ * 2026-10-06 (`symbol()`, `decimals()`): PLSX 18, HEX 8, USDC 6, USDT 6.
+ * `getAddress` checksums them at load, so a mistyped character fails the
+ * build rather than silently matching nothing.
+ */
+export declare const pulsechainTokenAddresses: Readonly<{
+    /** PulseX, the exchange's own token. */
+    PLSX: `0x${string}`;
+    /** HEX. */
+    HEX: `0x${string}`;
+    /** USD Coin, bridged from Ethereum. */
+    USDC: `0x${string}`;
+    /** Tether USD, bridged from Ethereum. */
+    USDT: `0x${string}`;
+}>;
 /** A map of chains to deprecated native asset out addresses */
 export declare const deprecatedNativeAssetOut: Partial<Record<Chains, Set<Hex>>>;
 /** A map of chains to uni v2 router addresses */