@pizzaton/ton 0.0.0-stage → 0.1.1

package/dist/nft/index.mjs

@@ -0,0 +1,51 @@
+import { invariant } from "../core/errors.mjs";
+import { MAX_TON_COINS, assertTonAmount } from "../core/amount.mjs";
+import { NFT_ONCHAIN_CONTENT_KEYS, assertCell, buildOnchainMetadata, nftContentFromCell, nftContentToCell, parseNftContentSlice, royaltyParamsToCell, storeNftContent } from "./content.mjs";
+import { NFT_COLLECTION_OPCODES, NftCollectionContract, buildNftBatchDeployBody, buildNftChangeOwnerBody, buildNftDeployItemBody, buildNftRoyaltyParamsBody, collectionConfigToCell } from "./collection.mjs";
+import { NFT_IMPLEMENTATION_PROFILES } from "./versions.mjs";
+import { SendMode, beginCell } from "@ton/core";
+//#region src/nft/index.ts
+const NFT_OPCODES = {
+	transfer: 1607220500,
+	ownershipAssigned: 85167505,
+	getStaticData: 801842850
+};
+var NftItemContract = class NftItemContract {
+	address;
+	constructor(address) {
+		this.address = address;
+	}
+	static create(address) {
+		return new NftItemContract(address);
+	}
+	async getData(provider) {
+		const { stack } = await provider.get("get_nft_data", []);
+		return {
+			initialized: stack.readBigNumber() !== 0n,
+			index: stack.readBigNumber(),
+			collection: stack.readAddress(),
+			owner: stack.readAddressOpt(),
+			content: stack.readCellOpt()
+		};
+	}
+	async sendTransfer(provider, via, input, value) {
+		assertTonAmount(value, "NFT transfer value");
+		await provider.internal(via, {
+			value,
+			body: buildNftTransferBody(input),
+			sendMode: SendMode.PAY_GAS_SEPARATELY
+		});
+	}
+};
+function buildNftTransferBody(input) {
+	const queryId = input.queryId ?? 0n;
+	const forwardAmount = input.forwardAmount ?? 0n;
+	invariant(queryId >= 0n && queryId < 2n ** 64n, "INVALID_TRANSACTION", "Query id is out of range");
+	invariant(forwardAmount >= 0n && forwardAmount <= MAX_TON_COINS, "INVALID_AMOUNT", "Forward amount is outside the TON coin range");
+	const builder = beginCell().storeUint(NFT_OPCODES.transfer, 32).storeUint(queryId, 64).storeAddress(input.newOwner).storeAddress(input.responseDestination).storeMaybeRef(input.customPayload).storeCoins(forwardAmount);
+	if (input.forwardPayload) builder.storeBit(1).storeRef(input.forwardPayload);
+	else builder.storeBit(0);
+	return builder.endCell();
+}
+//#endregion
+export { NFT_COLLECTION_OPCODES, NFT_IMPLEMENTATION_PROFILES, NFT_ONCHAIN_CONTENT_KEYS, NFT_OPCODES, NftCollectionContract, NftItemContract, assertCell, buildNftBatchDeployBody, buildNftChangeOwnerBody, buildNftDeployItemBody, buildNftRoyaltyParamsBody, buildNftTransferBody, buildOnchainMetadata, collectionConfigToCell, nftContentFromCell, nftContentToCell, parseNftContentSlice, royaltyParamsToCell, storeNftContent };

package/dist/nft/versions.d.mts

@@ -0,0 +1,11 @@
+//#region src/nft/versions.d.ts
+export type NftCollectionImplementationVersion = "default" | "compressed";
+export type NftItemImplementationVersion = "default" | "sbt" | "single";
+export interface NftImplementationProfile {
+  readonly version: NftCollectionImplementationVersion | NftItemImplementationVersion;
+  readonly transferable: boolean;
+  readonly supportsCollectionIndexing: boolean;
+  readonly supportsMerkleSelfDeployment: boolean;
+}
+export declare const NFT_IMPLEMENTATION_PROFILES: Readonly<Record<NftImplementationProfile["version"], NftImplementationProfile>>;
+//#endregion

