SDK Data Structures (Structs)

This file documents the primary data structures (types and interfaces often referred to as structs) used for configuration, data transfer, and results within the TAC SDK.

Core Data Structures

These structs are fundamental for configuring the SDK and initiating cross-chain transactions.

`SDKParams (Type)`

export type SDKParams = {
    network: Network;
    delay?: number;
    TACParams?: TACParams;
    TONParams?: TONParams;
    customLiteSequencerEndpoints?: string[];
    passLoggerToOpeners?: boolean;
}

Parameters for SDK:

network: Specifies TON network (Network type).
delay (optional): Delay in milliseconds between retry attempts when querying TON via the contract opener. Default is 0 ms.
TACParams (optional): Custom parameters for TAC side
TONParams (optional): Custom parameters for TON side
customLiteSequencerEndpoints (optional): Custom lite sequencer endpoints for API access.
passLoggerToOpeners (optional, default: true): Controls whether the logger passed to TacSdk.create is propagated to TON contractOpener(s). Set false to keep SDK-level logs while keeping openers silent.

`TONParams (Type)`

export type TONParams = {
    contractOpener?: ContractOpener;
    settingsAddress?: string;
    txFinalizer?: ITxFinalizer;
}

TON Parameters for SDK:

contractOpener (optional): Client used for TON smart contract interaction. Default is a RetryableContractOpener that combines TonClient (TAC endpoint), orbsOpener4, and orbsOpener as fallbacks. Provide your own opener primarily for tests or custom setups.
settingsAddress (optional): TON settings contract address. Needed to retrieve protocol data. Set for tests only.
txFinalizer (optional): TxFinalizer for tracking transaction tree. Used for advanced transaction tracking and verification.

`TACParams (Type)`

export type TACParams = {
    provider?: AbstractProvider;
    settingsAddress?: string;
    saFactoryAddress?: string;
}

TAC Parameters for SDK:

provider (optional): RPC EVM provider used for TAC smart contract interaction. Set custom provider for increasing RPC rate limit or for tests.
settingsAddress (optional): TAC settings contract address. Needed to retrieve protocol data. Set for tests only.
saFactoryAddress (optional): Address of TAC smart account factory contract. Set for tests only.

`ContractState (Type)`

export type ContractState = {
    balance: bigint;
    state: 'active' | 'uninitialized' | 'frozen';
    code: Buffer | null;
};

Represents the state of a TON smart contract:

balance: The contract's balance in nanoTONs.
state: The current state of the contract, which can be:
- active: The contract is deployed and active.
- uninitialized: The contract exists but has not been initialized.
- frozen: The contract is frozen (inactive).
code: The contract's code as a Buffer, or null if the contract has no code.

`ContractOpener (Interface)`

export interface ContractOpener {
    open<T extends Contract>(src: T): OpenedContract<T> | SandboxContract<T>;
    getContractState(address: Address): Promise<ContractState>;
    getTransactions(address: Address, opts: GetTransactionsOptions): Promise<Transaction[]>;
    closeConnections?: () => unknown;
    getTransactionByHash(address: Address, hash: string, opts?: GetTransactionsOptions): Promise<Transaction | null>;
    getTransactionByTxHash(address: Address, txHash: string, opts?: GetTransactionsOptions): Promise<Transaction | null>;
    getTransactionByInMsgHash(address: Address, inMsgHash: string, opts?: GetTransactionsOptions): Promise<Transaction | null>;
    getTransactionByOutMsgHash(address: Address, outMsgHash: string, opts?: GetTransactionsOptions): Promise<Transaction | null>;
    getAdjacentTransactions(address: Address, hash: string, opts?: GetTransactionsOptions): Promise<Transaction[]>;
    getAddressInformation(address: Address): Promise<AddressInformation>;
    getConfig(): Promise<string>;
    trackTransactionTree(address: string, hash: string, params?: TrackTransactionTreeParams): Promise<void>;
    trackTransactionTreeWithResult(address: string, hash: string, params?: TrackTransactionTreeParams): Promise<TrackTransactionTreeResult>;
}

Interface for opening and interacting with TON smart contracts:

open<T extends Contract>(src: T): Opens a contract for interaction, returning an OpenedContract or SandboxContract instance.
getContractState(address: Address): Retrieves the state of a contract at the specified address.
getTransactions(address: Address, opts: GetTransactionsOptions): Retrieves transactions for the specified address with pagination options.
closeConnections? (optional): Closes any open connections to the TON network.
getTransactionByHash(address: Address, hash: string, opts?: GetTransactionsOptions): Retrieves a transaction by its hash (transaction hash, incoming message hash, or outgoing message hash). Returns null if not found.
getTransactionByTxHash(address: Address, txHash: string, opts?: GetTransactionsOptions): Retrieves a transaction by its transaction hash specifically. Returns null if not found.
getTransactionByInMsgHash(address: Address, inMsgHash: string, opts?: GetTransactionsOptions): Retrieves a transaction by its incoming message hash. Returns null if not found.
getTransactionByOutMsgHash(address: Address, outMsgHash: string, opts?: GetTransactionsOptions): Retrieves a transaction by its outgoing message hash. Returns null if not found.
getAdjacentTransactions(address: Address, hash: string, opts?: GetTransactionsOptions): Retrieves transactions adjacent to the specified transaction hash (children and optionally parent).
getAddressInformation(address: Address): Retrieves address information including last transaction details.
getConfig(): Retrieves the blockchain configuration as a base64 encoded string.
trackTransactionTree(address: string, hash: string, params?: TrackTransactionTreeParams): Validates entire transaction tree using BFS, throws error if validation fails.
trackTransactionTreeWithResult(address: string, hash: string, params?: TrackTransactionTreeParams): Validates entire transaction tree using BFS, returns result object instead of throwing.

`RetryableContractOpener (Class)`

export interface OpenerConfig {
    opener: ContractOpener;
    retries: number;
    retryDelay: number;
}

