doc(alpen-ee): add alpen-ee readme by sapinb · Pull Request #1212 · alpenlabs/alpen

sapinb · 2025-12-16T11:38:03Z

Description

This covers the components currently implemented in alpen-ee.

AI disclosure: With help from claude, especially for the diagrams.

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature/Enhancement (non-breaking change which adds functionality or enhances an existing one)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update
Refactor
New or updated tests
Dependency Update

Notes to Reviewers

I'm not sure exactly where this should go. Or if it even belongs in this repo. Please suggest if this needs to go elsewhere.
My plan is to update this doc as more pieces of alpen-ee get integrated.

Checklist

I have performed a self-review of my code.
I have commented my code where necessary.
I have updated the documentation if needed.
My changes do not introduce new warnings.
I have added (where necessary) tests that prove my changes are effective or that my feature works.
New and existing tests pass with my changes.
I have disclosed my use of AI in the body of this PR.

Related Issues

This covers the components currently implemented in alpen-ee.

github-actions · 2025-12-16T12:06:24Z

Commit: 2049cd1

SP1 Execution Results

program	cycles	success
EVM EE STF	1,328,617	✅
CL STF	217,204	✅
Checkpoint	2,247	✅

storopoli

Amazing piece of documentation.
Thank you!
I have some suggestions.
Also one question: should we mention ASM or just treat "L1" as a blackbox like we already do?

storopoli · 2025-12-16T13:02:41Z

+
+## System Context
+
+The EE exists within a layered architecture anchored to Bitcoin:


Multiple EEs

Suggested change

The EE exists within a layered architecture anchored to Bitcoin:

EEs exist within a layered architecture anchored to Bitcoin:

storopoli · 2025-12-16T13:03:25Z

+        ┌──────────┐      ┌──────────┐      ┌──────────┐
+        │   EE 1   │      │   EE 2   │      │   EE N   │
+        │  (This)  │      │          │      │          │
+        └──────────┘      └──────────┘      └──────────┘


Suggested change

┌──────────┐ ┌──────────┐ ┌──────────┐

│ EE 1 │ │ EE 2 │ │ EE N │

│ (This) │ │ │ │ │

└──────────┘ └──────────┘ └──────────┘

┌──────────┐ ┌──────────┐ ┌──────────┐

│ EE 1 │ │ EE 2 │ │ EE N │

│ (Alpen) │ │ │ │ │

└──────────┘ └──────────┘ └──────────┘

Better than "this".

storopoli · 2025-12-16T13:05:31Z

+| **OL** | OL blocks grouped into epochs | OL client (not covered here) |
+| **EE** | EVM blocks | `alpen-client` (this binary) |


storopoli · 2025-12-16T13:08:14Z

+
+### Communication Pattern: Watch Channels
+
+Components communicate via `tokio::sync::watch` channels for efficient state broadcasting:


This could get outdated.

Suggested change

Components communicate via `tokio::sync::watch` channels for efficient state broadcasting:

Components communicate via `tokio` channels for efficient state broadcasting:

storopoli · 2025-12-16T13:08:56Z

+└── finalized: EeAccountStateAtEpoch  // State at finalized epoch
+```
+
+**Outputs** (via watch channels):


Suggested change

**Outputs** (via watch channels):

**Outputs** (via `tokio` channels):

storopoli · 2025-12-16T13:14:13Z

+**Responsibilities**:
+- Broadcast new block headers from sequencer
+- Receive and validate block headers from peers
+- Verify sequencer signatures (Schnorr over EIP-191 hash)


Oh god we created a monstrosity 😂 Schnorr over EIP-191 hash.
Are we the only ones using that?

I do have to agree that is BEAUTIFUL.
PKs are always 32 bytes and sigs are always 64 bytes.
EIP-191 hashes gives us ample support from most of the Rust ethereum ecosystem...

Cc @AaronFeickert and/or @sampkaALP for sanity checking.

storopoli · 2025-12-16T13:17:33Z

+**Key Points**:
+- Only messages from finalized OL blocks are processed (to avoid reorg issues)
+- Deposits are rate-limited per block (`max_deposits_per_block`)
+- Subject ID (32 bytes) is truncated to EVM address (20 bytes)


Truncated how? We add zero padding? If yes, to the left or to the right?

add? something needs to be removed.

This is also related with the work in #1229.

storopoli · 2025-12-16T13:17:50Z

+- Only messages from finalized OL blocks are processed (to avoid reorg issues)
+- Deposits are rate-limited per block (`max_deposits_per_block`)
+- Subject ID (32 bytes) is truncated to EVM address (20 bytes)
+- Bitcoin amounts (sats) are converted to wei


Point towards the sats_to_wei function in ee-common?

storopoli · 2025-12-16T13:18:52Z

+     │                │                │              │
+```
+
+**Status**: Withdrawal extraction is implemented. Batch submission to OL with SNARK proofs is not yet implemented.