package/dist/nft/versions.mjs

@@ -0,0 +1,29 @@
+//#region src/nft/versions.ts
+const NFT_IMPLEMENTATION_PROFILES = Object.freeze({
+	default: {
+		version: "default",
+		transferable: true,
+		supportsCollectionIndexing: true,
+		supportsMerkleSelfDeployment: false
+	},
+	compressed: {
+		version: "compressed",
+		transferable: true,
+		supportsCollectionIndexing: true,
+		supportsMerkleSelfDeployment: true
+	},
+	sbt: {
+		version: "sbt",
+		transferable: false,
+		supportsCollectionIndexing: true,
+		supportsMerkleSelfDeployment: false
+	},
+	single: {
+		version: "single",
+		transferable: true,
+		supportsCollectionIndexing: false,
+		supportsMerkleSelfDeployment: false
+	}
+});
+//#endregion
+export { NFT_IMPLEMENTATION_PROFILES };

package/dist/proof/index.d.mts

@@ -0,0 +1,62 @@
+import { TonNetwork } from "../core/network.mjs";
+import { Address } from "@ton/core";
+//#region src/proof/index.d.ts
+/** The trampoline wallet code used by WalletTg. */
+export declare const TON_CONNECT_WALLET_TG_CODE_HASH = "9149ae51c1e4689710cebf7830297b16acfbadb363a920a537893e7ffeeca768";
+export interface TonConnectProof {
+  readonly timestamp: number;
+  readonly domain: {
+    readonly lengthBytes: number;
+    readonly value: string;
+  };
+  readonly payload: string;
+  readonly signature: string;
+  readonly state_init: string;
+}
+export interface VerifyTonConnectProofInput {
+  readonly address: string;
+  readonly proof: TonConnectProof;
+  readonly expectedDomain: string;
+  readonly expectedPublicKey?: string | Uint8Array;
+}
+export interface VerifyTonConnectProofOptions {
+  readonly network: TonNetwork;
+  readonly now?: number;
+  readonly maxAgeSeconds?: number;
+  readonly maxDomainBytes?: number;
+  readonly maxPayloadBytes?: number;
+  /** Additional wallet code hashes whose public key is resolved externally. */
+  readonly delegatedWalletCodeHashes?: readonly string[];
+  /** Resolve the signing key for wallets that keep it outside state_init. */
+  readonly resolveDelegatedWalletPublicKey?: (address: Address, network: TonNetwork) => Promise<Uint8Array | null>;
+}
+export interface VerifyTonConnectSignDataInput {
+  readonly address: string;
+  readonly stateInit: string;
+  readonly timestamp: number;
+  readonly domain: {
+    readonly lengthBytes: number;
+    readonly value: string;
+  };
+  readonly payload: {
+    readonly text: string;
+  };
+  readonly signature: string;
+  readonly expectedDomain: string;
+  readonly expectedPublicKey?: string | Uint8Array;
+}
+/**
+ * Verifies the TON Connect `ton_proof` signature and its state-init wallet.
+ * WalletTg and additional delegated wallets can resolve their public key with
+ * `resolveDelegatedWalletPublicKey`; resolver errors are allowed to propagate
+ * so callers can distinguish an RPC outage from an invalid proof.
+ */
+export declare function verifyTonConnectProof(input: VerifyTonConnectProofInput, options: VerifyTonConnectProofOptions): Promise<boolean>;
+/**
+ * Verifies a text payload returned by TON Connect `signData`. This validates
+ * the canonical TON Connect digest, the state-init/address binding, and the
+ * expected signing domain. It does not replace the application's challenge,
+ * message-hash, or single-use checks.
+ */
+export declare function verifyTonConnectSignData(input: VerifyTonConnectSignDataInput, options: VerifyTonConnectProofOptions): Promise<boolean>;
+//#endregion

