@pizzaton/ton 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,482 @@
-# Temporary Holding Version
+# @pizzaton/ton
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed TON protocol infrastructure for PizzaTon applications. The package provides reusable primitives for TON addresses, amounts, messages, providers, standard Jetton and NFT contracts, wallet versions, TON Connect, emulation, simulation, Merkle airdrops, and vesting calculations.
+
+It is intentionally protocol-focused. Application workflows, database persistence, authentication, launchpad rules, product-specific contracts, and UI components belong in the application or domain packages that consume this package.
+
+## Requirements
+
+- Node.js 20 or newer, or Bun.
+- TypeScript with `strict` enabled in the consuming application.
+- The `@ton/core` peer dependency (npm installs compatible peers automatically).
+- TypeScript consumers also need the `@types/node` peer dependency (version 20 or newer).
+- A TON HTTP endpoint for server-side reads, or a `@ton/sandbox` instance for local execution.
+- A real serialized wallet message when simulating a wallet transaction. The package never invents signatures or silently signs user messages.
+
+All token and TON values are represented as `bigint` in the SDK. Convert user input with `parseUnits` or `parseTon`; never use JavaScript floating-point numbers for on-chain amounts.
+
+## Installation and imports
+
+```bash
+npm install @pizzaton/ton
+```
+
+The package is published as ESM with TypeScript declarations. Bun projects can use
+`bun add @pizzaton/ton` instead. The monorepo itself uses Bun workspaces for
+development.
+
+Some feature subpaths have optional peers so consumers only install those
+dependencies when they use the feature:
+
+```bash
+npm install @ton/sandbox @ton-api/client react @types/react
+```
+
+Install `@ton/sandbox` for `/emulator` and `/simulation`, `@ton-api/client` for
+`/indexer`, `/jetton/details`, and TonAPI simulation fallback, and `react` plus
+`@types/react` for `/react`.
+
+Use the narrowest subpath that contains the feature you need. This keeps browser bundles free of server-only and emulator dependencies.
+
+| Subpath | Use |
+| --- | --- |
+| `@pizzaton/ton/core` | Addresses, amounts, bytes, metadata, networks, and typed errors |
+| `@pizzaton/ton/transactions` | Validated transaction intents and TON Connect request conversion |
+| `@pizzaton/ton/provider` | Provider interfaces for application-defined adapters |
+| `@pizzaton/ton/server` | Server-side `@ton/ton` HTTP provider |
+| `@pizzaton/ton/connect` | TON Connect adapter and network validation |
+| `@pizzaton/ton/react` | React hooks over the adapter |
+| `@pizzaton/ton/jetton` | Jetton payloads, data readers, wallet resolution, and implementation profiles |
+| `@pizzaton/ton/jetton/details` | Server-side token detail lookup through TonAPI and TonCenter |
+| `@pizzaton/ton/indexer` | TonAPI-backed account and transaction indexer |
+| `@pizzaton/ton/nft` | Standard NFT collection/item payloads, readers, content, royalties, and profiles |
+| `@pizzaton/ton/wallet` | Versioned wallet contract/address models |
+| `@pizzaton/ton/emulator` | Local `@ton/sandbox` execution adapter |
+| `@pizzaton/ton/simulation` | Native transaction previews and optional TonAPI fallback |
+| `@pizzaton/ton/airdrop` | Canonical Merkle trees and proofs |
+| `@pizzaton/ton/vesting` | Integer-safe vesting calculations |
+| `@pizzaton/ton/contracts` | Generic contract-module registry and provider-backed client |
+| `@pizzaton/ton/contracts/catalog` | Versioned source and readiness descriptors |
+| `@pizzaton/ton/contracts/wrappers` | Native wrappers for supported TON protocols |
+| `@pizzaton/ton/contracts/hipo` | Hipo liquid-staking treasury, parent, and wallet contracts |
+| `@pizzaton/ton` | Shared, platform-neutral APIs and stable application ports |
+
+See [CONTRACTS.md](./CONTRACTS.md) for wrapper usage, source pins, and the
+contract integration boundaries. The wrappers ship as part of this TON
+package; there is no separate contracts workspace package.
+
+`@pizzaton/ton/server`, `@pizzaton/ton/jetton/details`, `@pizzaton/ton/emulator`, `@pizzaton/ton/simulation`, `@pizzaton/ton/indexer`, and `@pizzaton/ton/wallet` are feature subpaths outside the root entry point. Do not import them from browser components unless the bundler is explicitly configured for those dependencies. React components should use `@pizzaton/ton/connect`, `@pizzaton/ton/transactions`, and `@pizzaton/ton/react`.
+
+## Official TON SDK first
+
+The package uses the official TON libraries as its source of truth. `Address`, `Cell`, `Builder`, `ContractProvider`, `Sender`, `StateInit`, message codecs, dictionaries, and tuple types come from `@ton/core`. RPC clients, Jetton master/wallet readers, wallet-version contracts, and fee helpers come from `@ton/ton`. Cryptographic hashing comes from `@ton/crypto`; local execution comes from `@ton/sandbox`; wallet transport comes from `@tonconnect/sdk`.
+
+The package re-exports the official Jetton and wallet contract classes through their feature subpaths. Its own code adds only PizzaTon’s stable ports, validation, version/capability metadata, standard payload builders missing from the official surface, NFT codecs, and composition helpers. When an official API exists, prefer it directly or use the package wrapper that delegates to it. Do not copy an official contract implementation into an application package.
+
+## Core conventions
+
+### Addresses
+
+`Address` from `@ton/core` is the canonical runtime type. The package accepts either `Address` or a valid friendly/raw string at parsing boundaries. `toTonAddress` returns a branded raw address string for storage and comparison.
+
+```ts
+import { addressesEqual, parseTonAddress, toFriendlyAddress, toTonAddress } from "@pizzaton/ton/core";
+
+const address = parseTonAddress("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c");
+const raw = toTonAddress(address);
+const friendly = toFriendlyAddress(raw, { network: "mainnet", bounceable: true });
+
+if (addressesEqual(raw, friendly)) {
+	console.log("Same account");
+}
+```
+
+Invalid addresses throw `TonPackageError` with code `INVALID_ADDRESS`. Use `assertWorkchain` when a contract must be deployed to a specific workchain.
+
+### Amounts
+
+```ts
+import { formatTon, formatUnits, parseTon, parseUnits } from "@pizzaton/ton/core";
+
+const oneTon = parseTon("1.000000000"); // 1_000_000_000n
+const tokenAmount = parseUnits("12.50", 6); // 12_500_000n
+
+formatTon(oneTon); // "1"
+formatUnits(tokenAmount, 6); // "12.5"
+```
+
+Parsing rejects negative values, malformed decimals, and precision loss. `formatUnits` never rounds.
+
+### Errors
+
+```ts
+import { TonPackageError } from "@pizzaton/ton/core";
+
+try {
+	// protocol operation
+} catch (error: unknown) {
+	if (error instanceof TonPackageError) {
+		console.error(error.code, error.message, error.details);
+	}
+	throw error;
+}
+```
+
+The public error codes are `INVALID_ADDRESS`, `INVALID_AMOUNT`, `INVALID_NETWORK`, `INVALID_TRANSACTION`, `INVALID_METADATA`, `INVALID_PROOF`, `INVALID_SCHEDULE`, and `PROVIDER_ERROR`.
+
+## Reading the chain
+
+Create the server provider once and inject it into domain services or contract wrappers. Keep endpoint credentials on the server.
+
+```ts
+import { Address } from "@ton/core";
+import { createTonHttpProvider } from "@pizzaton/ton/server";
+
+const provider = createTonHttpProvider({
+	network: "mainnet",
+	endpoint: process.env.TON_RPC_ENDPOINT!,
+	apiKey: process.env.TON_RPC_API_KEY,
+	timeoutMs: 10_000,
+});
+
+const account = Address.parse("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c");
+const balance = await provider.getBalance(account);
+const state = await provider.getAccountState(account);
+const transactions = await provider.getTransactions(account, { limit: 20 });
+```
+
+`TonProvider` is the stable application port. Implement every method when the application uses another indexer or RPC service; contract wrappers remain independent of the transport. Keep that adapter in the application’s infrastructure layer and cover it with provider contract tests.
+
+## Generic contract client
+
+`TonContractClient` is useful when a contract wrapper already exists or when a product-specific contract is supplied later.
+
+```ts
+import { Address } from "@ton/core";
+import { TonContractClient } from "@pizzaton/ton/contracts";
+
+const contract = { address: Address.parse("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c") };
+const contractClient = new TonContractClient(
+	contract,
+	provider.contractProvider(contract.address),
+);
+
+const stack = await contractClient.get("get_wallet_data");
+// Add a Sender with .withSender(sender) before calling .send(...).
+```
+
+For product-specific contracts, implement a versioned `TonContractModule<TConfig, TState, TAction>` with explicit state decoding, address derivation, and message construction. Register modules with `createContractModuleRegistry()` rather than mixing incompatible layouts.
+
+## Jettons
+
+The Jetton entry point supports the standard transfer, burn, excess, wallet-address, wallet-data, and master-data operations.
+
+```ts
+import { Address } from "@ton/core";
+import {
+	JettonMaster,
+	buildJettonTransferBody,
+	getJettonImplementationProfile,
+	resolveJettonWalletAddress,
+} from "@pizzaton/ton/jetton";
+
+const masterAddress = Address.parse("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c");
+const owner = Address.parse("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c");
+const master = JettonMaster.create(masterAddress);
+const masterProvider = provider.contractProvider(master.address);
+
+const data = await master.getJettonData(masterProvider);
+const walletAddress = await resolveJettonWalletAddress(provider, master.address, owner);
+const transferBody = buildJettonTransferBody({
+	amount: 1_000_000n,
+	destination: owner,
+	responseDestination: owner,
+	forwardAmount: 0n,
+});
+
+const profile = getJettonImplementationProfile("jetton-2.0");
+if (!profile.supportsCustomTransferPayload) {
+	throw new Error("This deployment does not support custom transfer payloads");
+}
+```
+
+Jetton layouts are not interchangeable. Select the deployment profile explicitly: `jetton-1.0`, `discoverable`, `stablecoin`, `notcoin`, `mintless`, or `jetton-2.0`. The profile is capability metadata; it does not pretend that a custom product contract is a standard Jetton.
+
+Use the official `JettonWallet.create(walletAddress)` for the canonical balance reader. Use the package’s `JettonWalletContract.create(walletAddress)` when you also need `getWalletData`, `sendTransfer`, or `sendBurn`. Validate token decimals with `parseJettonAmount` before building a payload.
+
+## NFTs
+
+The NFT entry point models standard collection and item layers independently. It supports default collection/item messages, content codecs, TEP-66 royalty parameters, SBT capability metadata, single-item capability metadata, and compressed/cNFT capability metadata.
+
+```ts
+import { Address, beginCell } from "@ton/core";
+import {
+	NftItemContract,
+	NFT_IMPLEMENTATION_PROFILES,
+	buildNftTransferBody,
+	nftContentToCell,
+} from "@pizzaton/ton/nft";
+
+const owner = Address.parse("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c");
+const item = NftItemContract.create(owner);
+const itemData = await item.getData(provider.contractProvider(item.address));
+
+const metadata = nftContentToCell({ type: "offchain", uri: "ipfs://example/1.json" });
+const transferBody = buildNftTransferBody({
+	newOwner: owner,
+	responseDestination: owner,
+	forwardPayload: beginCell().storeUint(1, 32).endCell(),
+});
+
+const sbt = NFT_IMPLEMENTATION_PROFILES.sbt;
+if (!sbt.transferable) throw new Error("SBTs cannot be transferred");
+```
+
+Use `NftCollectionContract.createFromAddress` for an existing collection or `createFromConfig` with the verified collection code for deployment. Never reuse a collection or item code across versions without verifying its data layout and opcodes.
+
+## Wallet versions
+
+The wallet factory derives real contract addresses and state init for `v1r1`, `v1r2`, `v1r3`, `v2r1`, `v2r2`, `v3r1`, `v3r2`, `v4`, `v5beta`, and `v5r1`.
+
+```ts
+import { createTonWalletContract } from "@pizzaton/ton/wallet";
+
+const wallet = createTonWalletContract({
+	version: "v5r1",
+	publicKey: publicKeyBytes,
+	workchain: 0,
+	networkGlobalId: -239,
+	});
+
+const seqno = await wallet.getSeqno(provider.contractProvider(wallet.address));
+```
+
+The default is `v5r1`. Existing accounts must use their actual deployed version. Wallet private keys and signing are deliberately not handled by this package; keep them in an audited server or wallet flow.
+
+## Transactions and TON Connect
+
+Build a validated intent in shared/domain code, then convert it at the browser boundary.
+
+```ts
+import { Address, beginCell, toNano } from "@ton/core";
+import { createTransactionIntent } from "@pizzaton/ton/transactions";
+
+const intent = createTransactionIntent({
+	id: "launchpad-deposit-123",
+	validUntil: Math.floor(Date.now() / 1000) + 300,
+	messages: [
+		{
+			to: Address.parse("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c"),
+			value: toNano("0.1"),
+			body: beginCell().storeUint(0x12345678, 32).endCell(),
+			bounce: true,
+		},
+	],
+});
+```
+
+The validator enforces a non-empty id, a one-hour maximum lifetime, one to four messages, non-negative values, and the TON message amount range. `toTonConnectTransaction(intent, { network: "mainnet" })` returns the SDK’s current raw-message request shape with friendly addresses and base64 BoCs.
+
+```ts
+import { TonConnect } from "@tonconnect/sdk";
+import { createTonConnectAdapter } from "@pizzaton/ton/connect";
+
+const tonConnect = new TonConnect({ manifestUrl: "https://example.com/tonconnect-manifest.json" });
+const ton = createTonConnectAdapter(tonConnect, "mainnet");
+
+ton.connect({
+	universalLink: "https://app.tonkeeper.com/ton-connect",
+	bridgeUrl: "https://connect.ton.org/bridge",
+});
+const wallet = ton.getWallet();
+const broadcastedBoc = await ton.sendTransaction(intent);
+```
+
+The adapter checks that a wallet is connected and that its chain id matches the selected network. React applications can use `useTonWallet(adapter)` and `useTonTransaction(adapter)` from `@pizzaton/ton/react`; the transaction hook exposes `send`, `status`, `boc`, `error`, and `reset`.
+
+## Native transaction simulation
+
+The preferred simulator is native `@ton/sandbox` execution. It can run against a local blockchain or a pinned live-state snapshot hydrated through `TonClient4`; it does not call TonAPI for the primary path.
+
+### Local sandbox preview
+
+```ts
+import { beginCell, type Message, toNano } from "@ton/core";
+import { createTonEmulator } from "@pizzaton/ton/emulator";
+import { createTonSandboxSimulation } from "@pizzaton/ton/simulation";
+
+const emulator = await createTonEmulator();
+const sender = await emulator.treasury("preview-sender");
+const recipient = await emulator.treasury("preview-recipient");
+const simulation = createTonSandboxSimulation(emulator.blockchain);
+
+const message: Message = {
+	info: {
+		type: "internal",
+		ihrDisabled: true,
+		bounce: true,
+		bounced: false,
+		src: sender.address,
+		dest: recipient.address,
+		value: { coins: toNano("0.1") },
+		ihrFee: 0n,
+		forwardFee: 0n,
+		createdLt: 0n,
+		createdAt: 0,
+	},
+	body: beginCell().endCell(),
+};
+
+const result = await simulation.simulate({ message });
+console.log(result.success, result.cost.totalFees, result.transactions);
+```
+
+Preview simulations restore the blockchain snapshot by default. Set `persist: true` only for an intentional local state transition. Set `recordStorage: false` when storage cell diffs are not needed and throughput matters.
+
+### Live-state native preview
+
+```ts
+import { createTonClient4SandboxSimulation } from "@pizzaton/ton/simulation";
+
+const simulation = await createTonClient4SandboxSimulation({
+	endpoint: process.env.TON_CLIENT4_ENDPOINT!,
+	blockSeqno: pinnedMasterchainSeqno,
+	recordStorage: true,
+});
+
+// Use the exact external wallet message BoC produced by the wallet/signing flow.
+const result = await simulation.simulate({
+	message: externalMessageCell,
+	ignoreSignatureCheck: false,
+});
+```
+
+The simulator exposes a normalized result containing:
+
+- transaction hashes, logical time, account id, timestamps, statuses, success, exit codes, and action success;
+- parent/child transaction relationships and input/output message paths;
+- total, storage, gas, forwarding, and action fees as `bigint`;
+- gas usage and VM step counts;
+- blockchain, VM, and debug logs;
+- old/new storage cells when storage recording is enabled.
+
+Simulation is an estimate of the pinned snapshot, not a guarantee about a later live-chain execution. Account balances, configuration, libraries, fees, and contract state can change before a wallet signs or broadcasts. For external wallet messages, pass a serialized `Cell`/BoC so the wallet version, body, state init, and signature shape are the ones actually being analyzed.
+
+### Optional TonAPI fallback
+
+```ts
+import {
+	createTonApiSimulationFallback,
+	createTonClient4SandboxSimulation,
+	createTonSimulationWithFallback,
+} from "@pizzaton/ton/simulation";
+
+const native = await createTonClient4SandboxSimulation({
+	endpoint: process.env.TON_CLIENT4_ENDPOINT!,
+});
+const fallback = createTonApiSimulationFallback({
+	apiKey: process.env.TONAPI_KEY,
+});
+const simulator = createTonSimulationWithFallback(native, fallback);
+const result = await simulator.simulate({ message: externalMessageCell });
+```
+
+The fallback is explicit and only runs when the primary adapter cannot produce a result. A legitimate simulated contract failure is returned as a result and is not hidden by fallback behavior.
+
+## Emulator adapter
+
+Use `@pizzaton/ton/emulator` for deterministic contract tests and local workflows:
+
+```ts
+import { createTonEmulator } from "@pizzaton/ton/emulator";
+
+const emulator = await createTonEmulator();
+const treasury = await emulator.treasury("test-account");
+const snapshot = emulator.snapshot();
+
+// Open contracts, call get methods, or send a real Message/Cell here.
+emulator.setTime(1_700_000_000);
+await emulator.loadFrom(snapshot);
+```
+
+Use `sendMessageIter` when a test needs to observe each transaction as it is produced. Use `openContract` and `provider` to inject sandbox dependencies into contract wrappers.
+
+## Airdrops and vesting
+
+### Merkle airdrops
+
+```ts
+import { createMerkleTree, verifyMerkleProof } from "@pizzaton/ton/airdrop";
+
+const tree = await createMerkleTree([
+	{ account: "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c", amount: 1_000n },
+]);
+const proof = await tree.proofFor("EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c");
+const valid = await verifyMerkleProof(
+	{ account: "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c", amount: 1_000n },
+	proof,
+	tree.root,
+);
+```
+
+Entries are canonicalized to raw addresses, sorted deterministically, and checked for duplicate accounts and negative amounts. Persist the root and the exact leaf encoding used by the distribution process.
+
+### Vesting
+
+```ts
+import { claimableAmount, unlockedAmount } from "@pizzaton/ton/vesting";
+
+const schedule = {
+	totalAmount: 1_000_000n,
+	startTime: 1_700_000_000,
+	cliffDuration: 86_400,
+	duration: 365 * 86_400,
+};
+
+const unlocked = unlockedAmount(schedule, 1_750_000_000);
+const claimable = claimableAmount(schedule, 100_000n, 1_750_000_000);
+```
+
+All calculations use integer arithmetic. Validate schedule boundaries before persisting them or constructing a contract message.
+
+## Versioning and extension policy
+
+TON standards often have multiple deployed implementations with similar interfaces but incompatible code, data, or capabilities. This package therefore uses explicit profiles and versioned modules rather than guessing from a friendly name.
+
+- Jettons: legacy, discoverable, stablecoin, Notcoin, Mintless, and Jetton 2.0 profiles.
+- NFTs: default, compressed/cNFT, SBT, and single-item profiles.
+- Wallets: V1R1 through V5R1, including V5 Beta.
+- Arbitrary or PizzaTon-specific contracts: add a verified versioned module when the authoritative code, ABI/layout, and deployment rules are available.
+
+The package does not claim that a generic standard wrapper supports product-specific extensions. Add those extensions as separate modules with their own tests and profile capabilities.
+
+Merkle airdrop roots use a package-defined leaf encoding (`raw-address:decimal-amount`), sorted raw addresses, ordered left/right pair hashing, and duplicate-last handling for odd levels. Airdrop contract implementations must use this exact encoding or provide their own proof builder; TON does not define one universal airdrop Merkle format.
+
+## Production checklist
+
+1. Pin the network explicitly (`mainnet` or `testnet`) and validate endpoint configuration with `createNetworkConfig`.
+2. Keep RPC/API keys and private keys server-side; never expose them in a browser bundle.
+3. Treat all addresses, metadata, amounts, payloads, and external messages as untrusted input at application boundaries.
+4. Select the deployed wallet, Jetton, and NFT version explicitly when it is not known from trusted deployment metadata.
+5. Simulate the exact serialized external message whenever possible, then re-check balances and state immediately before signing.
+6. Treat simulation fees and paths as estimates; execution is asynchronous and state may change.
+7. Use `TonPackageError` codes for recoverable validation handling and preserve provider errors for observability.
+8. Add parity tests for every product-specific contract before enabling writes in production.
+
+## Type safety and testing
+
+The package is compiled with `strict`, `noUncheckedIndexedAccess`, `noUnusedLocals`, `noUnusedParameters`, `isolatedModules`, and `exactOptionalPropertyTypes`. Public APIs use explicit generics, discriminated unions, `bigint`, `readonly` collections, and `unknown` at untrusted boundaries instead of `any`.
+
+Run the package checks from the repository root:
+
+```bash
+bunx biome check packages/ton
+bunx tsc --noEmit -p packages/ton/tsconfig.json
+bun test packages/ton/src
+```
+
+The tests execute real sandbox transactions and validate standard payload encodings, metadata, airdrop proofs, vesting math, wallet address derivation, provider-facing contracts, and simulation rollback. Network-dependent tests should remain opt-in and use a pinned endpoint/configuration.
+
+## Source of truth
+
+Standard behavior must be verified against the deployed contract code and current TON specifications. When a contract differs from a standard implementation, provide its authoritative source or verified artifact and add a dedicated versioned module rather than extending a standard wrapper implicitly.

