crypto-aio 0.0.3 → 0.1.0

package/dist/adapters/ton/network.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHAIN_TIME_TOLERANCE = exports.MAX_VALID_FOR_SECONDS = exports.MIN_VALID_FOR_SECONDS = exports.DEFAULT_MAX_NETWORK_FEE = exports.TON_INDEXER_CAPABILITIES = exports.TON_CAPABILITIES = void 0;
+exports.recordedValidFrom = recordedValidFrom;
+exports.tonNetworkConfig = tonNetworkConfig;
+/**
+ * What the TON driver needs from a network's registry entry, validated once when a driver
+ * is created, so inconsistent data fails with `CONFIG_INVALID` instead of misbehaving.
+ * SDK-free.
+ */
+const error_1 = require("../../core/errors/error");
+const capability_1 = require("../../core/model/capability");
+const names_1 = require("../../core/util/names");
+const fees_1 = require("./fees");
+/**
+ * The TON manifest's capabilities; `address-history` comes with the indexer. No
+ * `batch-transfer`: the verdict answers `failed` for a partly delivered batch, and
+ * a failed Operation sent again whole would pay twice the outputs that moved, so a TON
+ * transfer carries exactly one output.
+ */
+exports.TON_CAPABILITIES = Object.freeze([
+    'tokens',
+    'memo',
+    'expiry',
+]);
+exports.TON_INDEXER_CAPABILITIES = Object.freeze([
+    'address-history',
+]);
+/**
+ * The only capabilities a TON network may add or remove. Never on TON: `block-scan`
+ * (sharded, no block source), `replace-fee` and `cancel` (TON has neither),
+ * `batch-transfer` (one output per transfer), nor any other.
+ */
+const OWN_CAPABILITIES = new Set([
+    ...exports.TON_CAPABILITIES,
+    ...exports.TON_INDEXER_CAPABILITIES,
+]);
+/** The TON network options (`NetworkInfo.params`); any other key is a typo. */
+const OPTIONS = new Set([
+    'validForSeconds',
+    'jettonAttached',
+    'jettonForwardAmount',
+    'finalitySkewBlocks',
+    'maxNetworkFee',
+]);
+/**
+ * The default economic ceiling on the `network` charge an endpoint's emulation suggests,
+ * which a network replaces with `params.maxNetworkFee`. TON signs no fee: the chain
+ * charges gas and forward fees by its config, so an inflated estimate cannot make a
+ * transfer pay more, but it would fail the funds check for good (`INSUFFICIENT_FUNDS`) or
+ * mislead whoever approves the fee. A basechain wallet's transfer costs about 0.001-0.01
+ * TON, and a whole gas limit (1M gas at 400 nanograms) 0.4 TON; a masterchain wallet pays
+ * about 25 times the gas and far more storage (about 6 TON a year for a v4r2 wallet at
+ * mainnet's config param 18), so 100 TON refuses only a wallet idle for more than about
+ * 13 years. Above the ceiling an estimate is a retryable `PROVIDER_INCONSISTENT`.
+ */
+exports.DEFAULT_MAX_NETWORK_FEE = Object.freeze({
+    basechain: 1000000000n,
+    masterchain: 100000000000n,
+});
+const WORKCHAINS = new Set(['basechain', 'masterchain']);
+/**
+ * A capability as an error may show it: a core capability's name is a fixed word, so
+ * it is shown; any other text could be a pasted secret, so it is not. Unknown option keys are
+ * never echoed either; their errors list the accepted names instead.
+ */
+const shown = (capability) => (0, names_1.knownName)(capability, capability_1.KNOWN_CAPABILITIES, 'an unknown capability');
+const isIntegerIn = (value, min, max) => Number.isSafeInteger(value) && value >= min && value <= max;
+/** The lifetimes a network may configure (`params.validForSeconds`), in seconds. */
+exports.MIN_VALID_FOR_SECONDS = 10;
+exports.MAX_VALID_FOR_SECONDS = 86_400;
+/** How far an endpoint's `sync_utime` may be from the local clock, in seconds. */
+exports.CHAIN_TIME_TOLERANCE = 300;
+/**
+ * A build's recorded chain time (`TonSeqnoOrdering.validFrom`) when the ordering holds
+ * a well-formed one for its lifetime: a safe integer at least the shortest lifetime before
+ * `validUntil`, and at most the longest (plus the chain-time tolerance) before it. Undefined
+ * otherwise (an attempt built before the field existed, or a damaged record).
+ */
+function recordedValidFrom(slot) {
+    const { validUntil } = slot;
+    const { validFrom } = slot;
+    return typeof validFrom === 'number' &&
+        Number.isSafeInteger(validFrom) &&
+        validFrom <= validUntil - exports.MIN_VALID_FOR_SECONDS &&
+        validFrom >= validUntil - exports.MAX_VALID_FOR_SECONDS - exports.CHAIN_TIME_TOLERANCE
+        ? validFrom
+        : undefined;
+}
+/**
+ * The only driver options (`HandleOptions.options`, `chains.ton.options`) the TON driver
+ * reads. Any other key is refused, so a typo fails loudly instead of leaving the default
+ * in place.
+ */
+const OPTION_KEYS = new Set(['maxNetworkFee']);
+function tonNetworkConfig(chain, network, options = {}) {
+    const fail = (reason) => {
+        throw new error_1.ConfigError('CONFIG_INVALID', `TON network ${chain.id}:${network.id}: ${reason}`);
+    };
+    const identity = network.identity;
+    if (identity === undefined || !/^-?[1-9][0-9]*$/.test(identity)) {
+        fail('its identity must be the decimal global id (config param 19)');
+    }
+    const globalId = Number(identity);
+    if (!isIntegerIn(globalId, -(2 ** 31), 2 ** 31 - 1)) {
+        fail('the global id must be an int32');
+    }
+    if (network.feeModel !== 'ton') {
+        fail(`its fee model must be 'ton'`);
+    }
+    if (network.finality.kind !== 'masterchain') {
+        fail(`its finality must be 'masterchain'`);
+    }
+    const params = network.params ?? {};
+    for (const key of Object.keys(params)) {
+        if (!OPTIONS.has(key)) {
+            fail(`params has a key that is not a TON network option (${[...OPTIONS].join(', ')})`);
+        }
+    }
+    // Own keys only; an explicit `undefined` is absent, so the library default applies.
+    const param = (key, fallback) => {
+        const value = Object.hasOwn(params, key) ? params[key] : undefined;
+        return value === undefined ? fallback : value;
+    };
+    const validFor = param('validForSeconds', 60);
+    if (!isIntegerIn(validFor, exports.MIN_VALID_FOR_SECONDS, exports.MAX_VALID_FOR_SECONDS)) {
+        fail('params.validForSeconds must be an integer in [10, 86400]');
+    }
+    // Encoded as Coins in every jetton wallet message: range-checked here, never wrapped.
+    const attached = param('jettonAttached', 50000000n);
+    if (typeof attached !== 'bigint' || attached <= 0n || attached > fees_1.MAX_COINS) {
+        fail('params.jettonAttached must be a bigint in [1, 2^120 - 1] (nanograms)');
+    }
+    const forward = param('jettonForwardAmount', 1n);
+    if (typeof forward !== 'bigint' || forward < 0n || forward >= attached) {
+        fail('params.jettonForwardAmount must be a bigint in [0, jettonAttached)');
+    }
+    const skew = param('finalitySkewBlocks', 10);
+    if (!isIntegerIn(skew, 1, 1_000)) {
+        fail('params.finalitySkewBlocks must be an integer in [1, 1000]');
+    }
+    // The refusal names the accepted option and shows neither the caller's key, which
+    // may be a pasted secret, nor its value.
+    for (const key of Object.keys(options)) {
+        if (!OPTION_KEYS.has(key)) {
+            fail((0, names_1.unknownName)('option', OPTION_KEYS));
+        }
+    }
+    // Per workchain, the handle's option, else the network's params, else the
+    // default. A network value is checked even where an option overrides it.
+    const networkFeeCeiling = feeCeiling(param('maxNetworkFee', {}), 'params.maxNetworkFee', exports.DEFAULT_MAX_NETWORK_FEE, fail);
+    const option = Object.hasOwn(options, 'maxNetworkFee')
+        ? options.maxNetworkFee
+        : undefined;
+    const maxNetworkFee = option === undefined
+        ? networkFeeCeiling
+        : feeCeiling(option, 'maxNetworkFee', networkFeeCeiling, fail);
+    const capabilities = new Set([
+        ...exports.TON_CAPABILITIES,
+        ...exports.TON_INDEXER_CAPABILITIES,
+    ]);
+    const own = (c) => OWN_CAPABILITIES.has(c) ? c : fail(`${shown(c)} is not available on TON`);
+    for (const c of network.capabilities?.add ?? [])
+        capabilities.add(own(c));
+    for (const c of network.capabilities?.remove ?? [])
+        capabilities.delete(own(c));
+    return {
+        globalId,
+        testnet: network.testnet,
+        validForSeconds: validFor,
+        jettonAttached: attached,
+        jettonForwardAmount: forward,
+        finalitySkewBlocks: skew,
+        maxNetworkFee,
+        capabilities,
+    };
+}
+/**
+ * `maxNetworkFee` (`name`: the network's `params.maxNetworkFee` or the handle option):
+ * `{ basechain?, masterchain? }`, each a positive bigint within Coins (the charge is
+ * compared with nanogram amounts); a workchain left out keeps `fallback`'s. Any other key,
+ * or value, is `CONFIG_INVALID`, which never echoes the key.
+ */
+function feeCeiling(value, name, fallback, fail) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return fail(`${name} must be { basechain?, masterchain? } (nanograms)`);
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!WORKCHAINS.has(key)) {
+            fail(`${name} takes only 'basechain' and 'masterchain'`);
+        }
+    }
+    const bound = (key) => {
+        const own = Object.hasOwn(record, key) ? record[key] : undefined;
+        const ceiling = own === undefined ? fallback[key] : own;
+        if (typeof ceiling !== 'bigint' || ceiling <= 0n || ceiling > fees_1.MAX_COINS) {
+            fail(`${name}.${key} must be a bigint in [1, 2^120 - 1] (nanograms)`);
+        }
+        return ceiling;
+    };
+    return Object.freeze({
+        basechain: bound('basechain'),
+        masterchain: bound('masterchain'),
+    });
+}
+//# sourceMappingURL=network.js.map