package/dist/proof/index.mjs

@@ -0,0 +1,227 @@
+import { bytesToHex, hexToBytes } from "../core/bytes.mjs";
+import { Address, Cell } from "@ton/core";
+import { sha256, signVerify } from "@ton/crypto";
+import { WalletContractV1R1, WalletContractV1R2, WalletContractV1R3, WalletContractV2R1, WalletContractV2R2, WalletContractV3R1, WalletContractV3R2, WalletContractV4, WalletContractV5R1, contractAddress as contractAddress$1, loadStateInit } from "@ton/ton";
+//#region src/proof/index.ts
+const MAX_STATE_INIT_BYTES = 12288;
+const DEFAULT_MAX_PROOF_AGE_SECONDS = 600;
+function isTonNetwork(value) {
+	return value === "mainnet" || value === "testnet";
+}
+/** The trampoline wallet code used by WalletTg. */
+const TON_CONNECT_WALLET_TG_CODE_HASH = "9149ae51c1e4689710cebf7830297b16acfbadb363a920a537893e7ffeeca768";
+const readV1V2 = (data) => {
+	const slice = data.beginParse();
+	slice.loadUint(32);
+	return slice.loadBuffer(32);
+};
+const readV3V4 = (data) => {
+	const slice = data.beginParse();
+	slice.loadUint(32);
+	slice.loadUint(32);
+	return slice.loadBuffer(32);
+};
+const readV5 = (data) => {
+	const slice = data.beginParse();
+	slice.loadBoolean();
+	slice.loadUint(32);
+	slice.loadUint(32);
+	return slice.loadBuffer(32);
+};
+const standardWallets = [
+	...[
+		WalletContractV1R1,
+		WalletContractV1R2,
+		WalletContractV1R3,
+		WalletContractV2R1,
+		WalletContractV2R2
+	].map((wallet) => ({
+		code: wallet.create({
+			workchain: 0,
+			publicKey: Buffer.alloc(32)
+		}).init.code,
+		readPublicKey: readV1V2
+	})),
+	...[
+		WalletContractV3R1,
+		WalletContractV3R2,
+		WalletContractV4
+	].map((wallet) => ({
+		code: wallet.create({
+			workchain: 0,
+			publicKey: Buffer.alloc(32)
+		}).init.code,
+		readPublicKey: readV3V4
+	})),
+	{
+		code: WalletContractV5R1.create({
+			workchain: 0,
+			publicKey: Buffer.alloc(32)
+		}).init.code,
+		readPublicKey: readV5
+	}
+];
+function parseStateInitWallet(addressValue, stateInitBase64) {
+	if (stateInitBase64.length === 0 || stateInitBase64.length > Math.ceil(MAX_STATE_INIT_BYTES * 4 / 3)) return null;
+	let address;
+	let stateInit;
+	try {
+		const bytes = Buffer.from(stateInitBase64, "base64");
+		if (bytes.length === 0 || bytes.length > MAX_STATE_INIT_BYTES || bytes.toString("base64") !== stateInitBase64) return null;
+		const cells = Cell.fromBoc(bytes);
+		if (cells.length !== 1) return null;
+		const cell = cells[0];
+		if (!cell) return null;
+		stateInit = loadStateInit(cell.beginParse());
+		address = Address.parse(addressValue);
+	} catch {
+		return null;
+	}
+	if (!stateInit.code || !stateInit.data) return null;
+	if (!contractAddress$1(address.workChain, stateInit).equals(address)) return null;
+	const codeHash = bytesToHex(stateInit.code.hash());
+	for (const wallet of standardWallets) {
+		if (!wallet.code.equals(stateInit.code)) continue;
+		try {
+			const publicKey = wallet.readPublicKey(stateInit.data);
+			return publicKey.length === 32 ? {
+				address,
+				codeHash,
+				publicKey,
+				delegated: false
+			} : null;
+		} catch {
+			return null;
+		}
+	}
+	return {
+		address,
+		codeHash,
+		publicKey: null,
+		delegated: true
+	};
+}
+function decodeExpectedPublicKey(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "string") return value.length === 32 ? value : null;
+	try {
+		const bytes = hexToBytes(value);
+		return bytes.length === 32 ? bytes : null;
+	} catch {
+		return null;
+	}
+}
+function decodeSignature(value) {
+	try {
+		const signature = Buffer.from(value, "base64");
+		return signature.length === 64 && signature.toString("base64") === value ? signature : null;
+	} catch {
+		return null;
+	}
+}
+async function resolveSigningPublicKey(parsed, expectedPublicKey, options) {
+	let publicKey = parsed.publicKey;
+	if (!publicKey) {
+		if (!options.resolveDelegatedWalletPublicKey) return null;
+		publicKey = await options.resolveDelegatedWalletPublicKey(parsed.address, options.network);
+		if (publicKey?.length !== 32) return null;
+	}
+	const expected = decodeExpectedPublicKey(expectedPublicKey);
+	if (expectedPublicKey !== void 0 && !expected) return null;
+	if (expected && !Buffer.from(publicKey).equals(Buffer.from(expected))) return null;
+	return publicKey;
+}
+/**
+* Verifies the TON Connect `ton_proof` signature and its state-init wallet.
+* WalletTg and additional delegated wallets can resolve their public key with
+* `resolveDelegatedWalletPublicKey`; resolver errors are allowed to propagate
+* so callers can distinguish an RPC outage from an invalid proof.
+*/
+async function verifyTonConnectProof(input, options) {
+	if (!input || !options || !isTonNetwork(options.network) || typeof input.address !== "string" || typeof input.expectedDomain !== "string" || input.expectedDomain.length === 0 || !input.proof || typeof input.proof.state_init !== "string" || typeof input.proof.domain?.value !== "string" || !Number.isSafeInteger(input.proof.domain.lengthBytes) || !Number.isSafeInteger(input.proof.timestamp) || typeof input.proof.payload !== "string" || typeof input.proof.signature !== "string") return false;
+	const { proof } = input;
+	const domain = Buffer.from(proof.domain.value, "utf8");
+	const payload = Buffer.from(proof.payload, "utf8");
+	const maxDomainBytes = options.maxDomainBytes ?? 128;
+	const maxPayloadBytes = options.maxPayloadBytes ?? 128;
+	const now = options.now ?? Math.floor(Date.now() / 1e3);
+	const maxAgeSeconds = options.maxAgeSeconds ?? DEFAULT_MAX_PROOF_AGE_SECONDS;
+	if (proof.domain.value !== input.expectedDomain || proof.domain.lengthBytes !== domain.length || domain.length > maxDomainBytes || payload.length > maxPayloadBytes || proof.timestamp < 0 || !Number.isSafeInteger(now) || !Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 0 || Math.abs(now - proof.timestamp) > maxAgeSeconds) return false;
+	const signature = decodeSignature(proof.signature);
+	if (!signature) return false;
+	const parsed = parseStateInitWallet(input.address, input.proof.state_init);
+	if (!parsed) return false;
+	const delegatedHashes = /* @__PURE__ */ new Set([TON_CONNECT_WALLET_TG_CODE_HASH, ...(options.delegatedWalletCodeHashes ?? []).map((hash) => hash.toLowerCase())]);
+	if (parsed.delegated && !delegatedHashes.has(parsed.codeHash)) return false;
+	const publicKey = await resolveSigningPublicKey(parsed, input.expectedPublicKey, options);
+	if (!publicKey) return false;
+	const workchain = Buffer.alloc(4);
+	workchain.writeInt32BE(parsed.address.workChain, 0);
+	const domainLength = Buffer.alloc(4);
+	domainLength.writeUInt32LE(domain.length, 0);
+	const timestamp = Buffer.alloc(8);
+	timestamp.writeBigUInt64LE(BigInt(proof.timestamp), 0);
+	const message = Buffer.concat([
+		Buffer.from("ton-proof-item-v2/", "utf8"),
+		workchain,
+		parsed.address.hash,
+		domainLength,
+		domain,
+		timestamp,
+		payload
+	]);
+	const messageHash = await sha256(message);
+	const digest = await sha256(Buffer.concat([
+		Buffer.from([255, 255]),
+		Buffer.from("ton-connect", "utf8"),
+		messageHash
+	]));
+	return signVerify(digest, signature, Buffer.from(publicKey));
+}
+/**
+* Verifies a text payload returned by TON Connect `signData`. This validates
+* the canonical TON Connect digest, the state-init/address binding, and the
+* expected signing domain. It does not replace the application's challenge,
+* message-hash, or single-use checks.
+*/
+async function verifyTonConnectSignData(input, options) {
+	if (!input || !options || !isTonNetwork(options.network) || typeof input.address !== "string" || typeof input.stateInit !== "string" || typeof input.expectedDomain !== "string" || input.expectedDomain.length === 0 || typeof input.domain?.value !== "string" || !Number.isSafeInteger(input.domain.lengthBytes) || !Number.isSafeInteger(input.timestamp) || typeof input.payload?.text !== "string" || typeof input.signature !== "string") return false;
+	const domain = Buffer.from(input.domain.value, "utf8");
+	const payload = Buffer.from(input.payload.text, "utf8");
+	const now = options.now ?? Math.floor(Date.now() / 1e3);
+	const maxAgeSeconds = options.maxAgeSeconds ?? DEFAULT_MAX_PROOF_AGE_SECONDS;
+	const maxPayloadBytes = options.maxPayloadBytes ?? 2e3;
+	if (input.timestamp < 0 || !Number.isSafeInteger(now) || !Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 0 || input.domain.value !== input.expectedDomain || input.domain.lengthBytes !== domain.length || domain.length > (options.maxDomainBytes ?? 128) || payload.length === 0 || payload.length > maxPayloadBytes || input.timestamp > now + 60 || now - input.timestamp > maxAgeSeconds) return false;
+	const signature = decodeSignature(input.signature);
+	if (!signature) return false;
+	const parsed = parseStateInitWallet(input.address, input.stateInit);
+	if (!parsed) return false;
+	const delegatedHashes = /* @__PURE__ */ new Set([TON_CONNECT_WALLET_TG_CODE_HASH, ...(options.delegatedWalletCodeHashes ?? []).map((hash) => hash.toLowerCase())]);
+	if (parsed.delegated && !delegatedHashes.has(parsed.codeHash)) return false;
+	const publicKey = await resolveSigningPublicKey(parsed, input.expectedPublicKey, options);
+	if (!publicKey) return false;
+	const workchain = Buffer.alloc(4);
+	workchain.writeInt32BE(parsed.address.workChain, 0);
+	const domainLength = Buffer.alloc(4);
+	domainLength.writeUInt32BE(domain.length, 0);
+	const timestamp = Buffer.alloc(8);
+	timestamp.writeBigUInt64BE(BigInt(input.timestamp), 0);
+	const payloadLength = Buffer.alloc(4);
+	payloadLength.writeUInt32BE(payload.length, 0);
+	const message = Buffer.concat([
+		Buffer.from([255, 255]),
+		Buffer.from("ton-connect/sign-data/", "utf8"),
+		workchain,
+		parsed.address.hash,
+		domainLength,
+		domain,
+		timestamp,
+		Buffer.from("txt", "utf8"),
+		payloadLength,
+		payload
+	]);
+	const digest = await sha256(message);
+	return signVerify(digest, signature, Buffer.from(publicKey));
+}
+//#endregion
+export { TON_CONNECT_WALLET_TG_CODE_HASH, verifyTonConnectProof, verifyTonConnectSignData };