export class RetryableContractOpener implements ContractOpener {
    constructor(openerConfigs: OpenerConfig[]);
    open<T extends Contract>(src: T): OpenedContract<T> | SandboxContract<T>;
    getContractState(address: Address): Promise<ContractState>;
    closeConnections(): void;
}

A resilient implementation of ContractOpener that provides retry capabilities and fallback mechanisms when interacting with TON contracts.

Constructor Parameters

openerConfigs: An array of OpenerConfig objects, each containing:
- opener: A ContractOpener instance.
- retries: Number of retry attempts for failed operations.
- retryDelay: Delay in milliseconds between retry attempts.

Methods

open<T extends Contract>(src: T): Opens a contract with retry capabilities. If the primary opener fails, it will automatically retry using the configured retry policy.
getContractState(address: Address): Retrieves contract state with retry capabilities. If the primary opener fails, it will try alternative openers according to the configured retry policy.
closeConnections(): Closes all connections across all configured openers.

Helper Functions

export async function createDefaultRetryableOpener(
    artifacts: typeof testnet | typeof mainnet,
    maxRetries = 3,
    retryDelay = 1000,
): Promise<ContractOpener>

Creates a default RetryableContractOpener with multiple fallback providers:

artifacts: Network artifacts (testnet or mainnet).
maxRetries (optional): Maximum number of retry attempts. Default is 3.
retryDelay (optional): Delay in milliseconds between retry attempts. Default is 1000.

Returns a RetryableContractOpener configured with:

TonClient by TAC (primary)
orbsOpener4 (first fallback)
orbsOpener (second fallback)

This function provides a convenient way to create a robust contract opener with sensible defaults for production use.

`GetTransactionsOptions (Type)`

export type GetTransactionsOptions = {
    limit?: number;
    lt?: string;
    hash?: string;
    to_lt?: string;
    inclusive?: boolean;
    archival?: boolean;
    timeoutMs?: number;
    retryDelayMs?: number;
};

Options for retrieving transactions from the blockchain with pagination and filtering capabilities.

limit (optional): Maximum number of transactions to retrieve.
lt (optional): Logical time of the transaction to start from (for pagination).
hash (optional): Hash of the transaction to start from (for pagination).
to_lt (optional): Logical time of the transaction to end at (upper bound).
inclusive (optional): Whether to include the starting transaction in the results.
archival (optional): Whether to search in archival nodes for historical data.
timeoutMs (optional): Request timeout in milliseconds.
retryDelayMs (optional): Delay between retry attempts in milliseconds.

`AddressInformation (Type)`

export type AddressInformation = {
    lastTransaction: {
        lt: string;
        hash: string;
    };
};

Contains information about an address on the TON blockchain.

lastTransaction: Information about the most recent transaction of the address.
- lt: Logical time of the last transaction.
- hash: Hash of the last transaction in base64 format.

`EvmProxyMsg (Type)`

export type EvmProxyMsg = {
    evmTargetAddress: string,
    methodName?: string,
    encodedParameters?: string,
    gasLimit?: bigint,
    [key: string]: unknown;
}

Represents a proxy message to a TAC.

evmTargetAddress: Target address on the EVM network.
methodName (optional): Method name to be called on the target contract. Either method name MethodName or signature MethodName(bytes,bytes) must be specified (strictly (bytes,bytes)).
encodedParameters (optional): Parameters for the method, encoded as a string.
gasLimit (optional): gasLimit is a parameter that will be passed on the TAC side. The executor must allocate at least gasLimit gas for executing the transaction on the TAC side. If this parameter is not specified, it will be calculated using the simulateTACMessage method(prefered).

This structure defines the logic you want to execute on the TAC side. This message is sent along with all the sharded messages related to the jetton bridging, enabling the TAC to process the intended logic on the TAC side during the crosschain transaction.

`CrossChainTransactionOptions`

An optional configuration object for customizing advanced crosschain transaction behavior.

export type CrossChainTransactionOptions = {
    allowSimulationError?: boolean;
    ensureTxExecuted?: boolean;
    shouldValidateFees?: boolean;
    isRoundTrip?: boolean;
    protocolFee?: bigint;
    evmValidExecutors?: string[];
    evmExecutorFee?: bigint;
    tvmValidExecutors?: string[];
    tvmExecutorFee?: bigint;
    calculateRollbackFee?: boolean;
    withoutSimulation?: boolean;
    validateAssetsBalance?: boolean;
    waitOperationId?: boolean;
    waitOptions?: WaitOptions<string>;
    evmDataBuilder?: evmDataBuilder;
};

allowSimulationError (optional):
If true, transaction simulation phase is skipped.
Default: false
ensureTxExecuted (optional):
If true, validates TON transaction execution before waiting for operation ID.
Default: true
shouldValidateFees (optional):
If true, validates explicitly provided fee params against suggested values.
Default: true
isRoundTrip (optional):
Indicates whether the transaction involves a round-trip execution (e.g., a return message from TAC to TON).
Default: will be determined by simulation.
protocolFee (optional):
An optional override for the protocol fee in bigint. If not specified, the SDK calculates this automatically based on network parameters.
evmValidExecutors (optional):
A list of EVM executor addresses that are allowed to execute this transaction on the TAC.
evmExecutorFee (optional):
Fee in bigint to be paid (in TON token) to the executor on the EVM side for executing the transaction.
tvmValidExecutors (optional):
A list of TVM (TON) executor addresses that are authorized to execute the message on the TON network.
tvmExecutorFee (optional):
Fee in bigint to be paid (in TON token) to the executor on the TON side.
calculateRollbackFee (optional):
Whether to calculate rollback fee during simulation.
Default: false
withoutSimulation (optional):
If true, skips the simulation phase entirely.
Default: false
validateAssetsBalance (optional):
If true, validates that the sender has sufficient balance for the specified assets before sending the transaction.
Default: true
waitOperationId (optional):
If true, waits for operation ID after sending the transaction. When false, the transaction is sent without waiting for operation tracking information.
Default: true
waitOptions (optional):
Custom waiting configuration for operation ID resolution. See WaitOptions for available options.
Default: {}
evmDataBuilder (optional):
Custom function to build the EVM data cell. Default: buildEvmDataCell