package/dist/adapters/ton/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../src/adapters/ton/network.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What the TON driver needs from a network's registry entry, validated once when a driver\n * is created, so inconsistent data fails with `CONFIG_INVALID` instead of misbehaving.\n * SDK-free.\n */\nimport { ConfigError } from '../../core/errors/error';\nimport { KNOWN_CAPABILITIES, type Capability } from '../../core/model/capability';\nimport type { ChainInfo, NetworkInfo } from '../../core/model/chain';\nimport { knownName, unknownName } from '../../core/util/names';\nimport { MAX_COINS } from './fees';\n\n/**\n * The TON manifest's capabilities; `address-history` comes with the indexer. No\n * `batch-transfer`: the verdict answers `failed` for a partly delivered batch, and\n * a failed Operation sent again whole would pay twice the outputs that moved, so a TON\n * transfer carries exactly one output.\n */\nexport const TON_CAPABILITIES: readonly Capability[] = Object.freeze([\n  'tokens',\n  'memo',\n  'expiry',\n]);\nexport const TON_INDEXER_CAPABILITIES: readonly Capability[] = Object.freeze([\n  'address-history',\n]);\n/**\n * The only capabilities a TON network may add or remove. Never on TON: `block-scan`\n * (sharded, no block source), `replace-fee` and `cancel` (TON has neither),\n * `batch-transfer` (one output per transfer), nor any other.\n */\nconst OWN_CAPABILITIES: ReadonlySet<Capability> = new Set([\n  ...TON_CAPABILITIES,\n  ...TON_INDEXER_CAPABILITIES,\n]);\n\n/** The TON network options (`NetworkInfo.params`); any other key is a typo. */\nconst OPTIONS: ReadonlySet<string> = new Set([\n  'validForSeconds',\n  'jettonAttached',\n  'jettonForwardAmount',\n  'finalitySkewBlocks',\n  'maxNetworkFee',\n]);\n\n/** The ceiling of each workchain's `network` charge, in nanograms. */\nexport interface TonFeeCeiling {\n  readonly basechain: bigint;\n  readonly masterchain: bigint;\n}\n\n/**\n * The default economic ceiling on the `network` charge an endpoint's emulation suggests,\n * which a network replaces with `params.maxNetworkFee`. TON signs no fee: the chain\n * charges gas and forward fees by its config, so an inflated estimate cannot make a\n * transfer pay more, but it would fail the funds check for good (`INSUFFICIENT_FUNDS`) or\n * mislead whoever approves the fee. A basechain wallet's transfer costs about 0.001-0.01\n * TON, and a whole gas limit (1M gas at 400 nanograms) 0.4 TON; a masterchain wallet pays\n * about 25 times the gas and far more storage (about 6 TON a year for a v4r2 wallet at\n * mainnet's config param 18), so 100 TON refuses only a wallet idle for more than about\n * 13 years. Above the ceiling an estimate is a retryable `PROVIDER_INCONSISTENT`.\n */\nexport const DEFAULT_MAX_NETWORK_FEE: TonFeeCeiling = Object.freeze({\n  basechain: 1_000_000_000n,\n  masterchain: 100_000_000_000n,\n});\n\nconst WORKCHAINS: ReadonlySet<string> = new Set(['basechain', 'masterchain']);\n\n/**\n * A capability as an error may show it: a core capability's name is a fixed word, so\n * it is shown; any other text could be a pasted secret, so it is not. Unknown option keys are\n * never echoed either; their errors list the accepted names instead.\n */\nconst shown = (capability: Capability): string =>\n  knownName(capability, KNOWN_CAPABILITIES, 'an unknown capability');\n\nexport interface TonNetworkConfig {\n  /** Config param 19; the network identity. */\n  readonly globalId: number;\n  readonly testnet: boolean;\n  /** A message's lifetime past chain time, in seconds. */\n  readonly validForSeconds: number;\n  /** Nanograms attached to each jetton wallet message; the unspent part is refunded. */\n  readonly jettonAttached: bigint;\n  /** Nanograms forwarded with each jetton notification. */\n  readonly jettonForwardAmount: bigint;\n  /** Masterchain blocks the attested head first trails the freshest endpoint by. */\n  readonly finalitySkewBlocks: number;\n  /** The most an estimate's `network` charge may be, per workchain of the sender. */\n  readonly maxNetworkFee: TonFeeCeiling;\n  readonly capabilities: ReadonlySet<Capability>;\n}\n\nconst isIntegerIn = (value: unknown, min: number, max: number): value is number =>\n  Number.isSafeInteger(value) && (value as number) >= min && (value as number) <= max;\n\n/** The lifetimes a network may configure (`params.validForSeconds`), in seconds. */\nexport const MIN_VALID_FOR_SECONDS = 10;\nexport const MAX_VALID_FOR_SECONDS = 86_400;\n\n/** How far an endpoint's `sync_utime` may be from the local clock, in seconds. */\nexport const CHAIN_TIME_TOLERANCE = 300;\n\n/**\n * A build's recorded chain time (`TonSeqnoOrdering.validFrom`) when the ordering holds\n * a well-formed one for its lifetime: a safe integer at least the shortest lifetime before\n * `validUntil`, and at most the longest (plus the chain-time tolerance) before it. Undefined\n * otherwise (an attempt built before the field existed, or a damaged record).\n */\nexport function recordedValidFrom(slot: {\n  readonly validUntil: number;\n}): number | undefined {\n  const { validUntil } = slot;\n  const { validFrom } = slot as { readonly validFrom?: unknown };\n  return typeof validFrom === 'number' &&\n    Number.isSafeInteger(validFrom) &&\n    validFrom <= validUntil - MIN_VALID_FOR_SECONDS &&\n    validFrom >= validUntil - MAX_VALID_FOR_SECONDS - CHAIN_TIME_TOLERANCE\n    ? validFrom\n    : undefined;\n}\n\n/**\n * The only driver options (`HandleOptions.options`, `chains.ton.options`) the TON driver\n * reads. Any other key is refused, so a typo fails loudly instead of leaving the default\n * in place.\n */\nconst OPTION_KEYS: ReadonlySet<string> = new Set(['maxNetworkFee']);\n\nexport function tonNetworkConfig(\n  chain: ChainInfo,\n  network: NetworkInfo,\n  options: Readonly<Record<string, unknown>> = {},\n): TonNetworkConfig {\n  const fail = (reason: string): never => {\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      `TON network ${chain.id}:${network.id}: ${reason}`,\n    );\n  };\n  const identity = network.identity;\n  if (identity === undefined || !/^-?[1-9][0-9]*$/.test(identity)) {\n    fail('its identity must be the decimal global id (config param 19)');\n  }\n  const globalId = Number(identity);\n  if (!isIntegerIn(globalId, -(2 ** 31), 2 ** 31 - 1)) {\n    fail('the global id must be an int32');\n  }\n  if (network.feeModel !== 'ton') {\n    fail(`its fee model must be 'ton'`);\n  }\n  if (network.finality.kind !== 'masterchain') {\n    fail(`its finality must be 'masterchain'`);\n  }\n  const params = network.params ?? {};\n  for (const key of Object.keys(params)) {\n    if (!OPTIONS.has(key)) {\n      fail(\n        `params has a key that is not a TON network option (${[...OPTIONS].join(', ')})`,\n      );\n    }\n  }\n  // Own keys only; an explicit `undefined` is absent, so the library default applies.\n  const param = (key: string, fallback: unknown): unknown => {\n    const value = Object.hasOwn(params, key) ? params[key] : undefined;\n    return value === undefined ? fallback : value;\n  };\n  const validFor = param('validForSeconds', 60);\n  if (!isIntegerIn(validFor, MIN_VALID_FOR_SECONDS, MAX_VALID_FOR_SECONDS)) {\n    fail('params.validForSeconds must be an integer in [10, 86400]');\n  }\n  // Encoded as Coins in every jetton wallet message: range-checked here, never wrapped.\n  const attached = param('jettonAttached', 50_000_000n);\n  if (typeof attached !== 'bigint' || attached <= 0n || attached > MAX_COINS) {\n    fail('params.jettonAttached must be a bigint in [1, 2^120 - 1] (nanograms)');\n  }\n  const forward = param('jettonForwardAmount', 1n);\n  if (typeof forward !== 'bigint' || forward < 0n || forward >= (attached as bigint)) {\n    fail('params.jettonForwardAmount must be a bigint in [0, jettonAttached)');\n  }\n  const skew = param('finalitySkewBlocks', 10);\n  if (!isIntegerIn(skew, 1, 1_000)) {\n    fail('params.finalitySkewBlocks must be an integer in [1, 1000]');\n  }\n  // The refusal names the accepted option and shows neither the caller's key, which\n  // may be a pasted secret, nor its value.\n  for (const key of Object.keys(options)) {\n    if (!OPTION_KEYS.has(key)) {\n      fail(unknownName('option', OPTION_KEYS));\n    }\n  }\n  // Per workchain, the handle's option, else the network's params, else the\n  // default. A network value is checked even where an option overrides it.\n  const networkFeeCeiling = feeCeiling(\n    param('maxNetworkFee', {}),\n    'params.maxNetworkFee',\n    DEFAULT_MAX_NETWORK_FEE,\n    fail,\n  );\n  const option = Object.hasOwn(options, 'maxNetworkFee')\n    ? options.maxNetworkFee\n    : undefined;\n  const maxNetworkFee =\n    option === undefined\n      ? networkFeeCeiling\n      : feeCeiling(option, 'maxNetworkFee', networkFeeCeiling, fail);\n  const capabilities = new Set<Capability>([\n    ...TON_CAPABILITIES,\n    ...TON_INDEXER_CAPABILITIES,\n  ]);\n  const own = (c: Capability): Capability =>\n    OWN_CAPABILITIES.has(c) ? c : fail(`${shown(c)} is not available on TON`);\n  for (const c of network.capabilities?.add ?? []) capabilities.add(own(c));\n  for (const c of network.capabilities?.remove ?? []) capabilities.delete(own(c));\n  return {\n    globalId,\n    testnet: network.testnet,\n    validForSeconds: validFor as number,\n    jettonAttached: attached as bigint,\n    jettonForwardAmount: forward as bigint,\n    finalitySkewBlocks: skew as number,\n    maxNetworkFee,\n    capabilities,\n  };\n}\n\n/**\n * `maxNetworkFee` (`name`: the network's `params.maxNetworkFee` or the handle option):\n * `{ basechain?, masterchain? }`, each a positive bigint within Coins (the charge is\n * compared with nanogram amounts); a workchain left out keeps `fallback`'s. Any other key,\n * or value, is `CONFIG_INVALID`, which never echoes the key.\n */\nfunction feeCeiling(\n  value: unknown,\n  name: string,\n  fallback: TonFeeCeiling,\n  fail: (reason: string) => never,\n): TonFeeCeiling {\n  if (value === null || typeof value !== 'object' || Array.isArray(value)) {\n    return fail(`${name} must be { basechain?, masterchain? } (nanograms)`);\n  }\n  const record = value as Readonly<Record<string, unknown>>;\n  for (const key of Object.keys(record)) {\n    if (!WORKCHAINS.has(key)) {\n      fail(`${name} takes only 'basechain' and 'masterchain'`);\n    }\n  }\n  const bound = (key: keyof TonFeeCeiling): bigint => {\n    const own = Object.hasOwn(record, key) ? record[key] : undefined;\n    const ceiling = own === undefined ? fallback[key] : own;\n    if (typeof ceiling !== 'bigint' || ceiling <= 0n || ceiling > MAX_COINS) {\n      fail(`${name}.${key} must be a bigint in [1, 2^120 - 1] (nanograms)`);\n    }\n    return ceiling as bigint;\n  };\n  return Object.freeze({\n    basechain: bound('basechain'),\n    masterchain: bound('masterchain'),\n  });\n}\n"]}

