Blockchain TL-B Coverage
Purpose And Source
This page tracks the checked blockchain TL-B surface implemented in src/tlb.
The protocol source of truth is upstream ton-blockchain/ton
crypto/block/block.tlb; the local checked snapshot is
src/tlb/schemas/block.tlb.
The current snapshot is not yet the complete upstream file. It contains the families that are backed by typed codecs or raw-preserving public wrappers. Full upstream sync, constructor drift checks for every family, and fixture-backed block/shard/config/proof roundtrips remain active TODO items.
Coverage Matrix
| Upstream family | Rust model | Codec status | Tests or examples |
|---|---|---|---|
MsgAddress, Message, StateInit | tlb::message::* | typed | TL-B unit tests, tlb_message_roundtrip |
Account, ShardAccount | tlb::transaction::* | typed | TL-B unit tests, tlb_account_state_roundtrip |
Transaction, phases, account blocks | tlb::transaction::* | typed | TL-B unit tests, tlb_transaction_roundtrip, tlb_read_tx_data |
ShardIdent, ExtBlkRef, BlockIdExt | tlb::block::* | typed | block unit tests |
Block | tlb::Block | typed root with referenced child cells | tlb_block_wrapper_decode |
BlockInfo, BlockPrevInfo | tlb::BlockInfo, tlb::BlockPrevInfo | raw-preserving wrappers | schema summary check |
ValueFlow | tlb::ValueFlow | constructor-checked raw payload | block unit tests |
BlockExtra, McBlockExtra | tlb::BlockExtra, tlb::McBlockExtra | raw-preserving wrappers | schema summary check |
ShardState, ShardStateUnsplit | tlb::ShardState, tlb::ShardStateUnsplit | constructor-checked raw payload | block unit tests |
ConfigParams | tlb::ConfigParams | typed address, decoded Hashmap 32 ^Cell entries, raw-preserving wrappers for common param ids | tlb_config_params_wrapper, block unit tests |
HASH_UPDATE | tlb::HashUpdate | typed | block unit tests |
MERKLE_PROOF, MERKLE_UPDATE | tlb::MerkleProof, tlb::MerkleUpdate | exotic-cell wrappers with virtual hash checks | proof_verify |
Derive And Adapter Surface
The optional tlb-derive feature enables the tonutils-macros proc-macro
crate and re-exports tlb::Tlb and tlb::TlbDerive. The macro generates the
existing runtime traits, not a separate runtime. Supported attributes are:
#[tlb(tag = "101")],#[tlb(tag = "0b101")],#[tlb(tag = "0x5")], and#[tlb(tag = "#5")]on structs or enum variants for fixed constructor tags. Hex tags expand to four bits per digit.#[tlb(bits = N)]on integer/hash fields for exact-width encoding throughStoreBits<N>andLoadBits<N>. Unsigned primitive fieldsu8,u16,u32,u64, andu128infer their natural width. Signed integer fields requirebits; float primitive fields are rejected because the runtime does not define TL-B float semantics.#[tlb(reference)]or#[tlb(ref)]on fields for^Tchild-cell encoding.
Runtime helpers added for macro and handwritten codecs:
CellRef<T>for referenced typed values.RawCellfor intentionally opaque cell payloads.VarUInteger<N>for canonical variable-width unsigned integers.TlbHashmapE<T, N>for typed dictionary values using TL-B codecs.
Exact top-level decode continues to use TlbDeserialize::from_cell, which
rejects trailing bits and references. Referenced decode uses load_ref_tlb and
also requires exact child consumption.
Known Limits
The derive macro currently handles product structs and simple tagged enums. It
does not yet generate schema-driven dictionary adapters, parameterized TL-B
types, implicit CRC tags, ambiguous-prefix decision trees, or trybuild-style
negative tests. Those gaps are tracked in TODO.md.