`BatchCrossChainTransactionOptions`

A restricted version of CrossChainTransactionOptions for use in batch operations.

export type BatchCrossChainTransactionOptions = Omit<CrossChainTransactionOptions, 'waitOperationId' | 'waitOptions' | 'ensureTxExecuted'>;

This type excludes waitOperationId, waitOptions, and ensureTxExecuted from individual transactions in batch operations, as these options are controlled at the batch level through CrossChainTransactionsOptions. All other options from CrossChainTransactionOptions are available for individual transactions within a batch.

`CrossChainTransactionsOptions`

Configuration options for batch cross-chain transaction operations.

export type CrossChainTransactionsOptions = {
    waitOperationIds?: boolean;
    waitOptions?: WaitOptions<OperationIdsByShardsKey>;
};

waitOperationIds (optional):
If true, waits for operation IDs for all transactions in the batch. When false, transactions are sent without waiting for operation tracking information.
Default: true
waitOptions (optional):
Custom waiting configuration for operation IDs resolution in batch operations. See WaitOptions for available options.
Default: {}

`CrosschainTx`

export type CrosschainTx = {
    evmProxyMsg: EvmProxyMsg;
    assets?: Asset[];
    options?: CrossChainTransactionOptions;
};

Represents a crosschain transaction.

evmProxyMsg: The message to be sent to the TAC proxy.
assets (optional): An array of assets involved in the transaction.
options (optional): Additional options for the transaction.

`BatchCrossChainTx`

export type BatchCrossChainTx = {
    evmProxyMsg: EvmProxyMsg;
    assets?: Asset[];
    options?: BatchCrossChainTransactionOptions;
};

Represents a crosschain transaction for use in batch operations.

evmProxyMsg: The message to be sent to the TAC proxy.
assets (optional): An array of assets involved in the transaction.
options (optional): Additional options for the transaction (excludes waitOperationId, waitOptions, and ensureTxExecuted which are controlled at batch level).

`AssetLike`

export type AssetLike =
    | Asset
    | FT
    | NFT
    | { rawAmount: bigint }
    | { amount: number }
    | { address: TVMAddress | EVMAddress }
    | { address: TVMAddress | EVMAddress; rawAmount: bigint }
    | { address: TVMAddress | EVMAddress; amount: number }
    | { address: TVMAddress | EVMAddress; itemIndex: bigint };

Represents various types of asset-like objects that can be used in cross-chain operations. This union type allows flexibility in specifying assets through different interfaces, supporting multiple formats for different asset types:

Native TON Assets

For native TON coin transfers, use one of these formats:

{ rawAmount: bigint }: Specify amount in raw base units (nanotons)
{ amount: number }: Specify amount in human-readable units (TON)

Examples:

// 1.5 TON in raw units (1.5 * 10^9 nanotons)
{ rawAmount: 1500000000n }

// 1.5 TON in human units
{ amount: 1.5 }

Fungible Token (FT) Assets

For FT tokens (Jettons), specify the token address and amount:

{ address: TVMAddress | EVMAddress; rawAmount: bigint }: Token address + raw amount
{ address: TVMAddress | EVMAddress; amount: number }: Token address + human-readable amount

Examples:

// USDT with raw amount (considering decimals)
{ address: "EQC_1YoM8RBixN95lz7odcF3Vrkc_N8Ne7gQi7Abtlet_Efi", rawAmount: 1000000n }

// USDT with human amount (1 USDT)
{ address: "EQC_1YoM8RBixN95lz7odcF3Vrkc_N8Ne7gQi7Abtlet_Efi", amount: 1 }

NFT Item Assets

For specific NFT items that have their own contract address:

{ address: TVMAddress | EVMAddress }: Just the NFT item address

Examples:

// Specific NFT item by its contract address
{ address: "EQBx1tKgO2QXj7vGi7VwK4uEINxwUbWxBFmJoW6gBZtCWcfG" }

NFT Collection Assets

For NFT items within a collection, specify collection address and item index:

{ address: TVMAddress | EVMAddress; itemIndex: bigint }: Collection address + specific item index

Examples:

// NFT item #42 from a collection
{ address: "EQD-cvR0Nz6XAyRBpUzoMAC1b4-jXqZtUgSxhFfHWA7xAPgm", itemIndex: 42n }

This flexible typing system allows you to work with assets in the most convenient format for your use case while maintaining type safety.

`BatchCrossChainTxWithAssetLike`

export type BatchCrossChainTxWithAssetLike = Omit<BatchCrossChainTx, 'assets'> & { assets?: AssetLike[] };

Represents a batch crosschain transaction using AssetLike objects instead of strict Asset instances. This provides more flexibility when working with different asset representations in batch operations, while ensuring that individual transactions cannot specify wait-related options (which are controlled at the batch level).

`CrossChainPayloadResult (Type)`

export type CrossChainPayloadResult = {
    body: Cell;
    destinationAddress: string;
    tonAmount: bigint;
    tonNetworkFee: bigint;
    tacEstimatedGas?: bigint;
    transactionLinker: TransactionLinker;
};

Represents a prepared transaction payload for a cross-chain operation, ready to be signed and sent.

body: The serialized message payload as a TON Cell, containing all transaction data and parameters
destinationAddress: Target contract address for this message (e.g., jetton wallet, NFT item, cross-chain layer)
tonAmount: Amount of TON to send with this message in nanotons (for asset transfer or contract interaction)
tonNetworkFee: Network fee for this specific message in nanotons
tacEstimatedGas (optional): Estimated gas required for TAC-side execution
transactionLinker: Transaction linker for tracking the operation across chains

`TransactionLinker (Type)`

export type TransactionLinker = {
    caller: string,
    shardCount: number,
    shardsKey: string,
    timestamp: number,
    sendTransactionResult?: SendResult,
}

Linker to track TON transaction for crosschain operation.