package/dist/adapters/ton/plugin.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The TON family plugin: the chain, jettons and toncenter presets as data, plus
+ * one adapter manifest (library `@ton/ton`). SDK-free: only the manifest's `load()` requires
+ * the library module, and with it the driver, `@ton/ton`, `@ton/core` and `@ton/crypto`.
+ */
+import type { AdapterManifest, PeerDependency } from '../../core/driver/types';
+import type { Plugin } from '../../core/registry/plugin';
+/**
+ * The SDK versions this adapter is validated against, keyed by package name. The one
+ * `@ton/ton` library needs all three: `@ton/ton` and `@ton/core` both declare
+ * `@ton/crypto` as a peer, and `@ton/core` requires it at load time.
+ */
+export declare const TON_PEER_DEPENDENCIES: Readonly<Record<'@ton/ton' | '@ton/core' | '@ton/crypto', PeerDependency>>;
+/**
+ * The `@ton/ton` manifest, built once, at module level, like the presets, so every
+ * `tonPlugin()` carries the same `load` function and registering it again is the same
+ * plugin: the registry compares functions by identity, and a different plugin under a
+ * registered name is `CONFIG_INVALID`. Its capabilities are exactly `TON_CAPABILITIES`:
+ * no `batch-transfer`, since a TON transfer carries one output (each message lands in its
+ * own transaction, so a batch could be partly delivered).
+ */
+export declare const tonManifest: AdapterManifest;
+/** The built-in TON family: chain `ton`, networks mainnet and testnet. */
+export declare function tonPlugin(): Plugin;

