Ol stf draft #1036

bewakes · 2025-09-16T12:50:58Z

Description

This is a draft and PoC implementation of OL STF. It is a PoC but not meant to discard as it follows the spec document to most extent. Some specific details like snark verification and mmr, and possibly some validation are omitted for simplicity.

The PR consists of two aspects:

Add services/stf-runner crate: This is the main change for this PR. All the new OL related types from various docs are present right here. Not the best way to do but I did not want to interfere with other crates. Later we can either swap or replace the types and traits. Also, used the name stf-runner to be different from chain-executor, although similar in functionalities, to reduce confusion.
Add bin/stf-runner-demo binary(using CLAUDE): The sole purpose is to see in action how the state and roots change. This has generator for deposit logs, and ol transactions. See corresponding readme for info on how to run this. This is meant to be removed as this PR evolves.

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

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

delbonis

There's some procedural issues with this PR too, it's bound to be an even huger PR than it appears. It also goes and implements the snark account spec, which should have been implemented separately first (probably in its own crates).

The demo runner crate should be replaced a bunch of unit tests in the stf crate(s). The kinds of operations that are in that crate should be unit tests that we can run more reliably. I realize it's a Claude invention but Claude is really bad at understanding project organization.

delbonis · 2025-09-16T13:19:58Z

crates/services/stf-runner/src/block.rs

+    account_serial: u32,
+    account_id: AccountId,
+    payload: Vec<u8>, // TODO: make this typed, serialization can be done at the edges


Having both the serial and ID is redundant, we should only need the serial.

Also no, the payload should not be typed, because serialization can be done at the edges.

Having both the serial and ID is redundant, we should only need the serial.

Oh yes, having both is redundant.

Regarding payload, we should have some struct that gets serialized into payload: Vec<u8>, right? There's got to be something to serialize.

delbonis · 2025-09-16T13:21:00Z

crates/chainexec/src/output.rs

+pub struct BlockExecutionOutput<WB = WriteBatch, L = LogMessage> {
+    // TODO: Generic parameters, WB and L for transition
    /// State root as computed by the STF.
    computed_state_root: Buf32,

    /// Log messages emitted while executing the block.
    ///
    /// These will eventually be accumulated to be processed by ASM.
-    logs: Vec<LogMessage>,
+    logs: Vec<L>,

    /// Changes to the state we store in the database.
    ///
    /// This is NOT a state diff, that requires more precise tracking.
-    write_batch: WriteBatch,
+    write_batch: WB,
 }