caller: Address of the transaction initiator.
shardCount: Number of shards involved.
shardsKey: Identifier for the shard.
timestamp: Timestamp of the transaction.
sendTransactionResult (optional): Result of sending transaction. May be used to check result of sending transaction. Default TonClient does NOT fill this field. However, in unit tests @ton/sandbox set transaction result object to this field. Type is SendResult which includes success, boc, result, error, and lastMessageIndex fields.

This structure is designed to help track the entire execution path of a operation across all levels. By using it, you can identify the operationId and subsequently monitor the operation status through a public API. This is particularly useful for ensuring visibility and transparency in the operation lifecycle, allowing you to verify its progress and outcome.

`TransactionLinkerWithOperationId (Type)`

export type TransactionLinkerWithOperationId = TransactionLinker & {
    operationId?: string;
};

This structure is extended version of TransactionLinker with operationId field that is retrieved automatically by TacSDK when sending crosschain transaction.

`OperationIds (Type)`

export type OperationIds = {
    operationIds: string[];
};

Contains a collection of operation identifiers for tracking multiple operations.

operationIds: Array of operation ID strings for tracking crosschain operations.

`OperationIdsByShardsKey (Type)`

export type OperationIdsByShardsKey = Record<string, OperationIds>;

Maps shard keys to their corresponding operation IDs, allowing efficient lookup of operations by shard identifier.

`TrackTransactionTreeParams (Type)`

export type TrackTransactionTreeParams = {
    limit?: number;
    maxDepth?: number;
    maxScannedTransactions?: number;
    ignoreOpcodeList?: number[];
    direction?: 'forward' | 'backward' | 'both';
};

Parameters for tracking and validating transaction trees.

limit (optional): Maximum number of transactions to fetch per pagination request. Default: 100.
maxDepth (optional): Maximum depth to traverse in the transaction tree, inclusive (depth 0 is the root). Default: 10.
maxScannedTransactions (optional): Maximum number of transactions to scan while searching by hash in account history. Default: 100.
ignoreOpcodeList (optional): List of operation codes (opcodes) that mark transactions as skippable for extra checks. Phase validation is still applied. Default: [0xd53276db] (excess message).
direction (optional): Direction to search the transaction tree:
- 'forward': only search children (outgoing messages)
- 'backward': only search parents (incoming messages)
- 'both': search in both directions (default)

`TransactionValidationError (Type)`

export type TransactionValidationError = {
    txHash: string;
    exitCode: number | 'N/A';
    resultCode: number | 'N/A';
    reason: 'aborted' | 'compute_phase_missing' | 'compute_phase_failed' | 'action_phase_failed' | 'not_found';
    address?: string;
    hashType?: 'unknown' | 'in' | 'out';
};

Details about a transaction validation error.

txHash: Base64-encoded hash of the failed transaction.
exitCode: Exit code from the compute phase, or 'N/A' if compute phase is missing.
resultCode: Result code from the action phase, or 'N/A' if action phase is missing.
reason: Reason for validation failure:
- 'aborted': transaction was aborted
- 'compute_phase_missing': compute phase is missing
- 'compute_phase_failed': compute phase failed (exitCode !== 0)
- 'action_phase_failed': action phase failed (resultCode !== 0)
- 'not_found': transaction or message hash not found during traversal
address (optional): Address where the lookup happened (for 'not_found').
hashType (optional): Hash type used in lookup ('unknown' | 'in' | 'out', for 'not_found').

`TrackTransactionTreeResult (Type)`

export type TrackTransactionTreeResult = {
    success: boolean;
    error?: TransactionValidationError;
};

Result of transaction tree tracking and validation.

success: Whether all transactions in the tree passed validation.
error (optional): Details about the first validation error encountered (if any).

`TONAsset`

export type TONAsset = {
    amount: string;
    tokenAddress: string;
    assetType: AssetType;
};

Represents a TON asset used in cross-chain operations.

amount: The amount of the asset as a string.
tokenAddress: The address of the token on TON.
assetType: The type of the asset (FT or NFT) from the AssetType enum.

`TACCallParams`

export type TACCallParams = {
    arguments: string;
    methodName: string;
    target: string;
};

Represents parameters for calling a method on the TAC network.

arguments: Encoded arguments for the method call.
methodName: Name of the method to be called.
target: The target contract address on TAC.

`TACSimulationParams`

export type TACSimulationParams = {
    tacCallParams: TACCallParams;
    evmValidExecutors?: string[];
    tvmValidExecutors?: string[];
    extraData?: string;
    shardsKey: string;
    tonAssets: TONAsset[];
    tonCaller: string;
    calculateRollbackFee?: boolean;
};

Represents parameters for simulating a TAC message execution.

tacCallParams: TACCallParams object containing parameters for the TAC call.
evmValidExecutors (optional): Valid executors for TAC. Default: config.TACParams.trustedTACExecutors.
tvmValidExecutors (optional): Valid executors for TON. Default: config.TACParams.trustedTONExecutors.
extraData (optional): Additional non-root data to be included in TAC call. Default: "0x".
shardsKey: Key identifying shards for the operation.
tonAssets: Array of TONAsset objects involved in the transaction.
tonCaller: Address of the caller on the TON network.
calculateRollbackFee (optional): Whether to include rollback path fee in estimation. Default: true.

Note:

When using SDK helpers (e.g., Simulator), if tacCallParams.arguments are omitted, they will be set to "0x".
tacCallParams.methodName is validated and normalized via formatSolidityMethodName.

`ExecutionFeeEstimationResult`

export type ExecutionFeeEstimationResult = {
  feeParams: FeeParams;
  simulation?: TACSimulationResult;
}

Description

The result of a cross-chain transaction simulation, containing both the estimated fees and the outcome of the TAC-side message simulation.

Fields

feeParams: FeeParams
simulation: TACSimulationResult

Purpose

Used to pre-evaluate:

whether the transaction will succeed on the TAC side,
how much fee is required in the chosen asset.

Enables safe transaction previews before actual submission.

