Skip to content

Conversation

@unnawut
Copy link
Collaborator

@unnawut unnawut commented Aug 13, 2025

🗒️ Description

Introducing the 1st draft of pqdevnet-0 client specs.

This PR contains only the markdown specs. The python specs is paused for clearer direction before resuming.

Closes leanEthereum/pm#27

🔗 Related Issues or PRs

Combined #5 and #7.

✅ 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.

@unnawut unnawut self-assigned this Aug 13, 2025
This was referenced Aug 13, 2025
Copy link
Collaborator Author

@unnawut unnawut left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made these annotations when I submitted this PR but forgot to submit


Topics are plain UTF-8 strings and are encoded on the wire as determined by
protobuf (gossipsub messages are enveloped in protobuf messages). Topic strings
have form: `/leanconsensus/devnet0/Name/Encoding`. This defines both the type of
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Originally /eth2/ForkDigestValue/Name/Encoding in the beacon specs

Copy link
Contributor

@g11tech g11tech Aug 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should probably retain ForkDigestValue here instead of devnet0

Copy link
Collaborator Author

@unnawut unnawut Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related convo at #8 (comment) so what's concluded there will be updated here.


- `ssz_snappy` - All objects are SSZ-encoded and then compressed with
[Snappy](https://github.com/google/snappy) block compression. Example: The
lean block topic string is `/leanconsensus/devnet0/lean_block/ssz_snappy`,
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Originally /eth2/446a7232/beacon_aggregate_and_proof/ssz_snappy

With:

- `ProtocolPrefix` - messages are grouped into families identified by a shared
libp2p protocol name prefix. In this case, we use `/leanconsensus/req`.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Originally /eth2/beacon_chain/req


##### LeanBlocksByRoot v1

**Protocol ID:** `/leanconsensus/req/lean_blocks_by_root/1/`
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Originally /eth2/beacon_chain/req/beacon_blocks_by_root/1/


```
(
List[Root, MAX_REQUEST_BLOCKS]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we define MAX_REQUEST_BLOCKS here?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copied over 2*10 (= 1024) from beacon specs: d19d93

This is 1024 * 4 / 60 = 68 minutes worth of block under 4s block time

```python
class SignedVote(Container):
data: Vote,
signature: Bytes32,
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To update to exact size (~3KiB) based on researchers' input

@unnawut
Copy link
Collaborator Author

unnawut commented Aug 25, 2025

Merging now as the overall suggestions are addressed. We can continue to make specific changes in separate PRs.

Some few last changes:

  1. Gossip topic settled at /leanconsensus/devnet{N}/Name/Encoding: 14d5ac2
  2. lean_* prefixes removed from gossip topic names and Req/Resp: 72909be, c551aa2
  3. Revert ed25519 identities back to secp256k1 per @g11tech's new findings for zeam: 64acd24, 884cc1d

@unnawut unnawut merged commit e9bb80c into leanEthereum:main Aug 25, 2025
6 checks passed
@unnawut unnawut deleted the pqdevnet0-md branch August 25, 2025 11:15
@unnawut unnawut added the specs Scope: Changes to the specifications label Oct 28, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

specs Scope: Changes to the specifications

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Initial containers & networking specs

8 participants