@anywalletkit/wallet-ton 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,704 @@
+import { Cell, StateInit, TupleReader, Address, TupleItem, Transaction, MessageRelaxed } from '@ton/core';
+import { SignerError, IWalletAccountReadOnly, IWalletAccount, Signer, TransferResult, WalletManager, FeeRates } from '@anywalletkit/core';
+export { HistoryFetch, HistoryUnavailableError, TonChainTx, TonHistoryBackend, TonHistoryCursor, TonHistoryOptions, TonHistoryPage, TonHistoryRaw, TonHistorySource, TonapiAction, TonapiEvent, V3Transaction, createTonHistory, decodeCursor as decodeHistoryCursor, encodeCursor as encodeHistoryCursor, mapActions as mapTonapiActions, mapTonapiEvent, mapToncenterTransaction, rawTonAddress, tonExplorerTxUrl, valueFlowTransfers } from './history.js';
+
+/**
+ * Set `globalThis.Buffer` to the `buffer` polyfill when the runtime has none (Hermes, browsers).
+ * Runs on import.
+ */
+declare function installBufferGlobal(): void;
+
+/** A toncenter v2 JSON-RPC endpoint (api keys there are meant for client-side wallets). */
+interface TonEndpoint {
+    url: string;
+    secretKey?: string;
+}
+/** Anything that can answer a toncenter v2 JSON-RPC call (an endpoint wrapper, a test double, a proxy). */
+interface TonRpc {
+    call<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+}
+/** A toncenter endpoint (URL and optional key) or a ready `TonRpc`. */
+type TonProvider = TonEndpoint | TonRpc;
+/**
+ * Options for a TON wallet manager or account: toncenter endpoints, network, fee caps and emulation
+ * before signing.
+ */
+interface TonConfig {
+    /** toncenter endpoint(s) or `TonRpc`(s). A list fails over in order. Omit for an offline (sign-only) wallet. */
+    tonClient?: TonProvider | TonProvider[];
+    /** Alias of `tonClient`. */
+    provider?: TonProvider | TonProvider[];
+    /** Extra rounds across the endpoint list after the first full pass (default 3). */
+    retries?: number;
+    /** Per-request timeout in ms (default 15 000). */
+    timeoutMs?: number;
+    /** Injectable fetch (tests, custom agents). Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Max fee (nanotons) for `transfer`. */
+    transferMaxFee?: bigint | number;
+    /** Max fee (nanotons) for `sendTransaction` / `signTransaction`. */
+    transactionMaxFee?: bigint | number;
+    /** toncenter v3 base used for receipts (default https://toncenter.com/api/v3). */
+    indexerUrl?: string;
+    /** tonapi base used for fee rates and (by default) emulation (default https://tonapi.io/v2). */
+    tonApiUrl?: string;
+    /** tonapi bearer key (sent as `Authorization: Bearer …`); also sent as X-API-Key to a toncenter-v3 emulator. */
+    tonApiKey?: string;
+    /**
+     * Preflight emulation of every send (zero-signed external). Default
+     * `{kind: 'tonapi'}`: `POST {tonApiUrl}/wallet/emulate` (verdict + `risk`),
+     * falling back to `/traces/emulate`. `{kind: 'toncenter-v3', url}` posts to a
+     * toncenter `emulateTrace` endpoint instead. `false` = `estimateFee` only.
+     * A non-zero compute exit, an aborted transaction, a failed action phase or a
+     * failed FIRST-HOP internal message throws `SimulationError` before signing.
+     */
+    emulate?: TonEmulateConfig;
+    /** @deprecated Use `emulate: {kind: 'toncenter-v3', url}`. Still honoured when `emulate` is unset. */
+    emulateUrl?: string;
+    /**
+     * Allow a body whose emulated `risk.transfer_all_remaining_balance` is true
+     * (send mode 128 / CARRY_ALL_BALANCE). Refused by default — nothing this
+     * wallet builds does that, so it only ever comes from a foreign `bodyBoc`.
+     */
+    allowDrainingTransactions?: boolean;
+    /** Run the preflight (estimateFee + emulation when configured) before signing. Default true. */
+    simulate?: boolean;
+    /** Seconds a signed external stays valid (default 60, max 600). */
+    validUntilSeconds?: number;
+    /** Nanotons attached to a jetton transfer on top of `forwardTonAmount` (default 0.05 TON). */
+    jettonAttachedValue?: bigint | number | string;
+    /**
+     * 'mainnet' (ton:-239, default) or 'testnet' (ton:-3). Sets the CAIP-2 id, the address flags and the
+     * wallet_id network (-239 / -3), so a testnet wallet has its own address and its signed messages are
+     * not valid on mainnet (as in Tonkeeper and @ton/ton).
+     */
+    network?: 'mainnet' | 'testnet';
+    /**
+     * V5R1 wallet_id parts. Defaults (network id from `network`, subwallet 0) give the
+     * addresses Tonkeeper and Tonhub derive for a key; change the subwallet only to
+     * reach a wallet that was created with a different one. A networkGlobalId that
+     * contradicts `network` is refused.
+     */
+    walletId?: {
+        networkGlobalId?: number;
+        subwalletNumber?: number;
+    };
+}
+/** One internal message. `value` in nanotons. `body`: text comment or a Cell; `bodyBoc`: the same as base64 BoC. */
+interface TonTransaction {
+    to: string;
+    value: bigint | number | string;
+    /** Defaults to the flag in a friendly address (EQ… bounceable, UQ… not); raw addresses default to bounceable. */
+    bounceable?: boolean;
+    body?: string | Cell;
+    /** Prebuilt message body as base64 BoC (e.g. an Omniston escrow payload). Ignored when `body` is set. */
+    bodyBoc?: string;
+    /** StateInit to attach (deploys the destination): `{code, data}`, a StateInit cell, or its base64 BoC. */
+    stateInit?: StateInit | Cell | string;
+    /** Send mode for this message (default PAY_GAS_SEPARATELY; IGNORE_ERRORS is always OR-ed in for externals). */
+    sendMode?: number;
+}
+/**
+ * What `sendTransaction` / `signTransaction` accept: one message, several
+ * messages in ONE external (up to 255 — swaps need it), or an already signed
+ * V5R1 external-message body Cell.
+ */
+type TonSendable = TonTransaction | TonTransaction[] | Cell;
+/** A native TON or jetton transfer. Amount in nanotons or the jetton's base units. */
+interface TonTransferOptions {
+    /** Jetton master address. Omit for native TON. */
+    token?: string;
+    /** Wallet address that receives (for a jetton, its owner, not its jetton wallet). */
+    recipient: string;
+    amount: bigint | number | string;
+    /** Jetton only: nanotons forwarded to the recipient with the transfer notification (default 1). */
+    forwardTonAmount?: bigint | number | string;
+    /** Jetton only: forward payload — a text comment or a Cell (DEX / escrow payloads). */
+    forwardPayload?: Cell | string;
+    /**
+     * Text memo (a deposit memo, an exchange tag). Jetton: sent as the forward-payload comment (TEP-74);
+     * native TON: the message comment. Cannot be combined with `forwardPayload`.
+     */
+    memo?: string;
+    /** Jetton only: custom payload cell (rarely needed; e.g. mintless jettons). */
+    customPayload?: Cell;
+    /** Jetton only: where excess TON returns (default: this wallet). */
+    responseDestination?: string;
+    /** Jetton only: query id (default random). */
+    queryId?: bigint | number;
+    /** Jetton only: nanotons attached to the jetton-wallet call (default config.jettonAttachedValue + forwardTonAmount). */
+    attachedValue?: bigint | number | string;
+}
+/** toncenter `estimateFee` source fees, nanotons. */
+interface TonFees {
+    inFwdFee: bigint;
+    storageFee: bigint;
+    gasFee: bigint;
+    fwdFee: bigint;
+    /** Sum of the four. */
+    total: bigint;
+}
+/**
+ * Where to emulate a transaction before signing: tonapi, a toncenter v3 endpoint, or `false` for a
+ * fee estimate only.
+ */
+type TonEmulateConfig = {
+    kind: 'tonapi';
+    url?: string;
+} | {
+    kind: 'toncenter-v3';
+    url: string;
+} | false;
+/** What a message would move out of the wallet, per tonapi's `risk`. */
+interface TonRisk {
+    /** Nanotons leaving the wallet (value + fees the emulator attributes). */
+    ton: bigint;
+    jettons: Array<{
+        address: string;
+        walletAddress: string;
+        amount: bigint;
+        symbol?: string;
+        decimals?: number;
+    }>;
+    /** Send mode 128: the whole remaining balance goes with the message. */
+    transferAllRemainingBalance: boolean;
+}
+/**
+ * Which service produced a simulation; `estimate-only` means fees were estimated without emulation.
+ */
+type TonSimulationSource = 'tonapi' | 'toncenter-v3' | 'estimate-only';
+/**
+ * Outcome of a simulation: the fees and, when emulated, whether the wallet transaction and its
+ * actions succeeded.
+ */
+type TonSimulation = {
+    ok: true;
+    fees: TonFees;
+    emulated: boolean;
+    source: TonSimulationSource;
+    exitCode?: number;
+    actionSuccess?: boolean;
+    risk?: TonRisk;
+    warnings: string[];
+} | {
+    ok: false;
+    fees?: TonFees;
+    emulated: true;
+    source: Exclude<TonSimulationSource, 'estimate-only'>;
+    reason: string;
+    exitCode?: number;
+    aborted?: boolean;
+    risk?: TonRisk;
+    warnings: string[];
+};
+/** Outcome of a sent wallet transaction, found by the body hash `sendTransaction` returned. */
+interface TonReceipt {
+    /** The body hash that was returned by sendTransaction. */
+    hash: string;
+    /** 1 when the wallet transaction completed without abort, 0 otherwise. */
+    status: 0 | 1;
+    /** Logical time of the account transaction. */
+    blockNumber: bigint;
+    /** Account transaction hash (base64). */
+    transactionHash: string;
+    /** Fees of the account transaction, in nanotons. */
+    totalFees: bigint;
+    /** The raw @ton/core Transaction. */
+    raw: unknown;
+}
+/** CAIP-2 ids of TON mainnet and testnet. */
+declare const CAIP2: Record<'mainnet' | 'testnet', string>;
+
+/**
+ * Refused before signing: the message would almost certainly misbehave or
+ * strand funds (zero value, wrong network flag, exotic workchain, a
+ * `valid_until` further away than the wallet contract tolerates…).
+ */
+declare class UnsafeTransactionError extends SignerError {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Emulation of the external message failed (non-zero compute exit, aborted, action phase failed); nothing was signed or sent. */
+declare class SimulationError extends Error {
+    readonly exitCode: number | undefined;
+    readonly aborted: boolean;
+    constructor(reason: string, details?: {
+        exitCode?: number;
+        aborted?: boolean;
+    });
+}
+
+/** JSON-RPC over one toncenter v2 endpoint. */
+declare function tonCenterEndpoint(endpoint: TonEndpoint, opts?: {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): TonRpc;
+/** One RPC, or a failover RPC walking the configured list (`retries` extra rounds after the first full pass). */
+declare function createTonRpc(config: TonConfig): TonRpc | undefined;
+/** State of a TON account on chain. */
+type TonAccountStatus = 'active' | 'uninitialized' | 'frozen' | 'nonexist';
+/** Balance, status, code and data of an account. */
+interface TonAccountState {
+    balance: bigint;
+    state: TonAccountStatus;
+    code: Cell | null;
+    data: Cell | null;
+    lastTransaction: {
+        lt: string;
+        hash: string;
+    } | null;
+}
+/** Result of a contract get-method call. */
+interface GetMethodResult {
+    exitCode: number;
+    gasUsed: number;
+    stack: TupleReader;
+}
+/** The toncenter calls a wallet uses, with parsed results. */
+declare class TonCenter {
+    readonly rpc: TonRpc;
+    constructor(rpc: TonRpc);
+    /** Balance, status, code and data of an account. */
+    getAddressInformation(address: Address): Promise<TonAccountState>;
+    /** Call a contract get-method; the result carries the exit code. */
+    runGetMethod(address: Address, method: string, stack?: TupleItem[]): Promise<GetMethodResult>;
+    /** Like runGetMethod but throws on a non-zero exit code. */
+    runGetMethodOk(address: Address, method: string, stack?: TupleItem[]): Promise<GetMethodResult>;
+    /** Broadcast a signed external message. */
+    sendBoc(message: Cell): Promise<void>;
+    /** Broadcast and return the external-message hash (base64) toncenter reports. */
+    sendBocReturnHash(message: Cell): Promise<string>;
+    getTransactions(address: Address, opts: {
+        limit: number;
+        lt?: string;
+        hash?: string;
+        archival?: boolean;
+    }): Promise<Transaction[]>;
+    estimateFee(address: Address, args: {
+        body: Cell;
+        init?: StateInit;
+        ignoreSignature?: boolean;
+    }): Promise<TonFees>;
+}
+/**
+ * Whether an emulated wallet transaction succeeded: compute exit code, abort flag, action phase.
+ */
+interface EmulationVerdict {
+    ok: boolean;
+    exitCode?: number;
+    aborted?: boolean;
+    actionSuccess?: boolean;
+    reason?: string;
+}
+/**
+ * Reduce an `emulateTrace` response to a verdict for the ROOT transaction (the
+ * wallet's own): compute-phase exit code, aborted flag, action-phase success.
+ * Tolerant of the field spellings the v3 API has used (`description.compute_ph`
+ * / `compute`, `action.success`); anything unrecognisable is a NetworkError, not
+ * a silent pass.
+ */
+declare function parseEmulation(json: unknown): EmulationVerdict;
+/** POST the external message to a toncenter v3 emulation endpoint and reduce the trace. */
+declare function emulateExternal(url: string, message: Cell, opts?: {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    apiKey?: string;
+}): Promise<EmulationVerdict>;
+
+/**
+ * Preflight emulation of a zero-signed external through tonapi
+ * (`POST /v2/wallet/emulate`, fallback `POST /v2/traces/emulate`) or a
+ * toncenter v3 `emulateTrace` endpoint. The verdict decides whether the
+ * account signs at all; `risk` (tonapi only) summarises what would leave the
+ * wallet so a foreign body cannot quietly drain it.
+ *
+ * tonapi shapes used (OpenAPI v2):
+ *   MessageConsequences = { trace: Trace, event: AccountEvent, risk: Risk }
+ *   Trace   = { transaction: Transaction, interfaces: string[], children?: Trace[], emulated?: boolean }
+ *   Transaction.compute_phase = { skipped, skip_reason?, success?, exit_code?, exit_code_description? }
+ *   Transaction.action_phase  = { success, result_code, … }
+ *   Transaction.{ success, aborted, bounce_phase? }
+ *   Risk = { transfer_all_remaining_balance, ton, jettons: [{ quantity, wallet_address: { address }, jetton: { address, symbol, decimals } }], nfts }
+ */
+
+/** Default tonapi root used for emulation. */
+declare const DEFAULT_TONAPI = "https://tonapi.io/v2";
+/** Service an emulation came from. */
+type EmulationSource = 'tonapi' | 'toncenter-v3';
+/** An emulation verdict with its source and any deeper failures. */
+interface EmulationOutcome extends EmulationVerdict {
+    source: EmulationSource;
+    /** Failed/bounced transactions deeper than the first hop — informational. */
+    warnings: string[];
+    /** tonapi `risk`: what the message would move out of the wallet. */
+    risk?: TonRisk;
+}
+/**
+ * Reduce a tonapi `Trace` to a verdict. The root (the wallet's own transaction)
+ * decides: compute exit ≠ 0, aborted or a failed action phase → not ok. A
+ * failing FIRST-HOP child is also fatal: for every message this wallet builds
+ * (TON to a contract, jetton transfer to its own jetton wallet) a bounced
+ * first hop means the operation did not happen and the value comes back minus
+ * fees. Deeper failures (e.g. a jetton notify the recipient's wallet rejects)
+ * become warnings — the transfer itself already settled.
+ */
+declare function parseTonapiTrace(trace: unknown): Omit<EmulationOutcome, 'source' | 'risk'>;
+/** tonapi `Risk` → nanotons / jetton base units as bigints. Malformed → NetworkError. */
+declare function parseTonapiRisk(risk: unknown): TonRisk;
+/** tonapi `MessageConsequences` (wallet/emulate) → outcome with risk. */
+declare function parseTonapiConsequences(json: unknown): EmulationOutcome;
+/** Options for emulating a message through tonapi or toncenter v3. */
+interface EmulateOptions {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    /** tonapi bearer key / toncenter X-API-Key. */
+    apiKey?: string;
+}
+/**
+ * Emulate through tonapi: `/wallet/emulate` first (verdict + risk), then
+ * `/traces/emulate` when the first is not served (404). The external carries a
+ * zero signature; `ignore_signature_check=true` is sent on both calls.
+ */
+declare function emulateViaTonapi(baseUrl: string, message: Cell, opts?: EmulateOptions): Promise<EmulationOutcome>;
+/** Resolve the effective emulation config: explicit `emulate`, legacy `emulateUrl`, else tonapi by default. */
+declare function resolveEmulate(config: {
+    emulate?: TonEmulateConfig;
+    emulateUrl?: string;
+    tonApiUrl?: string;
+}): Exclude<TonEmulateConfig, false> | false;
+/** Run the configured emulation for an external message. */
+declare function runEmulation(config: {
+    emulate?: TonEmulateConfig;
+    emulateUrl?: string;
+    tonApiUrl?: string;
+    tonApiKey?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}, message: Cell): Promise<EmulationOutcome | undefined>;
+
+/** Code of the Wallet V5R1 contract (BoC hex). */
+declare const V5R1_CODE_HEX = "b5ee9c7241021401000281000114ff00f4a413f4bcf2c80b01020120020d020148030402dcd020d749c120915b8f6320d70b1f2082106578746ebd21821073696e74bdb0925f03e082106578746eba8eb48020d72101d074d721fa4030fa44f828fa443058bd915be0ed44d0810141d721f4058307f40e6fa1319130e18040d721707fdb3ce03120d749810280b99130e070e2100f020120050c020120060902016e07080019adce76a2684020eb90eb85ffc00019af1df6a2684010eb90eb858fc00201480a0b0017b325fb51341c75c875c2c7e00011b262fb513435c280200019be5f0f6a2684080a0eb90fa02c0102f20e011e20d70b1f82107369676ebaf2e08a7f0f01e68ef0eda2edfb218308d722028308d723208020d721d31fd31fd31fed44d0d200d31f20d31fd3ffd70a000af90140ccf9109a28945f0adb31e1f2c087df02b35007b0f2d0845125baf2e0855036baf2e086f823bbf2d0882292f800de01a47fc8ca00cb1f01cf16c9ed542092f80fde70db3cd81003f6eda2edfb02f404216e926c218e4c0221d73930709421c700b38e2d01d72820761e436c20d749c008f2e09320d74ac002f2e09320d71d06c712c2005230b0f2d089d74cd7393001a4e86c128407bbf2e093d74ac000f2e093ed55e2d20001c000915be0ebd72c08142091709601d72c081c12e25210b1e30f20d74a111213009601fa4001fa44f828fa443058baf2e091ed44d0810141d718f405049d7fc8ca0040048307f453f2e08b8e14038307f45bf2e08c22d70a00216e01b3b0f2d090e2c85003cf1612f400c9ed54007230d72c08248e2d21f2e092d200ed44d0d2005113baf2d08f54503091319c01810140d721d70a00f2e08ee2c8ca0058cf16c9ed5493f2c08de20010935bdb31e1d74cd0b4d6c35e";
+/** The V5R1 contract code cell (parsed once). */
+declare function v5r1Code(): Cell;
+/** Op codes of Wallet V5R1 messages. */
+declare const V5R1_OP: {
+    readonly signedExternal: 1936287598;
+    readonly signedInternal: 1936289396;
+    readonly extension: 1702392942;
+};
+/** Global id of TON mainnet, part of the V5R1 wallet id. */
+declare const MAINNET_GLOBAL_ID = -239;
+/** Global id of TON testnet. */
+declare const TESTNET_GLOBAL_ID = -3;
+/** PAY_GAS_SEPARATELY | IGNORE_ERRORS — the mode every external-message action carries. */
+declare const DEFAULT_SEND_MODE: number;
+/** Most outgoing messages one V5R1 transaction can carry. */
+declare const MAX_ACTIONS = 255;
+interface V5R1WalletIdParts {
+    networkGlobalId?: number;
+    workchain?: number;
+    subwalletNumber?: number;
+}
+/**
+ * Serialized wallet_id (int32): `networkGlobalId XOR context`, where the client
+ * context is {1 bit "client", int8 workchain, uint8 version (0 = v5r1), uint15 subwallet}.
+ */
+declare function v5r1WalletId(parts?: V5R1WalletIdParts): bigint;
+/** State init (code and data) of a V5R1 wallet for a public key. */
+declare function v5r1StateInit(publicKey: Uint8Array, walletId?: bigint): StateInit;
+/** Address of the V5R1 wallet for a public key. */
+declare function v5r1Address(publicKey: Uint8Array, opts?: {
+    workchain?: number;
+    walletId?: bigint;
+}): Address;
+interface V5R1Message {
+    message: MessageRelaxed;
+    mode?: number;
+}
+interface V5R1SigningParams {
+    walletId: bigint;
+    /** Unix seconds. */
+    validUntil: number;
+    seqno: number;
+    messages: V5R1Message[];
+}
+/** The cell that gets hashed and signed: op | wallet_id | valid_until | seqno | out-list ref | no extended actions. */
+declare function v5r1SigningMessage(p: V5R1SigningParams): Cell;
+/** Signature goes at the tail (V5R1 layout). */
+declare function v5r1PackSigned(signing: Cell, signature: Uint8Array): Cell;
+/** Same body with a zero signature — what `estimateFee(ignore_chksig)` and emulation take. */
+declare function v5r1PackUnsigned(signing: Cell): Cell;
+/** The external-in message (as a cell, ready for sendBoc) carrying `body` to the wallet, with `init` when it is not deployed yet. */
+declare function v5r1ExternalMessage(to: Address, body: Cell, init?: StateInit): Cell;
+interface ParsedV5R1Body {
+    op: number;
+    walletId: bigint;
+    validUntil: number;
+    seqno: number;
+    messages: Array<{
+        message: MessageRelaxed;
+        mode: number;
+    }>;
+    /** True when the 64-byte tail signature is present (externals and internals carry one). */
+    signed: boolean;
+}
+/** Parse a signed (or zero-signed) V5R1 external body back into its messages. Returns null for anything else. */
+declare function parseV5R1Body(body: Cell): ParsedV5R1Body | null;
+
+/**
+ * "What am I signing" for TON — offline. Decodes the messages of a
+ * {@link TonSendable} (or a prebuilt V5R1 body) into human-checkable items and
+ * flags the classic mistakes before any key is touched.
+ */
+
+/** TEP-74 `transfer` op code of a jetton wallet. */
+declare const JETTON_TRANSFER_OP = 260734629;
+/** What one outgoing message does. */
+type TonDescribedKind = 'ton-transfer' | 'jetton-transfer' | 'contract-call';
+/** Fields of a TEP-74 jetton `transfer` body. */
+interface TonJettonDetails {
+    queryId: bigint;
+    amount: bigint;
+    destination: string;
+    responseDestination: string | null;
+    forwardTonAmount: bigint;
+    forwardPayload: 'none' | 'comment' | 'cell';
+    forwardComment?: string;
+    hasCustomPayload: boolean;
+}
+/** One outgoing message of a wallet transaction, decoded. */
+interface TonDescribedMessage {
+    kind: TonDescribedKind;
+    /** Destination as given (friendly) or raw `wc:hex`. */
+    to: string;
+    value: bigint;
+    bounceable: boolean;
+    /** Test-only flag of a friendly address; undefined for raw addresses. */
+    testOnly?: boolean;
+    /** Text comment (op 0). */
+    comment?: string;
+    /** Body op code for contract calls (hex). */
+    op?: string;
+    jetton?: TonJettonDetails;
+    hasStateInit: boolean;
+    bodyBits: number;
+}
+/** Problems a TON description is flagged with. */
+type TonWarningCode = 'zero-value' | 'non-bounceable-contract-call' | 'unknown-body' | 'large-forward-amount' | 'testnet-address' | 'mainnet-address' | 'exotic-workchain' | 'extended-actions';
+/** One flagged problem; `index` is the message it is about. */
+interface TonWarning {
+    code: TonWarningCode;
+    message: string;
+    index?: number;
+}
+/**
+ * A TON wallet transaction decoded for a confirmation screen: each outgoing message and the
+ * warnings.
+ */
+interface TonDescription {
+    kind: TonDescribedKind | 'mixed';
+    items: TonDescribedMessage[];
+    warnings: TonWarning[];
+    /** Present when the input was a prebuilt V5R1 body. */
+    external?: {
+        seqno: number;
+        validUntil: number;
+        walletId: bigint;
+        signed: boolean;
+    };
+}
+/** A message body decoded: empty, a text comment, a jetton transfer, or unknown. */
+type DecodedBody = {
+    type: 'empty';
+} | {
+    type: 'comment';
+    text: string;
+} | {
+    type: 'jetton-transfer';
+    jetton: TonJettonDetails;
+} | {
+    type: 'op';
+    op: number;
+} | {
+    type: 'unknown';
+};
+/** Decode a message body cell. */
+declare function decodeBody(body: Cell): DecodedBody;
+/** A text comment body (op 0 plus the text), as wallets show it. */
+declare function commentCell(text: string): Cell;
+/** Describe one outgoing message and push its warnings into `warnings`. */
+declare function describeMessageRelaxed(i: number, m: MessageRelaxed, warnings: TonWarning[], ctx?: {
+    network?: 'mainnet' | 'testnet';
+}): TonDescribedMessage;
+/** Describe what a {@link TonSendable} will do. Offline; never throws on malformed bodies (they become warnings). */
+declare function describeTransaction(tx: TonSendable, ctx?: {
+    network?: 'mainnet' | 'testnet';
+}): TonDescription;
+
+/** PAY_GAS_SEPARATELY | IGNORE_ERRORS, the mode every action in an external carries. */
+declare const SEND_MODE: number;
+/**
+ * A TON V5R1 wallet without a key: balance, jetton balances, seqno, fee estimates, emulation,
+ * receipts and signature checks.
+ */
+declare class WalletAccountReadOnlyTon implements IWalletAccountReadOnly {
+    readonly chain: string;
+    /** Ed25519 public key the wallet is derived from. */
+    readonly publicKey: Uint8Array;
+    /** User-friendly address. */
+    readonly address: string;
+    protected readonly _config: TonConfig;
+    protected readonly _walletId: bigint;
+    protected readonly _init: StateInit;
+    protected readonly _address: Address;
+    protected readonly _rpc: TonCenter | undefined;
+    constructor(publicKey: Uint8Array | string, config?: TonConfig);
+    protected requireRpc(what: string): TonCenter;
+    /** The user-friendly address. */
+    getAddress(): Promise<string>;
+    /** Native balance in nanotons. */
+    getBalance(): Promise<bigint>;
+    /** Current seqno — 0 until the wallet contract is deployed. Always fetched fresh. */
+    getSeqno(): Promise<number>;
+    /** Resolve this wallet's jetton wallet for a jetton master. */
+    getJettonWalletAddress(token: string): Promise<Address>;
+    /**
+     * Read a jetton wallet and prove it is ours for `token`: `get_wallet_data`
+     * must name this wallet as owner and `token` as master. The master's own
+     * `get_wallet_address` answer is not trusted on its own — a fake master could
+     * point at our real wallet of another jetton (e.g. USDT).
+     */
+    protected jettonWalletData(token: string, jw: Address): Promise<bigint>;
+    /**
+     * Jetton balance in base units, read from this wallet's jetton wallet; 0 when it does not exist.
+     */
+    getTokenBalance(token: string): Promise<bigint>;
+    protected stateInitOf(src: TonTransaction['stateInit']): StateInit | undefined;
+    protected transactionMessage(tx: TonTransaction): V5R1Message;
+    protected jettonTransferMessage(o: TonTransferOptions): Promise<V5R1Message>;
+    protected toMessages(tx: TonTransaction | TonTransaction[]): V5R1Message[];
+    protected validUntil(): number;
+    /** The cell to sign for `messages` at the CURRENT seqno (fetched fresh every time). */
+    protected signingCell(messages: V5R1Message[]): Promise<{
+        signing: Cell;
+        seqno: number;
+        validUntil: number;
+    }>;
+    /** StateInit to attach to an external when the wallet is not deployed yet. */
+    protected initIfNeeded(): Promise<StateInit | undefined>;
+    /** in_fwd + storage + gas + fwd from toncenter's estimateFee (signature ignored). */
+    estimateFees(body: Cell): Promise<TonFees>;
+    /**
+     * Preflight an external body: fees via estimateFee and, unless
+     * `config.emulate === false`, a trace emulation (tonapi by default, see
+     * {@link TonConfig.emulate}) whose compute/action phases — and the first-hop
+     * internal messages — decide `ok`. Never throws for a failing emulation,
+     * only for transport problems or a malformed emulator response.
+     */
+    simulateBody(body: Cell): Promise<TonSimulation>;
+    /** Preflight a {@link TonSendable} (unsigned body, current seqno). */
+    simulateTransaction(tx: TonSendable): Promise<TonSimulation>;
+    /** Estimated fee of a transaction, in nanotons. */
+    quoteSendTransaction(tx: TonSendable): Promise<{
+        fee: bigint;
+    }>;
+    /** Estimated fee of a transfer, in nanotons. */
+    quoteTransfer(o: TonTransferOptions): Promise<{
+        fee: bigint;
+    }>;
+    /** Offline description of what `tx` does — see {@link describeTransaction}. */
+    describe(tx: TonSendable): TonDescription;
+    /**
+     * Receipt for a body hash returned by sendTransaction: toncenter v3 maps the
+     * message body hash to the account transaction, which is then fetched.
+     */
+    getTransactionReceipt(hash: string): Promise<TonReceipt | undefined>;
+    /** ed25519 over the raw message bytes; `signature` hex. */
+    verify(message: string | Uint8Array, signature: string): Promise<boolean>;
+}
+
+/**
+ * Signing TON account on Wallet V5R1. It never holds a key: the V5R1 body is
+ * signed by `signer.sign(signingCell.hash(), {scheme: 'ed25519', context:
+ * 'ton-external'})` — a {@link LocalSigner} for seed wallets, anything else
+ * (hardware, MPC, backend) through `externalSigner()`.
+ *
+ * Every send runs: hard checks → fresh seqno → preflight on the zero-signed
+ * body (estimateFee, emulation when configured, fee cap) → sign → broadcast.
+ * The preflight body carries a zero signature, so the signer is only asked
+ * once the transaction has passed.
+ */
+declare class WalletAccountTon extends WalletAccountReadOnlyTon implements IWalletAccount {
+    /** seqno and fees come from the network before signing. */
+    readonly needsNetwork = true;
+    /** Derivation path, `ton-mnemonic`, or `external`. */
+    readonly path: string;
+    /** The signer that holds the key. */
+    readonly signer: Signer;
+    private _readOnly;
+    /** `publicKey` is the signer's 32-byte ed25519 key; the V5R1 address derives from it synchronously. */
+    constructor(signer: Signer, publicKey: Uint8Array, path: string, config?: TonConfig);
+    /** Back-compat: wrap a raw derived key in a {@link LocalSigner} (the account takes ownership; it cannot derive). */
+    static fromPrivateKey(privateKey: Uint8Array, publicKey: Uint8Array, path: string, config?: TonConfig): WalletAccountTon;
+    /** Account index for the standard m/44'/607'/i' path. */
+    get index(): number | undefined;
+    /** Hex ed25519 signature over the raw message bytes (ton_proof and the like). */
+    sign(message: string | Uint8Array): Promise<string>;
+    private checkMaxFee;
+    /**
+     * Checks → seqno → preflight → signed body. The preflight runs on the
+     * zero-signed body (ignore_chksig), so nothing is signed before it passes.
+     */
+    private prepare;
+    private preflight;
+    /** Sign without broadcasting. Returns the external-message BODY as base64 BoC (pass it back to sendTransaction as a Cell). */
+    signTransaction(tx: TonSendable): Promise<string>;
+    private broadcast;
+    /** Sign and broadcast; `hash` is the body hash (hex) — resolve it with getTransactionReceipt. */
+    sendTransaction(tx: TonSendable): Promise<TransferResult>;
+    /** TON (no `token`) or jetton transfer. */
+    transfer(o: TonTransferOptions): Promise<TransferResult>;
+    /** The same wallet as a {@link WalletAccountReadOnlyTon}. */
+    toReadOnlyAccount(): IWalletAccountReadOnly;
+    /** Disposes the signer: a local key is zeroized, an external one is released. */
+    dispose(): void;
+}
+
+/** Base derivation path for BIP-39 seeds; account `i` is at `m/44'/607'/i'`. */
+declare const TON_BASE_PATH = "m/44'/607'";
+/** Path label of the account a TON-native (Tonkeeper-style) mnemonic yields — there is exactly one. */
+declare const TON_MNEMONIC_PATH = "ton-mnemonic";
+/**
+ * One seed → TON accounts at m/44'/607'/i' (SLIP-10 ed25519) on Wallet V5R1 —
+ * the derivation Trust Wallet and Ledger use for a BIP-39 phrase. Paths
+ * may be relative to m/44'/607' ("0'") or full.
+ *
+ * Built with an ed25519 `Signer` instead of a seed, the manager wraps it:
+ * - a derivable `SeedSigner` sitting at `m/44'/607'` yields `getAccount(i)` → `i'` children;
+ * - a `SeedSigner` at a leaf, or any external signer, is `getAccount(0)` (path = the
+ *   signer's path, or 'external'); other indexes/paths throw.
+ *
+ * Tonkeeper-style 24-word TON mnemonics (not BIP-39) are imported with
+ * {@link WalletManagerTon.fromTonMnemonic}; they yield one account at `ton-mnemonic`.
+ */
+declare class WalletManagerTon extends WalletManager<WalletAccountTon, TonConfig> {
+    constructor(seedOrSigner: string | Uint8Array | Signer, config?: TonConfig);
+    /**
+     * Import a TON-native mnemonic (24 words, Tonkeeper / Tonhub / MyTonWallet
+     * default): PBKDF2 per @ton/crypto, one ed25519 key, one V5R1 account at
+     * path `ton-mnemonic` with the address those wallets show.
+     */
+    static fromTonMnemonic(words: string[] | string, config?: TonConfig): Promise<WalletManagerTon>;
+    getAccount(index?: number): Promise<WalletAccountTon>;
+    getAccountByPath(path: string): Promise<WalletAccountTon>;
+    /** The one path a non-derivable signer answers to: its own, or 'external'. */
+    private singlePath;
+    /** Resolve `path` against an injected signer: the signer itself, or a child when it can derive there. */
+    private fromSigner;
+    /** Watch-only account for a public key (hex or bytes) — TON addresses derive from the key, not the other way round. */
+    getReadOnlyAccount(publicKey: Uint8Array | string): WalletAccountReadOnlyTon;
+    /** Gas price from config param 21 via tonapi (normal = fast there; slow = ×0.8 here). */
+    getFeeRates(): Promise<FeeRates>;
+}
+
+export { CAIP2, DEFAULT_SEND_MODE, DEFAULT_TONAPI, type DecodedBody, type EmulateOptions, type EmulationOutcome, type EmulationSource, type EmulationVerdict, type GetMethodResult, JETTON_TRANSFER_OP, MAINNET_GLOBAL_ID, MAX_ACTIONS, type ParsedV5R1Body, SEND_MODE, SimulationError, TESTNET_GLOBAL_ID, TON_BASE_PATH, TON_MNEMONIC_PATH, type TonAccountState, type TonAccountStatus, TonCenter, type TonConfig, type TonDescribedKind, type TonDescribedMessage, type TonDescription, type TonEmulateConfig, type TonEndpoint, type TonFees, type TonJettonDetails, type TonProvider, type TonReceipt, type TonRisk, type TonRpc, type TonSendable, type TonSimulation, type TonSimulationSource, type TonTransaction, type TonTransferOptions, type TonWarning, type TonWarningCode, UnsafeTransactionError, type V5R1Message, type V5R1SigningParams, type V5R1WalletIdParts, V5R1_CODE_HEX, V5R1_OP, WalletAccountReadOnlyTon, WalletAccountTon, WalletManagerTon, commentCell, createTonRpc as createTonClient, createTonRpc, decodeBody, WalletManagerTon as default, describeMessageRelaxed, describeTransaction, emulateExternal, emulateViaTonapi, installBufferGlobal, parseEmulation, parseTonapiConsequences, parseTonapiRisk, parseTonapiTrace, parseV5R1Body, resolveEmulate, runEmulation, tonCenterEndpoint, v5r1Address, v5r1Code, v5r1ExternalMessage, v5r1PackSigned, v5r1PackUnsigned, v5r1SigningMessage, v5r1StateInit, v5r1WalletId };