package/dist/provider/index.d.mts

@@ -0,0 +1,32 @@
+import { TonNetwork } from "../core/network.mjs";
+import { Address, Contract, ContractProvider, OpenedContract, StateInit, TupleItem, TupleReader } from "@ton/core";
+//#region src/provider/index.d.ts
+export interface TonAccountState {
+  readonly status: "active" | "uninitialized" | "frozen" | "non-existing";
+  readonly balance: bigint;
+}
+export interface TonTransactionSummary {
+  readonly lt: bigint;
+  readonly hash: string;
+  readonly timestamp: number;
+}
+export interface TonGetMethodResult {
+  readonly gasUsed: number;
+  readonly stack: TupleReader;
+  readonly exitCode?: number;
+}
+export interface TonProvider {
+  readonly network: TonNetwork;
+  openContract<T extends Contract>(contract: T): OpenedContract<T>;
+  contractProvider(address: Address, init?: StateInit | null): ContractProvider;
+  getBalance(address: Address): Promise<bigint>;
+  getAccountState(address: Address): Promise<TonAccountState>;
+  runGetMethod(address: Address, method: string, args?: readonly TupleItem[]): Promise<TonGetMethodResult>;
+  getTransactions(address: Address, options?: {
+    readonly limit?: number;
+    readonly lt?: bigint;
+    readonly hash?: string;
+  }): Promise<readonly TonTransactionSummary[]>;
+  isContractDeployed(address: Address): Promise<boolean>;
+}
+//#endregion

