TON-858: tonapi emulation

.changeset/tonapi-emulation-domain-models.md

@@ -0,0 +1,7 @@
+---
+'@ton/walletkit': patch
+'@ton/appkit': patch
+'@ton/mcp': patch
+---
+
+Added emulation support to the TonAPI client and introduced provider-agnostic emulation domain models under `api/models/emulation` (`EmulationResult`, `EmulationResponse`, `EmulationTransaction`, `EmulationMessage`, `EmulationAction`, `EmulationTraceNode`, `EmulationAddressBookEntry`). `ApiClient.fetchEmulation` now returns `EmulationResult` instead of the toncenter-specific `ToncenterEmulationResult`, so callers get the same shape regardless of backend. Reorganized toncenter raw types under `clients/toncenter/types/*` (NFTs, jettons, DNS, metadata, raw emulation), moved the `ApiClient` interface to `api/interfaces`, removed legacy emulation parsing utilities (`utils/toncenterEmulation`, message/jetton parser handlers), and migrated optional NFT and DNS results from `null` to `undefined` across walletkit, appkit, and mcp.

packages/appkit/src/actions/nft/get-nft.ts

@@ -19,7 +19,7 @@ export interface GetNftOptions {
     network?: Network;
 }
 
-export type GetNftReturnType = NFT | null;
+export type GetNftReturnType = NFT | undefined;
 
 export const getNft = async (appKit: AppKit, options: GetNftOptions): Promise<GetNftReturnType> => {
     const { address, network } = options;

packages/appkit/src/queries/nft/get-nft.ts

@@ -41,7 +41,7 @@ export const getNftQueryOptions = <selectData = GetNftData>(
     };
 };
 
-export type GetNftQueryFnData = Compute<NFT | null>;
+export type GetNftQueryFnData = Compute<NFT | undefined>;
 
 export type GetNftData = GetNftQueryFnData;
 

packages/mcp/src/services/McpWalletService.ts