Here's your corrected structure documentation in the same format:

`SuggestedTVMExecutorFee`

export type SuggestedTVMExecutorFee = {
  inTAC: string;
  inTON: string;
}

Description

Contains estimated TVM executor fee for TON bridging operations in both TAC and TON denominations.

Fields

inTAC: Fee amount in TAC tokens
inTON: Fee amount in TON tokens

Purpose

Allows users to:

Estimate costs before initiating transactions in both currencies

`TransactionData`

export type TransactionData = {
    hash: string;
    blockchainType: BlockchainType;
};

Represents transaction details.

hash: The hash of the transaction.
blockchainType: The type of the blockchain (TON or TAC).

`NoteInfo`

export type NoteInfo = {
    content: string;
    errorName: string;
    internalMsg: string;
    internalBytesError: string;
};

Provides detailed information about any notes or errors encountered during operation processing.

content: Content of the note.
errorName: Name of the error.
internalMsg: Internal message related to the note or error.
internalBytesError: Detailed bytes error information.

`FeeParams`

export type FeeParams = {
    isRoundTrip: boolean,
    gasLimit: bigint,
    protocolFee: bigint,
    evmExecutorFee: bigint,
    tvmExecutorFee: bigint,
    evmEstimatedGas?: bigint,
};

Represents the calculated fee parameters used for crosschain transaction execution.

isRoundTrip:
Indicates whether the transaction is expected to perform a round-trip (e.g., from TAC to TON and back to TAC).
gasLimit:
Estimated gas limit for the EVM-side transaction execution.
protocolFee:
Fee charged by the protocol for facilitating the crosschain message.
evmExecutorFee:
Fee (in TON) to be paid to the executor responsible for handling execution on the EVM side.
tvmExecutorFee:
Fee (in TON) to be paid to the executor responsible for handling execution on the TON side.
evmEstimatedGas (optional):
Estimated gas amount for EVM-side execution, if available from simulation.

`StageData`

export type StageData = {
    success: boolean;
    timestamp: number;
    transactions: TransactionData[] | null;
    note: NoteInfo | null;
};

Represents data for a specific stage of operation execution.

Properties

success: Indicates whether the stage was successful.
timestamp: Timestamp of when the stage was executed.
transactions (optional): Array of transaction data related to the stage. null if none.
note (optional): Additional notes or errors related to the stage. null if none.

`StatusInfo`

export type StatusInfo = StageData & {
    stage: StageName;
};

Combines StageData with an additional stage identifier.

stage: Current stage in StageName enum.
Other Properties from StageData

`MetaInfo`

export type MetaInfo = {
    initialCaller: InitialCallerInfo;
    validExecutors: ValidExecutors;
    feeInfo: FeeInfo;
    sentAssets: AssetMovementInfo | null;
    receivedAssets: AssetMovementInfo | null;
};

Holds metadata associated with a crosschain transaction, including the initiating party, allowed executors, detailed fee information, and asset movement details.

initialCaller:
Information about the original sender of the transaction, including address and source blockchain.
validExecutors:
Specifies the list of executor addresses authorized to handle execution on TAC and TON.
feeInfo:
Object containing detailed information about fees required for the transaction execution.
sentAssets:
Information about assets sent in the transaction, including caller, target, transaction hash, and asset movements.
receivedAssets:
Information about assets received in the transaction, including caller, target, transaction hash, and asset movements.

`AssetMovementInfo`

export type AssetMovementInfo = {
    caller: InitialCallerInfo;
    target: InitialCallerInfo;
    transactionHash: TransactionHash;
    assetMovements: AssetMovement[];
};

Represents information about asset movements in a transaction.

caller:
Information about the caller address and blockchain type.
target:
Information about the target address and blockchain type.
transactionHash:
The transaction hash and its blockchain type.
assetMovements:
Array of individual asset movements in the transaction.

`AssetMovement`

export type AssetMovement = {
    assetType: AssetType;
    tvmAddress: string;
    evmAddress: string;
    amount: string;
    tokenId: string | null;
};

Represents a single asset movement in a transaction.

assetType:
The type of asset being moved (FT for fungible tokens, NFT for non-fungible tokens).
tvmAddress:
The TVM (TON Virtual Machine) address of the asset.
evmAddress:
The EVM (Ethereum Virtual Machine) address of the asset.
amount:
The amount of the asset being moved as a string.
tokenId:
The token ID for NFTs, or null for fungible tokens.

`TransactionHash`

export type TransactionHash = {
    hash: string;
    blockchainType: BlockchainType;
};

Represents a transaction hash with its associated blockchain type.

hash:
The transaction hash string.
blockchainType:
The blockchain type (TON or TAC) where the transaction occurred.

`InitialCallerInfo`

export type InitialCallerInfo = {
    address: string;
    blockchainType: BlockchainType;
};

Represents the originator of the transaction.

address:
The address of the caller that initiated the crosschain transaction.
blockchainType:
The blockchain network (TON or TAC) where the caller originated from.

`ValidExecutors`

export type ValidExecutors = {
    tac: string[];
    ton: string[];
};

Specifies the set of executor addresses that are permitted to execute the transaction.

tac:
A list of allowed executor addresses on the TAC (EVM) network.
ton:
A list of allowed executor addresses on the TON network.

`ProfilingStageData`

export type ProfilingStageData = {
    exists: boolean;
    stageData: StageData | null;
};

Provides profiling information for a specific stage.

exists: Indicates whether profiling data exists for the stage.
stageData (optional): Detailed data of the stage. null if none.

`ExecutionStages`

export type ExecutionStages = {
  operationType: OperationType;
  metaInfo: MetaInfo;
} & Record<StageName, ProfilingStageData>;

Represents the profiling data for all execution stages within an operation.

`ExecutionStagesByOperationId`

export type ExecutionStagesByOperationId = Record<string, ExecutionStages>;

Maps each operationId to its respective executionStages.

`StatusInfosByOperationId`

export type StatusInfosByOperationId = Record<string, StatusInfo>;