package/dist/provider/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/react/index.d.mts

@@ -0,0 +1,13 @@
+import { TransactionIntent } from "../transactions/index.mjs";
+import { TonConnectAdapter, TonConnectWallet } from "../connect/index.mjs";
+//#region src/react/index.d.ts
+export declare function useTonWallet(adapter: TonConnectAdapter | null): TonConnectWallet | null;
+export type TonTransactionStatus = "idle" | "sending" | "sent" | "error";
+export declare function useTonTransaction(adapter: TonConnectAdapter | null): {
+  readonly send: (intent: TransactionIntent) => Promise<string | null>;
+  readonly status: TonTransactionStatus;
+  readonly boc: string | null;
+  readonly error: Error | null;
+  readonly reset: () => void;
+};
+//#endregion

package/dist/react/index.mjs

@@ -0,0 +1,48 @@
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+//#region src/react/index.ts
+function useTonWallet(adapter) {
+	return useSyncExternalStore((listener) => adapter?.subscribe(listener) ?? (() => void 0), () => adapter?.getWallet() ?? null, () => null);
+}
+function useTonTransaction(adapter) {
+	const [status, setStatus] = useState("idle");
+	const [boc, setBoc] = useState(null);
+	const [error, setError] = useState(null);
+	const sending = useRef(false);
+	const reset = useCallback(() => {
+		setStatus("idle");
+		setBoc(null);
+		setError(null);
+	}, []);
+	const send = useCallback(async (intent) => {
+		if (!adapter) throw new Error("A TON Connect adapter is required");
+		if (sending.current) throw new Error("A TON transaction is already being sent");
+		sending.current = true;
+		setStatus("sending");
+		setError(null);
+		try {
+			const result = await adapter.sendTransaction(intent);
+			setBoc(result);
+			setStatus("sent");
+			return result;
+		} catch (cause) {
+			const nextError = cause instanceof Error ? cause : new Error(String(cause));
+			setError(nextError);
+			setStatus("error");
+			return null;
+		} finally {
+			sending.current = false;
+		}
+	}, [adapter]);
+	useEffect(() => {
+		if (!adapter) reset();
+	}, [adapter, reset]);
+	return {
+		send,
+		status,
+		boc,
+		error,
+		reset
+	};
+}
+//#endregion
+export { useTonTransaction, useTonWallet };