@@ -1104,15 +1104,17 @@ export class McpWalletService {
      */
     async resolveDns(domain: string): Promise<string | null> {
         const client = this.wallet.getClient();
-        return client.resolveDnsWallet(domain);
+        const address = await client.resolveDnsWallet(domain);
+        return address ?? null;
     }
 
     /**
      * Reverse resolve a wallet address to a TON DNS domain
      */
     async backResolveDns(address: string): Promise<string | null> {
         const client = this.wallet.getClient();
-        return client.backResolveDnsWallet(address);
+        const domain = await client.backResolveDnsWallet(address);
+        return domain ?? null;
     }
 
     /**

packages/walletkit-android-bridge/src/adapters/AndroidAPIClientAdapter.ts

@@ -19,7 +19,7 @@ import type {
     TransactionsResponse,
     JettonsResponse,
     FullAccountState,
-    ToncenterEmulationResult,
+    EmulationResult,
     ToncenterResponseJettonMasters,
     ToncenterTracesResponse,
     TransactionsByAddressRequest,
@@ -139,7 +139,7 @@ export class AndroidAPIClientAdapter implements ApiClient {
         throw new Error('nftItemsByOwner is not implemented yet');
     }
 
-    async fetchEmulation(_messageBoc: Base64String, _ignoreSignature?: boolean): Promise<ToncenterEmulationResult> {
+    async fetchEmulation(_messageBoc: Base64String, _ignoreSignature?: boolean): Promise<EmulationResult> {
         throw new Error('fetchEmulation is not implemented yet');
     }
 
@@ -179,11 +179,11 @@ export class AndroidAPIClientAdapter implements ApiClient {
         throw new Error('getPendingTrace is not implemented yet');
     }
 
-    async resolveDnsWallet(_domain: string): Promise<string | null> {
+    async resolveDnsWallet(_domain: string): Promise<string | undefined> {
         throw new Error('resolveDnsWallet is not implemented yet');
     }
 
-    async backResolveDnsWallet(_address: UserFriendlyAddress): Promise<string | null> {
+    async backResolveDnsWallet(_address: UserFriendlyAddress): Promise<string | undefined> {
         throw new Error('backResolveDnsWallet is not implemented yet');
     }
 

packages/walletkit-ios-bridge/src/SwiftAPIClientAdapter.ts

@@ -19,7 +19,7 @@ import type {
     TransactionsResponse,
     JettonsResponse,
     FullAccountState,
-    ToncenterEmulationResult,
+    EmulationResult,
     ToncenterResponseJettonMasters,
     ToncenterTracesResponse,
     TransactionsByAddressRequest,
@@ -62,7 +62,7 @@ export class SwiftAPIClientAdapter implements ApiClient {
         throw new Error('nftItemsByOwner is not implemented yet');
     }
 
-    async fetchEmulation(_messageBoc: Base64String, _ignoreSignature?: boolean): Promise<ToncenterEmulationResult> {
+    async fetchEmulation(_messageBoc: Base64String, _ignoreSignature?: boolean): Promise<EmulationResult> {
         throw new Error('fetchEmulation is not implemented yet');
     }
 
@@ -94,11 +94,11 @@ export class SwiftAPIClientAdapter implements ApiClient {
         throw new Error('getPendingTrace is not implemented yet');
     }
 
-    async resolveDnsWallet(_domain: string): Promise<string | null> {
+    async resolveDnsWallet(_domain: string): Promise<string | undefined> {
         throw new Error('resolveDnsWallet is not implemented yet');
     }
 
-    async backResolveDnsWallet(_address: UserFriendlyAddress): Promise<string | null> {
+    async backResolveDnsWallet(_address: UserFriendlyAddress): Promise<string | undefined> {
         throw new Error('backResolveDnsWallet is not implemented yet');
     }
 

packages/walletkit/package.json

@@ -85,6 +85,7 @@
     "build:esm": "tsc -p tsconfig.esm.json",
     "dev": "tsc -p tsconfig.esm.json --watch",
     "test": "vitest run",
+
     "test:coverage": "vitest run --coverage",
     "test:mutation": "stryker run stryker.config.js",
     "quality": "pnpm test:coverage",

packages/walletkit/src/types/toncenter/ApiClient.ts → packages/walletkit/src/api/interfaces/ApiClient.ts

@@ -8,9 +8,9 @@
 
 import type { Address } from '@ton/core';
 
-import type { ToncenterResponseJettonMasters, ToncenterTracesResponse } from './emulation';
-import type { FullAccountState } from './api';
-import type { Event } from './AccountEvent';
+import type { ToncenterResponseJettonMasters, ToncenterTracesResponse } from '../../types/toncenter/emulation';
+import type { FullAccountState } from '../../types/toncenter/api';
+import type { Event } from '../../types/toncenter/AccountEvent';
 import type {
     Base64String,
     UserNFTsRequest,
@@ -23,8 +23,8 @@ import type {
     RawStackItem,
     GetMethodResult,
     MasterchainInfo,
-} from '../../api/models';
-import type { ToncenterEmulationResult } from '../../utils/toncenterEmulation';
+} from '../models';
+import type { EmulationResult } from '../models';
 
 export interface LimitRequest {
     limit?: number;
@@ -97,7 +97,7 @@ export interface GetEventsResponse {
 export interface ApiClient {
     nftItemsByAddress(request: NFTsRequest): Promise<NFTsResponse>;
     nftItemsByOwner(request: UserNFTsRequest): Promise<NFTsResponse>;
-    fetchEmulation(messageBoc: Base64String, ignoreSignature?: boolean): Promise<ToncenterEmulationResult>;
+    fetchEmulation(messageBoc: Base64String, ignoreSignature?: boolean): Promise<EmulationResult>;
     sendBoc(boc: Base64String): Promise<string>;
     runGetMethod(
         address: UserFriendlyAddress,
@@ -116,8 +116,8 @@ export interface ApiClient {
     getTrace(request: GetTraceRequest): Promise<ToncenterTracesResponse>;
     getPendingTrace(request: GetPendingTraceRequest): Promise<ToncenterTracesResponse>;
 
-    resolveDnsWallet(domain: string): Promise<string | null>;
-    backResolveDnsWallet(address: UserFriendlyAddress): Promise<string | null>;
+    resolveDnsWallet(domain: string): Promise<string | undefined>;
+    backResolveDnsWallet(address: UserFriendlyAddress): Promise<string | undefined>;
 
     jettonsByAddress(request: GetJettonsByAddressRequest): Promise<ToncenterResponseJettonMasters>;
     jettonsByOwnerAddress(request: GetJettonsByOwnerRequest): Promise<JettonsResponse>;

packages/walletkit/src/api/interfaces/Wallet.ts

@@ -6,7 +6,7 @@
  *
  */
 
-import type { ApiClient } from '../../types/toncenter/ApiClient';
+import type { ApiClient } from './ApiClient';
 import type {
     TokenAmount,
     TONTransferRequest,
@@ -52,5 +52,5 @@ export interface WalletNftInterface {
     createTransferNftTransaction(params: NFTTransferRequest): Promise<TransactionRequest>;
     createTransferNftRawTransaction(params: NFTRawTransferRequest): Promise<TransactionRequest>;
     getNfts(params: NFTsRequest): Promise<NFTsResponse>;
-    getNft(address: UserFriendlyAddress): Promise<NFT | null>;
+    getNft(address: UserFriendlyAddress): Promise<NFT | undefined>;
 }

packages/walletkit/src/api/interfaces/index.ts

@@ -22,3 +22,19 @@ export type { TONConnectSessionManager } from './TONConnectSessionManager';
 // Streaming interfaces
 export type { StreamingProvider, StreamingProviderFactory } from './StreamingProvider';
 export type { StreamingAPI } from './StreamingAPI';
+
+export type {
+    LimitRequest,
+    NftItemsRequest,
+    NftItemsByOwnerRequest,
+    TransactionsByAddressRequest,
+    GetTransactionByHashRequest,
+    GetPendingTransactionsRequest,
+    GetTraceRequest,
+    GetPendingTraceRequest,
+    GetJettonsByOwnerRequest,
+    GetJettonsByAddressRequest,
+    GetEventsRequest,
+    GetEventsResponse,
+    ApiClient,
+} from './ApiClient';

packages/walletkit/src/api/models/emulation/EmulationAction.ts

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { UserFriendlyAddress, LogicalTime, Hex } from '../core/Primitives';
+
+/**
+ * High-level action extracted from an emulated transaction trace.
+ */
+export interface EmulationAction {
+    /**
+     * Trace identifier this action belongs to
+     */
+    traceId?: string;
+
+    /**
+     * Hex-encoded unique identifier of the action
+     */
+    actionId: Hex;
+
+    /**
+     * Logical time when the action started
+     */
+    startLt: LogicalTime;
+
+    /**
+     * Logical time when the action ended
+     */
+    endLt: LogicalTime;
+
+    /**
+     * Unix timestamp when the action started
+     * @format timestamp
+     */
+    startUtime: number;
+
+    /**
+     * Unix timestamp when the action ended
+     * @format timestamp
+     */
+    endUtime: number;
+
+    /**
+     * Logical time when the trace ended
+     */
+    traceEndLt: LogicalTime;
+
+    /**
+     * Unix timestamp when the trace ended
+     * @format timestamp
+     */
+    traceEndUtime: number;
+
+    /**
+     * Masterchain block sequence number when the trace ended
+     * @format int
+     */
+    traceMcSeqnoEnd: number;
+
+    /**
+     * Hex-encoded hashes of transactions involved in this action
+     */
+    transactions: Hex[];
+
+    /**
+     * Whether the action completed successfully
+     */
+    isSuccess: boolean;
+
+    /**
+     * Action type identifier (e.g. "jetton_transfer", "ton_transfer", "jetton_swap")
+     */
+    type: string;
+
+    /**
+     * Hex-encoded external message hash of the root trace
+     */
+    traceExternalHash: Hex;
+
+    /**
+     * Addresses of accounts involved in this action
+     */
+    accounts: UserFriendlyAddress[];
+
+    /**
+     * Action-specific detail fields keyed by name
+     */
+    details: { [key: string]: unknown };
+}

packages/walletkit/src/api/models/emulation/EmulationAddressBookEntry.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { UserFriendlyAddress } from '../core/Primitives';
+
+/**
+ * Address book entry providing human-readable metadata for an on-chain address.
+ */
+export interface EmulationAddressBookEntry {
+    /**
+     * DNS domain name associated with the address, if any
+     */
+    domain?: string;
+
+    /**
+     * User-friendly representation of the address
+     */
+    userFriendly: UserFriendlyAddress;
+
+    /**
+     * List of known interfaces implemented by the contract
+     */
+    interfaces: string[];
+}