World State

Overview

The primary functions of the world state package are to maintain the collection of Merkle Trees comprising the global state of the system and to offer an interface with which the trees can be queried.

The Merkle Tree DB, a collection of Merkle Trees of varying types.

As of the time of writing the collection consisted of the following trees.

Standard 'Append Only' trees

• The Contract Tree. Every contract created within the system has a 'Function Tree', a tree of leaves generated from the functions on the contract. The root of the function tree is inserted as a leaf in the contracts tree.
• The Contract Tree Roots Tree. A tree whose leaves are the historical roots of the contract tree.
• The Note Hash Tree. A tree whose leaves are the note hashes of notes generated by the private contract function calls within the system.
• The Note Hash Tree Roots Tree. A tree whose leaves are the historical roots of the note hash tree.

Indexed trees

• The Nullifier Tree. A tree whose leaves contain the consumed values (commitments, tx hashes etc) of the system.

Sparse trees

• The Public Data Tree. A tree whose leaves are the current value of every item of public state in the system, addressed as leaf_index = hash(contract_address, storage_slot_in_contract)

The Synchronizer

The synchronizer's role is to periodically poll for new block information and reconcile that information with the current state of the Merkle Trees.

Once a new block is received, the synchronizer checks the uncommitted root values of all of the trees against the roots published as part of the block. If they are all equal, the tree state is committed. If they are not equal, the tree states are rolled back to the last committed state before the published data is inserted and committed.

The Merkle Tree Interface

The interface to the Merkle Tree DB offers a unified asynchronous API to the set of trees available. Reads from the Merkle Trees need to be marked as to whether they should include uncommitted state. For this reason, the MerkleTreeOperationsFacade exists to abstract this detail away from the end consumer.

Building/Testing

Building the package is as simple as calling yarn build from the package root.

Running yarn test will execute the packages unit tests.