TON-858: tonapi emulation

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');
     }
 

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');
     }
 

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/emulation';
 
 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,

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,

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 | null;
+
+    /**
+     * 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: Record<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[];
+}

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

@@ -0,0 +1,122 @@
+/**
+ * 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, Base64String } from '../core/Primitives';
+import type { TokenAmount } from '../core/TokenAmount';
+import type { ExtraCurrencies } from '../core/ExtraCurrencies';
+
+/**
+ * Message sent or received within an emulated transaction trace.
+ */
+export interface EmulationMessage {
+    /**
+     * Hex-encoded hash of the message
+     */
+    hash: Hex;
+
+    /**
+     * Hex-encoded normalized hash used for deduplication across message variants
+     */
+    normalizedHash?: Hex;
+
+    /**
+     * Source address of the message, or null for external inbound messages
+     */
+    source: UserFriendlyAddress | null;
+
+    /**
+     * Destination address of the message
+     */
+    destination: UserFriendlyAddress;
+
+    /**
+     * Amount of nanotons transferred, or null for external inbound messages
+     */
+    value: TokenAmount | null;
+
+    /**
+     * Extra currencies transferred with the message
+     */
+    valueExtraCurrencies: ExtraCurrencies;
+
+    /**
+     * Forwarding fee in nanotons, or null for external inbound messages
+     */
+    fwdFee: TokenAmount | null;
+
+    /**
+     * IHR (Instant Hypercube Routing) fee in nanotons, or null for external inbound messages
+     */
+    ihrFee: TokenAmount | null;
+
+    /**
+     * Logical time when the message was created, or null for external inbound messages
+     */
+    createdLt: LogicalTime | null;
+
+    /**
+     * Unix timestamp when the message was created, or null for external inbound messages
+     * @format timestamp
+     */
+    createdAt: number | null;
+
+    /**
+     * Hex-encoded opcode from the message body, if present
+     */
+    opcode: Hex | null;
+
+    /**
+     * Whether IHR delivery is disabled, or null for external inbound messages
+     */
+    ihrDisabled: boolean | null;
+
+    /**
+     * Whether the message requested a bounce on failure, or null for external inbound messages
+     */
+    isBounce: boolean | null;
+
+    /**
+     * Whether the message was bounced back, or null for external inbound messages
+     */
+    isBounced: boolean | null;
+
+    /**
+     * Import fee paid for delivering an external inbound message, null for all other message types
+     */
+    importFee: TokenAmount | null;
+
+    /**
+     * Decoded content of the message body
+     */
+    messageContent: EmulationMessageContent;
+
+    /**
+     * Initial state (StateInit) attached to the message, if any
+     */
+    initState: unknown | null;
+}
+
+/**
+ * Decoded content of an emulation message body.
+ */
+export interface EmulationMessageContent {
+    /**
+     * Hex-encoded hash of the message content, or null if not available
+     */
+    hash: Hex | null;
+
+    /**
+     * Message body in BOC base64 format, or null if not available
+     */
+    body: Base64String | null;
+
+    /**
+     * Structured decoded representation of the message body, if available
+     */
+    decoded: unknown | null;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * 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 { Hex, Base64String } from '../core/Primitives';
+import type { EmulationAction } from './EmulationAction';
+import type { EmulationAddressBookEntry } from './EmulationAddressBookEntry';
+import type { EmulationTraceNode } from './EmulationTraceNode';
+import type { EmulationTransaction } from './EmulationTransaction';
+
+/**
+ * Unified emulation response model, normalised from either Toncenter or TonAPI sources.
+ */
+export interface EmulationResponse {
+    /**
+     * Masterchain block sequence number used during emulation
+     * @format int
+     */
+    mcBlockSeqno: number;
+
+    /**
+     * Root node of the transaction execution tree
+     */
+    trace: EmulationTraceNode;
+
+    /**
+     * Map of transaction hashes to transaction details
+     */
+    transactions: Record<string, EmulationTransaction>;
+
+    /**
+     * High-level actions extracted from the trace
+     */
+    actions: EmulationAction[];
+
+    /**
+     * Random seed used during emulation, hex-encoded
+     */
+    randSeed: Hex;
+
+    /**
+     * Whether the trace is incomplete due to limits or errors
+     */
+    isIncomplete: boolean;
+
+    /**
+     * Map of code cell hashes to their BOC base64 representations
+     */
+    codeCells: Record<string, Base64String>;
+
+    /**
+     * Map of data cell hashes to their BOC base64 representations
+     */
+    dataCells: Record<string, Base64String>;
+
+    /**
+     * Address book mapping raw addresses to human-readable metadata
+     */
+    addressBook: Record<string, EmulationAddressBookEntry>;
+}