Maps each operationId to its respective statusInfo.

`UserWalletBalanceExtended`

Provides extended information about a user's Jetton balance.

Union Types

If the Jetton wallet exists:

{
    exists: true;
    amount: number;       // The formatted balance of the Jetton token.
    rawAmount: bigint;    // The raw balance of the Jetton token.
    decimals: number;     // The number of decimals for the Jetton token.
}

If the Jetton wallet does not exist:
```
{
    exists: false;
}
```
exists: Indicates whether the Jetton wallet exists.
amount (optional): The formatted balance of the Jetton token. Present only if exists is true.
rawAmount (optional): The raw balance of the Jetton token. Present only if exists is true.
decimals (optional): The number of decimals for the Jetton token. Present only if exists is true.

`NFTItemData`

Provides information about NFT item.

export type NFTItemData = {
    init?: boolean;
    index: bigint;
    collectionAddress: Address;
    ownerAddress?: Address;
    content?: Cell;
};

init (optional): Indicates whether item is active, i.e initialized by NFT collection and has not been burnt
index: Index of the item in collection (as bigint)
collectionAddress: Address of collection
ownerAddress (optional): Address of the item owner
content (optional): Content(metadata) of the item

`NFTCollectionData`

Provides information about NFT collection.

export type NFTCollectionData = {
    nextIndex: bigint;
    content: Cell;
    adminAddress: Address;
};

nextIndex: Next item index to be minted in the collection (as bigint)
content: Content(metadata) of the collection
adminAddress: Address of the collection admin

`TACSimulationResult`

export type TACSimulationResult = {
    estimatedGas: bigint;
    feeParams: {
      currentBaseFee: string;
      isEip1559: boolean;
      suggestedGasPrice: string;
      suggestedGasTip: string;
    };
    message: string;
    outMessages:
            | {
      callerAddress: string;
      operationId: string;
      payload: string;
      queryId: number;
      targetAddress: string;
      tokensBurned: {
        amount: string;
        tokenAddress: string;
      }[];
      tokensLocked: {
        amount: string;
        tokenAddress: string;
      }[];
      nftBurned: {
        amount: string;
        tokenAddress: string;
      }[];
      nftLocked: {
        amount: string;
        tokenAddress: string;
      }[];
    }[]
            | null;
    simulationError: string;
    simulationStatus: boolean;
    suggestedTonExecutionFee: string;
    suggestedTacExecutionFee: string;
    debugInfo: {
      from: string;
      to: string;
      callData: string;
      blockNumber: number;
    };
};

Provides TAC simulation results.

estimatedGas: The estimated gas required for the message.
feeParams: The parameters related to the fee.
- currentBaseFee: The current base fee.
- isEip1559: Indicates if EIP-1559 is applied.
- suggestedGasPrice: The suggested gas price.
- suggestedGasTip: The suggested gas tip.
message: The message details.
outMessages (optional): The outgoing messages. Maybe null if there is a bridge operation.
- callerAddress: The address of the caller.
- operationId: The operation ID.
- payload: The payload.
- queryId: The query ID.
- targetAddress: The target address.
- tokensBurned: The tokens burned.
  - amount: The amount of tokens burned.
  - tokenAddress: The address of the token.
- tokensLocked: The tokens locked.
- nftBurned: The NFTs burned.
- nftLocked: The NFTs locked.
simulationError: Any error encountered during the simulation.
simulationStatus: The status of the simulation.
suggestedTonExecutionFee: Suggested fee (in TON) that should be attached to ensure successful execution on the TON network.
suggestedTacExecutionFee: Suggested fee (in TON) that should be attached to ensure successful execution on the TAC network.
debugInfo: Debugging information.
- from: The sender address.
- to: The recipient address.
- callData: The call data.
- blockNumber: The block number.

`GeneralFeeInfo`

export type GeneralFeeInfo = {
    protocolFee: string;
    executorFee: string;
    tokenFeeSymbol: TokenSymbol;
};

Represents the fee structure for a blockchain protocol.

protocolFee: The fee amount charged by the protocol itself.
executorFee: The fee amount paid to the transaction executor.
tokenFeeSymbol: The symbol/identifier of the token used to pay fees.

`AdditionalFeeInfo`

export type AdditionalFeeInfo = {
    attachedProtocolFee: string;
    tokenFeeSymbol: TokenSymbol;
};

Represents additional fee information attached to the transaction.

attachedProtocolFee: The additional protocol fee amount attached to the transaction.
tokenFeeSymbol: The symbol/identifier of the token used for the additional fee.

`FeeInfo`

export type FeeInfo = {
    additionalFeeInfo: AdditionalFeeInfo;
    tac: GeneralFeeInfo;
    ton: GeneralFeeInfo;
};

Contains fee information for both TAC and TON blockchain networks, plus additional fee information.

additionalFeeInfo: Additional fee information attached to the transaction.
tac: Complete fee structure for transactions on the TAC blockchain.
ton: Complete fee structure for transactions on the TON blockchain.

`WaitOptions (Interface)`

export interface WaitOptions<T = unknown, TContext = unknown> {
    timeout?: number;
    maxAttempts?: number;
    delay?: number;
    logger?: ILogger;
    context?: TContext;
    successCheck?: (result: T, context?: TContext) => boolean;
    onSuccess?: (result: T, context?: TContext) => Promise<void> | void;
    includeErrorTrace?: boolean;
}

Allows to specify custom options for waiting for operation resolution with enhanced callback capabilities and context parameter support.

timeout (optional): Timeout in milliseconds. Default is 300000 (5 minutes).
maxAttempts (optional): Maximum number of attempts. Default is 30.
delay (optional): Delay between attempts in milliseconds. Default is 10000 (10 seconds).
logger (optional): Logger used to output debug information during waiting.
context (optional): Optional context object to pass additional parameters to callbacks. This allows passing custom data like OperationTracker instances, configurations, user settings, and other dependencies without relying on closures.
successCheck (optional): Function to check if the result is successful. Receives both the result and optional context parameter. If not provided, any non-error result is considered successful.
onSuccess (optional): Custom callback function that executes when operation is successful. Receives both the result and optional context with additional parameters. Can be used for additional processing like profiling data retrieval. Supports both synchronous and asynchronous callbacks.
includeErrorTrace (optional): Include underlying stack trace in FetchError.innerStack when all endpoints fail. Default is false.