package/dist/server/index.d.mts

@@ -0,0 +1,11 @@
+import { TonNetwork } from "../core/network.mjs";
+import { TonProvider } from "../provider/index.mjs";
+//#region src/server/index.d.ts
+export interface TonHttpProviderOptions {
+  readonly network: TonNetwork;
+  readonly endpoint: string;
+  readonly apiKey?: string;
+  readonly timeoutMs?: number;
+}
+export declare function createTonHttpProvider(options: TonHttpProviderOptions): TonProvider;
+//#endregion

package/dist/server/index.mjs

@@ -0,0 +1,55 @@
+import { invariant } from "../core/errors.mjs";
+import { createNetworkConfig } from "../core/network.mjs";
+import { TonClient } from "@ton/ton";
+//#region src/server/index.ts
+function createTonHttpProvider(options) {
+	const networkConfig = createNetworkConfig({
+		network: options.network,
+		endpoint: options.endpoint
+	});
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	invariant(Number.isSafeInteger(timeoutMs) && timeoutMs > 0, "INVALID_NETWORK", "TON provider timeout must be a positive safe integer");
+	const client = new TonClient({
+		endpoint: networkConfig.endpoint,
+		...options.apiKey === void 0 ? {} : { apiKey: options.apiKey },
+		timeout: timeoutMs
+	});
+	return {
+		network: options.network,
+		openContract: (contract) => client.open(contract),
+		contractProvider: (address, init) => client.provider(address, init),
+		getBalance: (address) => client.getBalance(address),
+		async getAccountState(address) {
+			const state = await client.getContractState(address);
+			return {
+				status: state.state === "active" ? "active" : state.state === "frozen" ? "frozen" : "uninitialized",
+				balance: state.balance
+			};
+		},
+		async runGetMethod(address, method, args) {
+			const result = await client.runMethodWithError(address, method, args ? [...args] : []);
+			return {
+				gasUsed: result.gas_used,
+				stack: result.stack,
+				exitCode: result.exit_code
+			};
+		},
+		async getTransactions(address, transactionOptions) {
+			const limit = transactionOptions?.limit ?? 20;
+			invariant(Number.isSafeInteger(limit) && limit >= 1 && limit <= 1e3, "INVALID_TRANSACTION", "Transaction limit must be an integer from 1 to 1000");
+			if (transactionOptions?.lt !== void 0) invariant(transactionOptions.lt >= 0n, "INVALID_TRANSACTION", "Transaction logical time cannot be negative");
+			return (await client.getTransactions(address, {
+				limit,
+				...transactionOptions?.lt !== void 0 ? { lt: transactionOptions.lt.toString() } : {},
+				...transactionOptions?.hash ? { hash: transactionOptions.hash } : {}
+			})).map((transaction) => ({
+				lt: transaction.lt,
+				hash: transaction.hash().toString("hex"),
+				timestamp: transaction.now
+			}));
+		},
+		isContractDeployed: (address) => client.isContractDeployed(address)
+	};
+}
+//#endregion
+export { createTonHttpProvider };

