> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tac.build/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Download from <a href='https://www.npmjs.com/package/@tonappchain/sdk'>NPM</a>

Below are listed the notable changes to the @tonappchain/sdk, including new features, improvements, bug fixes, and breaking changes.

<Update label="0.7.2" description="February 2026">
  ### Added

  * TEP-526 support for scaled UI in FT tokens with display multiplier functionality (display multiplier caching with 5-minute TTL for FT assets)
  * Fee parameter constants and factory functions for transaction fee calculation steps.
  * Automatic TON blockchain fee parameters retrieval from network config with fallback to standard values.
  * Enhanced transaction tracking with failure case handling and track params.
  * TacSdk support for preparing cross-chain payloads.
  * New `TacExplorerClient` class for interacting with TAC Explorer API.
  * `getTransactions()` method added to `ContractOpener` interface for standardized transaction fetching.

  ### Changed

  * `Configuration` class now retrieves and stores TON fee parameters during initialization.
  * Refactored transaction finalization logic for improved speed and reliability.
  * Refactoring of ContractOpener architecture:
  * All openers converted to class-based implementations extending `BaseContractOpener`:
  * `TonClientOpener`: TonClient implementation.
  * `TonClient4Opener`: TonClient4 implementation.
  * `LiteClientOpener`: LiteClient implementation with connection management.
  * `SandboxOpener`: Sandbox testing implementation.
  * Eliminated code duplication by moving common logic to base class:
  * `getTransactionByHash()`: Transaction lookup with retry logic.
  * `getAdjacentTransactions()`: Child and parent transaction discovery.
  * `trackTransactionTree()`: Full transaction tree validation.
  * Each opener now implements only provider-specific methods (`open`, `getContractState`, `getTransactions`, `getAddressInformation`, `getConfig`).
  * Removed `helpers.ts` file - functionality integrated into `BaseContractOpener`.
  * Shared utility functions in `OpenerUtils.ts`:
  * `getHttpEndpointWithRetry()`: Unified HTTP endpoint retrieval with retry logic.
  * `getHttpV4EndpointWithRetry()`: Unified HTTP V4 endpoint retrieval with retry logic.
  * Transaction tree validation errors now always include transaction hash, `exitCode`, and `resultCode` for better debugging.
</Update>

<Update label="0.7.1" description="October 2025">
  ### Changed

  * Fixed bug with evm address of `TON` in `normalizeAssets`.
</Update>

<Update label="0.7.0" description="September 2025">
  ### Added

  * **New Assets Module**: Added classes and utilities for working with FT, NFT, and TON assets, including AssetFactory and AssetCache
  * **Logger Components**: ConsoleLogger and NoopLogger for flexible logging configuration - SDK components are silent by default unless logger is provided
  * **Simulator Component**: Internal simulation component for TAC-side transaction simulation, gas estimation, and fee calculation
  * **Transaction Managers**: TONTransactionManager and TACTransactionManager for handling cross-chain transaction execution
  * **TonTxFinalizer**: Utility for verifying transaction tree success on TON blockchain using TON Center API
  * **RetryableContractOpener**: Enhanced contract opener for improved SDK stability and reliability
  * **Balance Verification**: Automatic balance checking before sending cross-chain transactions
  * **Batch Transaction Support**: RawSender can now send transactions in batches (254 for V5R1 wallets, 4 for other wallet versions)
  * **Wait Options**: Optional `waitOptions` parameter for OperationTracker methods and `sendCrossChainTransaction(s)` to automatically wait for operation completion
  * **AgnosticProxy SDK**: Experimental SDK for building complex DeFi operations with dynamic value replacement (testing only)

  ### Changed

  * **Performance Optimizations**: Significantly improved SDK initialization speed by parallelizing blockchain queries and initialization steps
  * **Sender Architecture**: Refactored BatchSender, RawSender, and TonConnectSender with improved contractOpener and retryableContractOpener
  * **Core Infrastructure**: Updated error handling, structs, utilities, and OperationTracker components
  * **Method Signatures**: OperationTracker methods and `sendCrossChainTransaction(s)` now accept optional `waitOptions` for automatic completion waiting
