@gibs/bridge-sdk 1.12.0 → 1.13.0

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/package.json

@@ -1,41 +1,221 @@
 {
   "name": "@gibs/bridge-sdk",
-  "version": "1.12.0",
-  "main": "index.js",
-  "access": "public",
+  "version": "1.13.0",
+  "description": "Build and price cross-chain transfers between PulseChain, Ethereum, and Binance Smart Chain.",
+  "keywords": [
+    "ethereum",
+    "pulsechain",
+    "bridge",
+    "omnibridge",
+    "viem",
+    "cross-chain"
+  ],
+  "license": "ISC",
+  "author": "Gibs Finance",
+  "homepage": "https://gibs.finance",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gibsfinance/bridge.git",
+    "directory": "packages/bridge-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/gibsfinance/bridge/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./types": "./src/types.ts",
-    "./config": "./src/config.ts",
-    "./abis": "./src/abis.ts",
-    "./image-links": "./src/image-links.ts",
-    "./chains": "./src/chains.ts",
-    "./chain-info": "./src/chain-info.ts",
-    "./fee-type": "./src/fee-type.ts",
-    "./settings": "./src/settings.ts"
+    ".": {
+      "gibs-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "gibs-source": "./src/types.ts",
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./config": {
+      "gibs-source": "./src/config.ts",
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./referral": {
+      "gibs-source": "./src/referral.ts",
+      "types": "./dist/referral.d.ts",
+      "default": "./dist/referral.js"
+    },
+    "./consolidated-quote": {
+      "gibs-source": "./src/consolidated-quote.ts",
+      "types": "./dist/consolidated-quote.d.ts",
+      "default": "./dist/consolidated-quote.js"
+    },
+    "./origin-deposit": {
+      "gibs-source": "./src/origin-deposit.ts",
+      "types": "./dist/origin-deposit.d.ts",
+      "default": "./dist/origin-deposit.js"
+    },
+    "./hyperliquid-execution": {
+      "gibs-source": "./src/hyperliquid-execution.ts",
+      "types": "./dist/hyperliquid-execution.d.ts",
+      "default": "./dist/hyperliquid-execution.js"
+    },
+    "./ton-execution": {
+      "gibs-source": "./src/ton-execution.ts",
+      "types": "./dist/ton-execution.d.ts",
+      "default": "./dist/ton-execution.js"
+    },
+    "./tron-execution": {
+      "gibs-source": "./src/tron-execution.ts",
+      "types": "./dist/tron-execution.d.ts",
+      "default": "./dist/tron-execution.js"
+    },
+    "./relay-quote": {
+      "gibs-source": "./src/relay-quote.ts",
+      "types": "./dist/relay-quote.d.ts",
+      "default": "./dist/relay-quote.js"
+    },
+    "./near-intents": {
+      "gibs-source": "./src/near-intents.ts",
+      "types": "./dist/near-intents.d.ts",
+      "default": "./dist/near-intents.js"
+    },
+    "./near-intents-route": {
+      "gibs-source": "./src/near-intents-route.ts",
+      "types": "./dist/near-intents-route.d.ts",
+      "default": "./dist/near-intents-route.js"
+    },
+    "./quote-fees": {
+      "gibs-source": "./src/quote-fees.ts",
+      "types": "./dist/quote-fees.d.ts",
+      "default": "./dist/quote-fees.js"
+    },
+    "./relay-currencies": {
+      "gibs-source": "./src/relay-currencies.ts",
+      "types": "./dist/relay-currencies.d.ts",
+      "default": "./dist/relay-currencies.js"
+    },
+    "./pre-quote": {
+      "gibs-source": "./src/pre-quote.ts",
+      "types": "./dist/pre-quote.d.ts",
+      "default": "./dist/pre-quote.js"
+    },
+    "./ecosystems": {
+      "gibs-source": "./src/ecosystems.ts",
+      "types": "./dist/ecosystems.d.ts",
+      "default": "./dist/ecosystems.js"
+    },
+    "./providers": {
+      "gibs-source": "./src/providers.ts",
+      "types": "./dist/providers.d.ts",
+      "default": "./dist/providers.js"
+    },
+    "./destination-calldata": {
+      "gibs-source": "./src/destination-calldata.ts",
+      "types": "./dist/destination-calldata.d.ts",
+      "default": "./dist/destination-calldata.js"
+    },
+    "./bridge-limits": {
+      "gibs-source": "./src/bridge-limits.ts",
+      "types": "./dist/bridge-limits.d.ts",
+      "default": "./dist/bridge-limits.js"
+    },
+    "./abis": {
+      "gibs-source": "./src/abis.ts",
+      "types": "./dist/abis.d.ts",
+      "default": "./dist/abis.js"
+    },
+    "./image-links": {
+      "gibs-source": "./src/image-links.ts",
+      "types": "./dist/image-links.d.ts",
+      "default": "./dist/image-links.js"
+    },
+    "./lifi-execution-guard": {
+      "gibs-source": "./src/lifi-execution-guard.ts",
+      "types": "./dist/lifi-execution-guard.d.ts",
+      "default": "./dist/lifi-execution-guard.js"
+    },
+    "./prices": {
+      "gibs-source": "./src/prices.ts",
+      "types": "./dist/prices.d.ts",
+      "default": "./dist/prices.js"
+    },
+    "./chains": {
+      "gibs-source": "./src/chains.ts",
+      "types": "./dist/chains.d.ts",
+      "default": "./dist/chains.js"
+    },
+    "./chain-info": {
+      "gibs-source": "./src/chain-info.ts",
+      "types": "./dist/chain-info.d.ts",
+      "default": "./dist/chain-info.js"
+    },
+    "./chain-names": {
+      "gibs-source": "./src/chain-names.ts",
+      "types": "./dist/chain-names.d.ts",
+      "default": "./dist/chain-names.js"
+    },
+    "./fee-type": {
+      "gibs-source": "./src/fee-type.ts",
+      "types": "./dist/fee-type.d.ts",
+      "default": "./dist/fee-type.js"
+    },
+    "./settings": {
+      "gibs-source": "./src/settings.ts",
+      "types": "./dist/settings.d.ts",
+      "default": "./dist/settings.js"
+    },
+    "./route-steps": {
+      "gibs-source": "./src/route-steps.ts",
+      "types": "./dist/route-steps.d.ts",
+      "default": "./dist/route-steps.js"
+    },
+    "./routing": {
+      "gibs-source": "./src/routing/index.ts",
+      "types": "./dist/routing/index.d.ts",
+      "default": "./dist/routing/index.js"
+    }
   },