package/dist/airdrop/index.d.mts

@@ -0,0 +1,18 @@
+//#region src/airdrop/index.d.ts
+export interface AirdropEntry {
+  readonly account: string;
+  readonly amount: bigint;
+}
+export interface MerkleProof {
+  readonly leaf: string;
+  readonly siblings: readonly string[];
+  readonly index: number;
+}
+export interface MerkleTree {
+  readonly root: string;
+  readonly entries: readonly AirdropEntry[];
+  proofFor(account: string): Promise<MerkleProof>;
+}
+export declare function createMerkleTree(entries: readonly AirdropEntry[]): Promise<MerkleTree>;
+export declare function verifyMerkleProof(entry: AirdropEntry, proof: MerkleProof, root: string): Promise<boolean>;
+//#endregion

package/dist/airdrop/index.mjs

@@ -0,0 +1,86 @@
+import { invariant } from "../core/errors.mjs";
+import { toTonAddress } from "../core/address.mjs";
+import { bytesToHex, hexToBytes } from "../core/bytes.mjs";
+import { sha256 } from "@ton/crypto";
+//#region src/airdrop/index.ts
+async function createMerkleTree(entries) {
+	invariant(entries.length > 0, "INVALID_PROOF", "A Merkle tree needs at least one entry");
+	const normalizedEntries = entries.map((entry) => ({
+		...entry,
+		account: toTonAddress(entry.account)
+	})).sort((left, right) => left.account < right.account ? -1 : left.account > right.account ? 1 : 0);
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of normalizedEntries) {
+		invariant(entry.amount >= 0n, "INVALID_AMOUNT", "Airdrop amounts cannot be negative");
+		invariant(!seen.has(entry.account), "INVALID_PROOF", "Airdrop accounts must be unique");
+		seen.add(entry.account);
+	}
+	const normalized = Object.freeze(normalizedEntries.map((entry) => Object.freeze(entry)));
+	const leafHashes = await Promise.all(normalized.map(hashEntry));
+	const levels = [leafHashes];
+	while (true) {
+		const current = levels.at(-1);
+		invariant(current !== void 0, "INVALID_PROOF", "Merkle levels are malformed");
+		if (current.length <= 1) break;
+		const next = [];
+		for (let index = 0; index < current.length; index += 2) {
+			const left = current[index];
+			const right = current[index + 1] ?? left;
+			invariant(left !== void 0 && right !== void 0, "INVALID_PROOF", "Merkle level is malformed");
+			next.push(await hashPair(left, right));
+		}
+		levels.push(next);
+	}
+	return Object.freeze({
+		root: levels[levels.length - 1]?.[0] ?? "",
+		entries: normalized,
+		async proofFor(account) {
+			const canonicalAccount = toTonAddress(account);
+			const index = normalized.findIndex((entry) => entry.account === canonicalAccount);
+			invariant(index >= 0, "INVALID_PROOF", "Airdrop account is not in the tree");
+			const siblings = [];
+			let currentIndex = index;
+			for (let level = 0; level < levels.length - 1; level += 1) {
+				const nodes = levels[level] ?? [];
+				const sibling = nodes[currentIndex % 2 === 0 ? currentIndex + 1 : currentIndex - 1] ?? nodes[currentIndex];
+				invariant(sibling !== void 0, "INVALID_PROOF", "Merkle sibling is missing");
+				siblings.push(sibling);
+				currentIndex = Math.floor(currentIndex / 2);
+			}
+			return {
+				leaf: leafHashes[index] ?? "",
+				siblings,
+				index
+			};
+		}
+	});
+}
+async function verifyMerkleProof(entry, proof, root) {
+	try {
+		if (await hashEntry(entry) !== proof.leaf || !Number.isSafeInteger(proof.index) || proof.index < 0) return false;
+		let current = proof.leaf;
+		let index = proof.index;
+		for (const sibling of proof.siblings) {
+			current = await hashPair(index % 2 === 0 ? current : sibling, index % 2 === 0 ? sibling : current);
+			index = Math.floor(index / 2);
+		}
+		return current === root;
+	} catch {
+		return false;
+	}
+}
+async function hashEntry(entry) {
+	invariant(entry.amount >= 0n, "INVALID_AMOUNT", "Airdrop amounts cannot be negative");
+	return bytesToHex(await sha256(`${toTonAddress(entry.account)}:${entry.amount.toString()}`));
+}
+async function hashPair(left, right) {
+	const leftBytes = hexToBytes(left);
+	const rightBytes = hexToBytes(right);
+	invariant(leftBytes.length === 32 && rightBytes.length === 32, "INVALID_PROOF", "Merkle node hashes must be 32 bytes");
+	const pair = /* @__PURE__ */ new Uint8Array(64);
+	pair.set(leftBytes);
+	pair.set(rightBytes, leftBytes.length);
+	return bytesToHex(await sha256(Buffer.from(pair)));
+}
+//#endregion
+export { createMerkleTree, verifyMerkleProof };

