Java SDK for The Open Network (TON)

[![Based on TON][ton-svg]][ton]

Java libraries and wrapper for interacting with TON blockchain. ton4j requires minimum Java 11.

Maven [![Maven Central][maven-central-svg]][maven-central]

<dependency>
    <groupId>org.ton.ton4j</groupId>
    <artifactId>smartcontract</artifactId>
    <version>2.0.2</version>
</dependency>

Jitpack [![JitPack][jitpack-svg]][jitpack]

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>org.ton.ton4j</groupId>
    <artifactId>ton4j</artifactId>
    <version>2.0.2</version>
</dependency>

Repository structure

You can use each submodule individually. Click the module below to get more details.

• Tonlib - use external Tonlib shared library to communicate with TON blockchain.
• Adnl - Lite-client based on native ADNL protocol.
• SmartContract - create and deploy custom and predefined smart-contracts.
• Cell - create, read and manipulate Bag of Cells.
• BitString - construct bit-strings.
• Address - create and parse TON wallet addresses.
• Mnemonic - helpful methods for generating deterministic keys for TON blockchain.
• Emulator - wrapper for using with external precompiled emulator shared library.
• Exporter - TON database reader/exporter that uses RocksDB Java JNA libraries.
• Liteclient - wrapper for using with external precompiled lite-client binary.
• TonCenter Client V2 - wrapper used to send REST calls towards TonCenter API v2 .
• TonCenter Client V3 - wrapper used to send REST calls towards TonCenter Indexer API v3 .
• Fift - wrapper for using external precompiled fift binary.
• Func - wrapper for using external precompiled func binary.
• Tolk - wrapper for using external precompiled tolk binary.
• TonConnect – implementation of a TON Connect standard.
• Disassembler - TON Smart Contract disassembler.
• TL-B - TL-B structures and their de/serialization.
• TL - TL structures and their de/serialization. Used mainly for lite-server queries and responses as well as for RockDB key/values.
• Utils - create private and public keys, convert data, etc.

How to use

• Connection
  • Tonlib shared library
  • ADNL lite-client
  • Native lite-client
  • TonCenter API V2
  • TonCenter API V3
  • Ton Provider
• Smart contract address
• Wallets
  • Create
  • Transfer
  • Deploy and transfer with externally signed
  • Transfer to up to 4 recipients
  • Transfer to up to 1000 recipients
  • Transfer to up to 1000 recipients using Secp256k1 and externally signed
  • Send message to a contract
  • Send message signed externally
• Accounts
  • List transactions
  • List messages
  • Get balance
  • Get state
• Get block
• Mnemonic
• NFT
  • Mint NFT collection
  • Mint NFT item
  • Get NFT information
  • Transfer NFT
  • Change NFT collection owner
  • Edit NFT collection content
  • Create your own NFT marketplace
  • Sell NFT
  • Cancel NFT sale
  • Buy NFT
• Jettons
  • Create USDT jetton wallet
  • Transfer USDT to a single wallet
  • Transfer USDT to multiple wallets
  • Mint Jetton
  • Get Jetton information
  • Edit minter jetton content
  • Edit jetton admin address
  • Transfer Jetton
  • Burn Jettons
• DNS
  • Resolve
  • Deploy own root DNS
• Smart Contracts
  • Retrieve contract's information
  • Develop custom smart contract
• BitString
• Cells
  • Create using CellBuilder
  • Parse using CellSlice
  • Hashmaps / Dicts
  • TLB Loader/Serializer
• Emulators
  • TVM emulator
  • TX emulator
• TON Connect
• Smart contract disassembler
• Notes

Connection

In the TON ecosystem you can interact with a TON blockchain in four ways:

• Tonlib shared library — connect to lite-server via tonlibjson.so/dll/dylib shared library;
• ADNL lite-client — used to connect to lite-server using native Java ADNL protocol implementation; In the current implementation it does not download proofs on start and thus is much faster than tonlibjson.
• Native lite-client — a java wrapper for compiled lite-client executable. Handles and parses responses returned by lite-client. Obsolete way of connecting to TON blockchain and should not be used.
• TonCenter API — a java wrapper to interact with a TonCenter HTTP API service. For production usage consider getting an API key.

TonProvider interface is used to unite three most commonly used clients Tonlib, AdnlLiteClient and TonCenter. It is preferable to use it in all smart contract builders. See below.

To quickly run the below snippets, add a lomboc dependency to your project:

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.38</version>
</dependency>

and then other dependencies for particular use cases, like one of the below:

<dependency>
    <groupId>org.ton.ton4j</groupId>
    <artifactId>tonlib</artifactId>
    <version>2.0.2</version>
</dependency>

Tonlib

Connect to the TON Mainnet with the latest tonlibjson downloaded from the TON Github release. You can also specify an absolute path to your tonlibjson shared library.

<dependency>
    <groupId>org.ton.ton4j</groupId>
    <artifactId>tonlib</artifactId>
    <version>2.0.2</version>
</dependency>

Tonlib tonlib =
  Tonlib.builder()
    .pathToTonlibSharedLib(Utils.getTonlibGithubUrl())
    .testnet(false)
    .build();
BlockIdExt block = tonlib.getLast().getLast();
log.info("block {}", block);

More examples with Tonlibjson can be found in tests.

ADNL lite-client

Connect to the TON Mainnet using an ADNL lite-client.

<dependency>
    <groupId>org.ton.ton4j</groupId>
    <artifactId>adnl</artifactId>
    <version>2.0.2</version>
</dependency>

AdnlLiteClient client = AdnlLiteClient.builder().mainnet().build();
MasterchainInfo info = client.getMasterchainInfo();

Connect to the TON Testnet

AdnlLiteClient client = AdnlLiteClient.builder().testnet().build();
MasterchainInfo info = client.getMasterchainInfo();

Connect to MyLocalTon

AdnlLiteClient client = AdnlLiteClient.builder().myLocalTon().build();
MasterchainInfo info = client.getMasterchainInfo();

More examples with AdnlLiteClient can be found in tests.

Native lite-client

<dependency>
    <groupId>org.ton.ton4j</groupId>
    <artifactId>liteclient</artifactId>
    <version>2.0.2</version>
</dependency>

Download lite-client executable and run its methods and parse the results

LiteClient liteClient =
LiteClient.builder()
  .testnet(false)
  .pathToLiteClientBinary(Utils.getLiteClientGithubUrl())
  .build();
String last = liteClient.executeLast();
log.info("Last command stdOut: {}", last);
ResultLastBlock lastParsed = LiteClientParser.parseLast(last);
log.info("Last command parsed: {}", lastParsed);

liteClient.executeRunMethod(
            "EQDCJVrezD71y-KPcTIG-YeKNj4naeiR7odpQgVA1uDsZqPC",
            "(-1,8000000000000000,20301499):070D07EB64D36CCA2D8D20AA644489637059C150E2CD466247C25B4997FB8CD9:D7D7271D466D52D0A98771F9E8DCAA06E43FCE01C977AACD9DE9DAD9A9F9A424",
            "seqno", "");

Download the latest block's dump and parse it

LiteClient liteClient =
  LiteClient.builder()
    .testnet(false)
    .pathToLiteClientBinary(Utils.getLiteClientGithubUrl())
    .build();
Str