co-work-stark-specs

This repository provides a systematic breakdown and explanation of core components in the Starknet protocol implementation.

The main focus is on three key modules: Sequencer, Prover, and Settlement. The code spans across multiple repositories including starkware-libs/sequencer, starkware-libs/stone-prover, starkware-libs/starkex-contracts, madara-alliance/madara, and starkware-libs/cairo-lang.

Architecture Overview

Quick Example: How a Transfer Flows Through the System

Below is a simple example that ties together the three core components - Sequencer, Prover, and Settlement - to help you build a mental model before diving into the documentation.

Let's say Alice wants to send 1 ETH to Bob on Starknet. The process goes through these three stages:

1. Sequencer - Queue, Execute, Package

1. The transaction first enters the Sequencer's memory pool (mempool).
2. The Sequencer picks a batch of transactions from the queue, executes them locally, and verifies rules like sufficient balance.
3. Successful transactions are written to a block; failed ones are dropped or rolled back.
4. Once sealed, the block is broadcast to other Sequencers for quick consensus.

2. Prover - Mathematical Proof

1. The newly confirmed block enters the Prover queue, where it can be processed in parallel with other blocks.
2. The Prover records the complete Execution Trace and State Diff.
3. It then performs "blow-up and mixing" operations to amplify and randomize potential errors.
4. The algorithm randomly samples to generate a STARK proof that will fail if there are any data inconsistencies.

3. Settlement - Ethereum Final Settlement

1. The Prover packages the "STARK proof + State Diff" into an L1 transaction and sends it to Ethereum.
2. The Ethereum Verifier contract spot-checks the proof and rejects it immediately if any inconsistencies are found.
3. After passing verification, the Starknet Core contract updates the state.
4. The updated state is permanently stored with the Ethereum block, giving the transaction its finality.

This example shows the complete cycle of Sequencer → Prover → Settlement, which are the main focus of this repository. Other sections like Governance and Chore provide supplementary information to help you better understand the Starknet ecosystem.

The following documentation is arranged in recommended reading order:

First of First

• First of First

Sequencer

1. Sequencer Overview
2. Mempool
3. Transaction Flow
4. Block Sealing
5. Consensus

Prover

1. Prover Line-up
2. Execution Trace
3. State Diff
4. Data Blow-up
5. Valid Data

Settlement

1. Proof & State Diff
2. Verifier Flow
3. Failure Handling
4. Starknet Core
5. Finalized

Governance

• Governance
• Governance Demo

Chore (Additional Resources)

• Engine API
• Cairo VM
• Derivation
• Deposit
• Withdraw
• Madara Data Submission Job
• Mastering the Stone Prover for Developers
• Starknet Version History

Glossary

• Glossary

---

Feel free to open an Issue or submit a PR for any questions or suggestions.