feat: initialize lean node architecture

[syjn99]

What was wrong?

We need some base setup to accelerate our devs. I hope that this PR works like a cornerstone for our first lean node.

How was it fixed?

I wrote a post for providing more context and rationale on it. Reading the post will be helpful to understand the changes that are introduced in this PR.

Notes

About the original code

Most of the code is from the last PR(#672) (kudos to @unnawut). Refer to the part of the write-up for where they are originated from.

Running example

$ cargo run --release lean_node --network ./bin/ream/assets/lean/sample_spec.yml

You don't have to set up GENESIS_TIME manually: I put some hacky code for making our lives easier to review this PR. We might need some shell script or config to handle it later on.

Also you don't have to set up validators, the code will put placeholders for missing validators.

2025-08-07T01:21:27.014805Z  INFO ream_validator_lean::service: Built block for validator 1. Block Info(slot: 21, parent: 0xbd71b8f31e34ebf1e17a7ad2acb39a672e081710ed9d09e04221949a9bce3e4a, len(votes): 0, state_root: 0x147df283939deed0fe1dc6fd0eb004141386fe312a4e03b27598a20cd0d181e6)
2025-08-07T01:21:30.013921Z  INFO ream_validator_lean::service: Vote.
2025-08-07T01:21:30.013982Z  INFO ream_validator_lean::service: Built votes for validators: Vote { validator_id: 0, slot: 21, head: 0xbd71b8f31e34ebf1e17a7ad2acb39a672e081710ed9d09e04221949a9bce3e4a, head_slot: 20, target: 0x9e04df04e25b9bdae697d30ca8b7e48ebbb0d13d862749752bf861bf2c07ab04, target_slot: 18, source: 0x49eba49dee2764b7a5b9de3712448d7ba4b1de5f9f253bc9519969247aca8269, source_slot: 17 }
2025-08-07T01:21:30.013989Z  INFO ream_chain_lean::service: Received vote_item: Unsigned(Vote { validator_id: 0, slot: 21, head: 0xbd71b8f31e34ebf1e17a7ad2acb39a672e081710ed9d09e04221949a9bce3e4a, head_slot: 20, target: 0x9e04df04e25b9bdae697d30ca8b7e48ebbb0d13d862749752bf861bf2c07ab04, target_slot: 18, source: 0x49eba49dee2764b7a5b9de3712448d7ba4b1de5f9f253bc9519969247aca8269, source_slot: 17 })
2025-08-07T01:21:30.013994Z  INFO ream_chain_lean::service: Received vote_item: Unsigned(Vote { validator_id: 1, slot: 21, head: 0xbd71b8f31e34ebf1e17a7ad2acb39a672e081710ed9d09e04221949a9bce3e4a, head_slot: 20, target: 0x9e04df04e25b9bdae697d30ca8b7e48ebbb0d13d862749752bf861bf2c07ab04, target_slot: 18, source: 0x49eba49dee2764b7a5b9de3712448d7ba4b1de5f9f253bc9519969247aca8269, source_slot: 17 })
2025-08-07T01:21:30.013996Z  INFO ream_chain_lean::service: Received vote_item: Unsigned(Vote { validator_id: 2, slot: 21, head: 0xbd71b8f31e34ebf1e17a7ad2acb39a672e081710ed9d09e04221949a9bce3e4a, head_slot: 20, target: 0x9e04df04e25b9bdae697d30ca8b7e48ebbb0d13d862749752bf861bf2c07ab04, target_slot: 18, source: 0x49eba49dee2764b7a5b9de3712448d7ba4b1de5f9f253bc9519969247aca8269, source_slot: 17 })
2025-08-07T01:21:30.014080Z  INFO ream_chain_lean::service: Received vote_item: Unsigned(Vote { validator_id: 3, slot: 21, head: 0xbd71b8f31e34ebf1e17a7ad2acb39a672e081710ed9d09e04221949a9bce3e4a, head_slot: 20, target: 0x9e04df04e25b9bdae697d30ca8b7e48ebbb0d13d862749752bf861bf2c07ab04, target_slot: 18, source: 0x49eba49dee2764b7a5b9de3712448d7ba4b1de5f9f253bc9519969247aca8269, source_slot: 17 })
2025-08-07T01:21:33.015136Z  INFO ream_chain_lean::service: Compute safe target.
2025-08-07T01:21:36.014774Z  INFO ream_chain_lean::service: Accept new votes.

^ You can see the chain is getting into consensus.

Feedbacks are welcomed

I think the design decision needs more feedbacks because it may have a critical flaws. I don't want to force this PR getting merged right now: I'm happy if we have some better consensus on our lean node architecture. Please share your opinions!

Next TODOs

• Make it fully run in one-node-environment. Related issue: Support spinning up a custom devnet with a single node based on 3SF #677
  • Remove some hacky codes.
• Implement NetworkService. I guess the best starting point is to consume a static peer list from the command line option.

To-Do

• I have read CONTRIBUTING.md.
• This PR title follows conventional commits.

[syjn99]

This should be integrated with our pqc crate after #668 merged.

[syjn99]

We might introduce some kind of ClockService that emits tick every 12 / 4 seconds.

[shariqnaiyer]

We were using tokio::time::interval in the ValidatorService. I can implement it once this PR is merged.

[Kayden-ML]

Most of the code is from the last PR(#672) (kudos to @unnawut), and I decided not to delete the original code in this PR

I don't think it makes sense to keep both copies of the code, since this will just lead to debt tech. Why do we need duplicate functions etc?

[syjn99]

I don't think it makes sense to keep both copies of the code, since this will just lead to debt tech. Why do we need duplicate functions etc?

true, only receive() method is not yet implemented in this PR. I wanted to defer its implementation because:

1. it would not be just copy-paste from staker.rs since it needs communication between services
2. I wanted to make PR as small as possible.

But maybe I can just implement receive and deleting the original code in this PR. Will ping you after complete

[syjn99]

@Kayden-ML

96af999 deletes the original code. You might refer to the post where these methods are located in this version.

[unnawut]

Lgtm! Just 2 minor nits and 1 note so I'll approve in advance

[syjn99]

It would be best if this PR gets at least 3 approval, so please don't hesitate to submit reviews! Thanks.

[ch4r10t33r]

lgtm

[Kayden-ML]

Looks good 👍