package/dist/simulation/index.d.mts

@@ -0,0 +1,112 @@
+import { Address, Cell, Message, StateInit } from "@ton/core";
+import { AccountEvent } from "@ton-api/client";
+import { Blockchain, BlockchainConfig, Event } from "@ton/sandbox";
+//#region src/simulation/index.d.ts
+export type TonSimulationSource = "sandbox" | "tonapi";
+export interface TonSimulationInput {
+  /** A serialized external or internal message, or a message object for local sandbox execution. */
+  readonly message: Cell | Message;
+  /** Required for unsigned external-wallet previews. Internal messages do not need this flag. */
+  readonly ignoreSignatureCheck?: boolean;
+  /** Keep mutations in a local sandbox. Preview callers should leave this false. */
+  readonly persist?: boolean;
+}
+export interface TonSimulationMessage {
+  readonly type: "internal" | "external-in" | "external-out";
+  readonly source?: Address;
+  readonly destination?: Address;
+  readonly value?: bigint;
+  readonly body?: Cell;
+  readonly init?: StateInit;
+  readonly createdAt?: number;
+  readonly createdLt?: bigint;
+}
+export interface TonSimulationTransaction {
+  readonly hash: string;
+  readonly logicalTime: bigint;
+  /** Raw 256-bit account identifier; TON transactions do not carry the workchain in this field. */
+  readonly accountId: string;
+  readonly timestamp: number;
+  readonly success: boolean;
+  readonly oldStatus: string;
+  readonly endStatus: string;
+  readonly totalFees: bigint;
+  readonly storageFees: bigint;
+  readonly gasFees: bigint;
+  readonly forwardFees: bigint;
+  readonly actionFees: bigint;
+  readonly gasUsed: bigint;
+  readonly vmSteps: number;
+  readonly exitCode?: number;
+  readonly actionSuccess?: boolean;
+  readonly input?: TonSimulationMessage;
+  readonly outputs: readonly TonSimulationMessage[];
+  readonly parentHash?: string;
+  readonly childHashes: readonly string[];
+  readonly blockchainLogs: string;
+  readonly vmLogs: string;
+  readonly debugLogs: string;
+  readonly oldStorage?: Cell;
+  readonly newStorage?: Cell;
+}
+export interface TonSimulationCost {
+  readonly totalFees: bigint;
+  readonly storageFees: bigint;
+  readonly gasFees: bigint;
+  readonly forwardFees: bigint;
+  readonly actionFees: bigint;
+  readonly gasUsed: bigint;
+  readonly vmSteps: number;
+}
+export interface TonSimulationError {
+  readonly message: string;
+  readonly exitCode?: number;
+}
+export interface TonSimulationResult {
+  readonly source: TonSimulationSource;
+  readonly success: boolean;
+  readonly transactions: readonly TonSimulationTransaction[];
+  readonly cost: TonSimulationCost;
+  readonly rootTransactionHash?: string;
+  readonly events?: readonly Event[] | readonly AccountEvent[];
+  readonly error?: TonSimulationError;
+  /** Always true for remote previews because the remote chain may change before signing. */
+  readonly speculative: boolean;
+}
+export interface TonSimulationAdapter {
+  readonly source: TonSimulationSource;
+  simulate(input: TonSimulationInput): Promise<TonSimulationResult>;
+}
+export declare function createTonSimulationWithFallback(primary: TonSimulationAdapter, fallback: TonSimulationAdapter): TonSimulationAdapter;
+export interface TonSandboxSimulation extends TonSimulationAdapter {
+  readonly source: "sandbox";
+  readonly blockchain: Blockchain;
+}
+export interface TonSandboxSimulationOptions {
+  /** Recording storage snapshots makes state diffs available but is slower. */
+  readonly recordStorage?: boolean;
+}
+export declare function messageToCell(message: Message): Cell;
+export declare function createTonSandboxSimulation(blockchain: Blockchain, options?: TonSandboxSimulationOptions): TonSandboxSimulation;
+export interface TonClient4SandboxSimulationOptions {
+  readonly endpoint: string;
+  readonly timeoutMs?: number;
+  readonly blockSeqno?: number;
+  readonly config?: BlockchainConfig;
+  readonly now?: number;
+  readonly recordStorage?: boolean;
+}
+/**
+ * Creates a native sandbox backed by a read-only snapshot of the live chain.
+ * Contract code and account state are fetched lazily from TonClient4.
+ */
+export declare function createTonClient4SandboxSimulation(options: TonClient4SandboxSimulationOptions): Promise<TonSandboxSimulation>;
+export interface TonApiSimulationFallbackOptions {
+  readonly baseUrl?: string;
+  readonly apiKey?: string;
+  readonly timeoutMs?: number;
+  readonly fetch?: typeof globalThis.fetch;
+}
+/** Optional fallback for clients that cannot hydrate a native sandbox snapshot. */
+export declare function createTonApiSimulationFallback(options?: TonApiSimulationFallbackOptions): TonSimulationAdapter;
+//#endregion