Ledger ADTs
Reference for Midnight's ledger abstract data types for on-chain state management.
Available ADTs
| ADT |
Purpose |
Key Operations |
Cell<T> |
Single mutable value |
read, write |
Counter |
Increment-only counter |
increment, value |
Map<K, V> |
Key-value storage |
lookup, insert, remove |
Set<T> |
Membership collection |
member, insert, remove |
List<T> |
Ordered collection |
append, nth, length |
MerkleTree<T> |
Membership proofs |
insert, root, pathForLeaf |
HistoricMerkleTree<T> |
Historical roots |
Same + resetHistory |
Quick Examples
Counter
ledger counter: Counter;
export circuit increment(): Uint<64> {
counter.increment(1);
return counter.value();
}
Map
ledger balances: Map<Bytes<32>, Uint<64>>;
export circuit get_balance(user: Bytes<32>): Uint<64> {
const result = balances.lookup(user);
return if result is Maybe::Some(balance) { balance } else { 0 };
}
MerkleTree
ledger members: MerkleTree<Bytes<32>>;
export circuit prove_membership(
leaf: Bytes<32>,
path: Vector<Bytes<32>, 20>
): Boolean {
const computed_root = merkleTreePathRoot(leaf, path);
return computed_root == members.root();
}
Compact vs TypeScript Operations
Some ADT operations are only available in TypeScript:
| ADT |
Compact |
TypeScript Only |
| Counter |
value, increment |
- |
| Map |
lookup, insert, remove |
entries, keys |
| Set |
member, insert, remove |
entries, size |
| List |
nth, append |
entries, length |
| MerkleTree |
insert, root |
pathForLeaf, iteration |
References
1---2name: compact-core-ledger-adts3description: Use when working with Compact on-chain state management using ledger ADTs including Cell, Counter, Map, Set, List, MerkleTree, or HistoricMerkleTree, or when needing to understand which operations are available in Compact vs TypeScript.4---5
6# Ledger ADTs
7
8Reference for Midnight's ledger abstract data types for on-chain state management.
9
10## Available ADTs
11
12| ADT | Purpose | Key Operations |
13|-----|---------|----------------|
14| `Cell<T>` | Single mutable value | `read`, `write` |
15| `Counter` | Increment-only counter | `increment`, `value` |
16| `Map<K, V>` | Key-value storage | `lookup`, `insert`, `remove` |
17| `Set<T>` | Membership collection | `member`, `insert`, `remove` |
18| `List<T>` | Ordered collection | `append`, `nth`, `length` |
19| `MerkleTree<T>` | Membership proofs | `insert`, `root`, `pathForLeaf` |
20| `HistoricMerkleTree<T>` | Historical roots | Same + `resetHistory` |
21
22## Quick Examples
23
24### Counter
25```compact
26ledger counter: Counter;
27
28export circuit increment(): Uint<64> {
29 counter.increment(1);
30 return counter.value();
31}
32```
33
34### Map
35```compact
36ledger balances: Map<Bytes<32>, Uint<64>>;
37
38export circuit get_balance(user: Bytes<32>): Uint<64> {
39 const result = balances.lookup(user);
40 return if result is Maybe::Some(balance) { balance } else { 0 };
41}
42```
43
44### MerkleTree
45```compact
46ledger members: MerkleTree<Bytes<32>>;
47
48export circuit prove_membership(
49 leaf: Bytes<32>,
50 path: Vector<Bytes<32>, 20>
51): Boolean {
52 const computed_root = merkleTreePathRoot(leaf, path);
53 return computed_root == members.root();
54}
55```
56
57## Compact vs TypeScript Operations
58
59Some ADT operations are only available in TypeScript:
60
61| ADT | Compact | TypeScript Only |
62|-----|---------|-----------------|
63| Counter | `value`, `increment` | - |
64| Map | `lookup`, `insert`, `remove` | `entries`, `keys` |
65| Set | `member`, `insert`, `remove` | `entries`, `size` |
66| List | `nth`, `append` | `entries`, `length` |
67| MerkleTree | `insert`, `root` | `pathForLeaf`, iteration |
68
69## References
70
71- [Counter](./references/counter.md) - Counter operations and patterns
72- [Collections](./references/collections.md) - Map, Set, List operations
73- [Merkle Trees](./references/merkle-trees.md) - MerkleTree and HistoricMerkleTree
74- [Kernel](./references/kernel.md) - Special kernel operations
majiayu000