Skip to main content

108. Injectable Service Pattern for TON

Status: Accepted Date: 2025-07-06

Context​

The kaido-ton library provides functionality that needs to be accessed from different parts of our NestJS-based applications (e.g., the Arcana domain). We need a standard, clean, and maintainable way to integrate this blockchain functionality into our main application, consistent with our overall architectural style.

Decision​

The kaido-ton library will be exposed as a standard, injectable NestJS Service. This follows the exact same pattern as our kaido-telegram library (adr://nestjs-service-pattern).

  • A TonModule will be created that provides a TonService.
  • Any application module that needs to interact with the TON blockchain (like ArcanaModule) will import this TonModule.
  • It can then inject the TonService into its own services or controllers using NestJS's standard dependency injection.
  • The TonService will expose a simple, high-level API for our specific use cases (e.g., recordHashOnTON(hash)), abstracting away the complexities of the underlying tonweb library.

Consequences​

Positive:

  • Seamless Integration: This approach integrates perfectly with our existing NestJS architecture (adr://nestjs-enterprise-framework).
  • Dependency Injection: Services that use the TON integration can have other application dependencies injected into them, and they can themselves be injected into other services.
  • Testability: The TonService can be easily mocked in unit tests. We can test the logic of a service that records a hash on-chain without actually needing to connect to the TON network during tests.
  • Centralized Configuration: The TON API key and endpoint URL can be managed by NestJS's central ConfigService.

Negative:

  • Tightly Coupled to NestJS: This pattern makes the kaido-ton library tightly coupled to the NestJS framework.

Mitigation:

  • Acceptable Coupling: This is an acceptable trade-off. The kaido-ton library is being built specifically to serve our NestJS applications. It is not intended to be a general-purpose, framework-agnostic library. Coupling it to NestJS allows us to provide a much better and more consistent developer experience for its intended users.