package/dist/connect/errors.d.mts

@@ -0,0 +1,4 @@
+//#region src/connect/errors.d.ts
+/** Converts TonConnect/provider errors into safe, user-facing copy. */
+export declare function readableTonConnectError(error: unknown, fallback?: string): string;
+//#endregion

package/dist/connect/errors.mjs

@@ -0,0 +1,21 @@
+//#region src/connect/errors.ts
+const USER_REJECTED_PATTERNS = [
+	"user rejects the action",
+	"user declined",
+	"user rejected",
+	"rejected by the user",
+	"action rejected"
+];
+/** Converts TonConnect/provider errors into safe, user-facing copy. */
+function readableTonConnectError(error, fallback = "The wallet could not complete this request.") {
+	const message = error instanceof Error ? error.message.trim() : "";
+	const normalized = message.toLowerCase();
+	if (USER_REJECTED_PATTERNS.some((pattern) => normalized.includes(pattern))) return "Transaction cancelled in your wallet.";
+	if (normalized.includes("manifest") || normalized.includes("tonconnect")) return "Wallet connection is temporarily unavailable. Please try again.";
+	if (normalized.includes("network") || normalized.includes("timeout") || normalized.includes("timed out")) return "The network took too long to respond. Please try again.";
+	if (normalized.includes("insufficient") || normalized.includes("not enough") || normalized.includes("balance")) return "Your wallet balance is not enough for this transaction and its network fee.";
+	if (!message || normalized === "unknown error occurred") return fallback;
+	return fallback;
+}
+//#endregion
+export { readableTonConnectError };

