crypto-aio 0.0.3 → 0.1.0

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

@@ -0,0 +1,344 @@
+import type { Transport } from '../../core/transport/types';
+import type { TonCallTags } from './types';
+export declare const READ: TonCallTags;
+export declare const MONITOR: TonCallTags;
+export declare const PROOF: TonCallTags;
+export declare const BROADCAST: TonCallTags;
+export declare const withSignal: (tags: TonCallTags, signal?: AbortSignal) => TonCallTags;
+/** The masterchain's one shard, as toncenter v2 writes it. */
+export declare const 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.
+ */
+export declare const MAX_BODY_CELLS: number;
+/**
+ * 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.
+ */
+export declare const MAX_BODY_BOC_LENGTH: number;
+/**
+ * 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.
+ */
+export declare const MAX_STATE_CELLS: number;
+/**
+ * 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.
+ */
+export declare const MAX_STATE_BOC_LENGTH: number;
+/**
+ * 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.
+ */
+export declare function bocWithinLimits(boc: string): boolean;
+/** A 32-byte hash given in base64 (toncenter's form) as lower-case hex. */
+export declare function hashHex(value: unknown): string | undefined;
+/** toncenter v3 writes raw addresses in upper case; the canonical form is lower case. */
+export declare function rawOf(value: unknown): string | null | undefined;
+export interface BlockId {
+    readonly workchain: number;
+    /** A signed 64-bit shard id in canonical decimal (the masterchain's: `MASTERCHAIN_SHARD`). */
+    readonly shard: string;
+    readonly seqno: number;
+    /** Lower-case hex. */
+    readonly rootHash: string;
+    readonly fileHash: string;
+}
+export interface BlockHeader {
+    readonly id: BlockId;
+    readonly globalId: number;
+    /** Seconds. */
+    readonly genUtime: number;
+    readonly prev: readonly BlockId[];
+}
+export type AccountStatus = 'active' | 'uninitialized' | 'frozen';
+export interface AccountState {
+    readonly balance: bigint;
+    readonly status: AccountStatus;
+    readonly lastLt: bigint;
+    /** Lower-case hex; all zeros for an account that never had a transaction. */
+    readonly lastHash: string;
+    /** The masterchain block the state was read at. */
+    readonly blockSeqno: number;
+    /** That block's full id: a proof binds the state to the block it asked for. */
+    readonly block: BlockId;
+    /** The state's time (seconds): the chain's `now` for the next message. */
+    readonly syncUtime: number;
+}
+export type StackEntry = {
+    readonly type: 'num';
+    readonly value: bigint;
+}
+/** A cell or slice (base64 BOC), within one message's limits. */
+ | {
+    readonly type: 'cell';
+    readonly boc: string;
+} | {
+    readonly type: 'other';
+};
+export interface RunResult {
+    readonly exitCode: number;
+    readonly stack: readonly StackEntry[];
+}
+/** A transaction's id: its logical time and hash (lower-case hex). */
+export interface TransactionId {
+    readonly lt: bigint;
+    readonly hash: string;
+}
+/**
+ * A get-method's result with what it was run on: the masterchain block and the
+ * account's last transaction there, as live toncenter answers name them.
+ */
+export interface BoundRunResult extends RunResult {
+    readonly block: BlockId;
+    readonly lastTransaction: TransactionId;
+}
+/**
+ * One transaction as the liteserver serves it (v2 `getTransactions`): its id and its raw
+ * cell (base64 BOC, within an account state's limits), which a caller hashes itself:
+ * only a cell whose hash is the id it expects authenticates anything.
+ */
+export interface RawTransaction {
+    readonly lt: bigint;
+    readonly hash: string;
+    readonly boc: string;
+}
+/** toncenter v3's account statuses (`orig_status`, `end_status`). */
+export type V3AccountStatus = 'nonexist' | 'uninit' | 'active' | 'frozen';
+export interface SourceFees {
+    readonly importFee: bigint;
+    readonly storageFee: bigint;
+    readonly gasFee: bigint;
+    readonly forwardFee: bigint;
+}
+export interface SentMessage {
+    readonly hash: string;
+    readonly hashNorm: string;
+}
+export interface V3Message {
+    readonly hash: string;
+    readonly hashNorm?: string;
+    readonly source: string | null;
+    readonly destination: string | null;
+    readonly value: bigint | null;
+    readonly bounce: boolean | null;
+    readonly bounced: boolean | null;
+    /** Body hash (hex) and body (base64 BOC), when the indexer has them. */
+    readonly bodyHash?: string;
+    readonly body?: string;
+}
+export interface V3Transaction {
+    readonly hash: string;
+    readonly lt: bigint;
+    readonly account: string;
+    readonly now: number;
+    readonly mcSeqno: number;
+    /** The trace's id (its root transaction's hash), lower-case hex. */
+    readonly traceId: string;
+    readonly totalFees: bigint;
+    readonly aborted: boolean;
+    /**
+     * The compute phase. A skipped one is `{ skipped: true, success: false }`, and so is the
+     * missing phase of a transaction type that has none (storage, split, merge).
+     */
+    readonly compute: {
+        readonly skipped: boolean;
+        readonly success: boolean;
+        readonly exitCode?: number;
+    };
+    readonly action?: {
+        readonly success: boolean;
+        readonly resultCode: number;
+        readonly skippedActions: number;
+        readonly msgsCreated: number;
+    };
+    /** The bounce phase's type (`ok`, `nofunds`, `negfunds`), when there was one. */
+    readonly bounce?: string;
+    /**
+     * The account's status before and after, when the indexer writes them: the proof reads
+     * a wallet's earlier incarnations from them.
+     */
+    readonly origStatus?: V3AccountStatus;
+    readonly endStatus?: V3AccountStatus;
+    readonly inMsg: V3Message | null;
+    readonly outMsgs: readonly V3Message[];
+}
+export interface V3Trace {
+    /** Lower-case hex. */
+    readonly traceId: string;
+    readonly complete: boolean;
+    readonly transactions: readonly V3Transaction[];
+}
+/** One page of an account's history, newest first. */
+export interface TransactionPage {
+    /** The page's committed transactions (not yet finalized ones are left out). */
+    readonly transactions: V3Transaction[];
+    /**
+     * The `endLt` of the next page, when the indexer's page was full. Counted on the
+     * page as the indexer served it, before the transactions not yet final were left out, so
+     * a pager never stops early and never skips an older final transaction.
+     */
+    readonly next?: bigint;
+}
+/** A jetton master's TEP-64 content cell, as `get_jetton_data` returns it (entry 3). */
+export type JettonContentCell = {
+    readonly kind: 'cell';
+    readonly boc: string;
+}
+/** Beyond one message's limits: never decoded. */
+ | {
+    readonly kind: 'oversized';
+};
+export interface JettonData {
+    readonly exitCode: number;
+    /** Absent when the get-method failed or its fourth entry is not a cell. */
+    readonly content?: JettonContentCell;
+}
+/**
+ * A token's metadata as the indexer fetched it (for a jetton: its off-chain JSON). `null`
+ * marks a field the token's metadata holds but that is not one (ill-typed, out of range or
+ * over its limit): the token's own data, which every endpoint agrees on, for the caller to
+ * judge only if it uses that field.
+ */
+export interface TokenInfo {
+    readonly symbol?: string | null;
+    /** 0..255, in decimal. */
+    readonly decimals?: string | null;
+    readonly name?: string;
+}
+/** Whether two block ids name the same block: workchain, shard, seqno and both hashes. */
+export declare const sameBlock: (a: BlockId, b: BlockId) => boolean;
+export declare function transactionOf(value: unknown, route: string): V3Transaction;
+/** The newest masterchain block's seqno in a v2 `getMasterchainInfo` answer body. */
+export declare function masterchainInfoSeqno(body: unknown, route: string): number;
+/**
+ * A v3 `masterchainInfo` answer body: the indexed head's seqno (`masterchainSeqnoOf`) and the
+ * network's global id, an int32.
+ */
+export declare function indexedHeadOf(body: unknown, route: string): {
+    readonly seqno: number;
+    readonly globalId: number;
+};
+/** A config param's cell (base64 BOC, within one message's limits) in a v2 answer body. */
+export declare function configParamBoc(body: unknown, route: string): string;
+/** A v2 `runGetMethod` answer body, parsed; for callers' quorum predicates. */
+export declare function runResultOf(body: unknown): RunResult;
+/** A v2 `runGetMethod` answer body with its binding, parsed; for callers' quorum keys. */
+export declare function boundRunResultOf(body: unknown): BoundRunResult;
+/** A v2 `get_jetton_data` answer body, parsed; for callers' quorum keys. */
+export declare function jettonDataOf(body: unknown): JettonData;
+export declare class TonApi {
+    #private;
+    private readonly rpc;
+    private readonly indexer;
+    constructor(rpc: Transport, indexer: Transport);
+    /** The rpc transport's lag tolerance, as the pool resolved it; proofs' last skew. */
+    get lagTolerance(): number;
+    /** The newest masterchain block the liteserver knows. */
+    masterchainHead(tags: TonCallTags): Promise<number>;
+    /**
+     * 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: number, tags: TonCallTags): Promise<boolean>;
+    /** A block's header; `seqno` above the endpoint's head fails (retryable). */
+    blockHeader(block: {
+        readonly workchain: number;
+        readonly shard: string;
+        readonly seqno: number;
+    }, tags: TonCallTags): Promise<BlockHeader>;
+    masterchainHeader(seqno: number, tags: TonCallTags): Promise<BlockHeader>;
+    /** The shard blocks masterchain block `seqno` commits. */
+    shards(seqno: number, tags: TonCallTags): Promise<BlockId[]>;
+    /** A config param's cell (base64 BOC, within one message's limits). */
+    configParam(param: number, tags: TonCallTags, seqno?: number): Promise<string>;
+    /** An account's state, at masterchain block `seqno` when given. */
+    account(address: string, tags: TonCallTags, seqno?: number): Promise<AccountState>;
+    /** A get-method, at masterchain block `seqno` when given. */
+    runGetMethod(address: string, method: string, stack: readonly (readonly [string, string])[], tags: TonCallTags, seqno?: number): Promise<RunResult>;
+    /**
+     * 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: string, method: string, stack: readonly (readonly [string, string])[], tags: TonCallTags, seqno: number): Promise<BoundRunResult>;
+    /**
+     * 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.
+     */
+    rawTransactions(address: string, from: TransactionId, limit: number, tags: TonCallTags): Promise<RawTransaction[]>;
+    /** A jetton master's `get_jetton_data`: its exit code and content cell (`jettonDataOf`). */
+    jettonData(master: string, tags: TonCallTags, seqno?: number): Promise<JettonData>;
+    /** The emulated source fees of an external message body (signature check skipped). */
+    estimateFee(request: {
+        readonly address: string;
+        readonly body: string;
+        readonly initCode?: string;
+        readonly initData?: string;
+    }, tags: TonCallTags): Promise<SourceFees>;
+    /** Sends an external message; resolves with the node's hashes (hex). */
+    send(boc: string, tags: TonCallTags): Promise<SentMessage>;
+    /** The indexer's newest indexed masterchain block and the network's global id. */
+    indexerHead(tags: TonCallTags): Promise<{
+        readonly seqno: number;
+        readonly globalId: number;
+    }>;
+    /**
+     * 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: number, tags: TonCallTags): Promise<boolean>;
+    /** The seqno of the masterchain block with this root hash (hex); null if unknown. */
+    masterchainSeqnoOf(rootHash: string, tags: TonCallTags): Promise<number | 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: string, tags: TonCallTags): Promise<V3Transaction[]>;
+    /** The committed transaction with this hash; null when the indexer has none (yet). */
+    transaction(hash: string, tags: TonCallTags): Promise<V3Transaction | 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.
+     */
+    accountTransactionsPage(account: string, options: {
+        readonly limit: number;
+        readonly endLt?: bigint;
+    }, tags: TonCallTags): Promise<TransactionPage>;
+    /** An account's committed transactions: one page (`accountTransactionsPage`). */
+    accountTransactions(account: string, options: {
+        readonly limit: number;
+        readonly endLt?: bigint;
+    }, tags: TonCallTags): Promise<V3Transaction[]>;
+    /** The trace that holds this transaction; null when the indexer has none (yet). */
+    trace(txHash: string, tags: TonCallTags): Promise<V3Trace | null>;
+    /**
+     * 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.
+     */
+    tokenInfo(address: string, tags: TonCallTags): Promise<TokenInfo | undefined>;
+}