|
| 1 | +# TON SDK — Overview |
| 2 | + |
| 3 | +TON SDK is a modular SDK for building applications on The Open Network (TON). It offers first‑class support for Kotlin |
| 4 | +and Java on the JVM/Android, and can be consumed from Swift on iOS via Kotlin Multiplatform. It provides the core data |
| 5 | +structures (Cells/BOC), TL‑B codecs, crypto primitives, networking stacks (ADNL/RLDP), and high‑level APIs (contracts, |
| 6 | +lite client) so you can integrate TON from server, desktop, Android, or iOS with one codebase. |
| 7 | + |
| 8 | +This document explains the SDK at a high level: what it is, how it is organized, and when to use each module. For |
| 9 | +hands‑on guides and API details, see the other topics in this documentation set. |
| 10 | + |
| 11 | +## What is TON SDK? |
| 12 | + |
| 13 | +A collection of modular libraries published on Maven Central under the `org.ton.kotlin` group. Each module focuses on a |
| 14 | +well‑defined layer of the TON stack, from low‑level binary formats up to ready‑to‑use APIs. |
| 15 | + |
| 16 | +### Key features |
| 17 | + |
| 18 | +- Kotlin Multiplatform first: shared code for JVM, Android, and other targets. |
| 19 | +- Zero‑dependency core for critical primitives (Cells, BOC, TL‑B). |
| 20 | +- TL‑B serialization/deserialization with code‑generated schemas for blockchain objects. |
| 21 | +- Networking layers for TON (ADNL, RLDP) and a Lite Client API. |
| 22 | +- Contract utilities to work with smart‑contracts from Kotlin. |
| 23 | +- Carefully tested with cross‑platform test suites. |
| 24 | + |
| 25 | +## Module map (current) |
| 26 | + |
| 27 | +- ton-sdk-blockchain — Core blockchain primitives such as Address, BlockId, Transaction, Message, etc. |
| 28 | +- ton-sdk-crypto — ED25519, SHA, CRC, and related crypto utilities. |
| 29 | +- ton-sdk-tl — Type Language (TL) serializer for kotlinx-serialization used in network protocols and more. |
| 30 | +- ton-sdk-cell — The fundamental immutable binary structure in TON used by TVM; also includes the BOC (Bag of Cells) |
| 31 | + container format. |
| 32 | +- ton-sdk-liteapi-client — LiteAPI (LiteClient) for RPC, requests unindexed data from blockchain nodes via LiteServer. |
| 33 | +- ton-sdk-toncenter-client — HTTP RPC client for TonCenter V3 (Indexed) and TonCenter V2 (Unindexed). |
| 34 | +- ton-sdk-dict — TVM Dictionary built on top of Cells. |
| 35 | +- ton-sdk-bitstring — Small module for BitStrings (used by Cells and for byte-level serialization). |
| 36 | +- ton-sdk-bigint — Cross‑platform big integer; on JVM it aliases java.math.BigInteger, with platform implementations |
| 37 | + elsewhere. |
| 38 | + |
| 39 | +Note: Artifact coordinates in Maven Central may use org.ton.kotlin with module names like ton-kotlin-*. Refer to the |
| 40 | +README for the latest coordinates and versions. |
| 41 | + |
| 42 | +## Typical use cases |
| 43 | + |
| 44 | +- Indexers and backends that need to parse blocks/transactions and verify proofs. |
| 45 | +- Wallets and apps that compose and serialize messages and contracts. |
| 46 | +- Services querying blockchain data via the Lite Client. |
| 47 | +- Tooling and middleware that rely on TL‑B codecs and BOC manipulation. |
| 48 | + |
| 49 | +## Installation |
| 50 | + |
| 51 | +Add TON SDK modules from Maven Central. Use the coordinates under the org.ton.kotlin group. Keep module versions |
| 52 | +aligned (e.g., 0.5.0). |
| 53 | + |
| 54 | +Gradle (Kotlin DSL): |
| 55 | + |
| 56 | +```kotlin |
| 57 | +val tonVersion = "0.5.0" |
| 58 | + |
| 59 | +dependencies { |
| 60 | + implementation("org.ton.kotlin:ton-kotlin-tvm:$tonVersion") // Cells/BOC |
| 61 | + implementation("org.ton.kotlin:ton-kotlin-crypto:$tonVersion") // Crypto |
| 62 | + implementation("org.ton.kotlin:ton-kotlin-tlb:$tonVersion") // TL-B codec |
| 63 | + implementation("org.ton.kotlin:ton-kotlin-liteclient:$tonVersion") // Lite client API |
| 64 | + // Optional: |
| 65 | + implementation("org.ton.kotlin:ton-kotlin-contract:$tonVersion") // Contracts helpers |
| 66 | + implementation("org.ton.kotlin:ton-kotlin-adnl:$tonVersion") // ADNL transport |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +Gradle (Groovy DSL): |
| 71 | + |
| 72 | +```groovy |
| 73 | +def tonVersion = '0.5.0' |
| 74 | +
|
| 75 | +dependencies { |
| 76 | + implementation "org.ton.kotlin:ton-kotlin-tvm:$tonVersion" |
| 77 | + implementation "org.ton.kotlin:ton-kotlin-crypto:$tonVersion" |
| 78 | + implementation "org.ton.kotlin:ton-kotlin-tlb:$tonVersion" |
| 79 | + implementation "org.ton.kotlin:ton-kotlin-liteclient:$tonVersion" |
| 80 | + // Optional: |
| 81 | + implementation "org.ton.kotlin:ton-kotlin-contract:$tonVersion" |
| 82 | + implementation "org.ton.kotlin:ton-kotlin-adnl:$tonVersion" |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +Maven: |
| 87 | + |
| 88 | +```xml |
| 89 | + |
| 90 | +<dependencies> |
| 91 | + <dependency> |
| 92 | + <groupId>org.ton.kotlin</groupId> |
| 93 | + <artifactId>ton-kotlin-tvm</artifactId> |
| 94 | + <version>0.5.0</version> |
| 95 | + </dependency> |
| 96 | + <dependency> |
| 97 | + <groupId>org.ton.kotlin</groupId> |
| 98 | + <artifactId>ton-kotlin-crypto</artifactId> |
| 99 | + <version>0.5.0</version> |
| 100 | + </dependency> |
| 101 | + <dependency> |
| 102 | + <groupId>org.ton.kotlin</groupId> |
| 103 | + <artifactId>ton-kotlin-tlb</artifactId> |
| 104 | + <version>0.5.0</version> |
| 105 | + </dependency> |
| 106 | + <dependency> |
| 107 | + <groupId>org.ton.kotlin</groupId> |
| 108 | + <artifactId>ton-kotlin-liteclient</artifactId> |
| 109 | + <version>0.5.0</version> |
| 110 | + </dependency> |
| 111 | + <!-- Optional --> |
| 112 | + <dependency> |
| 113 | + <groupId>org.ton.kotlin</groupId> |
| 114 | + <artifactId>ton-kotlin-contract</artifactId> |
| 115 | + <version>0.5.0</version> |
| 116 | + </dependency> |
| 117 | + <dependency> |
| 118 | + <groupId>org.ton.kotlin</groupId> |
| 119 | + <artifactId>ton-kotlin-adnl</artifactId> |
| 120 | + <version>0.5.0</version> |
| 121 | + </dependency> |
| 122 | +</dependencies> |
| 123 | +``` |
| 124 | + |
| 125 | +## Quick start |
| 126 | + |
| 127 | +Add the artifacts you need from Maven Central and start from the level that fits your use case. |
| 128 | + |
| 129 | +### Kotlin (JVM/Android) |
| 130 | + |
| 131 | +Creating a Cell and serializing to BOC: |
| 132 | + |
| 133 | +```kotlin |
| 134 | +val cell = org.ton.cell.buildCell { |
| 135 | + storeUInt(0xDEADBEEFu, 32) |
| 136 | +} |
| 137 | +val boc: ByteArray = org.ton.boc.BagOfCells.of(cell).toByteArray() |
| 138 | +``` |
| 139 | + |
| 140 | +Decoding a TL‑B object (schema provided by block‑tlb module): |
| 141 | + |
| 142 | +```kotlin |
| 143 | +val block = org.ton.tlb.loadTlb<Block>(boc) |
| 144 | +``` |
| 145 | + |
| 146 | +### Java (JVM) |
| 147 | + |
| 148 | +Creating a Cell and serializing to BOC: |
| 149 | + |
| 150 | +```java |
| 151 | +public class Example { |
| 152 | + static void main(String[] args) { |
| 153 | + var builder = org.ton.cell.CellBuilderKt.beginCell(); |
| 154 | + builder.storeUInt(0xDEADBEEF, 32); |
| 155 | + org.ton.cell.Cell cell = builder.endCell(); |
| 156 | + byte[] boc = org.ton.boc.BagOfCells.Companion.of(new org.ton.cell.Cell[]{cell}).toByteArray(); |
| 157 | + } |
| 158 | +} |
| 159 | +``` |
| 160 | + |
| 161 | +See examples/ and tests in the repository for more scenarios. |
| 162 | + |
| 163 | +## Supported platforms |
| 164 | + |
| 165 | +- JVM / Android — Kotlin and Java (first‑class) |
| 166 | +- iOS — Swift via Kotlin Multiplatform bindings (availability may vary by module) |
| 167 | +- Desktop/Server — JVM |
| 168 | +- Other Kotlin targets may be available per‑module; check each module’s README or Gradle metadata. |
| 169 | + |
| 170 | +## Versioning and compatibility |
| 171 | + |
| 172 | +- Semantic‑like versioning across modules. Prefer matching versions (e.g., 0.5.x) for best compatibility. |
| 173 | +- Wire formats (BOC, TL‑B) follow TON specifications; backwards compatibility is preserved unless TON protocol changes. |
| 174 | + |
| 175 | +## Where to go next |
| 176 | + |
| 177 | +- Project README: architecture, badges, and links |
| 178 | +- Wiki/Docs: deeper guides and API references |
| 179 | +- Examples directory: runnable samples |
| 180 | +- Telegram chat: community support and announcements |
| 181 | + |
| 182 | +## Glossary |
| 183 | + |
| 184 | +- Cell — The fundamental immutable binary structure in TON used by TVM. |
| 185 | +- BOC (Bag of Cells) — A container format for serializing graphs of Cells. |
| 186 | +- TL‑B — Type language for describing binary data structures in TON. |
| 187 | +- ADNL — Abstract Datagram Network Layer, a TON network transport. |
| 188 | +- RLDP — Reliable Link over Datagram Protocol used over ADNL. |
| 189 | +- Lite Client — A client that queries TON blockchain data without running a full node. |
0 commit comments