Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve execution env + nodes docs #46

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions technical-specs/characteristics/execution-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@

The Citrea VM is a fully Ethereum Virtual Machine (EVM) equivalent VM running on Bitcoin and using $cBTC as its native token. EVMs as a concept are the most battle-tested and mature VM in the cryptocurrency ecosystem. It is a deterministic, stack-based virtual machine, renowned for its ability to efficiently execute smart contracts in a secure and isolated environment.

Citrea implements its own EVM, referred to as a "zkEVM". A zkEVM is a special EVM implementation that makes the full VM implementation provable. Citrea zkEVM is classified as Type 2, which means full equivalency and a scalable and trustless proof system due to being based on zk-STARKs. Citrea zkEVM is built using RISC Zero.
Citrea implements its own EVM, referred to as a "zkEVM". A zkEVM is a special EVM implementation that makes the full VM implementation provable. Citrea zkEVM is classified as Type 2, which means full equivalency and a scalable and trustless proof system due to being based on zk-STARKs. Developers can utilize Solidity, Vyper, and other EVM-compatible languages to develop their smart contracts without any changes.

For further compatibility, Citrea is implemented intentionally to make multiple VMs interoperable.
Citrea zkEVM is built using [RISC Zero](https://www.risczero.com/).

### Differences from Ethereum

- Block times: Citrea as a block time of 2 seconds, compared to Ethereum's 12 seconds.

- Custom Block Gas Limit: Citrea has an 8 million gas limit per block, compared to Ethereum's 30 million. While individual blocks provide a lower block gas limit, given Citrea has a 2 second block time, in a total of 12 seconds Citrea provides more gas throughput than Ethereum (48 million vs 30 million).

<!-- TODO: Improve Fee Calculation Info, perhaps provide more explanation & check correctness -->
- Custom Fee Calculation: In rollups, the fee calculation typically covers two major points: Rollup (i.e. "L2") execution costs and the DA cost (+ proof generation costs for ZK rollups). Citrea has a custom fee calculation mechanism that covers both of these points. However, this mechanism comes with its own challenges as Bitcoin's fee mechanism is entirely different from Ethereum's. In Bitcoin, fees can rise or fall very dramatically in just 1 - 2 blocks. Along with that, if the state diff size is large and sats/vByte is high too, the fees can be even higher. To prevent such volatility and to keep the rollup fees reasonable, Citrea charges a statistically calculated dynamic `L1_FEE_OVERHEAD` along with networks' own fees based on mempool demands. `l1_fee_rate` field is also returned in the RPC requests to inform users as well.

-----

For further compatibility, Citrea is initially intentionally designed to make multiple VMs interoperable. You can find more information about this concept [here](../../future-research/multi-vm-approach.md).
25 changes: 19 additions & 6 deletions technical-specs/characteristics/nodes.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,28 @@
# Nodes

Nodes are machines that run in Citrea network.

There are three types of nodes in Citrea currently:

- [Sequencer](/technical-specs/characteristics/block-production/sequencer.md): A special node that produces blocks in the Citrea network.
<!-- TODO: Fix this link once prover details are more organized -->
- [Prover](/technical-specs/characteristics/proof-generation.md): A special node that generates zero-knowledge proofs of execution for the sequencer's blocks.
- Full Node

## Full Nodes

Full nodes in Citrea are the nodes that sync with the sequencer(s) as well as verify the zk proofs. Full nodes are designed for users who need instant confirmations from the sequencer or need the full history of Citrea.
Full nodes in Citrea are the nodes that sync with the sequencer. They also verify the ZK proofs by reading the DA. Full nodes are designed for users who need instant soft-confirmations from the sequencer or need the full history of Citrea.

#### How it works

Once the sequencer produces a block and broadcasts it over a network of full nodes, full nodes apply the sequencer block to their local state. Their RPC endpoints can then serve the block data to explorers, wallets, and other applications without waiting for additional zk proving unless they're waiting for a finalization.

A sequencer that produced a block then broadcasts the block over a network of full nodes. Full nodes apply the sequencer block to their local state. RPC endpoints can now serve the block data to explorers, wallets, and other applications without waiting for additional zk proving. After a batch of blocks is proven and inscribed in Bitcoin, full nodes extract and verify the proofs. According to the result of the proof they confirm, finalize, or revert the sequencer broadcasted blocks.
After a batch of blocks is proven and inscribed in Bitcoin, full nodes extract and verify the proofs. According to the result of the proof they confirm, finalize, or revert the sequencer broadcasted blocks.

## Light Nodes
Full nodes can store the entire state & history of Citrea. Depending on the run configuration, they can also provide transaction receipts with more details.

&#x20;A light node is a node that is designed to fully validate the full nodes' responses using minimal bandwidth and storage requirements. In Citrea, light nodes run next to a Bitcoin light node (SPV) or full node and only need the several latest Bitcoin block headers to trustlessly access the latest light client proof. They can also directly connect to the peer-to-peer network and retrieve the light client proof through the network.
We're working towards multiple types of full node implementations, such as archival & pruned full nodes, to let users choose the node type that best suits their needs.

Using the state root extracted from the light client proof, Citrea light nodes can validate full node and RPC endpoint responses. With the advancements in light node technology on Bitcoin like ZeroSync header chain proofs, the proofs that verify a chain of Bitcoin block headers thus allow instant sync with Bitcoin headers allowing Citrea light nodes to sync with the rollup near-instantaneously.&#x20;
#### Who can run a full node?

This improvement significantly reduces the trust on full nodes and boosts decentralization of Citrea with more verifying nodes. Such a light node can also live in another blockchain, which enables trust-minimized bridges with every other smart contract-capable blockchain ecosystem.
Anyone can run a full node permissionlessly for their own security. However, please note that there are no keys or incentives to run a full node. For more details, you can visit the node running guide [here](/users/node/run-a-node.md).