Skip to main content

105. TonWeb for TON Blockchain Integration

Status: Accepted Date: 2025-07-06

Context​

To interact with the TON (The Open Network) blockchain from our TypeScript application, we need a library or SDK that handles the low-level details of creating transactions, signing them, and communicating with the network. Building this from scratch is complex and error-prone. We need to choose a mature, well-maintained library to serve as the foundation for our kaido-ton integration.

Decision​

We will use tonweb as the primary library for all interactions with the TON blockchain.

tonweb is a popular, comprehensive, and well-maintained JavaScript/TypeScript library for TON. It provides all the necessary functionality we need, including:

  • Connecting to TON HTTP API providers (adr://toncenter-api-endpoint).
  • Creating and managing wallets.
  • Building, signing, and sending transactions (known as "messages" in TON).
  • Parsing blockchain data.

The kaido-ton library will be built as a higher-level abstraction layer on top of tonweb, simplifying its API for our specific use case of hash-based verification.

Consequences​

Positive:

  • Leverages Mature SDK: We are building on top of a mature library that is used by many projects in the TON ecosystem, which means it is battle-tested and its developers have already solved many of the complex problems of blockchain interaction.
  • Faster Development: Using tonweb allows us to focus on our application's business logic instead of the low-level details of the TON protocol.
  • Comprehensive Functionality: It provides all the features we need for our current and foreseeable future interactions with the TON network.

Negative:

  • Adds a Dependency: Introduces a significant external dependency for a core piece of functionality. Our integration is now subject to the quality, maintenance, and potential bugs of this third-party library.
  • Abstraction Hides Complexity: While our service will abstract tonweb, a deep understanding of the underlying library will still be required to debug complex issues.

Mitigation:

  • Well-Chosen Dependency: tonweb is a reputable and widely-used library in its ecosystem. The risk of using it is far lower than the risk of implementing our own crypto library from scratch.
  • Version Pinning: We will pin the version of tonweb in our package.json and only upgrade it deliberately after reviewing the changelogs, mitigating the risk of breaking changes being introduced unexpectedly.
  • Focused Abstraction: Our TonService will abstract away the most common use cases, but for debugging, developers will have full access to the underlying tonweb instance if needed.