Feat/lean rainbowstaking by vlladin · Pull Request #36 · leanEthereum/leanSpec

vlladin · 2025-09-08T09:26:00Z

🗒️ Description

This PR introduces the concept of the Staker and the roles it can assume. It is intended as a discussion starter and a foundation to build on top.

The main idea behind these roles is to give a Staker the ability to activate one or more roles at any given time. These roles can be: Attester, Includer, Proposer. They are currently defined in src/lean_spec/subspecs/staker/role.py. I also mocked some parameters I expect will be useful moving forward.

I’ve added a subspec called staker (though it might need renaming to rainbow staking) where the roles and staker settings are defined, along with a new Staker container that uses them. There is no real implementation of the roles yet (so no tests). I also added some types needed by the roles (e.g., Gwei, Epoch). I assume these types will need to be expanded anyway, so I went ahead and started on that.

One discussion point I want to raise is the separation of state between roles. For example, the balance of a Staker could be global (shared between roles) or separated for each role. I’m not sure what the best approach is, so for now I assumed some form of separation (also needed for staking/delegation).

Currently, these roles connect to the Staker via src/lean_spec/subspecs/staker/settings.py. Stakers are now part of the State via the Staker container.

Getting these roles set up is necessary to advance the Rainbow Staking specs. As discussions and development begin to crystallize, I will update the docs and tests as needed.

✅ Checklist

Ran tox checks to avoid unnecessary CI fails:
```
uvx --with=tox-uv tox
```
Considered adding appropriate tests for the changes.
Considered updating the online docs in the ./docs/ directory.

…roposer roles for Staker. Added needed new types: Byte1, Epoch, Gwei, StakerIndex.

tcoratger

It looks good to me. I just left minor comments, mostly due to very recent and significant changes to the repo. But the logic looks good to me, and this doesn't affect the rest of the code in any way, so we can merge without any worries and come back to it later.

For now, there are no methods implemented here, and I think we'll see what's wrong when we merge the first methods and interact with the client teams.

tcoratger · 2025-09-12T13:42:54Z

src/lean_spec/subspecs/containers/staker.py

@@ -0,0 +1,26 @@
+"""Staker Container"""


Here in the header can we put a 5 lines (IA generated no problem) summary of this 3TS proposal https://ethresear.ch/t/three-tier-staking-3ts-unbundling-attesters-includers-and-execution-proposers/21648/1 as I imagine this is where this comes from?

We could also put the link or multiple links if needed for the reader to understand here what we are talking about.

I suspect that this container will be able to evolve over time but this is good to have an updated summary of what we are doing each time and update the description as this evolves.

tcoratger · 2025-09-12T13:44:05Z

src/lean_spec/subspecs/containers/staker.py

+    role_config: Annotated[
+        list[StakerSettings],
+        Field(min_length=3, max_length=3),
+    ]


We should be able to use List or Vector now that we have them.

See https://github.com/leanEthereum/leanSpec/blob/main/src/lean_spec/types/collections.py and usage over the codebase.

src/lean_spec/subspecs/containers/staker.py

tcoratger · 2025-09-12T13:47:55Z

src/lean_spec/subspecs/containers/state.py

+    stakers: Annotated[
+        list[Staker],
+        Field(max_length=DEVNET_CONFIG.staker_registry_limit),
+    ]


Same here you should be able to use List instead now

src/lean_spec/subspecs/staker/config.py

tcoratger · 2025-09-12T13:52:12Z

src/lean_spec/subspecs/staker/role.py