Default Behavior

When waitOptions parameter is not specified (undefined) in methods like OperationTracker.getOperationId(), the SDK automatically applies default retry settings defined in defaultWaitOptions:

timeout: 300000ms (5 minutes)
maxAttempts: 30 - from DEFAULT_WAIT_MAX_ATTEMPTS
delay: 10000ms (10 seconds) - from DEFAULT_WAIT_DELAY_MS

This ensures resilient behavior against rate limits and temporary network issues without requiring explicit configuration.

Disabling Retries

To disable retry behavior and use a single attempt, explicitly pass null instead of WaitOptions:

// Single attempt, no retries
await tracker.getOperationId(linker, null);

// Default retry behavior (30 attempts with 10s delay)
await tracker.getOperationId(linker);

// Custom retry behavior
await tracker.getOperationId(linker, { maxAttempts: 5, delay: 2000 });

Usage Examples

For comprehensive examples and usage patterns, including detailed context parameter usage, see the Enhanced WaitOptions Examples documentation.

`TVMAddress`

export type TVMAddress = string;

TON Virtual Machine address in friendly/raw string form.

`EVMAddress`

export type EVMAddress = string;

EVM-compatible checksum address string.

`JettonMinterData`

export type JettonMinterData = {
    totalSupply: bigint;
    mintable: boolean;
    adminAddress?: Address;
    content: Cell;
    walletCode: Cell;
};

Represents the data structure returned by Jetton minter contracts, containing essential information about a Jetton (fungible token).

totalSupply: Total supply of the Jetton in raw units (considering decimals)
mintable: Whether the Jetton can still be minted (true) or if minting is disabled (false)
adminAddress (optional): Address of the admin who controls the Jetton minter contract
content: Cell containing Jetton metadata (name, symbol, decimals, description, image, etc.) encoded according to TEP-64 standard
walletCode: Cell containing the code for Jetton wallet contracts that will be deployed for each holder

`FTOriginAndData`

export type FTOriginAndData = {
    origin: Origin;
    jettonMinter: OpenedContract<JettonMinter> | SandboxContract<JettonMinter>;
    evmAddress?: string;
    jettonData?: JettonMinterData;
};

Contains comprehensive information about a fungible token's origin and associated data.

origin: The origin of the token (Origin.TON or Origin.TAC) indicating whether it's native to TON or wrapped from TAC
jettonMinter: Opened contract instance of the jetton minter for direct interaction
evmAddress (optional): EVM address of the token, present for TAC-origin tokens
jettonData (optional): Jetton metadata and information, present for TON-origin tokens

This structure is returned by the FT.getOriginAndData method and provides all necessary information to work with fungible tokens regardless of their origin.

`AssetFromFTArg`

export type AssetFromFTArg = {
    address: TVMAddress | EVMAddress;
    tokenType: AssetType.FT;
};

Use for fungible tokens (Jettons). Address may be TVM or EVM.

address: Token address (TVM or EVM format)
tokenType: Must be AssetType.FT

`AssetFromNFTItemArg`

export type AssetFromNFTItemArg = {
    address: TVMAddress;
    tokenType: AssetType.NFT;
    addressType: NFTAddressType.ITEM;
};

Use for a specific NFT item. Address must be a TVM item address.

address: NFT item address (TVM format only)
tokenType: Must be AssetType.NFT
addressType: Must be NFTAddressType.ITEM

`AssetFromNFTCollectionArg`

export type AssetFromNFTCollectionArg = {
    address: TVMAddress | EVMAddress;
    tokenType: AssetType.NFT;
    addressType: NFTAddressType.COLLECTION;
    index: bigint;
};

Use for an NFT item derived from a collection and an on-chain index. Address may be TVM or EVM collection address.

address: NFT collection address (TVM or EVM format)
tokenType: Must be AssetType.NFT
addressType: Must be NFTAddressType.COLLECTION
index: Index of the specific NFT item within the collection

`GeneratePayloadParams`

export type GeneratePayloadParams = {
    excessReceiver: string;
    evmData: Cell;
    crossChainTonAmount?: bigint;
    forwardFeeTonAmount?: bigint;
    feeParams?: FeeParams;
};

Parameters for generating transaction payloads for cross-chain operations.

excessReceiver: Address that will receive excess TON after execution.
evmData: Serialized EVM-side call data to be forwarded via the bridge.
crossChainTonAmount (optional): TON amount to transfer cross-chain with the message.
forwardFeeTonAmount (optional): TON amount used to cover forwarding fees on TON.
feeParams (optional): Fee parameters to fine-tune execution costs.

`GetTVMExecutorFeeParams`

export type GetTVMExecutorFeeParams = {
    feeSymbol: string;
    tonAssets: TONAsset[];
    tvmValidExecutors: string[];
};

Parameters for calculating TVM executor fees for cross-chain operations.

feeSymbol: Symbol of the token to express the fee in (e.g., 'TAC', 'TON').
tonAssets: Array of TONAsset objects representing assets involved in the operation.
tvmValidExecutors: Array of valid TVM executor addresses to use for fee calculation.

`TacGasPrice`

export type TacGasPrice = {
    average: number;
    fast: number;
    slow: number;
};

Represents TAC gas prices at different priority levels.

average: Average gas price for standard transaction processing.
fast: Higher gas price for faster transaction processing.
slow: Lower gas price for slower but more economical transaction processing.

`ConvertCurrencyParams`

export type ConvertCurrencyParams = {
    value: bigint;
    currency: CurrencyType;
};

Input parameters to convert a raw bigint amount for the selected currency type.

value: The raw bigint amount to convert
currency: The currency type to convert from

