diff --git a/yellow-paper/docs/contracts/index.md b/yellow-paper/docs/contracts/index.md index ef08e33450a2..52130daf1abf 100644 --- a/yellow-paper/docs/contracts/index.md +++ b/yellow-paper/docs/contracts/index.md @@ -1,5 +1,6 @@ --- title: Cross-chain communication +sidebar_position: 100 --- This section describes what our L1 contracts do, what they are responsible for and how they interact with the circuits. diff --git a/yellow-paper/docs/rollup-circuits/base_rollup.md b/yellow-paper/docs/rollup-circuits/base_rollup.md new file mode 100644 index 000000000000..9a20ebc4c77f --- /dev/null +++ b/yellow-paper/docs/rollup-circuits/base_rollup.md @@ -0,0 +1,4 @@ +--- +title: Base Rollup +sidebar_position: 2 +--- \ No newline at end of file diff --git a/yellow-paper/docs/rollup-circuits/index.md b/yellow-paper/docs/rollup-circuits/index.md index 19c78f38ac11..33b757fde755 100644 --- a/yellow-paper/docs/rollup-circuits/index.md +++ b/yellow-paper/docs/rollup-circuits/index.md @@ -1,14 +1,56 @@ --- title: Rollup Circuits +sidebar_position: 99 --- + +import DocCardList from '@theme/DocCardList'; + + + :::warning This part is not yet complete, only just started. I'm considering whether to create some of the types that @benesjan and I discussed to improve clarity on the snapshots etc a bit more. Should make it a bit easier to follow what is going on. ::: -# Rollup Circuits - ## Overview +To generate our rollups, we are using a tree structure for the proofs. Rolling the proofs up in this order allows us to keep the workload of the individual proof small, while making it very parallelizable. This works very well for case where we want many actors to be able to participate in the proof generation. + +The tree structure is outlined below, but the general idea is that we have a tree where all the leafs are transactions (kernel proofs) and through $\log n$ steps we can then "compress" it down to just a single proof. Note that we have three (3) different types of "merger" circuits, namely: +- The base rollup + - Merges two kernel proofs +- The merge rollup + - Merges two base rollup proofs OR two merge rollup proofs +- The root rollup + - Merges two merge rollup proofs + +In the diagram the size of the tree is limited for show, but a larger tree will have more layers of merge rollups proofs. + +```mermaid +graph TD + R[Root] --> M0[Merge 0] + R --> M1[Merge 1] + + M0 --> B0[Base 0] + M0 --> B1[Base 1] + M1 --> B2[Base 2] + M1 --> B3[Base 3] + + B0 --> K0[Kernel 0] + B0 --> K1[Kernel 1] + B1 --> K2[Kernel 2] + B1 --> K3[Kernel 3] + B2 --> K4[Kernel 4] + B2 --> K5[Kernel 5] + B3 --> K6[Kernel 6] + B3 --> K7[Kernel 7] +``` + +In the coming sections we will look at the flow, and then go into the checks that each of the rollups perform. + +### Types + + + ## Base Rollup ### Inputs @@ -136,7 +178,7 @@ It is unclear how we do this at the current moment. ## Merge Rollup ## Root Rollup - +The root rollup output (public inputs) will be the values that make their way onto the validating light node, see **REFERENCE** for more. ### Updating trees Algorithm gives - Given a list of leaves to add, create a Merkle tree of them diff --git a/yellow-paper/docs/rollup-circuits/merge_rollup.md b/yellow-paper/docs/rollup-circuits/merge_rollup.md new file mode 100644 index 000000000000..d586d962ce7c --- /dev/null +++ b/yellow-paper/docs/rollup-circuits/merge_rollup.md @@ -0,0 +1,4 @@ +--- +title: Merge Rollup +sidebar_position: 3 +--- \ No newline at end of file diff --git a/yellow-paper/docs/rollup-circuits/root_rollup.md b/yellow-paper/docs/rollup-circuits/root_rollup.md new file mode 100644 index 000000000000..4e182a3fdbb4 --- /dev/null +++ b/yellow-paper/docs/rollup-circuits/root_rollup.md @@ -0,0 +1,4 @@ +--- +title: Root Rollup +sidebar_position: 4 +--- \ No newline at end of file diff --git a/yellow-paper/docs/rollup-circuits/types.md b/yellow-paper/docs/rollup-circuits/types.md new file mode 100644 index 000000000000..7dbd058fe5ad --- /dev/null +++ b/yellow-paper/docs/rollup-circuits/types.md @@ -0,0 +1,325 @@ +--- +title: Types +sidebar_position: 1 +--- + +# Types + + +## State + + +```mermaid +classDiagram +direction TB + + +class PartialStateReference { + noteHashTree: Snapshot + nullifierTree: Snapshot + contractTree: Snapshot + publicDataTree: Snapshot +} + +class StateReference { + l1ToL2MessageTree: Snapshot +} +StateReference *-- PartialStateReference: partial + +class GlobalVariables { + block_number: Fr + timestamp: Fr + version: Fr + chain_id: Fr + coinbase: Address +} + +class Header { + last_archive: Snapshot +} +Header *.. Header : parentHash +Header *.. Body : contentHash +Header *-- StateReference : state +Header *-- GlobalVariables : globalVariables + +class Logs { + private: EncryptedLogs + public: UnencryptedLogs +} + + +class PublicDataWrite { + index: Fr + value: Fr +} + + +class ContractData { + leaf: Fr + address: Address + portal: EthAddress +} + +class TxEffect { + noteHashes: List~Fr~ + nullifiers: List~Fr~ + l2ToL1Msgs: List~Fr~ +} +TxEffect *-- "m" ContractData: contracts +TxEffect *-- "m" PublicDataWrite: publicWrites +TxEffect *-- Logs : logs + +class Body { + l1ToL2Messages: List~Fr~ +} +Body *-- "m" TxEffect + +class Archive { + type: AppendOnlyMerkleTree +} +Archive *-- "m" Header : leaves + + +class NoteHashTree { + type: AppendOnlyMerkleTree + leaves: List~Fr~ +} + +class ContractTree { + type: AppendOnlyMerkleTree +} +ContractTree *.. "m" ContractData : leaves + +class PublicDataTree { + type: SparseMerkleTree +} +PublicDataTree *.. "m" PublicDataWrite : leaves + +class L1ToL2MessageTree { + type: AppendOnlyMerkleTree + leaves: List~Fr~ +} + +class NullifierPreimage { + value: Fr + successor_index: Fr + successor_value: Fr +} + +class NullifierTree { + type: SuccessorMerkleTree +} +NullifierTree *.. "m" NullifierPreimage : leaves + +class State { } +State *-- NoteHashTree : noteHashTree +State *-- NullifierTree : nullifierTree +State *-- L1ToL2MessageTree : l1ToL2MessageTree +State *-- PublicDataTree : publicDataTree +State *-- ContractTree : contractTree +State *-- Archive : archive +``` + +## Overview +Below is a partial diagram of all the types and how they are connected. This is particularly interested in the data that go into and comes out of the rollup circuits and don't care particularly about the data for kernels right now. + +```mermaid +classDiagram +direction TB + + +class PartialStateReference { + noteHashTree: Snapshot + nullifierTree: Snapshot + contractTree: Snapshot + publicDataTree: Snapshot +} + +class StateReference { + l1ToL2MessageTree: Snapshot +} +StateReference *-- PartialStateReference: partial + +class GlobalVariables { + block_number: Fr + timestamp: Fr + version: Fr + chain_id: Fr + coinbase: Address +} + +class Header { + last_archive: Snapshot +} +Header *.. Header : parentHash +Header *.. Body : contentHash +Header *-- StateReference : state +Header *-- GlobalVariables : globalVariables + +class ContractData { + leaf: Fr + address: Address + portal: EthAddress +} + +class Logs { + private: EncryptedLogs + public: UnencryptedLogs +} + +class PublicDataWrite { + index: Fr + value: Fr +} + +class TxEffect { + noteHashes: List~Fr~ + nullifiers: List~Fr~ + l2ToL1Msgs: List~Fr~ +} +TxEffect *-- "m" ContractData: contracts +TxEffect *-- "m" PublicDataWrite: publicWrites +TxEffect *-- Logs : logs + +class Body { + l1ToL2Messages: List~Fr~ +} +Body *-- "m" TxEffect + +class ProvenBlock { + archive: Snapshot +} + +ProvenBlock *-- Header : header +ProvenBlock *-- Body : body + + + + +class ConstantRollupData { + last_archive: Snapshot + base_rollup_vk_hash: Fr, + merge_rollup_vk_hash: Fr, +} +ConstantRollupData *-- GlobalVariables : globalVariables + +class PublicDataUpdateRequest { + index: Fr + old_value: Fr + new_value: Fr +} + +class PublicDataRead { + index: Fr + value: Fr +} + +class CombinedAccumulatedData { + aggregation_object: AggregationObject + read_requests: List~Fr~ + pending_read_requests: List~Fr~ + note_hashes: List~Fr~ + nullifiers: List~Fr~ + nullified_note_hashes: List~Fr~ + + l2_to_l1_messages: List~Fr~ + + private_call_stack: List~CallRequest~ + public_call_stack: List~CallRequest~ +} +CombinedAccumulatedData *-- "m" ContractData: contracts +CombinedAccumulatedData *-- "m" PublicDataUpdateRequest: publicUpdateRequests +CombinedAccumulatedData *-- "m" PublicDataRead: publicReads +CombinedAccumulatedData *-- Logs : logs + +class ContractDeploymentData { + deployer_public_key: Point + constructor_vk_hash: Fr + constructor_args_hash: Fr + function_tree_root: Fr + salt: Fr + portal_address: Fr +} + +class TxContext { + fee_context: FeeContext + is_contract_deployment: bool + chain_id: Fr + version: Fr +} +TxContext *-- ContractDeploymentData: contract_deployment_data + +class CombinedConstantData { } +CombinedConstantData *-- Header : historical_header +CombinedConstantData *-- TxContext : tx_context + +class KernelPublicInputs { + constants: CombinedConstantData + is_private: bool +} +KernelPublicInputs *-- CombinedAccumulatedData : end +KernelPublicInputs *-- CombinedConstantData : constants + +class KernelData { + proof: Proof +} +KernelData *-- KernelPublicInputs : publicInputs + +class StateDiffHints { + nullifier_predecessor_preimages: List~NullifierLeafPreimage~ + nullifier_predecessor_membership_witnesses: List~NullifierMembershipWitness~ + sorted_nullifiers: List~Fr~ + sorted_nullifier_indexes: List~Fr~ + note_hash_subtree_sibling_path: List~Fr~, + nullifier_hash_subtree_sibling_path: List~Fr~, + contracts_subtree_sibling_path: List~Fr~, + public_data_update_requests_sibling_paths: List~List~Fr~~ + public_data_reads_sibling_paths: List~List~Fr~~ +} + +class BaseRollupInputs { + historical_header_membership_witnesses: List~HeaderMembershipWitness~ +} +BaseRollupInputs *-- "m" KernelData : kernelData +BaseRollupInputs *-- PartialStateReference : partial +BaseRollupInputs *-- StateDiffHints : stateDiffHints +BaseRollupInputs *-- ConstantRollupData : constants + + +class BaseOrMergeRollupPublicInputs { + type: Fr + height_in_block_tree: Fr + aggregation_object: AggregationObject + content_hash: Fr[2] +} + +BaseOrMergeRollupPublicInputs *-- PartialStateReference : start +BaseOrMergeRollupPublicInputs *-- PartialStateReference : end + +class ChildRollupData { + proof: Proof +} +ChildRollupData *-- BaseOrMergeRollupPublicInputs: inputs + +class MergeRollupInputs { } +MergeRollupInputs *-- ChildRollupData: left +MergeRollupInputs *-- ChildRollupData: right + +class RootRollupInputs { + l1_to_l2_msgs_tree: Snapshot + l1_to_l2_msgs: List~Fr~ + l1_to_l2_msgs_sibling_path: List~Fr~ + + last_archive: Snapshot + archive_sibling_path: List~Fr~ +} +RootRollupInputs *-- ChildRollupData: left +RootRollupInputs *-- ChildRollupData: right + + +class RootRollupPublicInputs { + aggregation_object: AggregationObject + archive: Snapshot +} +RootRollupPublicInputs *--Header : header +``` \ No newline at end of file