-impl BlockExecutionOutput {
-    pub fn new(computed_state_root: Buf32, logs: Vec<LogMessage>, write_batch: WriteBatch) -> Self {
+impl<WB, L> BlockExecutionOutput<WB, L> {
+    pub fn new(computed_state_root: Buf32, logs: Vec<L>, write_batch: WB) -> Self {


Why were these made generic?

These are transitional. Since the current chainstate differs significantly from the OLState in the spec, I did not want to make intrusive changes on the Chainstate and hence a new OLState which should be merged/replaced in the future. The generic is just to support both, with default being the Chainstate. I guess Log generic can be removed since the LogMessage and OLLog are pretty similar and thus only one should exist.

crates/chaintsn/src/context.rs

delbonis · 2025-09-16T13:22:48Z

crates/chaintsn/src/context.rs

+// TODO/NOTE: There's already a similar trait called `L2Header`, might need to merge those.
 pub trait BlockHeaderContext {


Trying to expose only a minimal amount of information about the block header to avoid an issue with the cyclical state root we had a while ago.

I see. We can probably tackle this with supertraits.

crates/services/stf-runner/src/ledger.rs

delbonis · 2025-09-16T13:34:46Z

crates/services/stf-runner/src/stf.rs

+    // state accessor is expected to allow CRUD operations on state
+    state_accessor: &mut impl StateAccessor<OLState>,
+    // ledger_provider is expected to allow CRUD operations on accounts ledger
+    ledger_provider: &mut impl LedgerProvider,


Why is OLState being passed in explicitly if we have a StateAccessor<OLState> also? Why does LedgerProvider exist separately when StateAccessor was created to be there to support accessing accounts in a structured way?

Why is OLState being passed in explicitly if we have a StateAccessor also?

See the comment on the first argument, I do intend to remove it.

Why does LedgerProvider exist separately when StateAccessor was created to be there to support accessing accounts in a structured way?

We should probably merge them, I had the thought as well. But StateAccessor is already huge so I wanted to separate out the logic.

delbonis · 2025-09-16T13:43:01Z

crates/services/stf-runner/src/service.rs

+    }
+}
+
+impl AsyncService for StfRunnerService {


It would be a sync service not an async one, but this already exists in the chain executor crate.

I see, will keep that in mind. Can I ask what's the rationale for this being Sync and not Async?

all of the DB calls are blocking and IO bound, so there's literally nothing gained by being async

crates/services/stf-runner/src/block.rs

crates/services/stf-runner/src/ledger.rs

barakshani · 2025-09-16T18:39:47Z

crates/services/stf-runner/src/ledger.rs

This supposed to be an account on the OL? There are some functionalities here that I'd defer to a later stage, like messaging. I think that right now the only kind of message we have is deposits, and I'm not sure if this is treated generically.

Yes, the consume_messages is not required actually. The only message that the impl deals with is the deposit messages. All other inter-EE messages are ignored.

crates/services/stf-runner/src/state.rs

barakshani · 2025-09-16T19:20:10Z

crates/services/stf-runner/src/ledger.rs

+        self.root_cache = None;
+    }
+
+    pub fn compute_root(&mut self) -> LedgerResult<Buf32> {


What exactly do we compute here?

This is an abstraction. We compute the accounts root here, or if we have a trie then we could just return the trie root from here.

crates/services/stf-runner/src/ledger.rs

crates/services/stf-runner/src/stf.rs

bewakes · 2025-09-17T04:34:15Z

The demo runner crate should be replaced a bunch of unit tests in the stf crate(s)

Totally agree @delbonis. I'll be gradually adding tests along the way as I start tightening the bolts - at this stage of the PR these feel maintenance burden. The binary is something claude is very good at creating, I can just quickly see what's happening and can be safely removed after a point.

github-actions · 2025-09-17T05:10:12Z

Commit: bcd9aa0

SP1 Execution Results

program	cycles	success
Bitcoin Blockspace	70,870	✅
EVM EE STF	1,172,715	✅
CL STF	377,814	✅
Checkpoint	4,229	✅

…unt processing

…hunks

* fix: shellcheck lints * nix: add shellcheck * just: add shellcheck * ci: add shellcheck

…m `process_block`

delbonis requested changes Sep 16, 2025

View reviewed changes

barakshani reviewed Sep 16, 2025

View reviewed changes

bewakes force-pushed the ol-stf-draft branch from d51c0fb to 29bbf8f Compare September 17, 2025 10:41

delbonis and others added 19 commits September 19, 2025 13:33

feature(acctsys, snacct, eert): add new crates

a60acf2

feature(ee-rt, ee-types): add high-level control logic for snark acco…

8873476

…unt processing

refactor: rework module names, improve concept modelling, fill in TODOs

9ba10cf

refactor(ee-acct): better structure for decoding messages

c7d5ad0

feature(ee-acct-runtime): add lots of supporting code for verifying c…

6f69fc1

…hunks

ci: add shellcheck lints (#1043)

d484fa8

* fix: shellcheck lints * nix: add shellcheck * just: add shellcheck * ci: add shellcheck

Rename sync_worker to service_worker

9a1cf94

Basic ol-stf types and flow

fa95da2

A basic flow for stf

9228b6c

Tighten loose ends except for snark verification

e664dbc

Use 'target' in tx payload as account id, remove state root check fro…

03882dd

…m `process_block`

Fix acct inner state update in execute_transaction

2f86a9b

Add stf-runner-demo binary

e93a347

Cleanup

13ebccb

Add more block validations, separate validation from actual execution

e1c4054

Remove demo binary

e720f96

Add epoch to checkpoint log

59534a9

Add more fields to OLState; update L1View

98735a3

wip

328cc48

prajwolrg assigned bewakes Sep 25, 2025

bewakes force-pushed the ol-stf-draft branch from 29bbf8f to 328cc48 Compare September 26, 2025 06:13

		// TODO/NOTE: There's already a similar trait called `L2Header`, might need to merge those.
		pub trait BlockHeaderContext {

Ol stf draft #1036

Are you sure you want to change the base?

Ol stf draft #1036

Uh oh!

Conversation

bewakes commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of Change

Notes to Reviewers

Checklist

Related Issues

Uh oh!

delbonis 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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bewakes Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bewakes commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bewakes commented Sep 16, 2025 •

edited

Loading

bewakes Sep 16, 2025 •

edited

Loading

bewakes commented Sep 17, 2025 •

edited

Loading

github-actions bot commented Sep 17, 2025 •

edited

Loading