crypto-aio 0.0.3 → 0.1.0

package/dist/adapters/ton/api.js

@@ -0,0 +1,942 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TonApi = exports.sameBlock = exports.MAX_STATE_BOC_LENGTH = exports.MAX_STATE_CELLS = exports.MAX_BODY_BOC_LENGTH = exports.MAX_BODY_CELLS = exports.MASTERCHAIN_SHARD = exports.withSignal = exports.BROADCAST = exports.PROOF = exports.MONITOR = exports.READ = void 0;
+exports.bocWithinLimits = bocWithinLimits;
+exports.hashHex = hashHex;
+exports.rawOf = rawOf;
+exports.transactionOf = transactionOf;
+exports.masterchainInfoSeqno = masterchainInfoSeqno;
+exports.indexedHeadOf = indexedHeadOf;
+exports.configParamBoc = configParamBoc;
+exports.runResultOf = runResultOf;
+exports.boundRunResultOf = boundRunResultOf;
+exports.jettonDataOf = jettonDataOf;
+/**
+ * The TON driver's only path to the network: toncenter API v2 (the `rpc` transport: live
+ * liteserver state, get-methods at a fixed masterchain block, fee emulation, sending) and
+ * API v3 (the `indexer` transport: message → transaction, traces, history, jetton
+ * metadata), as REST calls through the core transports. Not JSON-RPC: toncenter's
+ * `/jsonRPC` answers carry no `id`, which `transport.rpc` refuses, and `TonClient` would
+ * put a real timer on the request path. Each call carries its driver method's tags and a
+ * `route` with no identifiers in it (events and logs show it), and reads integers exactly
+ * (toncenter writes some u64 values as JSON numbers). Answers are validated here: a
+ * malformed one, including a missing or ill-typed field a verdict reads, is a retryable
+ * `PROVIDER_UNAVAILABLE`, never a default or a foreign error. Lookups by id keep only
+ * what they asked for, so a dropped server-side filter reads as "none yet"; a history
+ * that breaks its query is malformed. Numbers, cells and metadata are bounded before use.
+ * Under a quorum, every method compares the parsed facts it returns (so honest endpoints
+ * that format a fact differently agree), or the caller's predicate key. SDK-free.
+ */
+const error_1 = require("../../core/errors/error");
+const fees_1 = require("./fees");
+exports.READ = { purpose: 'read', retry: 'safe' };
+exports.MONITOR = { purpose: 'monitor', retry: 'safe' };
+exports.PROOF = { purpose: 'proof', retry: 'safe', quorum: 'proof' };
+exports.BROADCAST = {
+    purpose: 'broadcast',
+    retry: 'ambiguous-on-failure',
+};
+const withSignal = (tags, signal) => signal ? { ...tags, signal } : tags;
+exports.withSignal = withSignal;
+/** The masterchain's one shard, as toncenter v2 writes it. */
+exports.MASTERCHAIN_SHARD = '-9223372036854775808';
+/**
+ * The most cells a message body may hold, checked in the BOC header before the
+ * SDK parses anything. TON refuses a message of more than 2^13 cells or 2^21 bits (config
+ * param 43, "account and message limits", docs.ton.org/foundations/config; the node's
+ * defaults `max_msg_cells = 1 << 13` and `max_msg_bits = 1 << 21` in `SizeLimitsConfig`,
+ * ton-blockchain/ton `crypto/block/mc-config.h`), so no body the chain carried holds more.
+ * The text length alone does not bound the work: minimal cells cost about 4 bytes each,
+ * and `Cell.fromBoc` takes about 20-50 µs per cell.
+ */
+exports.MAX_BODY_CELLS = 1 << 13;
+/**
+ * The longest message body BOC text `cellFromBoc` decodes. The same limits give
+ * at most 2^21 / 8 bytes of data in 2^13 cells, each with 2 descriptor bytes, 4 two-byte
+ * refs, a rounding byte and a 3-byte index entry, plus a header and a checksum: under
+ * 377,000 bytes, about 502,500 base64 characters.
+ */
+exports.MAX_BODY_BOC_LENGTH = 1 << 19;
+/**
+ * The most cells of a jetton master's content that `jettonData` hands
+ * on. The content is part of the master's account state, not a message, and TON caps a state
+ * at 2^16 cells and 2^16 × 1023 bits (config param 43, `max_acc_state_cells` and
+ * `max_acc_state_bits`, the node's defaults in `SizeLimitsConfig`, ton-blockchain/ton
+ * `crypto/block/mc-config.h`), so no content the chain holds is larger.
+ */
+exports.MAX_STATE_CELLS = 1 << 16;
+/**
+ * The longest content BOC text `jettonData` hands on. The same limits
+ * give at most 2^16 × 1023 / 8 bytes of data in 2^16 cells, each with 2 descriptor bytes, 4
+ * three-byte refs, a rounding byte and a 4-byte index entry, plus a header and a checksum:
+ * under 9.7 MB, about 12.9 million base64 characters. Decoding a state of that size takes
+ * about 2 s (`@ton/core` 0.63.1, measured); only a master's metadata, read once per token
+ * and cached, can be that large.
+ */
+exports.MAX_STATE_BOC_LENGTH = 1 << 24;
+/**
+ * The cell count a BOC header declares, for the three layouts `@ton/core` reads (magic,
+ * then the size byte or flags with the size in their low 3 bits, the offset size, and the
+ * count in `size` bytes); undefined for anything else.
+ */
+function bocCellCount(bytes) {
+    if (bytes.length < 6)
+        return undefined;
+    const magic = bytes.readUInt32BE(0);
+    const head = bytes[4];
+    const size = magic === 0xb5ee9c72
+        ? head & 0x07
+        : magic === 0x68ff65f3 || magic === 0xacc3a728
+            ? head
+            : 0;
+    if (size < 1 || size > 4 || bytes.length < 6 + size)
+        return undefined;
+    return bytes.readUIntBE(6, size);
+}
+/**
+ * A base64 BOC measured against limits, by default one message's (at most
+ * `maxLength` characters, and a header, its first 16 characters, declaring at most
+ * `maxCells` cells): `oversized` beyond them, `malformed` without a BOC header.
+ */
+function bocSize(boc, maxCells = exports.MAX_BODY_CELLS, maxLength = exports.MAX_BODY_BOC_LENGTH) {
+    if (boc.length === 0)
+        return 'malformed';
+    const count = bocCellCount(Buffer.from(boc.slice(0, 16), 'base64'));
+    if (count === undefined)
+        return 'malformed';
+    return boc.length > maxLength || count > maxCells ? 'oversized' : 'ok';
+}
+/**
+ * Whether a base64 BOC is within one message's limits. SDK-free, so the API layer
+ * bounds the cells it hands on (config params, get-method stacks) and `cellFromBoc` the
+ * bodies it decodes.
+ */
+function bocWithinLimits(boc) {
+    return bocSize(boc) === 'ok';
+}
+/**
+ * The longest token metadata texts read from the indexer (decimals: 0..255). A longer or
+ * ill-typed `symbol` is reported unreadable; a `name` beyond its limit is absent, never
+ * an error: it is author-set text every endpoint agrees on, so a refusal would retry
+ * forever.
+ */
+const CONTENT_LIMITS = { symbol: 256, name: 256 };
+function malformed(route) {
+    return new error_1.ProviderError('PROVIDER_UNAVAILABLE', `malformed toncenter answer to ${route}`, {
+        retryable: true,
+    });
+}
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Checks, else throws the retryable malformed-answer error. */
+function need(value, route) {
+    if (value === undefined || value === null)
+        throw malformed(route);
+    return value;
+}
+/** An optional field: absent (undefined or null), else `read` must accept it. */
+function optional(value, read, route) {
+    return value === undefined || value === null ? undefined : need(read(value), route);
+}
+const str = (value) => typeof value === 'string' ? value : undefined;
+const bool = (value) => typeof value === 'boolean' ? value : undefined;
+const record = (value) => isRecord(value) ? value : undefined;
+const int = (value) => typeof value === 'number' && Number.isSafeInteger(value)
+    ? value
+    : typeof value === 'string' && /^-?\d{1,15}$/.test(value)
+        ? Number(value)
+        : undefined;
+/**
+ * An integer as a decimal string, a safe number or an exactly read bigint (the
+ * transport's `exactIntegers`). At most 80 digits (the core's exact-integer cap; u256 has
+ * 78), refused before `BigInt`.
+ */
+const big = (value) => typeof value === 'bigint'
+    ? value
+    : typeof value === 'string' && /^-?\d{1,80}$/.test(value)
+        ? BigInt(value)
+        : typeof value === 'number' && Number.isSafeInteger(value)
+            ? BigInt(value)
+            : undefined;
+const U64_MAX = 2n ** 64n - 1n;
+/** An unsigned integer up to `max`. */
+function unsigned(value, max) {
+    const n = big(value);
+    return n !== undefined && n >= 0n && n <= max ? n : undefined;
+}
+/** An amount of nanograms (`Coins`, a VarUInteger 16: below 2^120). */
+const coins = (value) => unsigned(value, fees_1.MAX_COINS);
+/** A logical time (u64). */
+const u64 = (value) => unsigned(value, U64_MAX);
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+/** A shard id (a signed 64-bit integer) as canonical decimal, however it was written. */
+function shardOf(value) {
+    const shard = big(value);
+    return shard !== undefined && shard >= INT64_MIN && shard <= INT64_MAX
+        ? shard.toString()
+        : undefined;
+}
+/** A 32-byte hash given in base64 (toncenter's form) as lower-case hex. */
+function hashHex(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (/^[0-9a-fA-F]{64}$/.test(value))
+        return value.toLowerCase();
+    if (!/^[A-Za-z0-9+/_-]{43}=?$/.test(value))
+        return undefined;
+    const bytes = Buffer.from(value.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+    return bytes.length === 32 ? bytes.toString('hex') : undefined;
+}
+/** toncenter v3 writes raw addresses in upper case; the canonical form is lower case. */
+function rawOf(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string' || !/^(0|-1):[0-9a-fA-F]{64}$/.test(value))
+        return undefined;
+    return value.toLowerCase();
+}
+/**
+ * A lookup that filters its answer by address needs the address's raw form (the
+ * codec's canonical form); anything else is refused before any request, never retried as a
+ * provider fault.
+ */
+function rawAddress(address) {
+    const raw = rawOf(address);
+    if (!raw) {
+        throw new error_1.ValidationError('INVALID_ADDRESS', 'a toncenter lookup needs a raw address');
+    }
+    return raw;
+}
+/** Whether two block ids name the same block: workchain, shard, seqno and both hashes. */
+const sameBlock = (a, b) => a.workchain === b.workchain &&
+    a.shard === b.shard &&
+    a.seqno === b.seqno &&
+    a.rootHash === b.rootHash &&
+    a.fileHash === b.fileHash;
+exports.sameBlock = sameBlock;
+// ---- parsers ------------------------------------------------------------------------------
+// A field a verdict reads is required, or optional and then well typed; a missing or
+// ill-typed one is malformed (retryable), never `false` or `0`. Every endpoint running
+// the same indexer would agree on a drifted answer, so a quorum does not catch what the
+// parser lets through: a truncated answer read as `false` would end a delivered transfer
+// `failed`, and a caller's retry with a new seqno would pay twice.
+function blockIdOf(value, route) {
+    const v = need(record(value), route);
+    return {
+        workchain: need(int(v.workchain), route),
+        shard: need(shardOf(v.shard), route),
+        seqno: need(int(v.seqno), route),
+        rootHash: need(hashHex(v.root_hash), route),
+        fileHash: need(hashHex(v.file_hash), route),
+    };
+}
+function v2Result(body, route) {
+    if (!isRecord(body) || body.ok !== true || !('result' in body))
+        throw malformed(route);
+    return body.result;
+}
+/** A cell's base64 BOC, within one message's limits. */
+function cellOf(value, route) {
+    const boc = need(str(value), route);
+    if (!bocWithinLimits(boc))
+        throw malformed(route);
+    return boc;
+}
+function stackOf(value, route) {
+    if (!Array.isArray(value))
+        throw malformed(route);
+    return value.map((entry) => {
+        if (!Array.isArray(entry) || entry.length !== 2)
+            throw malformed(route);
+        const [type, data] = entry;
+        if (type === 'num') {
+            const text = need(str(data), route);
+            const negative = text.startsWith('-');
+            const digits = negative ? text.slice(1) : text;
+            // A TVM integer has 257 bits (65 hex digits); bounded before `BigInt`.
+            if (!/^0x[0-9a-fA-F]{1,80}$/.test(digits))
+                throw malformed(route);
+            const value = BigInt(digits);
+            return { type: 'num', value: negative ? -value : value };
+        }
+        if (type === 'cell' ||
+            type === 'slice' ||
+            type === 'tvm.Cell' ||
+            type === 'tvm.Slice') {
+            return { type: 'cell', boc: cellOf(isRecord(data) ? data.bytes : data, route) };
+        }
+        return { type: 'other' };
+    });
+}
+function messageOf(value, route) {
+    const m = need(record(value), route);
+    const content = optional(m.message_content, record, route);
+    const source = rawOf(m.source ?? null);
+    const destination = rawOf(m.destination ?? null);
+    if (source === undefined || destination === undefined)
+        throw malformed(route);
+    const hashNorm = optional(m.hash_norm, hashHex, route);
+    const bodyHash = content ? optional(content.hash, hashHex, route) : undefined;
+    const body = content ? optional(content.body, str, route) : undefined;
+    return {
+        hash: need(hashHex(m.hash), route),
+        ...(hashNorm !== undefined ? { hashNorm } : {}),
+        source,
+        destination,
+        value: optional(m.value, coins, route) ?? null,
+        bounce: optional(m.bounce, bool, route) ?? null,
+        bounced: optional(m.bounced, bool, route) ?? null,
+        ...(bodyHash !== undefined ? { bodyHash } : {}),
+        ...(body !== undefined ? { body } : {}),
+    };
+}
+/** Transaction types with a compute phase (block.tlb `trans_ord`, `trans_tick_tock`). */
+const COMPUTING = new Set(['ord', 'tick_tock']);
+/** Bounce phase types (block.tlb `tr_phase_bounce_ok`, `_nofunds`, `_negfunds`). */
+const BOUNCES = new Set(['ok', 'nofunds', 'negfunds']);
+/** The compute phase; an ord or tick-tock transaction always has one. */
+function computeOf(d, route) {
+    const type = need(str(d.type), route);
+    if (d.compute_ph === undefined || d.compute_ph === null) {
+        if (COMPUTING.has(type))
+            throw malformed(route);
+        return { skipped: true, success: false };
+    }
+    const c = need(record(d.compute_ph), route);
+    const skipped = need(bool(c.skipped), route);
+    // A skipped phase (`tr_phase_compute_skipped`) carries only its reason.
+    const success = skipped
+        ? (optional(c.success, bool, route) ?? false)
+        : need(bool(c.success), route);
+    const exitCode = optional(c.exit_code, int, route);
+    return { skipped, success, ...(exitCode !== undefined ? { exitCode } : {}) };
+}
+/** The action phase, when there was one, with every field a verdict reads. */
+function actionOf(value, route) {
+    const a = optional(value, record, route);
+    if (!a)
+        return undefined;
+    return {
+        success: need(bool(a.success), route),
+        resultCode: need(int(a.result_code), route),
+        skippedActions: need(int(a.skipped_actions), route),
+        msgsCreated: need(int(a.msgs_created), route),
+    };
+}
+/** The bounce phase's type, one of block.tlb's three. */
+function bounceOf(value, route) {
+    const b = optional(value, record, route);
+    if (!b)
+        return undefined;
+    const type = need(str(b.type), route);
+    if (!BOUNCES.has(type))
+        throw malformed(route);
+    return type;
+}
+const V3_STATUSES = new Set([
+    'nonexist',
+    'uninit',
+    'active',
+    'frozen',
+]);
+/** A v3 account status: one of the four (well typed when present). */
+const accountStatus = (value) => V3_STATUSES.has(value) ? value : undefined;
+function transactionOf(value, route) {
+    const t = need(record(value), route);
+    const d = need(record(t.description), route);
+    const action = actionOf(d.action, route);
+    const bounce = bounceOf(d.bounce, route);
+    const origStatus = optional(t.orig_status, accountStatus, route);
+    const endStatus = optional(t.end_status, accountStatus, route);
+    return {
+        hash: need(hashHex(t.hash), route),
+        lt: need(u64(t.lt), route),
+        account: need(rawOf(t.account) ?? undefined, route),
+        now: need(int(t.now), route),
+        mcSeqno: need(int(t.mc_block_seqno), route),
+        traceId: need(hashHex(t.trace_id), route),
+        totalFees: need(coins(t.total_fees), route),
+        aborted: need(bool(d.aborted), route),
+        compute: computeOf(d, route),
+        ...(action ? { action } : {}),
+        ...(bounce !== undefined ? { bounce } : {}),
+        ...(origStatus !== undefined ? { origStatus } : {}),
+        ...(endStatus !== undefined ? { endStatus } : {}),
+        inMsg: t.in_msg === null || t.in_msg === undefined ? null : messageOf(t.in_msg, route),
+        outMsgs: need(Array.isArray(t.out_msgs) ? t.out_msgs : undefined, route).map((m) => messageOf(m, route)),
+    };
+}
+/**
+ * Whether a v3 `finality` is the masterchain's: live answers name the state (`finalized`),
+ * the swagger declares an int enum (0 pending, 1 confirmed, 2 finalized). An indexer that
+ * writes none is read as before: every transaction still needs its masterchain block.
+ */
+function finalized(f) {
+    return f === undefined || f === null || f === 'finalized' || f === 2;
+}
+/**
+ * Only chain evidence counts: an emulated (pending) transaction is toncenter's guess, and
+ * one not yet `finalized` (a shard block the masterchain has not committed) is not final;
+ * either reads as "not yet", and a trace holding one is incomplete.
+ */
+const committed = (value) => !(isRecord(value) && (value.emulated === true || !finalized(value.finality)));
+/**
+ * A v3 transaction list, emulated or not yet finalized ones dropped; more than `limit`
+ * items is malformed.
+ */
+function transactionsOf(body, route, limit) {
+    if (!isRecord(body) ||
+        !Array.isArray(body.transactions) ||
+        body.transactions.length > limit) {
+        throw malformed(route);
+    }
+    return body.transactions.filter(committed).map((t) => transactionOf(t, route));
+}
+/** A block header, parsed. */
+function headerOf(result, route) {
+    const h = need(record(result), route);
+    return {
+        id: blockIdOf(h.id, route),
+        globalId: need(int(h.global_id), route),
+        genUtime: need(int(h.gen_utime), route),
+        prev: Array.isArray(h.prev_blocks)
+            ? h.prev_blocks.map((p) => blockIdOf(p, route))
+            : [],
+    };
+}
+/**
+ * The one parser of a masterchain block id's seqno, for the proofs' head reads and the
+ * driver's health probes alike (a node's height is a claim): only a
+ * masterchain id (workchain -1), and only within a masterchain seqno's range (u32).
+ */
+function masterchainIdSeqno(value, route) {
+    const id = record(value);
+    const seqno = int(id?.seqno);
+    if (id?.workchain !== -1 || seqno === undefined || seqno < 0 || seqno > 0xffff_ffff) {
+        throw malformed(route);
+    }
+    return seqno;
+}
+/** The newest masterchain block's seqno in a v2 `getMasterchainInfo` answer body. */
+function masterchainInfoSeqno(body, route) {
+    return masterchainIdSeqno(record(v2Result(body, route))?.last, route);
+}
+/**
+ * A v3 `masterchainInfo` answer body: the indexed head's seqno (`masterchainSeqnoOf`) and the
+ * network's global id, an int32.
+ */
+function indexedHeadOf(body, route) {
+    const last = record(record(body)?.last);
+    const globalId = int(last?.global_id);
+    if (globalId === undefined || globalId < -(2 ** 31) || globalId > 2 ** 31 - 1) {
+        throw malformed(route);
+    }
+    return { seqno: masterchainIdSeqno(last, route), globalId };
+}
+/** A config param's cell (base64 BOC, within one message's limits) in a v2 answer body. */
+function configParamBoc(body, route) {
+    const result = v2Result(body, route);
+    return cellOf(need(isRecord(result) ? record(result.config) : undefined, route).bytes, route);
+}
+/** An account state, parsed. */
+function accountOf(result, route) {
+    const r = need(record(result), route);
+    const state = r.state;
+    const status = state === 'active' || state === 'frozen'
+        ? state
+        : state === 'uninitialized' || state === 'uninit' || state === 'nonexist'
+            ? 'uninitialized'
+            : undefined;
+    const last = transactionIdOf(r.last_transaction_id, route);
+    const block = blockIdOf(r.block_id, route);
+    return {
+        balance: need(coins(r.balance), route),
+        status: need(status, route),
+        lastLt: last.lt,
+        lastHash: last.hash,
+        blockSeqno: block.seqno,
+        block,
+        syncUtime: need(int(r.sync_utime), route),
+    };
+}
+/** A v2 `internal.transactionId`: lt and hash. */
+function transactionIdOf(value, route) {
+    const id = need(record(value), route);
+    return { lt: need(u64(id.lt), route), hash: need(hashHex(id.hash), route) };
+}
+function runOf(result, route) {
+    if (!isRecord(result))
+        throw malformed(route);
+    return {
+        exitCode: need(int(result.exit_code), route),
+        stack: stackOf(result.stack, route),
+    };
+}
+/** A v2 `runGetMethod` answer body, parsed; for callers' quorum predicates. */
+function runResultOf(body) {
+    return runOf(v2Result(body, '/runGetMethod'), '/runGetMethod');
+}
+/** A get-method's result with its block and the account's last transaction. */
+function boundRunOf(result, route) {
+    const r = need(record(result), route);
+    return {
+        ...runOf(result, route),
+        block: blockIdOf(r.block_id, route),
+        lastTransaction: transactionIdOf(r.last_transaction_id, route),
+    };
+}
+/** A v2 `runGetMethod` answer body with its binding, parsed; for callers' quorum keys. */
+function boundRunResultOf(body) {
+    return boundRunOf(v2Result(body, '/runGetMethod'), '/runGetMethod');
+}
+/**
+ * A v2 `getTransactions` result: at most `limit` rows, each with its id and a raw cell
+ * within an account state's limits, checked in the BOC header before anyone decodes it.
+ * What the rows are is for the caller to prove by their hashes.
+ */
+function rawTransactionsOf(result, route, limit) {
+    if (!Array.isArray(result) || result.length > limit)
+        throw malformed(route);
+    return result.map((item) => {
+        const row = need(record(item), route);
+        const { lt, hash } = transactionIdOf(row.transaction_id, route);
+        const boc = need(str(row.data), route);
+        if (bocSize(boc, exports.MAX_STATE_CELLS, exports.MAX_STATE_BOC_LENGTH) !== 'ok')
+            throw malformed(route);
+        return { lt, hash, boc };
+    });
+}
+/**
+ * `get_jetton_data`'s exit code and content cell (TEP-74: total supply, mintable, admin,
+ * content, wallet code). Only the content is read, so no other entry (a supply, a large
+ * wallet code) is held to anything. A content cell beyond an account state's limits
+ * (`MAX_STATE_CELLS`, `MAX_STATE_BOC_LENGTH`) is reported `oversized`, never decoded:
+ * no chain content is that large, and a caller that agrees on it under the proof quorum
+ * takes it as the token's own, not as an answer to retry forever.
+ * A stack that is not one, or a content entry without a BOC header, is malformed.
+ */
+function jettonDataFrom(result, route) {
+    const r = need(record(result), route);
+    const exitCode = need(int(r.exit_code), route);
+    const stack = need(Array.isArray(r.stack) ? r.stack : undefined, route);
+    if (exitCode !== 0)
+        return { exitCode };
+    const entry = stack[3];
+    if (entry === undefined)
+        return { exitCode };
+    if (!Array.isArray(entry) || entry.length !== 2)
+        throw malformed(route);
+    const [type, data] = entry;
+    if (type !== 'cell' &&
+        type !== 'slice' &&
+        type !== 'tvm.Cell' &&
+        type !== 'tvm.Slice') {
+        return { exitCode };
+    }
+    const boc = need(str(isRecord(data) ? data.bytes : data), route);
+    const size = bocSize(boc, exports.MAX_STATE_CELLS, exports.MAX_STATE_BOC_LENGTH);
+    if (size === 'malformed')
+        throw malformed(route);
+    return {
+        exitCode,
+        content: size === 'oversized' ? { kind: 'oversized' } : { kind: 'cell', boc },
+    };
+}
+/** A v2 `get_jetton_data` answer body, parsed; for callers' quorum keys. */
+function jettonDataOf(body) {
+    return jettonDataFrom(v2Result(body, '/runGetMethod'), '/runGetMethod');
+}
+/**
+ * A trace, parsed: its transactions in trace order, each listed once under its own hash
+ * (a transaction counted twice would count its transfer twice). An emulated or not yet
+ * finalized one is left out and leaves the trace incomplete.
+ */
+function traceOf(value, route) {
+    const t = need(record(value), route);
+    const info = isRecord(t.trace_info) ? t.trace_info : {};
+    const txs = need(record(t.transactions), route);
+    const order = need(Array.isArray(t.transactions_order) ? t.transactions_order : undefined, route);
+    const listed = new Set();
+    const entries = order.map((item) => {
+        const key = need(str(item), route);
+        const hash = need(hashHex(key), route);
+        if (listed.has(hash) || !Object.hasOwn(txs, key))
+            throw malformed(route);
+        listed.add(hash);
+        const value = txs[key];
+        if (!committed(value))
+            return undefined;
+        const tx = transactionOf(value, route);
+        if (tx.hash !== hash)
+            throw malformed(route);
+        return tx;
+    });
+    return {
+        traceId: need(hashHex(t.trace_id), route),
+        complete: t.is_incomplete === false &&
+            info.trace_state === 'complete' &&
+            entries.every((tx) => tx !== undefined),
+        transactions: entries.filter((tx) => tx !== undefined),
+    };
+}
+/**
+ * One `/metadata` token entry, the indexer's copy of the token's
+ * off-chain JSON. Only the fields a caller may use are read, and each as the token wrote it:
+ * a symbol or decimals that are not one are `null` (the token's own data, which every
+ * endpoint agrees on, so never malformed and retried forever); a name beyond its limit is
+ * absent. toncenter writes the JSON's decimals under `extra` (live, 2026-09-28).
+ */
+function tokenInfoOf(token) {
+    const info = {};
+    const { symbol, name, extra } = token;
+    if (symbol !== undefined && symbol !== null) {
+        info.symbol =
+            typeof symbol === 'string' && symbol.length <= CONTENT_LIMITS.symbol
+                ? symbol
+                : null;
+    }
+    if (typeof name === 'string' && name.length <= CONTENT_LIMITS.name)
+        info.name = name;
+    if (extra !== undefined && extra !== null) {
+        const decimals = isRecord(extra) ? extra.decimals : null;
+        const value = int(decimals);
+        if (!isRecord(extra))
+            info.decimals = null;
+        else if (decimals !== undefined && decimals !== null) {
+            info.decimals =
+                value !== undefined && value >= 0 && value <= 255 ? String(value) : null;
+        }
+    }
+    return info;
+}
+// ---- quorum facts -------------------------------------------------------------------------
+// Each method's key is its parsed value: honest endpoints that format a fact
+// differently (a number or a string, `uninit` or `uninitialized`, v2's `@extra`) agree, and
+// a key that throws is a disagreement. A key covers every field a verdict reads;
+// message bodies are left out (their serialization varies) and are bound to the keyed body
+// hash where they are decoded (`messageBody`). The transport compares keys as canonical
+// JSON, bigints included.
+/** Every fact of a transaction a verdict or a decoding reads, bodies as their hashes. */
+function factsOf(tx) {
+    const { inMsg, outMsgs, ...facts } = tx;
+    const message = (m) => {
+        if (!m)
+            return null;
+        const { body: _body, ...rest } = m;
+        return rest;
+    };
+    return { ...facts, inMsg: message(inMsg), outMsgs: outMsgs.map(message) };
+}
+/** A trace's id, completeness and every transaction's facts, in trace order. */
+function traceFacts(trace) {
+    return trace && { ...trace, transactions: trace.transactions.map(factsOf) };
+}
+const itself = (value) => value;
+/** The most transactions a message hash can name (a few forks of one external, retried). */
+const BY_MESSAGE_LIMIT = 8;
+class TonApi {
+    rpc;
+    indexer;
+    constructor(rpc, indexer) {
+        this.rpc = rpc;
+        this.indexer = indexer;
+    }
+    /** The rpc transport's lag tolerance, as the pool resolved it; proofs' last skew. */
+    get lagTolerance() {
+        return this.rpc.maxLagBlocks;
+    }
+    async #call(transport, request, tags, quorumKey) {
+        // The caller's key (a predicate) replaces the call's consensus facts.
+        const key = tags.quorumKey ?? quorumKey;
+        const options = {
+            ...tags,
+            exactIntegers: true,
+            ...(tags.quorum !== undefined ? { quorumKey: key } : {}),
+        };
+        try {
+            return await transport.http(request, options);
+        }
+        catch (error) {
+            // On a proof or monitor read, any definitive RPC error,
+            // whatever its text (a block the endpoint does not hold yet, pruned state, a provider
+            // that answers 4xx rather than toncenter's 500), decides nothing. TON's negatives come
+            // only from attested state, never from an error, so no error text is read here.
+            // A misconfigured endpoint (`PROVIDER_MISCONFIGURED`) still surfaces as the
+            // configuration error it is.
+            if ((tags.purpose === 'proof' || tags.purpose === 'monitor') &&
+                (0, error_1.isCryptoAioError)(error, 'RPC_ERROR') &&
+                !error.retryable) {
+                throw new error_1.ProviderError('PROVIDER_UNAVAILABLE', `${request.route ?? 'a state read'} was refused; deciding nothing`, { retryable: true, cause: error });
+            }
+            throw error;
+        }
+    }
+    /**
+     * One request whose answer `parse` validates. Under a quorum, each endpoint's answer is
+     * keyed on `facts` of its parsed value: the fields a verdict reads, never the envelope.
+     */
+    async #read(transport, request, tags, parse, facts = itself) {
+        const body = await this.#call(transport, request, tags, (answer) => facts(parse(answer, 'quorum')));
+        return parse(body, request.route);
+    }
+    #v2(route, query, tags, parse, facts) {
+        return this.#read(this.rpc, { method: 'GET', path: route, query, route }, tags, (body, label) => parse(v2Result(body, label), label), facts);
+    }
+    #v2Post(route, body, tags, parse, facts) {
+        return this.#read(this.rpc, { method: 'POST', path: route, body, route }, tags, (answer, label) => parse(v2Result(answer, label), label), facts);
+    }
+    #v3(route, query, tags, parse, facts) {
+        return this.#read(this.indexer, { method: 'GET', path: route, query, route }, tags, parse, facts);
+    }
+    /** The newest masterchain block the liteserver knows. */
+    masterchainHead(tags) {
+        return this.#v2('/getMasterchainInfo', {}, tags, (result, route) => masterchainIdSeqno(record(result)?.last, route));
+    }
+    /**
+     * Whether the liteserver holds masterchain block `seqno` (every masterchain block is
+     * final once it exists). Under a quorum the key is this predicate: endpoints
+     * past `seqno` agree whatever their heads.
+     */
+    reachedMasterchain(seqno, tags) {
+        return this.#v2('/getMasterchainInfo', {}, tags, (result, route) => masterchainIdSeqno(record(result)?.last, route) >= seqno);
+    }
+    /** A block's header; `seqno` above the endpoint's head fails (retryable). */
+    blockHeader(block, tags) {
+        return this.#v2('/getBlockHeader', {
+            workchain: String(block.workchain),
+            shard: block.shard,
+            seqno: String(block.seqno),
+        }, tags, headerOf, 
+        // The facts a proof reads; `prev_blocks` only feeds `getBlock`'s parent hash (a `read`).
+        ({ prev: _prev, ...facts }) => facts);
+    }
+    masterchainHeader(seqno, tags) {
+        return this.blockHeader({ workchain: -1, shard: exports.MASTERCHAIN_SHARD, seqno }, tags);
+    }
+    /** The shard blocks masterchain block `seqno` commits. */
+    shards(seqno, tags) {
+        return this.#v2('/getShards', { seqno: String(seqno) }, tags, (result, route) => need(isRecord(result) && Array.isArray(result.shards) ? result.shards : undefined, route).map((s) => blockIdOf(s, route)));
+    }
+    /** A config param's cell (base64 BOC, within one message's limits). */
+    configParam(param, tags, seqno) {
+        return this.#v2('/getConfigParam', {
+            param: String(param),
+            ...(seqno !== undefined ? { seqno: String(seqno) } : {}),
+        }, tags, (result, route) => cellOf(need(isRecord(result) ? record(result.config) : undefined, route).bytes, route));
+    }
+    /** An account's state, at masterchain block `seqno` when given. */
+    account(address, tags, seqno) {
+        return this.#v2('/getAddressInformation', { address, ...(seqno !== undefined ? { seqno: String(seqno) } : {}) }, tags, accountOf, 
+        // `sync_utime` is when the endpoint answered, not a fact of the state at that block.
+        ({ syncUtime: _syncUtime, ...facts }) => facts);
+    }
+    /** A get-method, at masterchain block `seqno` when given. */
+    runGetMethod(address, method, stack, tags, seqno) {
+        return this.#v2Post('/runGetMethod', { address, method, stack, ...(seqno !== undefined ? { seqno } : {}) }, tags, runOf);
+    }
+    /**
+     * A get-method at masterchain block `seqno`, with the block and the account's last
+     * transaction the answer names: a caller binds the result to the state it
+     * read, since an endpoint that drops the block answers at its own latest state.
+     */
+    runGetMethodAt(address, method, stack, tags, seqno) {
+        return this.#v2Post('/runGetMethod', { address, method, stack, seqno }, tags, boundRunOf);
+    }
+    /**
+     * Up to `limit` of an account's transactions (a raw address) from `from` back, as the
+     * liteserver serves them (v2 `getTransactions`), each with its raw cell. Under a quorum
+     * the endpoints agree on the ids; the cells are the caller's to hash.
+     */
+    async rawTransactions(address, from, limit, tags) {
+        rawAddress(address);
+        return this.#v2('/getTransactions', {
+            address,
+            lt: from.lt.toString(),
+            hash: from.hash,
+            limit: String(limit),
+            // A walk may reach old history, which only archive liteservers hold.
+            archival: 'true',
+        }, tags, (result, route) => rawTransactionsOf(result, route, limit), (rows) => rows.map(({ lt, hash }) => ({ lt, hash })));
+    }
+    /** A jetton master's `get_jetton_data`: its exit code and content cell (`jettonDataOf`). */
+    jettonData(master, tags, seqno) {
+        return this.#v2Post('/runGetMethod', {
+            address: master,
+            method: 'get_jetton_data',
+            stack: [],
+            ...(seqno !== undefined ? { seqno } : {}),
+        }, tags, jettonDataFrom);
+    }
+    /** The emulated source fees of an external message body (signature check skipped). */
+    estimateFee(request, tags) {
+        return this.#v2Post('/estimateFee', {
+            address: request.address,
+            body: request.body,
+            init_code: request.initCode ?? '',
+            init_data: request.initData ?? '',
+            ignore_chksig: true,
+        }, tags, (result, route) => {
+            // toncenter writes these fees as JSON numbers: read exactly, as coins.
+            const fees = need(isRecord(result) ? record(result.source_fees) : undefined, route);
+            return {
+                importFee: need(coins(fees.in_fwd_fee), route),
+                storageFee: need(coins(fees.storage_fee), route),
+                gasFee: need(coins(fees.gas_fee), route),
+                forwardFee: need(coins(fees.fwd_fee), route),
+            };
+        });
+    }
+    /** Sends an external message; resolves with the node's hashes (hex). */
+    send(boc, tags) {
+        return this.#v2Post('/sendBocReturnHash', { boc }, tags, (result, route) => {
+            const r = need(record(result), route);
+            return {
+                hash: need(hashHex(r.hash), route),
+                hashNorm: need(hashHex(r.hash_norm), route),
+            };
+        });
+    }
+    /** The indexer's newest indexed masterchain block and the network's global id. */
+    indexerHead(tags) {
+        return this.#v3('/masterchainInfo', {}, tags, indexedHeadOf);
+    }
+    /**
+     * Whether the indexer has indexed masterchain block `seqno`. Under a quorum the key is
+     * this predicate: indexers past `seqno` agree whatever their heads.
+     */
+    indexerReached(seqno, tags) {
+        return this.#v3('/masterchainInfo', {}, tags, (body, route) => indexedHeadOf(body, route).seqno >= seqno);
+    }
+    /** The seqno of the masterchain block with this root hash (hex); null if unknown. */
+    masterchainSeqnoOf(rootHash, tags) {
+        const wanted = hashHex(rootHash);
+        return this.#v3('/blocks', { workchain: '-1', root_hash: rootHash, limit: '1' }, tags, (body, route) => {
+            if (!isRecord(body) || !Array.isArray(body.blocks) || body.blocks.length > 1) {
+                throw malformed(route);
+            }
+            for (const item of body.blocks) {
+                const block = need(record(item), route);
+                const workchain = need(int(block.workchain), route);
+                // A lookup by id keeps only the block asked for.
+                if (workchain === -1 && need(hashHex(block.root_hash), route) === wanted) {
+                    return need(int(block.seqno), route);
+                }
+            }
+            return null;
+        });
+    }
+    /**
+     * Committed transactions whose inbound message has this raw or normalized hash (hex).
+     * Only those; a dropped filter's strangers read as "none yet".
+     */
+    transactionsByMessage(hash, tags) {
+        const wanted = hashHex(hash);
+        return this.#v3('/transactionsByMessage', { msg_hash: hash, direction: 'in', limit: String(BY_MESSAGE_LIMIT) }, tags, (body, route) => transactionsOf(body, route, BY_MESSAGE_LIMIT).filter((tx) => wanted !== undefined &&
+            tx.inMsg !== null &&
+            (tx.inMsg.hash === wanted || tx.inMsg.hashNorm === wanted)), (txs) => txs.map(factsOf));
+    }
+    /** The committed transaction with this hash; null when the indexer has none (yet). */
+    transaction(hash, tags) {
+        const wanted = hashHex(hash);
+        return this.#v3('/transactions', { hash, limit: '1' }, tags, (body, route) => transactionsOf(body, route, 1).find((tx) => tx.hash === wanted) ?? null, (tx) => (tx ? factsOf(tx) : null));
+    }
+    /**
+     * One page of an account's transactions (a raw address), newest first, at or below
+     * `endLt` when given, with the next page's `endLt` when this one was full. An answer that
+     * breaks the query (another account, an lt out of order or above `endLt`, more than
+     * `limit`), counting the transactions not yet final, is malformed: a verdict reads it as
+     * the account's history. `next` comes from the page as served, so a page whose
+     * newest transactions are not yet final still leads to the older ones.
+     */
+    async accountTransactionsPage(account, options, tags) {
+        const wanted = rawAddress(account);
+        return this.#v3('/transactions', {
+            account,
+            limit: String(options.limit),
+            sort: 'desc',
+            ...(options.endLt !== undefined ? { end_lt: options.endLt.toString() } : {}),
+        }, tags, (body, route) => {
+            if (!isRecord(body) ||
+                !Array.isArray(body.transactions) ||
+                body.transactions.length > options.limit) {
+                throw malformed(route);
+            }
+            const transactions = [];
+            let below = options.endLt === undefined ? undefined : options.endLt + 1n;
+            let last;
+            for (const item of body.transactions) {
+                const t = need(record(item), route);
+                const lt = need(u64(t.lt), route);
+                if (rawOf(t.account) !== wanted || (below !== undefined && lt >= below)) {
+                    throw malformed(route);
+                }
+                below = lt;
+                last = lt;
+                if (committed(item))
+                    transactions.push(transactionOf(item, route));
+            }
+            const full = body.transactions.length === options.limit;
+            return {
+                transactions,
+                ...(full && last !== undefined && last > 0n ? { next: last - 1n } : {}),
+            };
+        }, (page) => ({
+            transactions: page.transactions.map(factsOf),
+            next: page.next ?? null,
+        }));
+    }
+    /** An account's committed transactions: one page (`accountTransactionsPage`). */
+    async accountTransactions(account, options, tags) {
+        return (await this.accountTransactionsPage(account, options, tags)).transactions;
+    }
+    /** The trace that holds this transaction; null when the indexer has none (yet). */
+    trace(txHash, tags) {
+        const wanted = hashHex(txHash);
+        return this.#v3('/traces', { tx_hash: txHash, include_actions: 'false', limit: '1' }, tags, (body, route) => {
+            if (!isRecord(body) || !Array.isArray(body.traces) || body.traces.length > 1) {
+                throw malformed(route);
+            }
+            for (const value of body.traces) {
+                const trace = traceOf(value, route);
+                // A lookup by id keeps only the trace asked for.
+                if (trace.transactions.some((tx) => tx.hash === wanted))
+                    return trace;
+            }
+            return null;
+        }, traceFacts);
+    }
+    /**
+     * The indexer's metadata for a raw token address: its first valid jetton entry
+     * (`tokenInfoOf`). Undefined while the indexer has none: no entry (an unknown address, a
+     * lagging index or a dropped filter all read alike), an entry not indexed yet, or no
+     * valid metadata fetched (yet), so a caller never takes it for a definitive answer.
+     */
+    async tokenInfo(address, tags) {
+        const wanted = rawAddress(address);
+        return this.#v3('/metadata', { address }, tags, (body, route) => {
+            if (!isRecord(body))
+                throw malformed(route);
+            for (const [key, value] of Object.entries(body)) {
+                // The answer is keyed by address; a lookup by id reads only its own entry.
+                if (rawOf(key) !== wanted)
+                    continue;
+                const entry = need(record(value), route);
+                if (optional(entry.is_indexed, bool, route) === false)
+                    return undefined;
+                const info = optional(entry.token_info, (v) => (Array.isArray(v) ? v : undefined), route) ?? [];
+                for (const item of info) {
+                    const token = need(record(item), route);
+                    const type = optional(token.type, str, route);
+                    if (token.valid === false ||
+                        (type !== undefined && type !== 'jetton_masters')) {
+                        continue;
+                    }
+                    return tokenInfoOf(token);
+                }
+            }
+            return undefined;
+        }, (info) => info ?? null);
+    }
+}
+exports.TonApi = TonApi;
+//# sourceMappingURL=api.js.map