package/dist/connect/index.d.mts

@@ -0,0 +1,23 @@
+import { TonNetwork } from "../core/network.mjs";
+import { TonConnectTransaction, TransactionIntent } from "../transactions/index.mjs";
+import { readableTonConnectError } from "./errors.mjs";
+import { Account, ITonConnect, WalletConnectionSource } from "@tonconnect/sdk";
+//#region src/connect/index.d.ts
+export declare const TON_CONNECT_CHAIN_IDS: {
+  readonly mainnet: "-239";
+  readonly testnet: "-3";
+};
+export type TonConnectWallet = Pick<Account, "address" | "chain">;
+export type TonConnectClient = Pick<ITonConnect, "account" | "connect" | "disconnect" | "onStatusChange" | "sendTransaction" | "setConnectionNetwork">;
+export interface TonConnectAdapter {
+  readonly network: TonNetwork;
+  getWallet(): TonConnectWallet | null;
+  connect(source: WalletConnectionSource): string | undefined;
+  subscribe(listener: (wallet: TonConnectWallet | null) => void): () => void;
+  disconnect(): Promise<void>;
+  sendTransaction(intent: TransactionIntent): Promise<string>;
+}
+export declare function createTonConnectAdapter(client: TonConnectClient, network: TonNetwork): TonConnectAdapter;
+export declare function toWalletTransaction(intent: TransactionIntent, network: TonNetwork, now?: number): TonConnectTransaction;
+//#endregion
+export { readableTonConnectError };