I think we should remove the status, since we are working on batch assembly already.

Suggested change

**Status**: Withdrawal extraction is implemented. Batch submission to OL with SNARK proofs is not yet implemented.

storopoli · 2025-12-16T13:19:55Z

+- **Batch Assembly**: Grouping multiple EE blocks into batches for OL submission
+- **SNARK Proof Generation**: Proving EE state transitions
+- **OL Update Submission**: Posting proofs and state updates to OL
+- **Cross-EE Messaging**: Messages between different EEs via OL
+- **Independent Block Sync**: EE fullnodes currently rely on sequencer P2P


This has the risk of getting outdated soon.
We should just removed. It does not add anything from what we already know from our tickets and sprint planning.

at least let's add a date

bewakes

Very comprehensive! I like this.
Agree with @storopoli 's comments.

barakshani · 2025-12-19T11:03:53Z

+
+Fullnodes learn about new blocks through two mechanisms:
+
+1. **Consensus (Confirmed/Finalized)**: From OL via OL Tracker


let's add that in this case they actually learn about a sequence of blocks

barakshani · 2025-12-19T11:06:35Z

+
+**Important**: EE fullnodes do not have independent block sync. They rely on:
+- Reth's P2P for block data (triggered by gossip)
+- OL for consensus (confirmed/finalized status)


this is not quite block sync, right? (not only that technically this does not sync blocks, but) we are not syncing data from OL, it is needed to be fetched from bitcoin. This is not implemented right now, correct?

barakshani · 2025-12-19T11:10:37Z

+     ├─────────────►│              │              │
+     │              │              │              │
+     │   finalized  │              │              │
+     │◄─────────────┤              │              │


do we have a better way to pass the message that this should be a finalized block? The way I currently read it is that OL sends some finalized object to L1, but in fact it is not finalized when sent.

It would also be good to explain what this (finalized) object is. I am not sure.

barakshani · 2025-12-19T11:12:05Z

+**Key Points**:
+- Only messages from finalized OL blocks are processed (to avoid reorg issues)
+- Deposits are rate-limited per block (`max_deposits_per_block`)
+- Subject ID (32 bytes) is truncated to EVM address (20 bytes)


add? something needs to be removed.

barakshani · 2025-12-19T11:14:58Z

+```
+
+**Key Points**:
+- Only messages from finalized OL blocks are processed (to avoid reorg issues)


I fail to follow something here: what happens between DT and the inbox msg? Do we literally just wait for an OL batch that covers the L1 range where the DT is to be posted to and buried in L1? If so, I don't really see a reason for it.

barakshani · 2025-12-19T11:16:47Z

+- **Batch Assembly**: Grouping multiple EE blocks into batches for OL submission
+- **SNARK Proof Generation**: Proving EE state transitions
+- **OL Update Submission**: Posting proofs and state updates to OL
+- **Cross-EE Messaging**: Messages between different EEs via OL
+- **Independent Block Sync**: EE fullnodes currently rely on sequencer P2P


at least let's add a date

prajwolrg

This is really nice. Thank you so much.

I just have added a few nits.

prajwolrg · 2025-12-30T06:47:48Z

+┌─────────────────────────────────────────────────────────────────────┐
+│                         Bitcoin (L1)                                │
+│   - Source of truth for finality                                    │
+│   - Data Availability (DA) for OL state                             │


I don't think we need to talk about OL DA here. Maybe we should mention about EE DA instead.

prajwolrg · 2025-12-30T06:57:34Z

+```
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│   L1    │    │   OL    │    │   EE    │    │   EVM   │
+│(Bitcoin)│    │         │    │ Client  │    │  State  │
+└────┬────┘    └────┬────┘    └────┬────┘    └────┬────┘
+     │              │              │              │
+     │ deposit tx   │              │              │
+     ├─────────────►│              │              │
+     │              │              │              │
+     │   finalized  │              │              │
+     │◄─────────────┤              │              │


