rsk.zone An independent Rootstock reference

Rootstock's internal state

Every account, every contract, every storage cell Rootstock has ever written lives in a single tree called the Unitrie. This is a census of it: what is actually in there, counted by walking the whole structure rather than asking a node a question it cannot answer.

What the Unitrie is

Ethereum keeps its state in several separate structures: one trie for accounts, a further trie per contract for that contract's storage, and contract code held outside both. Rootstock inherited that arrangement and then abandoned it.

The Unitrie is a single tree holding all three. Accounts, the code of every contract, and every storage cell of every contract occupy one structure under one root hash. RSKIP16, which proposed it in 2016, is direct about the motivation, and it is not elegance:

The main problem is garbage collection: to prevent the state storage to grow without limit, old and unused parts of the state must be removed… However doing this over several synchronized databases without interrupting a full node requires a complex and error-prone garbage collecting algorithm. Therefore it's highly beneficial if all the information is held in a single trie.

Several things follow from the choice. One cache instead of several. One structure to synchronise rather than three that must agree. A single proof can cover an account and the storage cell beneath it, because they share a path. And the key space has room for things that are not accounts at all, which is how the design anticipated storing data such as block commitments for light clients beside the state proper.

The Unitrie arrived on mainnet with the Wasabi upgrade at block 1,591,000, on 18 Jul 2019. The release notes list it first among the changes, and warn operators that starting the new version would migrate their database — a one-time process of up to fifteen minutes. Later RSKIPs refine it rather than replace it: RSKIP107 on smaller nodes, RSKIP108 on a more efficient key mapping, and RSKIP112 on node identifiers.

RSKIP16 — Combined State Tree, the original proposal

rskj WASABI-1.0.0 release notes — "New state internal data structure (Unitrie)"

rskj — co/rsk/trie/Trie.java, the reference implementation

What the state contains

Measured at block 9,398,198, state root 0x071a9d9de5193cce…

Accounts
558,456
24,715 with code
Storage cells
5,729,719
across all contracts
Trie on disk
925.3 MB
12,587,626 nodes
Contract code
91.0 MB
deployed bytecode

Nine years of a live chain come to under a gigabyte of state. That is the number worth sitting with: the entire condition of the network — who holds what, every contract and everything each one remembers — is smaller than a phone's photo library.

Accounts

Account census at block 9,398,198
CategoryCountShareWhat it means
All accounts558,456100.00%Every account the state knows about.
Externally owned533,74195.57%No code. Controlled by a private key, or simply touched once and left.
Contracts24,7154.43%Accounts with a code leaf. That is the only definition the trie itself supports.
With a balance108,84719.49%Holding more than zero RBTC.
With a nonce142,47225.51%Has sent at least one transaction.

Only 19.5% of accounts hold any RBTC, and 25.5% have ever sent a transaction. The rest exist because something referred to them — a transfer that arrived and was spent, a contract that wrote to an address — and the trie remembers them regardless. An account is cheap to create and nothing removes it.

Contracts are 4.43% of all accounts, about one in 23.

Contract code

24,715 contracts hold 91.0 MB of bytecode between them. The average is 3,682 bytes and the largest is 24,573. That largest figure lands three bytes below 24,576, the cap Ethereum placed on contract size in EIP-170 — suggestive, though whether Rootstock enforces the same limit is not established here.

24,528 of those 24,715 code values are held outside their trie node. A value of 32 bytes or less is stored inline in the node itself; anything longer lives separately and the node keeps a reference. Almost all contract code is longer, so almost all of it sits out of line — the 187 exceptions are contracts whose entire compiled body fits in 32 bytes.

Contract storage

5,729,719 storage cells hold 114.0 MB — an average of 232 cells per contract, though averages hide a great deal here. Storage is 55.6% of all the value bytes in the state; contract code is the remainder.

Why there are more storage roots than contracts

There are 24,868 storage roots against 24,715 contracts — 153 more. The difference is accounts that have storage but no code. An account can be given a storage prefix without ever receiving a code leaf, and the census counts what is there rather than what ought to be. A small positive difference is expected; a large one would be worth investigating.

Why these numbers can be trusted

A census counts things nobody can check by eye. If the walk had quietly skipped a subtree, every figure on this page would be too low and would still look perfectly reasonable. So the census is not published unless it satisfies five conditions, each of which catches a different way the file could be wrong while appearing right.

All five checked before publication; the collector fails rather than publishing a figure that does not hold
CheckResultWhat it would mean otherwise
The scan ran to completionholdsA partial census that looks complete is the failure worth avoiding.
No unrecognised keysholdsLeaves were skipped, so every count is an undercount.
No undecodable accountsholdsSame: the account total is lower than reality.
Contracts + externally owned = totalholdsThe two categories do not partition the accounts.
Total balance is exactly 21,000,000 RBTCholdsA node bug or corrupt state.
On the supply figure

The last check is an invariant, not a measurement, and it is worth being clear that it says nothing about the peg. Rootstock mints no RBTC: the genesis block hands the Bridge the entire 21,000,000 and every balance since is a slice of that one premine. The total must therefore read exactly 21,000,000 RBTC at every height, for ever. It is computed here precisely because a number that must never change is the cheapest possible detector of a state that has.

How the census is taken

No RPC method answers "how many accounts are there". Answering needs a walk over the whole trie, which is the kind of question a node is not built to be asked. The walk is done by a separate read-only tool against the node's own trie store, taking no lock and writing nothing but its output.

The obvious way to do it does not work. A recursive descent issues dependent reads — the address of the next read comes out of the result of the last — so the disk sees one request outstanding at a time, and the page cache stops helping once the working set outgrows it. The rate falls away as the scan goes deeper, and a full pass over a trie this size is not realistically finishable that way.

The census tool splits before it walks. Every node records the byte weight of its children, so a subtree's size is known without reading it: take the largest piece, split it, repeat until no piece is large, then let workers claim pieces from a shared counter. The same committed sizes make the progress figure honest — bytes genuinely accounted for rather than nodes extrapolated.

The result is a complete scan of 12,587,626 nodes in 63 seconds at 201,451 nodes a second, on 2 threads, against a live node.

It runs at block head − 20 rather than at the head. A census of a block that is later reorganised away is worse than no census at all.

Rustock — the trie_census tool and its documentation