+  "files": [
+    "dist",
+    "!dist/tsconfig.tsbuildinfo",
+    "!dist/**/*.test-d.*",
+    "!dist/test-utils",
+    "LICENSE"
+  ],
   "scripts": {
+    "prepublishOnly": "npx tsc",
     "build": "npx tsc",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "test:fork": "../../scripts/fork-test.sh",
+    "test:live:near-intents": "../../scripts/near-intents-live.sh"
+  },
+  "dependencies": {
+    "@gibs/abis": "^1.13.0",
+    "@gibs/common": "^1.13.0",
+    "@ton/core": "^0.63.1",
+    "@ton/crypto": "^3.3.0",
+    "lodash-es": "^4.17.21"
+  },
+  "peerDependencies": {
+    "viem": ">=2.37.0 <3"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
   "devDependencies": {
-    "@types/lodash": "^4.17.16",
+    "@types/lodash-es": "^4.17.12",
     "@types/node": "^24",
     "@vitest/coverage-v8": "^3.1.1",
+    "fast-check": "^4.10.2",
     "typescript": "~5.7.2",
+    "viem": "^2.46.3",
     "vitest": "^3.1.1"
   },
-  "dependencies": {
-    "@gibs/abis": "^1.0.0",
-    "@gibs/common": "^1.0.0",
-    "lodash": "^4.17.21",
-    "viem": "^2.46.3"
+  "publishConfig": {
+    "access": "public"
   }
 }