`USDPriceInfo`

export type USDPriceInfo = {
    spot: bigint;
    ema: bigint;
    decimals: number;
};

Contains USD price information for a token with proper decimal handling:

spot: Current spot price in USD, represented as a bigint value multiplied by 10^decimals
ema: Exponential Moving Average price in USD, represented as a bigint value multiplied by 10^decimals
decimals: Number of decimal places used in the price representation. Typically 18 for most tokens.

Price Format Example: A price value of 3090143663312000000 with decimals: 18 represents 3.090143663312 USD (the value divided by 10^18).

`ConvertedCurrencyResult`

export type ConvertedCurrencyResult = {
    spotValue: bigint;
    emaValue: bigint;
    decimals: number;
    currency: CurrencyType;
    tacPrice: USDPriceInfo;
    tonPrice: USDPriceInfo;
};

Contains conversion results with detailed price information:

spotValue & emaValue: Converted amounts using spot and EMA prices respectively
decimals: Decimal places for the converted values
currency: The currency type that was converted
tacPrice & tonPrice: Reference USD price information for TAC and TON tokens used in the conversion calculation

`defaultWaitOptions`

The SDK exports defaultWaitOptions constant with the following default values:

export const defaultWaitOptions: WaitOptions = {
    timeout: DEFAULT_WAIT_TIMEOUT_MS,    // 300000ms = 5 minutes
    maxAttempts: DEFAULT_WAIT_MAX_ATTEMPTS,    // 30
    delay: DEFAULT_WAIT_DELAY_MS,       // 10000ms = 10 seconds
};

These defaults are automatically applied when waitOptions parameter is not specified (undefined) in methods that support retry behavior, such as all OperationTracker methods. This provides robust retry logic to handle rate limits and temporary network issues without explicit configuration.

The underlying constants are defined in src/sdk/Consts.ts:

DEFAULT_WAIT_TIMEOUT_MS = 300000 (5 minutes)
DEFAULT_WAIT_MAX_ATTEMPTS = 30
DEFAULT_WAIT_DELAY_MS = 10000 (10 seconds)

FilesExpand file tree

structs.md

Latest commit

History

structs.md

File metadata and controls

SDK Data Structures (Structs)

Table of Contents

Core Configuration

Contract Openers

Crosschain Transaction

Transaction Tracking

Simulation Structures

Execution & Status

Metadata & Fees

Jetton Wallet

NFT

Currency & Conversion

TAC Stats

FT Structures

Asset Factory

Address Types

Core Data Structures

SDKParams (Type)

TONParams (Type)

TACParams (Type)

ContractState (Type)

ContractOpener (Interface)

RetryableContractOpener (Class)

Constructor Parameters

Methods

Helper Functions

GetTransactionsOptions (Type)

AddressInformation (Type)

EvmProxyMsg (Type)

CrossChainTransactionOptions

BatchCrossChainTransactionOptions

CrossChainTransactionsOptions

CrosschainTx

BatchCrossChainTx

AssetLike

Native TON Assets

Fungible Token (FT) Assets

NFT Item Assets

NFT Collection Assets

BatchCrossChainTxWithAssetLike

CrossChainPayloadResult (Type)

TransactionLinker (Type)

TransactionLinkerWithOperationId (Type)

OperationIds (Type)

OperationIdsByShardsKey (Type)

TrackTransactionTreeParams (Type)

TransactionValidationError (Type)

TrackTransactionTreeResult (Type)

TONAsset

TACCallParams

TACSimulationParams

ExecutionFeeEstimationResult

Description

Fields

Purpose

SuggestedTVMExecutorFee

Description

Fields

Purpose

TransactionData

NoteInfo

FeeParams

StageData

Properties

StatusInfo

MetaInfo

AssetMovementInfo

AssetMovement

TransactionHash

InitialCallerInfo

ValidExecutors

ProfilingStageData

ExecutionStages

ExecutionStagesByOperationId

`SDKParams (Type)`

`TONParams (Type)`

`TACParams (Type)`

`ContractState (Type)`

`ContractOpener (Interface)`

`RetryableContractOpener (Class)`

`GetTransactionsOptions (Type)`

`AddressInformation (Type)`

`EvmProxyMsg (Type)`

`CrossChainTransactionOptions`

`BatchCrossChainTransactionOptions`

`CrossChainTransactionsOptions`

`CrosschainTx`

`BatchCrossChainTx`

`AssetLike`

`BatchCrossChainTxWithAssetLike`

`CrossChainPayloadResult (Type)`

`TransactionLinker (Type)`

`TransactionLinkerWithOperationId (Type)`

`OperationIds (Type)`

`OperationIdsByShardsKey (Type)`

`TrackTransactionTreeParams (Type)`

`TransactionValidationError (Type)`

`TrackTransactionTreeResult (Type)`

`TONAsset`

`TACCallParams`

`TACSimulationParams`

`ExecutionFeeEstimationResult`

`SuggestedTVMExecutorFee`

`TransactionData`

`NoteInfo`

`FeeParams`

`StageData`

`StatusInfo`

`MetaInfo`

`AssetMovementInfo`

`AssetMovement`

`TransactionHash`

`InitialCallerInfo`

`ValidExecutors`

`ProfilingStageData`

`ExecutionStages`

`ExecutionStagesByOperationId`

`StatusInfosByOperationId`

`UserWalletBalanceExtended`

`NFTItemData`

`NFTCollectionData`

`TACSimulationResult`

`GeneralFeeInfo`

`AdditionalFeeInfo`

`FeeInfo`

`WaitOptions (Interface)`

`TVMAddress`

`EVMAddress`

`JettonMinterData`

`FTOriginAndData`

`AssetFromFTArg`

`AssetFromNFTItemArg`

`AssetFromNFTCollectionArg`

`GeneratePayloadParams`

`GetTVMExecutorFeeParams`

`TacGasPrice`

`ConvertCurrencyParams`

`USDPriceInfo`

`ConvertedCurrencyResult`

`defaultWaitOptions`