</Update>

<Update label="v0.6.4" description="June 2025">
  ### Changed

  * Switched to spb(chain) set of addresses
</Update>

<Update label="v0.6.3" description="June 2025">
  ### Added

  * Advanced options to `sendCrossChainTransaction`
  * Method to send multiple crosschain transactions at once: `sendCrossChainTransactions`
  * Batch sending support for crosschain transactions
  * Error handling while sending crosschain transactions

  ### Changed

  * TonClient with TAC endpoint as default contract opener
</Update>

<Update label="v0.6.2" description="May 2025">
  ### Added

  * `metaInfo` field to the `ExecutionStages`
  * LiteSequencerClient to handle lite sequencer requests and its parameters
  * Method to calculate tvmExecutorFee: `getTVMExecutorFeeInfo`

  ### Changed

  * `getEVMTokenAddress` now automatically normalizes addresses to `EQ` form
  * For TAC->TON transactions tvmExecutorFee calculated via lite sequencer
</Update>

<Update label="v0.6.1" description="May 2025">
  ### Added

  * Fee support for crosschain transactions
  * New methods for requesting execution fees and simulation `getTransactionSimulationInfo`
  * Methods to work with NFT items: bridging and getting addresses

  ### Changed

  * Switched to v3 sequencer
</Update>

<Update label="v0.5.7" description="April 2025">
  ### Changed

  * Changed tvm jetton minter stateInit in `getJettonOpType`
</Update>

<Update label="v0.5.6" description="March 2025">
  ### Changed

  * Changed tvm jetton minter stateInit
</Update>

<Update label="v0.5.5" description="March 2025">
  ### Changed

  * Fixed bug with crossChainTonAmount in generating jetton payload
</Update>

<Update label="v0.5.4" description="March 2025">
  ### Changed

  * Due to an API change, updated the `operationId` retrieval. An empty string will be returned for 404 errors
</Update>

<Update label="v0.5.3" description="March 2025">
  ### Changed

  * Fixed bug with V5 wallet
</Update>

<Update label="v0.5.2" description="March 2025">
  ### Changed

  * `StageName` value namings
  * `startTracking` has been improved. Added optional parameters

  ### Removed

  * `ExecutionStagesTableData` type
  * `TrackingOperationResult` type
</Update>

<Update label="v0.5.1" description="March 2025">
  ### Added

  * `OperationType` type
  * `ExecutionStagesTableData` type
  * `TrackingOperationResult` type
  * `StageName` enum
  * `getOperationType` in `OperationTracker` retrieves the `OperationType` for `operationId`

  ### Changed

  * The stage names have been changed
  * Changed namings in enums
  * `OperationType` added in the `ExecutionStages`
  * `ExecutionStages` structure
  * Added return value in method `sendShardTransaction` in `TonConnectSender`
  * Added `forceSend` option in method `sendCrossChainTransaction` in `TacSdk`
  * `startTracking` has been improved. Added optional parameters and return values

  ### Removed

  * Deleted `isBridgeOperation` (now it can be determined with `getOperationType`)
</Update>

<Update label="v0.5.0" description="March 2025">
  ### Changed

  * **Changed package tac-sdk -> @tonappchain/sdk**
  * `calculateEVMTokenAddress` function now requires tokenUtils address as deployer and crossChainLayer address as constructor params
  * Rename shardedId -> shardsKey
  * A `gasLimit` field has been added to `EvmProxyMsg` (defaulting to undefined, which will be set through simulation in this case)
  * Renamed json properties in `buildEvmDataCell`
  * Renamed urls in `OperationTracker`

  ### Added

  * `options` parameter in `getSender` method to modify W5 and Highload V3 wallets
  * `customLiteSequencerEndpoints` parameter in `SDKParams` to specify custom lite sequencer endpoints
  * `simulateEVMMessage` method in `TacSdk` to simulate EVM message execution on TAC side
  * `getOperationStatuses` method in `OperationTracker` retrieves the statuses of multiple operations based on their respective `operationId's`
  * `getOperationIdsByShardsKeys` method in `OperationTracker` retrieves the `operationId's` based on their respective `shardsKey's`
  * `getStageProfilings` method in `OperationTracker` retrieves the `ExecutionStages's` based on their respective `operationId's`
  * `getStageProfiling` method in `OperationTracker` retrieves the `ExecutionStages` for `operationId`
  * Added a pre-check before sending to the blockchain to ensure the transaction will execute successfully on the TAC side using the `simulateEVMMessage` method
  * Support for highload V3 wallet as a sender
