Dictionary
TON-specific hash-map data structure built on a tree of cells. The standard way to store associative maps inside a TON contract.
Aliases: ton dictionary, hashmap, dict
Dictionary (formally HashmapE) is TON’s key→value data structure, implemented as a tree of cells. It plays the role Solidity’s mapping plays, but is laid out very differently — as a compressed prefix tree (Patricia trie) entirely inside cells.
Why it exists
Contracts often need to keep many pairs: “address → balance”, “id → NFT data”, “address → permissions”. TVM has no native mapping, and storing thousands of cells in a flat list would be expensive to search. A dictionary gives O(log n) access while staying compact in the cell tree.
Architecture
A dictionary is a cell tree where:
- Internal nodes store separating key prefixes.
- Leaves store values.
- Branching is done bit by bit on the key.
Lookups walk the tree bit by bit. The longer the shared prefix between keys, the denser the tree.
Operations
| Operation | What it does |
|---|---|
dict_get | Read value by key. |
dict_set | Insert or overwrite a value. |
dict_delete | Remove a key. |
dict_min/max | Find the smallest or largest key. |
udict_get_next | Iterate keys in ascending order. |
Tact and Tolk wrap these in typed map<K, V>. FunC exposes the stdlib functions directly.
Things to know
- Gas grows logarithmically. Good in principle, but with very large dictionaries (tens of thousands of entries) operations still become noticeably more expensive.
- Storage fee. Dictionary size feeds directly into the contract’s storage fee. You can hold a lot — but you’ll pay rent on it.
- Off-chain iteration. Walking a full dictionary through TVM is expensive. Most projects index dictionaries off-chain by reading state via a lite-server.
Dictionaries underpin every jetton, NFT collection, registry, and balance map on TON. Understanding them is mandatory for contract developers.