package/dist/adapters/ton/plugin.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tonManifest = exports.TON_PEER_DEPENDENCIES = void 0;
+exports.tonPlugin = tonPlugin;
+const freeze_1 = require("../../core/util/freeze");
+const chains_1 = require("./chains");
+const network_1 = require("./network");
+const presets_1 = require("./presets");
+const tokens_1 = require("./tokens");
+/**
+ * The SDK versions this adapter is validated against, keyed by package name. The one
+ * `@ton/ton` library needs all three: `@ton/ton` and `@ton/core` both declare
+ * `@ton/crypto` as a peer, and `@ton/core` requires it at load time.
+ */
+exports.TON_PEER_DEPENDENCIES = (0, freeze_1.deepFreeze)({
+    '@ton/ton': { name: '@ton/ton', range: '^16.3.0' },
+    '@ton/core': { name: '@ton/core', range: '^0.63.1' },
+    '@ton/crypto': { name: '@ton/crypto', range: '^3.3.0' },
+});
+/**
+ * The `@ton/ton` manifest, built once, at module level, like the presets, so every
+ * `tonPlugin()` carries the same `load` function and registering it again is the same
+ * plugin: the registry compares functions by identity, and a different plugin under a
+ * registered name is `CONFIG_INVALID`. Its capabilities are exactly `TON_CAPABILITIES`:
+ * no `batch-transfer`, since a TON transfer carries one output (each message lands in its
+ * own transaction, so a batch could be partly delivered).
+ */
+exports.tonManifest = Object.freeze({
+    family: 'ton',
+    library: '@ton/ton',
+    chains: Object.freeze(['ton']),
+    capabilities: network_1.TON_CAPABILITIES,
+    indexerCapabilities: network_1.TON_INDEXER_CAPABILITIES,
+    // Message → transaction resolution and trace-based finality need toncenter v3.
+    requiresIndexer: true,
+    peerDependencies: Object.freeze([
+        exports.TON_PEER_DEPENDENCIES['@ton/ton'],
+        exports.TON_PEER_DEPENDENCIES['@ton/core'],
+        exports.TON_PEER_DEPENDENCIES['@ton/crypto'],
+    ]),
+    load: async () => {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require('./native-client');
+        return mod.tonLibraryDriverFactory;
+    },
+});
+/** The built-in TON family: chain `ton`, networks mainnet and testnet. */
+function tonPlugin() {
+    return {
+        name: 'ton',
+        chains: chains_1.TON_CHAINS,
+        adapters: [exports.tonManifest],
+        presets: presets_1.TON_PRESETS,
+        assets: tokens_1.TON_TOKENS,
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/adapters/ton/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/adapters/ton/plugin.ts"],"names":[],"mappings":";;;AA2DA,8BAQC;AAxDD,mDAAoD;AACpD,qCAAsC;AACtC,uCAAuE;AACvE,uCAAwC;AACxC,qCAAsC;AAEtC;;;;GAIG;AACU,QAAA,qBAAqB,GAE9B,IAAA,mBAAU,EAAC;IACb,UAAU,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE;IAClD,WAAW,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE;IACpD,aAAa,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE;CACxD,CAAC,CAAC;AAEH;;;;;;;GAOG;AACU,QAAA,WAAW,GAAoB,MAAM,CAAC,MAAM,CAAC;IACxD,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,UAAU;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9B,YAAY,EAAE,0BAAgB;IAC9B,mBAAmB,EAAE,kCAAwB;IAC7C,+EAA+E;IAC/E,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC;QAC9B,6BAAqB,CAAC,UAAU,CAAC;QACjC,6BAAqB,CAAC,WAAW,CAAC;QAClC,6BAAqB,CAAC,aAAa,CAAC;KACrC,CAAC;IACF,IAAI,EAAE,KAAK,IAA4B,EAAE;QACvC,iEAAiE;QACjE,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAqC,CAAC;QAC3E,OAAO,GAAG,CAAC,uBAAuB,CAAC;IACrC,CAAC;CACF,CAAC,CAAC;AAEH,0EAA0E;AAC1E,SAAgB,SAAS;IACvB,OAAO;QACL,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,mBAAU;QAClB,QAAQ,EAAE,CAAC,mBAAW,CAAC;QACvB,OAAO,EAAE,qBAAW;QACpB,MAAM,EAAE,mBAAU;KACnB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The TON family plugin: the chain, jettons and toncenter presets as data, plus\n * one adapter manifest (library `@ton/ton`). SDK-free: only the manifest's `load()` requires\n * the library module, and with it the driver, `@ton/ton`, `@ton/core` and `@ton/crypto`.\n */\nimport type {\n  AdapterManifest,\n  DriverFactory,\n  PeerDependency,\n} from '../../core/driver/types';\nimport type { Plugin } from '../../core/registry/plugin';\nimport { deepFreeze } from '../../core/util/freeze';\nimport { TON_CHAINS } from './chains';\nimport { TON_CAPABILITIES, TON_INDEXER_CAPABILITIES } from './network';\nimport { TON_PRESETS } from './presets';\nimport { TON_TOKENS } from './tokens';\n\n/**\n * The SDK versions this adapter is validated against, keyed by package name. The one\n * `@ton/ton` library needs all three: `@ton/ton` and `@ton/core` both declare\n * `@ton/crypto` as a peer, and `@ton/core` requires it at load time.\n */\nexport const TON_PEER_DEPENDENCIES: Readonly<\n  Record<'@ton/ton' | '@ton/core' | '@ton/crypto', PeerDependency>\n> = deepFreeze({\n  '@ton/ton': { name: '@ton/ton', range: '^16.3.0' },\n  '@ton/core': { name: '@ton/core', range: '^0.63.1' },\n  '@ton/crypto': { name: '@ton/crypto', range: '^3.3.0' },\n});\n\n/**\n * The `@ton/ton` manifest, built once, at module level, like the presets, so every\n * `tonPlugin()` carries the same `load` function and registering it again is the same\n * plugin: the registry compares functions by identity, and a different plugin under a\n * registered name is `CONFIG_INVALID`. Its capabilities are exactly `TON_CAPABILITIES`:\n * no `batch-transfer`, since a TON transfer carries one output (each message lands in its\n * own transaction, so a batch could be partly delivered).\n */\nexport const tonManifest: AdapterManifest = Object.freeze({\n  family: 'ton',\n  library: '@ton/ton',\n  chains: Object.freeze(['ton']),\n  capabilities: TON_CAPABILITIES,\n  indexerCapabilities: TON_INDEXER_CAPABILITIES,\n  // Message → transaction resolution and trace-based finality need toncenter v3.\n  requiresIndexer: true,\n  peerDependencies: Object.freeze([\n    TON_PEER_DEPENDENCIES['@ton/ton'],\n    TON_PEER_DEPENDENCIES['@ton/core'],\n    TON_PEER_DEPENDENCIES['@ton/crypto'],\n  ]),\n  load: async (): Promise<DriverFactory> => {\n    // eslint-disable-next-line @typescript-eslint/no-require-imports\n    const mod = require('./native-client') as typeof import('./native-client');\n    return mod.tonLibraryDriverFactory;\n  },\n});\n\n/** The built-in TON family: chain `ton`, networks mainnet and testnet. */\nexport function tonPlugin(): Plugin {\n  return {\n    name: 'ton',\n    chains: TON_CHAINS,\n    adapters: [tonManifest],\n    presets: TON_PRESETS,\n    assets: TON_TOKENS,\n  };\n}\n"]}

package/dist/adapters/ton/presets.d.ts

@@ -0,0 +1,6 @@
+import type { ProviderPreset } from '../../core/registry/providers';
+/**
+ * Built once at module level, so the plugin's functions keep their identity and
+ * registering the plugin again is the same plugin.
+ */
+export declare const TON_PRESETS: readonly ProviderPreset[];

package/dist/adapters/ton/presets.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TON_PRESETS = void 0;
+/**
+ * TON provider presets: toncenter's API v2 (a liteserver proxy, the `rpc` endpoint) and
+ * API v3 (its indexer). Base URLs, the `X-API-Key` header and the limits (1 request per
+ * second keyless, 10 with a free key) are verified against docs.ton.org and toncenter's
+ * own API descriptions, and the 429s were reproduced live. The key travels in a header
+ * whose value is a `Secret`, so it never reaches logs, errors or events.
+ *
+ * One toncenter limit covers every request to a network, v2 and v3 alike (per IP keyless,
+ * per account with a key), so each API's endpoint gets half of it. Health probes take
+ * their tokens from the same buckets. The split holds on average only: after idle time
+ * each API's bucket holds its burst of one token (keyless by default, keyed set
+ * explicitly: with the default burst of five, v2 and v3 together sent about 18 requests
+ * in the first second) and refills at its rate, so v2 and v3 together can send 2 requests
+ * in the first second keyless (limit 1) and 12 with a key (limit 10); toncenter's 429
+ * then comes back as a retryable `RATE_LIMITED`.
+ */
+const error_1 = require("../../core/errors/error");
+const secret_1 = require("../../core/secret/secret");
+const freeze_1 = require("../../core/util/freeze");
+const HOSTS = Object.freeze({
+    mainnet: 'https://toncenter.com',
+    testnet: 'https://testnet.toncenter.com',
+});
+const API = Object.freeze({
+    rpc: '/api/v2',
+    indexer: '/api/v3',
+});
+/** Own keys only: `constructor`, `toString` or `__proto__` is not a network. */
+const supports = (chain, network) => chain === 'ton' && Object.hasOwn(HOSTS, network);
+function baseUrl(kind, input) {
+    // Unreachable through the catalog, which asks `supports` first.
+    if (!Object.hasOwn(HOSTS, input.network)) {
+        throw new Error(`no toncenter host for ${input.network}`);
+    }
+    return `${HOSTS[input.network]}${API[kind]}`;
+}
+/** The revealed key; the error names the preset and network, never the key. */
+function apiKeyOf(input) {
+    const key = input.apiKey === undefined ? undefined : (0, secret_1.reveal)(input.apiKey);
+    if (typeof key !== 'string' || key.trim() === '') {
+        throw new error_1.ConfigError('CONFIG_INVALID', `provider preset 'toncenter' requires a non-empty apiKey for ${input.chain}:${input.network}`);
+    }
+    return key;
+}
+function keyless(kind) {
+    return {
+        name: 'public',
+        kind,
+        production: false,
+        supports,
+        endpoints: (input) => [
+            {
+                name: 'toncenter',
+                url: baseUrl(kind, input),
+                // Half of the keyless 1 request per second, shared with the other API.
+                rateLimit: { rps: 0.5 },
+            },
+        ],
+    };
+}
+function keyed(kind) {
+    return {
+        name: 'toncenter',
+        kind,
+        requiresApiKey: true,
+        supports,
+        endpoints: (input) => [
+            {
+                name: 'toncenter',
+                url: baseUrl(kind, input),
+                headers: { 'X-API-Key': (0, secret_1.secret)(apiKeyOf(input)) },
+                // Half of the free-key limit of 10 requests per second
+                // (docs.ton.org/api/rate-limit), shared with the other API, with a burst of one
+                // rather than the default of five; a paid key overrides it with a custom endpoint
+                // config.
+                rateLimit: { rps: 5, burst: 1 },
+            },
+        ],
+    };
+}
+/**
+ * Built once at module level, so the plugin's functions keep their identity and
+ * registering the plugin again is the same plugin.
+ */
+exports.TON_PRESETS = (0, freeze_1.deepFreeze)([
+    keyless('rpc'),
+    keyless('indexer'),
+    keyed('rpc'),
+    keyed('indexer'),
+]);
+//# sourceMappingURL=presets.js.map

package/dist/adapters/ton/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../../src/adapters/ton/presets.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;GAeG;AACH,mDAAsD;AAEtD,qDAA0D;AAE1D,mDAAoD;AAEpD,MAAM,KAAK,GAAqC,MAAM,CAAC,MAAM,CAAC;IAC5D,OAAO,EAAE,uBAAuB;IAChC,OAAO,EAAE,+BAA+B;CACzC,CAAC,CAAC;AAEH,MAAM,GAAG,GAAgD,MAAM,CAAC,MAAM,CAAC;IACrE,GAAG,EAAE,SAAS;IACd,OAAO,EAAE,SAAS;CACnB,CAAC,CAAC;AAEH,gFAAgF;AAChF,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,OAAe,EAAW,EAAE,CAC3D,KAAK,KAAK,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAEnD,SAAS,OAAO,CAAC,IAAuB,EAAE,KAAkB;IAC1D,gEAAgE;IAChE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,+EAA+E;AAC/E,SAAS,QAAQ,CAAC,KAAkB;IAClC,MAAM,GAAG,GAAY,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAA,eAAM,EAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnF,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,+DAA+D,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAC9F,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,OAAO,CAAC,IAAuB;IACtC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,IAAI;QACJ,UAAU,EAAE,KAAK;QACjB,QAAQ;QACR,SAAS,EAAE,CAAC,KAAK,EAA6B,EAAE,CAAC;YAC/C;gBACE,IAAI,EAAE,WAAW;gBACjB,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;gBACzB,uEAAuE;gBACvE,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE;aACxB;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,IAAuB;IACpC,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,IAAI;QACJ,cAAc,EAAE,IAAI;QACpB,QAAQ;QACR,SAAS,EAAE,CAAC,KAAK,EAA6B,EAAE,CAAC;YAC/C;gBACE,IAAI,EAAE,WAAW;gBACjB,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;gBACzB,OAAO,EAAE,EAAE,WAAW,EAAE,IAAA,eAAM,EAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE;gBACjD,uDAAuD;gBACvD,gFAAgF;gBAChF,kFAAkF;gBAClF,UAAU;gBACV,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;aAChC;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACU,QAAA,WAAW,GAA8B,IAAA,mBAAU,EAAC;IAC/D,OAAO,CAAC,KAAK,CAAC;IACd,OAAO,CAAC,SAAS,CAAC;IAClB,KAAK,CAAC,KAAK,CAAC;IACZ,KAAK,CAAC,SAAS,CAAC;CACjB,CAAC,CAAC","sourcesContent":["/**\n * TON provider presets: toncenter's API v2 (a liteserver proxy, the `rpc` endpoint) and\n * API v3 (its indexer). Base URLs, the `X-API-Key` header and the limits (1 request per\n * second keyless, 10 with a free key) are verified against docs.ton.org and toncenter's\n * own API descriptions, and the 429s were reproduced live. The key travels in a header\n * whose value is a `Secret`, so it never reaches logs, errors or events.\n *\n * One toncenter limit covers every request to a network, v2 and v3 alike (per IP keyless,\n * per account with a key), so each API's endpoint gets half of it. Health probes take\n * their tokens from the same buckets. The split holds on average only: after idle time\n * each API's bucket holds its burst of one token (keyless by default, keyed set\n * explicitly: with the default burst of five, v2 and v3 together sent about 18 requests\n * in the first second) and refills at its rate, so v2 and v3 together can send 2 requests\n * in the first second keyless (limit 1) and 12 with a key (limit 10); toncenter's 429\n * then comes back as a retryable `RATE_LIMITED`.\n */\nimport { ConfigError } from '../../core/errors/error';\nimport type { PresetInput, ProviderPreset } from '../../core/registry/providers';\nimport { reveal, secret } from '../../core/secret/secret';\nimport type { EndpointConfig } from '../../core/transport/types';\nimport { deepFreeze } from '../../core/util/freeze';\n\nconst HOSTS: Readonly<Record<string, string>> = Object.freeze({\n  mainnet: 'https://toncenter.com',\n  testnet: 'https://testnet.toncenter.com',\n});\n\nconst API: Readonly<Record<'rpc' | 'indexer', string>> = Object.freeze({\n  rpc: '/api/v2',\n  indexer: '/api/v3',\n});\n\n/** Own keys only: `constructor`, `toString` or `__proto__` is not a network. */\nconst supports = (chain: string, network: string): boolean =>\n  chain === 'ton' && Object.hasOwn(HOSTS, network);\n\nfunction baseUrl(kind: 'rpc' | 'indexer', input: PresetInput): string {\n  // Unreachable through the catalog, which asks `supports` first.\n  if (!Object.hasOwn(HOSTS, input.network)) {\n    throw new Error(`no toncenter host for ${input.network}`);\n  }\n  return `${HOSTS[input.network]}${API[kind]}`;\n}\n\n/** The revealed key; the error names the preset and network, never the key. */\nfunction apiKeyOf(input: PresetInput): string {\n  const key: unknown = input.apiKey === undefined ? undefined : reveal(input.apiKey);\n  if (typeof key !== 'string' || key.trim() === '') {\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      `provider preset 'toncenter' requires a non-empty apiKey for ${input.chain}:${input.network}`,\n    );\n  }\n  return key;\n}\n\nfunction keyless(kind: 'rpc' | 'indexer'): ProviderPreset {\n  return {\n    name: 'public',\n    kind,\n    production: false,\n    supports,\n    endpoints: (input): readonly EndpointConfig[] => [\n      {\n        name: 'toncenter',\n        url: baseUrl(kind, input),\n        // Half of the keyless 1 request per second, shared with the other API.\n        rateLimit: { rps: 0.5 },\n      },\n    ],\n  };\n}\n\nfunction keyed(kind: 'rpc' | 'indexer'): ProviderPreset {\n  return {\n    name: 'toncenter',\n    kind,\n    requiresApiKey: true,\n    supports,\n    endpoints: (input): readonly EndpointConfig[] => [\n      {\n        name: 'toncenter',\n        url: baseUrl(kind, input),\n        headers: { 'X-API-Key': secret(apiKeyOf(input)) },\n        // Half of the free-key limit of 10 requests per second\n        // (docs.ton.org/api/rate-limit), shared with the other API, with a burst of one\n        // rather than the default of five; a paid key overrides it with a custom endpoint\n        // config.\n        rateLimit: { rps: 5, burst: 1 },\n      },\n    ],\n  };\n}\n\n/**\n * Built once at module level, so the plugin's functions keep their identity and\n * registering the plugin again is the same plugin.\n */\nexport const TON_PRESETS: readonly ProviderPreset[] = deepFreeze([\n  keyless('rpc'),\n  keyless('indexer'),\n  keyed('rpc'),\n  keyed('indexer'),\n]);\n"]}

package/dist/adapters/ton/proofs.d.ts

@@ -0,0 +1,66 @@
+import type { AddressHistorySource, ProofSource } from '../../core/driver/types';
+import { type BlockHeader } from './api';
+import { type TonContext } from './reader';
+/** How far back the consumer of a seqno is searched: pages of `CONSUMER_PAGE` transactions. */
+export declare const CONSUMER_PAGES = 8;
+/** How far the chain is walked: pages of `WALK_PAGE` transactions. */
+export declare const WALK_PAGES = 16;
+/**
+ * The one unanchored head: one endpoint's head, trailed by the network's skew and
+ * attested by the quorum; when a healthy peer trails further, retried at the transport's
+ * lag tolerance, the furthest a proof endpoint may trail. Never a false head, only a
+ * later one.
+ */
+export declare function attestedHead(ctx: TonContext): Promise<BlockHeader>;
+/**
+ * No block after `header` can include a message valid until `validUntil`: the
+ * masterchain block and every shard top it commits are at least that old, every later block
+ * of a shard is younger than its top (the collator's `now` rises), and a wallet rejects a
+ * message once `valid_until <= now()`. The shard tops are asked for the attested block's
+ * seqno; toncenter's answer names no block (live), so only the proof quorum binds the list
+ * to it, and it must cover the basechain. Each top's header is read under the quorum
+ * and bound to the id the list gives. A lifetime that is no time decides nothing.
+ */
+export declare function expiredAt(ctx: TonContext, header: BlockHeader, validUntil: number): Promise<boolean>;
+/**
+ * Stored bytes about to be sent again: the wallet they go to (raw), their TEP-467 hash, and
+ * the seqno and lifetime their signed header carries. `validFrom` is the build's recorded
+ * chain time when this driver assembled them; otherwise the widest lifetime applies.
+ */
+export interface StoredMessage {
+    readonly wallet: string;
+    readonly id: string;
+    readonly seqno: bigint;
+    readonly validUntil: number;
+    readonly validFrom?: number;
+}
+/**
+ * Whether stored bytes may go out again. A wallet reset (a deletion, then a deposit,
+ * or a re-deploy from the public `StateInit` back to our seqno) makes a message that already
+ * ran and paid runnable again while it is valid, so every send of stored bytes asks first:
+ * - `send`: the wallet's seqno is already above ours under the proof quorum, so the message
+ *   cannot run (no walk); or the chain shows it cannot have run: the walk reaches the
+ *   earliest time it could have run (`windowStartOf`, from the recorded build time, else
+ *   the widest lifetime) with no reset, or a chain start whose earlier history shows the
+ *   code never ran (a wallet funded a minute ago is sent to);
+ * - `ours`: the chain holds our message run to the end: it must never be sent again.
+ * The walk starts from the freshest state an endpoint serves (the attested head trails it
+ * by 10 to 150 blocks, and a reset in that trail is exactly the danger), and must lead
+ * down to the attested state's last transaction, so a lying fresh endpoint can hide only
+ * what the attested walk could not see either. Anything else, including a deletion or a
+ * new chain since the attested head, an activation or a destruction in the window, a walk
+ * past its cap, an indexer behind the fresh block or a failed read, throws a retryable
+ * error: the guard never sends while it cannot decide, and the proof decides.
+ * Known gap: once a wallet is reset (which takes software that shares its key), anyone
+ * can replay our message from the chain's public record; no client can stop that, and the
+ * guard covers only this library's own sends.
+ */
+export declare function replayVerdict(ctx: TonContext, message: StoredMessage): Promise<'send' | 'ours'>;
+export declare function createTonProofs(ctx: TonContext): ProofSource;
+/**
+ * An address's transactions from the indexer, newest first, decoded with jettons only for
+ * verified jetton wallets. The cursor is the next page's `end_lt`, taken from the page as
+ * the indexer served it, so rows not final yet never end the history early; a page
+ * is at most what toncenter serves.
+ */
+export declare function createTonHistory(ctx: TonContext): AddressHistorySource;