</Update>

<Update label="v0.4.2" description="February 2025">
  ### Added

  * Contract opener `orbsOpener4` that uses new version TON endpoints

  ### Changed

  * `orbsOpener4` set as default in SDK
</Update>

<Update label="v0.4.1" description="February 2025">
  ### Changed

  * `@tonappchain/artifacts` upgraded to `0.0.14`
</Update>

<Update label="v0.4.0" description="February 2025">
  ### Added

  * `getUserJettonBalanceExtended` method in `TacSdk` to get user jetton balance extended with decimals info

  ### Changed

  * `AssetBridgingData` now supports multiple formats of asset value: with decimals and without decimals. In case decimals are not provided, the SDK will try to extract it from chain
</Update>

<Update label="v0.3.7" description="January 2025">
  ### Added

  * Section in readme about TACHeader
  * AddLiquidity uniswap\_v2 test
  * `orbsOpener` method to construct custom contractOpener for TacSDK. It uses Orbs Network and does not have rate limits

  ### Changed

  * SDK uses orbsOpener by default
  * `address` field in `AssetBridgingData` can be either EVM or TVM address
  * Method `SenderFactory.getSender` requires additional parameter `network` when creating wallet wrapper using mnemonic
  * Fixed `getContractState` in `liteClientOpener`
  * Fixed all tests for TACHeader logic
  * Version `@tonappchain/artifacts` upgraded to `0.0.12-addresses`
  * Request to `/status` endpoint of Sequencer API changed from `GET` to `POST` with body
  * Signature of `getOperationStatus` is changed

  ### Removed

  * Deleted test bridgeData
</Update>

<Update label="v0.3.6" description="January 2025">
  ### Changed

  * Calculate token addresses through emulation
  * Renamed `TransactionStatus` to `OperationTracker`
  * Renamed method `OperationTracker.getStatusTransaction()` to `OperationTracker.getOperationStatus()`
  * Renamed method `OperationTracker.getSimpifiedTransactionStatus()` to `OperationTracker.getSimplifiedOperationStatus()`
  * Renamed `TacSDKTonClientParams` to `SDKParams`
  * Changed struct of `SDKParams`
  * Changed `ton-lite-client` library to its fork `@tonappchain/ton-lite-client`

  ### Added

  * Custom `TONParams` and `TACParams` in `SDKParams`
  * `network` and `customLiteSequencerEndpoints` params to `OperationTracker` constructor
  * Static async function `create` in `TacSdk` for creating an instance of `TacSdk`
  * Custom errors
  * Methods that may construct custom contractOpener for TacSDK
  * Method `closeConnections` in `TacSdk` for closing all network connections
  * Optional method `closeConnections` to `ContractOpener` interface

  ### Removed

  * `init` function in `TacSdk`
  * Public constructor of `TacSdk`
</Update>

<Update label="v0.3.5" description="December 2024">
  ### Added

  * Method to get TVM address based on EVM address
  * Tests for SDK methods using contract emulation
  * Support for custom contract opener
  * SDK uses @tonappchain/artifacts
  * Added get methods for native token addresses
  * Added support for native token address calculation in *getEVMTokenAddress* and *getTVMTokenAddress* methods

  ### Removed

  * Support for TON wallet v1
</Update>

<Update label="v0.3.4" description="December 2024">
  ### Added

  * Code formatting
</Update>

<Update label="v0.3.3" description="December 2024">
  ### Added

  * Support for all versions of TON wallet (v1 - v5)
  * SenderFactory to create AbstractSender
</Update>