@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/tron-execution.js

@@ -0,0 +1,239 @@
+/**
+ * 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. */
+export const 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.
+ */
+export const 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.
+ */
+export const 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
+ */
+export 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;
+};
+/**
+ * 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
+ */
+export const isSameTronAccount = (left, right) => {
+    const normalizedLeft = normalizeTronHexAddress(left);
+    const normalizedRight = normalizeTronHexAddress(right);
+    return normalizedLeft !== null && normalizedLeft === normalizedRight;
+};
+/**
+ * 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
+ */
+export const buildTriggerSmartContractRequest = (deposit, { feeLimitSun = defaultTronFeeLimitSun } = {}) => {
+    const ownerAddress = normalizeTronHexAddress(deposit.ownerAddress);
+    const contractAddress = normalizeTronHexAddress(deposit.contractAddress);
+    if (ownerAddress === null || contractAddress === null) {
+        return null;
+    }
+    if (!isExactInteger(deposit.callValue)) {
+        return null;
+    }
+    if (!Number.isInteger(feeLimitSun) || feeLimitSun <= 0 || feeLimitSun > maximumTronFeeLimitSun) {
+        return null;
+    }
+    return {
+        owner_address: ownerAddress,
+        contract_address: contractAddress,
+        data: bareHex(deposit.data),
+        call_value: Number(deposit.callValue),
+        fee_limit: feeLimitSun,
+        visible: false,
+    };
+};
+/**
+ * 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
+ */
+export 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;
+};
+/**
+ * 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
+ */
+export 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;
+};
+/**
+ * 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
+ */
+export 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;
+};

package/dist/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/types.js

@@ -0,0 +1 @@
+export {};

package/llms.txt

