@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/ton-connect.js

@@ -0,0 +1,200 @@
+/**
+ * Executing a deposit on The Open Network, as pure data, with no TON library.
+ *
+ * This module imports nothing outside the package, so it loads anywhere: a
+ * browser, Node, or a React Native app under Hermes, with no `Buffer` and no
+ * polyfill. It uses only `atob` and `btoa`, which Hermes provides. The one TON
+ * helper that needs `@ton/core`, the TEP-467 message hash, lives in
+ * `@gibs/bridge-sdk/ton` instead.
+ *
+ * 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,
+    };
+};

package/dist/ton-execution.d.ts

@@ -1,117 +1,7 @@
-import type { TonDeposit } from './origin-deposit.js';
 /**
- * Executing a deposit on The Open Network, as pure data.
+ * The original name of `@gibs/bridge-sdk/ton`, kept so existing imports work.
  *
- * 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
+ * @deprecated Import from `@gibs/bridge-sdk/ton` for the full TON surface, or
+ * from `@gibs/bridge-sdk/ton-connect` for the helpers that need no TON library.
  */
-export declare const tonExternalMessageHash: (boc: string) => string | null;
-export {};
+export * from './ton.js';

package/dist/ton-execution.js

@@ -1,247 +1,7 @@
-import { Cell, beginCell, loadMessage, storeMessage } from '@ton/core';
 /**
- * Executing a deposit on The Open Network, as pure data.
+ * The original name of `@gibs/bridge-sdk/ton`, kept so existing imports work.
  *
- * 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
+ * @deprecated Import from `@gibs/bridge-sdk/ton` for the full TON surface, or
+ * from `@gibs/bridge-sdk/ton-connect` for the helpers that need no TON library.
  */
-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;
-    }
-};
+export * from './ton.js';

package/dist/ton.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Everything the bridge SDK offers for The Open Network, in one entry point.
+ *
+ * It re-exports the pure TON Connect helpers from `./ton-connect.js` and adds
+ * {@link tonExternalMessageHash}, the only helper that needs `@ton/core`.
+ *
+ * Kept apart from the root entry point on purpose. `@ton/core` uses Node's
+ * `Buffer`, and its `@ton/crypto` dependency resolves, under React Native, to a
+ * build that requires `expo-crypto`. An application that bridges only between
+ * Ethereum-style chains never imports this file, so it never pays for either.
+ */
+export * from './ton-connect.js';
+/**
+ * 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;

package/dist/ton.js

@@ -0,0 +1,65 @@
+import { Cell, beginCell, loadMessage, storeMessage } from '@ton/core';
+/**
+ * Everything the bridge SDK offers for The Open Network, in one entry point.
+ *
+ * It re-exports the pure TON Connect helpers from `./ton-connect.js` and adds
+ * {@link tonExternalMessageHash}, the only helper that needs `@ton/core`.
+ *
+ * Kept apart from the root entry point on purpose. `@ton/core` uses Node's
+ * `Buffer`, and its `@ton/crypto` dependency resolves, under React Native, to a
+ * build that requires `expo-crypto`. An application that bridges only between
+ * Ethereum-style chains never imports this file, so it never pays for either.
+ */
+export * from './ton-connect.js';
+/**
+ * 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;
+    }
+};