Dictionary
TON-специфичная структура данных hash-map, реализованная на дереве cell-ов. Основной способ хранить ассоциативные массивы внутри контрактов.
Синонимы: словарь, ton dictionary, hashmap, dict
Dictionary (или просто HashmapE) — это TON-специфичная структура данных типа ключ→значение, реализованная на дереве cell-ов. Аналог mapping в Solidity, но устроена принципиально иначе — хранится как сжатое префиксное дерево (Patricia trie), полностью внутри cell-структур.
Зачем нужен
Контракту часто надо хранить много пар: «адрес → баланс», «id → данные NFT», «адрес → разрешения». Прямого mapping в TVM нет, и хранить тысячу cell-ов плоским списком было бы дорого по поиску. Dictionary даёт O(log n) доступ при компактном представлении в cell-дереве.
Архитектура
Dictionary — это дерево cell-ов, где:
- Внутренние узлы хранят разделяющие префиксы ключей.
- Листья хранят значения.
- Ветвление — по битам ключа.
Поиск идёт по биту-за-битом ключа, спускаясь по дереву. Чем длиннее общий префикс между ключами, тем плотнее дерево.
Операции
| Операция | Что делает |
|---|---|
dict_get | Получить значение по ключу. |
dict_set | Записать или перезаписать значение. |
dict_delete | Удалить ключ. |
dict_min/max | Найти минимальный/максимальный ключ. |
udict_get_next | Итерация по ключам по возрастанию. |
В Tact / Tolk эти операции обёрнуты в типизированные map<K, V>. В FunC — стандартные функции stdlib.
Что важно знать
- Газ растёт логарифмически. Это хорошо, но при очень больших dictionary (десятки тысяч ключей) операции всё равно становятся заметно дороже.
- Storage-fee. Размер dictionary напрямую влияет на storage-fee контракта. Хранить большие массивы можно — но платить за их объём придётся.
- Iterating off-chain. Полный обход dictionary через TVM дорог. Чаще dictionary индексируют off-chain, читая стейт через лайт-сервер.
Dictionary — основа всех jetton-, NFT-коллекций, реестров, балансов на TON. Понимать, как они устроены, обязательно для контрактного разработчика.