@@ -0,0 +1,169 @@
+# @gibs/bridge-sdk
+
+> A TypeScript library that prices and builds transfers across the Gibs
+> Finance omnibridges (PulseChain with Ethereum, PulseChain with BNB Smart
+> Chain). It also builds the requests for the aggregator routes (LI.FI,
+> Relay, NEAR Intents) that reach those bridges from other chains. It does
+> not sign or send anything. You bring a viem client and a wallet.
+
+## Install
+
+- Run `npm install @gibs/bridge-sdk viem`.
+- The package is ESM only. Use `import`, not `require`.
+- It needs Node 20 or later (`engines.node` is `>=20`).
+- viem is a peer dependency. The range is `>=2.37.0 <3`.
+- Version note: 1.12.0 and older on npm are broken. 1.13.0 is the first usable version.
+- In a browser, `@gibs/bridge-sdk/ton-execution` needs a global `Buffer`. No other entry point does.
+
+## Entry points
+
+Import from the narrowest subpath. The root `@gibs/bridge-sdk` exports everything.
+
+- `@gibs/bridge-sdk/config`: chains, providers, pathways, native-asset tables.
+- `@gibs/bridge-sdk/types`: shared types such as `BridgeKey` and `Token`.
+- `@gibs/bridge-sdk/chains`: viem chain objects with logos and RPC URLs.
+- `@gibs/bridge-sdk/chain-info`: on-chain reads (token mappings, fees, minimum amounts).
+- `@gibs/bridge-sdk/settings`: fee and amount arithmetic.
+- `@gibs/bridge-sdk/consolidated-quote`: LI.FI request builders and parsers.
+- `@gibs/bridge-sdk/relay-quote`: Relay request builders and parsers.
+- `@gibs/bridge-sdk/near-intents`: NEAR Intents requests and parsers.
+- `@gibs/bridge-sdk/pre-quote`: price checks before a binding quote.
+- `@gibs/bridge-sdk/routing`: route search across carriers.
+- `@gibs/bridge-sdk/image-links`: image URLs from gib.show.
+- `@gibs/bridge-sdk/abis`: contract ABIs.
+
+## Chains and pathways
+
+A chain is a hex id from the `Chains` enum. A route is a `BridgeKey`:
+`[provider, fromChain, toChain]`. `pathway` returns the contract addresses
+for a key, or `undefined` when no pathway exists.
+
+```ts
+import { Chains, Providers, pathway } from '@gibs/bridge-sdk/config'
+import type { BridgeKey } from '@gibs/bridge-sdk/types'
+
+const bridgeKey: BridgeKey = [Providers.PULSECHAIN, Chains.ETH, Chains.PLS]
+const route = pathway(bridgeKey, true) // true: mainnet only
+if (route) {
+  route.from // the mediator on Ethereum, where funds enter
+  route.feeManager // 'to': the PulseChain mediator owns the fee manager
+}
+```
+
+## Fees: direction and units
+
+These rules must hold in every integration.
+
+- PulseChain is the home side of both omnibridges.
+- Foreign to home (`feeF2H`) means entering PulseChain.
+- Home to foreign (`feeH2F`) means leaving PulseChain.
+- Use the fee for your direction. Do not use one fee for both.
+- Bridge fees are a rate per `1e18`. `1e18` is one hundred percent.
+- Aggregator referral fees are basis points. `10_000n` is one hundred percent.
+- LI.FI takes its fee as a decimal fraction (`0.001` is a tenth of a percent).
+- Fees are on-chain settings. Read them. Do not hard-code them.
+
+```ts
+import { loadBridgeFees } from '@gibs/bridge-sdk/chain-info'
+import { Chains, pathway, Providers } from '@gibs/bridge-sdk/config'
+import { amountAfterBridgeFee, bridgeCost } from '@gibs/bridge-sdk/settings'
+import type { PublicClient } from 'viem'
+
+declare const ethereumClient: PublicClient
+declare const pulsechainClient: PublicClient
+
+const route = pathway([Providers.PULSECHAIN, Chains.ETH, Chains.PLS], true)
+if (route) {
+  const { feeF2H } = await loadBridgeFees({
+    pathway: route,
+    fromChainClient: ethereumClient,
+    toChainClient: pulsechainClient,
+  })
+  const amountToBridge = 1_000_000n
+  const cost = bridgeCost({ amountToBridge, bridgeFee: feeF2H })
+  const received = amountAfterBridgeFee({ amountToBridge, bridgeCost: cost })
+}
+```
+
+`loadBridgeFees` reads the default rate. It does not read per-token rates.
+
+## Tokens that are not bridged yet
+
+`tokenBridgeInfo` asks both mediators how a token maps across the bridge.
+A `null` `assetOutAddress` is a normal answer. The token gets an address on
+the far side when its first transfer arrives. Always check for `null`.
+
+```ts
+import { tokenBridgeInfo } from '@gibs/bridge-sdk/chain-info'
+import { Chains, Providers } from '@gibs/bridge-sdk/config'
+import type { Token } from '@gibs/bridge-sdk/types'
+import type { PublicClient } from 'viem'
+
+declare const assetIn: Token
+declare const ethereumClient: PublicClient
+declare const pulsechainClient: PublicClient
+
+const info = await tokenBridgeInfo({
+  bridgeKey: [Providers.PULSECHAIN, Chains.ETH, Chains.PLS],
+  assetIn,
+  isProd: true,
+  fromChainClient: ethereumClient,
+  toChainClient: pulsechainClient,
+})
+if (info && info.assetOutAddress === null) {
+  // Not bridged yet. Do not treat this as an error.
+}
+```
+
+## Aggregator identity: pass your own
+
+The package ships no API key. Pass your own.
+
+- Relay: pass your own `apiKey` to `relayRequestHeaders`. Name your own `relayReferrer`. The package sends no referrer by default, because Relay rejects a referrer without a key.
+- LI.FI: set your own `lifiIntegrator`. A positive `lifiFee` without your own integrator throws.
+- NEAR Intents: no key is needed. Pass your own `userAgent` if you want one.
+
+```ts
+import {
+  buildLifiContractCallsRequest,
+  type ConsolidatedQuoteRequest,
+} from '@gibs/bridge-sdk/consolidated-quote'
+import { nearIntentsRequestHeaders } from '@gibs/bridge-sdk/near-intents'
+import { buildRelayQuoteRequest, relayQuoteUrl, relayRequestHeaders } from '@gibs/bridge-sdk/relay-quote'
+
+declare const baseRequest: ConsolidatedQuoteRequest
+declare const myRelayApiKey: string
+
+const request: ConsolidatedQuoteRequest = {
+  ...baseRequest,
+  lifiIntegrator: 'your-app.example',
+  lifiFee: 0.001,
+  relayReferrer: 'your-app.example',
+}
+
+const lifiBody = buildLifiContractCallsRequest(request)
+const relayBody = buildRelayQuoteRequest(request)
+if (relayBody) {
+  await fetch(relayQuoteUrl, {
+    method: 'POST',
+    body: JSON.stringify(relayBody),
+    headers: relayRequestHeaders(myRelayApiKey),
+  })
+}
+
+const nearHeaders = nearIntentsRequestHeaders(undefined, { userAgent: 'your-app/1.0' })
+```
+
+## Nulls and throws
+
+- A question the package cannot answer returns `null`, `undefined` or `false`.
+- A caller mistake or a failed chain read throws.
+- Every request builder returns `null` for a request its provider cannot express.
+- Every response parser returns `null` for an unexpected response shape.
+- Check each return value before you use it.
+
+## Links
+
+- [README](https://github.com/gibsfinance/bridge/blob/staging/packages/bridge-sdk/README.md): the full guide.
+- [Gibs Finance llms.txt](https://next.gibs.finance/llms.txt): the whole platform.
+- [@gibs/quotes](https://github.com/gibsfinance/bridge/blob/staging/packages/quotes/llms.txt): live multi-provider quotes.