+    for performance optimisation purposes."""
+
+
+class ProposerRole(BaseModel):


strict base model no?

src/lean_spec/subspecs/staker/role.py

tcoratger · 2025-09-12T13:54:39Z

src/lean_spec/subspecs/staker/role.py

+    delegations_quotas: Annotated[
+        list[Uint64],
+        Field(max_length=DEVNET_STAKER_CONFIG.delegations_registry_limit),
+    ]
+    """The quotas of each delegated balance for this role. This list is
+    parallel with the stakers list from the state."""
+
+    delegated_balances: Annotated[
+        list[Uint64],
+        Field(max_length=DEVNET_STAKER_CONFIG.delegations_registry_limit),
+    ]


List could be used here as well

tcoratger · 2025-09-12T13:55:13Z

src/lean_spec/subspecs/staker/settings.py

+class StakerSettings(BaseModel):
+    """Parameters for the StakerSettings."""
+
+    role_identifier: Bytes1


Should be Byte no? https://github.com/leanEthereum/leanSpec/blob/main/src/lean_spec/types/byte.py

tcoratger · 2025-09-12T13:55:36Z

src/lean_spec/types/bytes.py

+"""This defines all Byte types used."""
+
+from pydantic import Field
+from typing_extensions import Annotated
+
+Bytes1 = Annotated[
+    bytes,
+    Field(
+        min_length=1,
+        max_length=1,
+        description="A Byte1 type.",
+    ),
+]
+"""
+A type alias for a 1 byte value.
+"""


I think that we don't need this since we have https://github.com/leanEthereum/leanSpec/blob/main/src/lean_spec/types/byte.py

Co-authored-by: Thomas Coratger <60488569+tcoratger@users.noreply.github.com>

tcoratger · 2025-09-15T12:35:34Z

src/lean_spec/subspecs/chain/config.py

-VALIDATOR_REGISTRY_LIMIT: Final = Uint64(2**12)
-"""The maximum number of validators that can be in the registry."""
-
+STAKER_REGISTRY_LIMIT: Final = 2**12


Why this is not a Uint64 anymore?

src/lean_spec/subspecs/staker/config.py

Co-authored-by: Thomas Coratger <60488569+tcoratger@users.noreply.github.com>

tcoratger · 2025-11-19T19:26:27Z

@vlladin Can I close this one for now?

Seems like stale and rebasing would be a nightmare so that it is better to reopen when needed, what do you think?

gorondan · 2025-11-19T20:04:13Z

We were planning to reopen the PR from another branch, later, so I think it's ok to close this one.

gorondan and others added 2 commits September 4, 2025 16:44

skeleton structure for staker

5a1db53

Added Staker as a protocol object. Added the Attester, Includer and P…

95b6f7e

…roposer roles for Staker. Added needed new types: Byte1, Epoch, Gwei, StakerIndex.

tcoratger reviewed Sep 12, 2025

View reviewed changes

gorondan and others added 5 commits September 12, 2025 20:42

Update src/lean_spec/subspecs/containers/staker.py

de4079f

Co-authored-by: Thomas Coratger <60488569+tcoratger@users.noreply.github.com>

Update src/lean_spec/subspecs/staker/config.py

2368966

Co-authored-by: Thomas Coratger <60488569+tcoratger@users.noreply.github.com>

Update src/lean_spec/subspecs/staker/config.py

38b9054

Co-authored-by: Thomas Coratger <60488569+tcoratger@users.noreply.github.com>

Fixed conflicts

93726c6

added Staker Container docstring

04293f8

tcoratger reviewed Sep 15, 2025

View reviewed changes

gorondan and others added 5 commits September 15, 2025 16:58

Update src/lean_spec/subspecs/staker/config.py

42d4210

Co-authored-by: Thomas Coratger <60488569+tcoratger@users.noreply.github.com>

fixed typo in Staker Container docstring

2ed0b4b

fixed type in chain config

4c30294

Use BaseStrictMode, List and Byte where needed. Removed Byte1.

bc40df9

Staker files format fix.

e3417fc

vlladin marked this pull request as ready for review September 16, 2025 18:25

unnawut added the specs Scope: Changes to the specifications label Oct 28, 2025

tcoratger closed this Nov 19, 2025

		for performance optimisation purposes."""


		class ProposerRole(BaseModel):

Conversation

vlladin commented Sep 8, 2025

🗒️ Description

This PR introduces the concept of the Staker and the roles it can assume. It is intended as a discussion starter and a foundation to build on top.

✅ Checklist

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tcoratger commented Nov 19, 2025

Uh oh!

gorondan commented Nov 19, 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

gorondan commented Nov 19, 2025 •

edited

Loading