@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/ton-execution.d.ts

@@ -0,0 +1,117 @@
+import type { TonDeposit } from './origin-deposit.js';
+/**
+ * Executing a deposit on The Open Network, as pure data.
+ *
+ * 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 declare const tonConnectMainnetNetwork = "-239";
+/** How long a request stays valid by default, in seconds, matching Relay's adapter. */
+export declare const tonConnectDefaultValidForSeconds = 300;
+/** An address split into the parts that survive a change of encoding. */
+type ParsedTonAddress = {
+    workchain: number;
+    hash: Uint8Array;
+    /** Preserved rather than assumed: re-encoding a testnet address as mainnet would misdirect it. */
+    testOnly: boolean;
+};
+/**
+ * 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 declare const parseTonAddress: (value: string) => ParsedTonAddress | null;
+/**
+ * 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 declare const encodeTonAddress: (address: string, { bounceable }: {
+    bounceable: boolean;
+}) => string | null;
+/** One message of a TON Connect request. Note `address`/`amount`, not `to`/`value`. */
+export type TonConnectMessage = {
+    address: string;
+    /** Attached amount in nanotons, as a decimal string. */
+    amount: string;
+    /** Base64 bag-of-cells body, omitted when the message carries none. */
+    payload?: string;
+};
+/** The request handed to a wallet's TON Connect `sendTransaction` call. */
+export type TonConnectRequest = {
+    /** Unix seconds after which a wallet must refuse the request. */
+    validUntil: number;
+    network: string;
+    /** The sending account, when the deposit names one. */
+    from?: string;
+    messages: TonConnectMessage[];
+};
+/**
+ * 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 declare const buildTonConnectRequest: (deposit: TonDeposit, { validUntil }: {
+    validUntil: number;
+}) => TonConnectRequest | null;
+/**
+ * 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;
+export {};

package/dist/ton-execution.js

@@ -0,0 +1,247 @@
+import { Cell, beginCell, loadMessage, storeMessage } from '@ton/core';
+/**
+ * Executing a deposit on The Open Network, as pure data.
+ *
+ * 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
+ */
+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/dist/tron-execution.d.ts

@@ -0,0 +1,146 @@
+import type { TronDeposit } from './origin-deposit.js';
+/**
+ * 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 declare 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 declare const defaultTronFeeLimitSun = 30000000;
+/**
+ * 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 declare const maximumTronFeeLimitSun = 15000000000;
+/**
+ * The body of a `/wallet/triggersmartcontract` request.
+ *
+ * Field names are the node's own snake_case, deliberately: this object is
+ * serialized and posted verbatim, so renaming to the codebase's conventions
+ * would only invite a translation step that can drift.
+ */
+export type TriggerSmartContractRequest = {
+    owner_address: string;
+    contract_address: string;
+    /** Calldata as bare hex, with no `0x` prefix. */
+    data: string;
+    /** Native TRX sent with the call, in sun. */
+    call_value: number;
+    /** Energy spending cap, in sun. */
+    fee_limit: number;
+    /** Always false — the addresses above are hex, not base58. See the module note. */
+    visible: false;
+};
+/**
+ * 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 declare const normalizeTronHexAddress: (value: string) => string | 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 declare const isSameTronAccount: (left: string, right: string) => boolean;
+/**
+ * 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 declare const buildTriggerSmartContractRequest: (deposit: TronDeposit, { feeLimitSun }?: {
+    feeLimitSun?: number;
+}) => TriggerSmartContractRequest | 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 declare const tronErrorMessage: (payload: unknown) => string | null;
+/**
+ * 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 declare const readTriggerSmartContractResponse: (payload: unknown) => Record<string, unknown> | null;
+/**
+ * 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 declare const readBroadcastResponse: (payload: unknown) => string | null;