package/dist/connect/index.mjs

@@ -0,0 +1,34 @@
+import { toTonConnectTransaction } from "../transactions/index.mjs";
+import { readableTonConnectError } from "./errors.mjs";
+//#region src/connect/index.ts
+const TON_CONNECT_CHAIN_IDS = {
+	mainnet: "-239",
+	testnet: "-3"
+};
+function createTonConnectAdapter(client, network) {
+	client.setConnectionNetwork(TON_CONNECT_CHAIN_IDS[network]);
+	return {
+		network,
+		getWallet: () => client.account,
+		connect: (source) => {
+			const result = client.connect(source);
+			return typeof result === "string" ? result : void 0;
+		},
+		subscribe: (listener) => client.onStatusChange((wallet) => listener(wallet?.account ?? null)),
+		disconnect: () => client.disconnect(),
+		async sendTransaction(intent) {
+			const wallet = client.account;
+			if (!wallet) throw new Error("A TON wallet must be connected before sending a transaction");
+			if (wallet.chain !== TON_CONNECT_CHAIN_IDS[network]) throw new Error(`Connected wallet is not on the ${network} network`);
+			return (await client.sendTransaction(toTonConnectTransaction(intent, { network }))).boc;
+		}
+	};
+}
+function toWalletTransaction(intent, network, now) {
+	return toTonConnectTransaction(intent, now === void 0 ? { network } : {
+		network,
+		now
+	});
+}
+//#endregion
+export { TON_CONNECT_CHAIN_IDS, createTonConnectAdapter, readableTonConnectError, toWalletTransaction };