Doesn't mermaid support this?

prajwolrg · 2025-12-30T07:01:33Z

+**Key Points**:
+- Only messages from finalized OL blocks are processed (to avoid reorg issues)
+- Deposits are rate-limited per block (`max_deposits_per_block`)
+- Subject ID (32 bytes) is truncated to EVM address (20 bytes)


This is also related with the work in #1229.

prajwolrg · 2025-12-30T07:02:23Z

+```
+┌─────────┐    ┌─────────────┐    ┌─────────┐    ┌─────────┐
+│   EVM   │    │   Payload   │    │   OL    │    │   L1    │
+│  State  │    │   Builder   │    │         │    │(Bitcoin)│
+└────┬────┘    └──────┬──────┘    └────┬────┘    └────┬────┘
+     │                │                │              │
+     │ withdrawal     │                │              │
+     │ intent         │                │              │
+     ├───────────────►│                │              │
+     │                │                │              │
+     │                │ BlockOutputs   │              │
+     │                │ (SentMessage)  │              │
+     │                ├───────────────►│              │
+     │                │                │              │
+     │                │                │    bridge    │
+     │                │                ├─────────────►│
+     │                │                │              │
+```


nit: if we can use mermaid here.

barakshani · 2026-01-30T15:13:08Z

@sapinb let's push to merge this? It's stale for a month now

doc(alpen-ee): add alpen-ee architecture docs

8ec8ad2

This covers the components currently implemented in alpen-ee.

sapinb requested review from a team as code owners December 16, 2025 11:38

doc: moving to readme

67ff500

lint: ignore olt in codespell

8b0cd89

sapinb changed the title ~~doc(alpen-ee): add alpen-ee architecture docs~~ doc(alpen-ee): add alpen-ee readme Dec 16, 2025

storopoli requested changes Dec 16, 2025

View reviewed changes

storopoli assigned sapinb Dec 16, 2025

storopoli added the P2 - Nice to Have label Dec 16, 2025

bewakes reviewed Dec 16, 2025

View reviewed changes

barakshani reviewed Dec 19, 2025

View reviewed changes

prajwolrg approved these changes Dec 30, 2025

View reviewed changes


		## System Context

		The EE exists within a layered architecture anchored to Bitcoin:

	The EE exists within a layered architecture anchored to Bitcoin:
	EEs exist within a layered architecture anchored to Bitcoin:

		\| OL \| OL blocks grouped into epochs \| OL client (not covered here) \|
		\| EE \| EVM blocks \| `alpen-client` (this binary) \|


		### Communication Pattern: Watch Channels

		Components communicate via `tokio::sync::watch` channels for efficient state broadcasting:

	Components communicate via `tokio::sync::watch` channels for efficient state broadcasting:
	Components communicate via `tokio` channels for efficient state broadcasting:

	Outputs (via watch channels):
	Outputs (via `tokio` channels):


		Fullnodes learn about new blocks through two mechanisms:

		1. Consensus (Confirmed/Finalized): From OL via OL Tracker

Conversation

sapinb commented Dec 16, 2025

Description

Type of Change

Notes to Reviewers

Checklist

Related Issues

Uh oh!

github-actions Bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

storopoli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bewakes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prajwolrg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

barakshani commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented Dec 16, 2025 •

edited

Loading