tonutils-go

Instead of manual cell assembly using cell.BeginCell(), use TLB tags to map Go structs directly to TON cells. This is more error-prone to do manually and TLB is the recommended way for application-level code.

Common TLB Tags:

• tlb:"#hex": Exact hex magic/constructor.
• tlb:"## N": Fixed-width integer of N bits.
• tlb:"addr": TON address (*address.Address).
• tlb:"^": Referenced cell (nested value in a different cell).
• tlb:".": Nested struct in the current cell.
• tlb:"maybe <tag>": Optional value (presence bit + value).
• tlb:"either X Y": Selector bit (0 for X, 1 for Y).
• tlb:"dict N": Dictionary with N-bit keys.
• tlb:"?FieldName <tag>": Conditional field based on a previously declared boolean FieldName.

Use tlb.Parse(&struct, cell) to decode and tlb.ToCell(struct) to encode.

type ExamplePayload struct {
    _       tlb.Magic  `tlb:"#a1b2c3d4"` // Magic prefix
    QueryID uint64     `tlb:"## 64"`     // 64-bit uint
    Flags   uint8      `tlb:"## 8"`      // 8-bit uint
    Body    *cell.Cell `tlb:"^"`         // Referenced cell
}

// Parsing
var payload ExamplePayload
if err := tlb.Parse(&payload, payloadCell); err != nil {
    panic(err)
}

// Serializing
payloadCell, err := tlb.ToCell(payload)

The library supports two ways to create proofs:

1. Low-level ProofSkeleton: Used when you know the exact reference indices you want to keep.
2. MerkleProofBuilder (Recommended): Used when you want the proof to follow the path of data you actually loaded from a dictionary, slice, or nested structure. It automatically prunes unloaded branches.

To verify a proof, use cell.CheckProof(merkleProof, hash) or cell.UnwrapProof(merkleProof, hash) to continue reading the proof body.

// Recommended: MerkleProofBuilder
dict := cell.NewDict(32)
// ... populate dict ...

root := dict.AsCell()
proofBuilder := cell.NewMerkleProofBuilder(root)
observed := proofBuilder.Root().AsDict(32)

// Load value (this marks the path in the builder)
loaded, _ := observed.LoadValue(key)
// ... parse loaded value ...

// Create the proof
proof, err := proofBuilder.CreateProof()

// Verify
err = cell.CheckProof(proof, root.Hash())

To interact with the TON blockchain, you must first establish a connection using a connection pool. You can use public liteservers from the official TON configuration JSON files. The library manages a pool of connections and performs load balancing across them.

Note on Consistency: Because the library uses a connection pool, different requests might hit different nodes. If a node hasn't applied a specific block yet, you might encounter errors. To ensure all requests in a specific operation are routed to the same node, use client.StickyContext(context.Background()) and pass the resulting context to your API methods.

client := liteclient.NewConnectionPool()

configUrl := "https://ton-blockchain.github.io/testnet-global.config.json"
err := client.AddConnectionsFromConfigUrl(context.Background(), configUrl)
if err != nil {
    panic(err)
}
api := ton.NewAPIClient(client).WithRetryTimeout(0, 5*time.Second)

// To ensure consistency (all requests to the same node):
ctx := client.StickyContext(context.Background())
// Use 'ctx' in subsequent API calls

You can use existing wallets or generate new ones using wallet.NewSeed(). The library automatically handles contract deployment and initialization upon the first sent message.

Key operations:

• Initialize: Use wallet.FromSeedWithOptions with a seed phrase and wallet version (e.g., wallet.V3).
• Check Balance: Use w.GetBalance(ctx, block) where block is obtained from api.CurrentMasterchainInfo.
• Transfer: Use w.Transfer to send TON to an address with an optional comment.
• Custom Messages: Use w.Send to send any tlb.InternalMessage to any contract.

words := strings.Split("birth pattern ...", " ")

w, err := wallet.FromSeedWithOptions(api, words, wallet.V3)
if err != nil {
    panic(err)
}

block, err := api.CurrentMasterchainInfo(context.Background())
if err != nil {
    panic(err)
}

balance, err := w.GetBalance(context.Background(), block)
if err != nil {
    panic(err)
}

if balance.Nano().Uint64() >= 3000000 {
    addr := address.MustParseAddr("EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N")
    err = w.Transfer(context.Background(), addr, tlb.MustFromTON("0.003"), "Hey bro, happy birthday!")
    if err != nil {
        panic(err)
    }
}

To create a Lite server, use NewServer with a list of ed25519.PrivateKey objects. These keys are used to identify the server during the ADNL handshake. Once initialized, call Listen(addr) to start accepting TCP connections on the specified address. You must provide a query handler using SetQueryHandler to process incoming requests, otherwise, the server will log an error and ignore queries.

Note: SetQueryHandler is called synchronously from the connection read loop. To prevent blocking the server's ability to read new messages, perform heavy processing in a separate goroutine or worker pool.

import (
	"context"
	"crypto/ed25519"
	"github.com/xssnick/tonutils-go/liteclient"
)

// 1. Initialize server with keys
server := liteclient.NewServer([]ed25519.PrivateKey{myPrivateKey})

// 2. Set the query handler
server.SetQueryHandler(func(ctx context.Context, client *liteclient.ServerClient, queryID []byte, query tl.Serializable) {
	// Handle query asynchronously to avoid blocking the read loop
	go func() {
		// ... process query ...
		client.Answer(queryID, response)
	}()
})

// 3. Start listening
err := server.Listen("0.0.0.0:6080")
if err != nil {
	panic(err)
}