From 0cec39e2d8b7b607315ae33396e727d5a3191c63 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Mon, 26 May 2025 11:38:40 +0200 Subject: [PATCH 01/11] add adr for validator network --- specs/lazy-adr/adr-022-validator-network.md | 138 ++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 specs/lazy-adr/adr-022-validator-network.md diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md new file mode 100644 index 0000000000..0d1215ec26 --- /dev/null +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -0,0 +1,138 @@ +# 022 Validator / Attester Network — Push-Sign-Collect + +Date: 2025-05-25 +Status: Draft + +## Context + +The rollup currently relies on one centralized sequencer to order and publish blocks. Down-stream chains connected via IBC have no cryptographic evidence that other parties have examined those blocks before they propagate, producing a single point of failure and attack. + +## Decision + +### High-level workflow + + 1. Block broadcast — For every height h the sequencer broadcasts the canonical BlockBundle(h) (header, transactions, state root) to all active attesters over gRPC/WebSocket. + 2. Local verification — Each attester independently: + • validates header → parent → state transition; + • (optionally) re-executes the block using a connected full node; + • signs bytesToSign = SHA-256(height || blockHash || stateRoot) with its private key. + 3. Signature return — The attester sends SubmitSignature{height, blockHash, pubKey, signature} back to the sequencer (one-way unary gRPC). +❏ 5 s retry w/ exponential back-off. + 4. Aggregation & quorum — The sequencer collects signatures until ≥ ⅔ of current bonded voting power have signed (Cosmos-SDK staking module). +v0: embed bitmap + ordered Ed25519 signatures. +v1: support aggregated BLS signature once key migration is complete. + 5. Final block commit — Sequencer writes the quorum attestation into BlockHeader.ValidatorHash and gossips the block via IBC. + +### Signing schemes + +Version Crypto Encoding in header Verification cost on IBC chain +v0 (MVP) Ed25519 (Cosmos default) Attestation{bitArray, []Signature} O(#signers) Ed25519 checks +v1 BLS12-381 AggSig{aggregate, bitmap} 1 pairing check +v2 (optional) Dual-mode (Ed25519 ∥ BLS) Two parallel attestations, consumer picks Compatible with all relayers + +Key generation — Every validator stores an Ed25519 signing key today. A BLS key can be added via a MsgAddBLSKey transaction once v1 is activated. + +### Validator set & staking integration + + • The staking module remains the single source of truth for validator membership, voting power and slashing. + • Create / Edit / Unbond transactions work unchanged. The EndBlocker outputs a ValidatorSetUpdate event that both the sequencer and attesters subscribe to. + • Joining the Attester Network +– When a validator becomes bonded it must run the attester binary, configured with its signing key(s) and sequencer address. +– Non-participating bonded validators are jailed & slashed by the existing missed-signature mechanism. + • Leaving +– When a validator unbonds or is slashed below MinSelfDelegation, the sequencer drops its pubKey from the next height’s validator set bitmap. Any late signatures are ignored. + +2.4 Quorum and liveness + • Quorum rule: signedVotingPower ≥ 2/3 * totalVotingPower + • Timeouts +– AttesterTimeout = 2 s after broadcast. +– AggregationTimeout = 5 s; sequencer can still commit if quorum not met only in EmergencyMode (governance toggle) to avoid total halt. + • Safety vs. liveness — Because verification is local and deterministic, equivocation is impossible: the worst failure mode is not reaching quorum (→ halt) which staking incentives should discourage. + +## Architecture & Interfaces + +```mermaid +graph TD + SQ[Sequencer] -- gRPC broadcast --> A1[Attester 1]\nVerify & Sign + SQ -- gRPC --> A2[Attester 2] + SQ -- gRPC --> A3[Attester N] + A1 -- SubmitSignature --> SQ + A2 -- SubmitSignature --> SQ + A3 -- SubmitSignature --> SQ + SQ -- quorum aggregate --> HB[Block h header with Attestation] + HB --> IBC[IBC Relayer] +``` + +### Sequencer additions + + • /broadcastBlock (server-stream): pushes BlockBundle(h) to every connected attester. + • /SubmitSignature (rpc): receives SignatureMsg. + • Aggregation cache: map[height]SignatureAccumulator with bitset of pubkeys. + • State hooks: listens to staking.ValidatorSetUpdate to rebuild ActiveValidatorBitmap each height. + +### Attester service + + • Conn manager — maintains persistent stream to /broadcastBlock and unary client to /SubmitSignature. + • Verifier pipeline: + + 1. basic header checks; + 2. optional re-execution (--verify-full=true flag); + 3. produce signature; + 4. async submit with retries. + • Metrics / Prom: per-block verification time, submit latency, signed / missed counter. + +## Security considerations + + • Double-sign protection — Deterministic bytesToSign makes replay impossible; Ed25519 prevents malleability. + • Slashing — Existing Cosmos evidence (MsgEvidence) for missed or duplicate signatures applies unchanged. + • Sybil resistance — validator power is staked; no separate token. + • Forward compatibility — BLS upgrade path leaves Ed25519 untouched so IBC light clients that can’t do pairings still work. + +## Consequences + +### Easier + + • Removes RAFT complexity (no election timers, snapshots, log compaction). + • Latency drops to 1 broadcast + 1 unary round-trip per block. + • Natural fit with Cosmos validator-set semantics and existing slashing. + +### Harder + + • Sequencer must handle DoS on /SubmitSignature endpoint. + • Validator set changes require tight syncing between staking events and attester configs. + • Bitmap + signatures can bloat header size at very large validator sets (mitigated by BLS upgrade). + +## Future work + + 1. BLS aggregated signatures — governance proposal & CLI tool to add BLS keys, plus pairing verification gadget for IBC. + 2. Multi-sequencer fail-over — once fast-leader-election is required we can revisit consensus (e.g., HotStuff) purely for sequencer rotation. + 3. Light-client proofs — expose AttestationProof object so external bridges can verify signedVotingPower without full header. + 4. Bundle attestation & DA availability proof to offer optimistic fast-finality bridges. + +## Appendix A — gRPC proto (excerpt) + +```proto +service AttesterService { + rpc BroadcastBlock(stream BlockBundle) returns (stream Empty) {} + rpc SubmitSignature(SignatureMsg) returns (SubmitSignatureResponse) {} +} + +message BlockBundle { + uint64 height = 1; + bytes block_hash = 2; + bytes state_root = 3; + bytes header = 4; // protobuf-encoded header + bytes txs = 5; // amino bz2 concatenated +} + +message SignatureMsg { + uint64 height = 1; + bytes block_hash = 2; + bytes pub_key = 3; + bytes signature = 4; // ed25519 or bls +} + +message SubmitSignatureResponse { + bool ack = 1; +} +``` From d84060cfe860d60840b24b057be15897cbd8fbaf Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Mon, 26 May 2025 14:29:18 +0200 Subject: [PATCH 02/11] modify --- specs/lazy-adr/adr-022-validator-network.md | 87 ++++++++++++--------- 1 file changed, 51 insertions(+), 36 deletions(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index 0d1215ec26..f937a64df6 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -1,11 +1,13 @@ -# 022 Validator / Attester Network — Push-Sign-Collect +# 022 Validator Network Date: 2025-05-25 Status: Draft ## Context -The rollup currently relies on one centralized sequencer to order and publish blocks. Down-stream chains connected via IBC have no cryptographic evidence that other parties have examined those blocks before they propagate, producing a single point of failure and attack. +The validator network acts as an extra security layer and soft confirmation enabling the rollup to move faster than the underlying DA layer. Secondly a validator network introduces the opportunity to do more with the token of the chain. + +The original design and implementation was centered around IBC and adding a extra layer of security for counter party chains, so that the user is not solely trusting the sequencer to act correctly ## Decision @@ -17,32 +19,57 @@ The rollup currently relies on one centralized sequencer to order and publish bl • (optionally) re-executes the block using a connected full node; • signs bytesToSign = SHA-256(height || blockHash || stateRoot) with its private key. 3. Signature return — The attester sends SubmitSignature{height, blockHash, pubKey, signature} back to the sequencer (one-way unary gRPC). -❏ 5 s retry w/ exponential back-off. - 4. Aggregation & quorum — The sequencer collects signatures until ≥ ⅔ of current bonded voting power have signed (Cosmos-SDK staking module). -v0: embed bitmap + ordered Ed25519 signatures. -v1: support aggregated BLS signature once key migration is complete. + 4. Aggregation & quorum — The sequencer collects signatures until ≥ ⅔ of current bonded voting power have signed. (Optionally this step can be done async) 5. Final block commit — Sequencer writes the quorum attestation into BlockHeader.ValidatorHash and gossips the block via IBC. ### Signing schemes -Version Crypto Encoding in header Verification cost on IBC chain -v0 (MVP) Ed25519 (Cosmos default) Attestation{bitArray, []Signature} O(#signers) Ed25519 checks -v1 BLS12-381 AggSig{aggregate, bitmap} 1 pairing check -v2 (optional) Dual-mode (Ed25519 ∥ BLS) Two parallel attestations, consumer picks Compatible with all relayers +Different signature schemes can be doused in conjunction with the validator network. To start we will support ED25519 and later one we plan on adding other signature schemes based on how user demand requires. -Key generation — Every validator stores an Ed25519 signing key today. A BLS key can be added via a MsgAddBLSKey transaction once v1 is activated. +Some potential future additions could be BLS12-381 aggregate and/or a BLS threshold signature. ### Validator set & staking integration - • The staking module remains the single source of truth for validator membership, voting power and slashing. - • Create / Edit / Unbond transactions work unchanged. The EndBlocker outputs a ValidatorSetUpdate event that both the sequencer and attesters subscribe to. - • Joining the Attester Network -– When a validator becomes bonded it must run the attester binary, configured with its signing key(s) and sequencer address. -– Non-participating bonded validators are jailed & slashed by the existing missed-signature mechanism. - • Leaving -– When a validator unbonds or is slashed below MinSelfDelegation, the sequencer drops its pubKey from the next height’s validator set bitmap. Any late signatures are ignored. +The attester layer can plug into different validator‑set providers. Below we outline the existing Cosmos‑SDK flow and an alternative Reth / EVM flow patterned after UniChain’s staking design. Both share the same quorum rule (≥ ⅔ voting power) and slashing philosophy. + +#### Option A – Cosmos‑SDK (current main‑net) + +- The staking module is the single source of truth for membership and voting power. +- Create / Edit / Unbond msgs emit ValidatorSetUpdate events every block; sequencer & attesters rebuild the bitmap each height. +- Joining — once bonded, a validator runs the attester daemon; missed signatures trigger normal jailing & slashing. +- Leaving — when voting power reaches 0 the sequencer drops the validator from the next bitmap, ignoring late sigs. + +#### Option B - Reth/EVM Rollup + +- Stake manager contract holds the validator stake/weight and maps an address to a key. It will emit `StakeSnapshot(epoch)` events that will be consumed by the consensus client. +- Stake mirror listens for staking snapshot events in order to re build the validtor set. The proposer will always be the same, we do not support rotation at this time. Once the validator set is rebuilt any changes that are witnessed will be applied to the validator network. +- + +Solidity Contract + +```sol +contract StakeManager { + struct Validator { uint96 power; bytes32 edKey; bytes blsKey; } + mapping(address => Validator) public validators; + + function stake(uint96 amount, bytes32 edKey, bytes calldata blsKey) external; + function unstake(uint96 amount) external; + function slash(address val, uint96 amt) external /* onlyEvidence */; + function snapshot() external returns (bytes32 root); // called by sequencer each epoch +} +``` + +In rollkit we will introduce a new state entry for epochs, active set, stake and a registry of all participants in the validator network. + +```text +validators/stake/{addr} → power | edKey | blsKey | missedCtr +validators/epochRoot/{epoch} → bytes32 +validators/activeSet/{epoch} → addr[] +validators/registry → addr[] (permissioned only) +``` + +### Quorum and liveness -2.4 Quorum and liveness • Quorum rule: signedVotingPower ≥ 2/3 * totalVotingPower • Timeouts – AttesterTimeout = 2 s after broadcast. @@ -53,7 +80,7 @@ Key generation — Every validator stores an Ed25519 signing key today. A BLS ke ```mermaid graph TD - SQ[Sequencer] -- gRPC broadcast --> A1[Attester 1]\nVerify & Sign + SQ[Sequencer] -- gRPC broadcast --> A1[Attester 1] SQ -- gRPC --> A2[Attester 2] SQ -- gRPC --> A3[Attester N] A1 -- SubmitSignature --> SQ @@ -86,28 +113,16 @@ graph TD • Double-sign protection — Deterministic bytesToSign makes replay impossible; Ed25519 prevents malleability. • Slashing — Existing Cosmos evidence (MsgEvidence) for missed or duplicate signatures applies unchanged. • Sybil resistance — validator power is staked; no separate token. - • Forward compatibility — BLS upgrade path leaves Ed25519 untouched so IBC light clients that can’t do pairings still work. ## Consequences -### Easier - - • Removes RAFT complexity (no election timers, snapshots, log compaction). - • Latency drops to 1 broadcast + 1 unary round-trip per block. - • Natural fit with Cosmos validator-set semantics and existing slashing. - -### Harder - - • Sequencer must handle DoS on /SubmitSignature endpoint. - • Validator set changes require tight syncing between staking events and attester configs. - • Bitmap + signatures can bloat header size at very large validator sets (mitigated by BLS upgrade). +- Increased code complexity, more to maintain ## Future work - 1. BLS aggregated signatures — governance proposal & CLI tool to add BLS keys, plus pairing verification gadget for IBC. - 2. Multi-sequencer fail-over — once fast-leader-election is required we can revisit consensus (e.g., HotStuff) purely for sequencer rotation. - 3. Light-client proofs — expose AttestationProof object so external bridges can verify signedVotingPower without full header. - 4. Bundle attestation & DA availability proof to offer optimistic fast-finality bridges. +- Multi-sequencer fail-over — once fast-leader-election is required we can revisit consensus (e.g., HotStuff) purely for sequencer rotation. +- Light-client proofs — expose AttestationProof object so external bridges can verify signedVotingPower without full header. +- Bundle attestation & DA availability proof to offer optimistic fast-finality bridges. ## Appendix A — gRPC proto (excerpt) From 6c4cd5d4fdca9884507b1c6560d26091b44ddc99 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Tue, 27 May 2025 14:49:13 +0200 Subject: [PATCH 03/11] make adjustments --- specs/lazy-adr/adr-022-validator-network.md | 58 ++++++--------------- 1 file changed, 17 insertions(+), 41 deletions(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index f937a64df6..0bf5989ff9 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -5,12 +5,19 @@ Status: Draft ## Context +When a single sequencer is used there is a limited design space for the token and a limited set of security guarantees. The validator network offers an alternative to using a full consensus protocol, but offers security guarantees with more than one participant verifying the execution and ordering. + The validator network acts as an extra security layer and soft confirmation enabling the rollup to move faster than the underlying DA layer. Secondly a validator network introduces the opportunity to do more with the token of the chain. The original design and implementation was centered around IBC and adding a extra layer of security for counter party chains, so that the user is not solely trusting the sequencer to act correctly ## Decision +Rollkit will introduce a validator network in which there will be a set of validators verifying execution and construction. There are two options for how this can be done, blocking and non-blocking. + +- Blocking: The blocking design is centered around the propser waiting for signatures to return to it in order to consider the block having a soft confirmation. +- Non-blocking: The non-blocking design is centered around the proposer producing blocks as fast as possible but asking for signatures after fact. This design is optimized for block production performance. The validators will need to submit there attestations as a transaction to the state machine before the end of the epoch. If a validator does not submit their attesttation within the epoch, they will not be slashed but instead they will not get a reward. + ### High-level workflow 1. Block broadcast — For every height h the sequencer broadcasts the canonical BlockBundle(h) (header, transactions, state root) to all active attesters over gRPC/WebSocket. @@ -32,18 +39,24 @@ Some potential future additions could be BLS12-381 aggregate and/or a BLS thresh The attester layer can plug into different validator‑set providers. Below we outline the existing Cosmos‑SDK flow and an alternative Reth / EVM flow patterned after UniChain’s staking design. Both share the same quorum rule (≥ ⅔ voting power) and slashing philosophy. -#### Option A – Cosmos‑SDK (current main‑net) +#### Cosmos‑SDK + +For the Cosmos SDK the attester system will be located in the ABCI execution environment. + +OPEN QUESTIONS: + +- grpc based or libp2p based - The staking module is the single source of truth for membership and voting power. - Create / Edit / Unbond msgs emit ValidatorSetUpdate events every block; sequencer & attesters rebuild the bitmap each height. -- Joining — once bonded, a validator runs the attester daemon; missed signatures trigger normal jailing & slashing. +- Joining — once bonded, a validator runs the attester daemon. - Leaving — when voting power reaches 0 the sequencer drops the validator from the next bitmap, ignoring late sigs. -#### Option B - Reth/EVM Rollup +#### Reth/EVM Rollup - Stake manager contract holds the validator stake/weight and maps an address to a key. It will emit `StakeSnapshot(epoch)` events that will be consumed by the consensus client. - Stake mirror listens for staking snapshot events in order to re build the validtor set. The proposer will always be the same, we do not support rotation at this time. Once the validator set is rebuilt any changes that are witnessed will be applied to the validator network. -- +- The EVM will work in the non blocking way. The validators will be able to join and leave as they please with the requirement that they submit attestestions of execution in order to provide a soft confiramation at with in an epoch if they would like a reward for their work. Solidity Contract @@ -59,15 +72,6 @@ contract StakeManager { } ``` -In rollkit we will introduce a new state entry for epochs, active set, stake and a registry of all participants in the validator network. - -```text -validators/stake/{addr} → power | edKey | blsKey | missedCtr -validators/epochRoot/{epoch} → bytes32 -validators/activeSet/{epoch} → addr[] -validators/registry → addr[] (permissioned only) -``` - ### Quorum and liveness • Quorum rule: signedVotingPower ≥ 2/3 * totalVotingPower @@ -123,31 +127,3 @@ graph TD - Multi-sequencer fail-over — once fast-leader-election is required we can revisit consensus (e.g., HotStuff) purely for sequencer rotation. - Light-client proofs — expose AttestationProof object so external bridges can verify signedVotingPower without full header. - Bundle attestation & DA availability proof to offer optimistic fast-finality bridges. - -## Appendix A — gRPC proto (excerpt) - -```proto -service AttesterService { - rpc BroadcastBlock(stream BlockBundle) returns (stream Empty) {} - rpc SubmitSignature(SignatureMsg) returns (SubmitSignatureResponse) {} -} - -message BlockBundle { - uint64 height = 1; - bytes block_hash = 2; - bytes state_root = 3; - bytes header = 4; // protobuf-encoded header - bytes txs = 5; // amino bz2 concatenated -} - -message SignatureMsg { - uint64 height = 1; - bytes block_hash = 2; - bytes pub_key = 3; - bytes signature = 4; // ed25519 or bls -} - -message SubmitSignatureResponse { - bool ack = 1; -} -``` From 5c618b491691bdce4fd734a4dcbf92ca8ddbe895 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Tue, 27 May 2025 17:44:30 +0200 Subject: [PATCH 04/11] add x/attestion section --- specs/lazy-adr/adr-022-validator-network.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index 0bf5989ff9..823d638593 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -13,10 +13,9 @@ The original design and implementation was centered around IBC and adding a extr ## Decision -Rollkit will introduce a validator network in which there will be a set of validators verifying execution and construction. There are two options for how this can be done, blocking and non-blocking. +Rollkit will introduce a validator network in which there will be a set of validators verifying execution and construction. -- Blocking: The blocking design is centered around the propser waiting for signatures to return to it in order to consider the block having a soft confirmation. -- Non-blocking: The non-blocking design is centered around the proposer producing blocks as fast as possible but asking for signatures after fact. This design is optimized for block production performance. The validators will need to submit there attestations as a transaction to the state machine before the end of the epoch. If a validator does not submit their attesttation within the epoch, they will not be slashed but instead they will not get a reward. +- The design is centered around the proposer producing blocks as fast as possible but asking for signatures after fact. This design is optimized for block production performance. The validators will need to submit there attestations as a transaction to the state machine before the end of the epoch. If a validator does not submit their attesttation within the epoch, they will not be slashed but instead they will not get a reward. ### High-level workflow @@ -43,15 +42,13 @@ The attester layer can plug into different validator‑set providers. Below we o For the Cosmos SDK the attester system will be located in the ABCI execution environment. -OPEN QUESTIONS: - -- grpc based or libp2p based - - The staking module is the single source of truth for membership and voting power. - Create / Edit / Unbond msgs emit ValidatorSetUpdate events every block; sequencer & attesters rebuild the bitmap each height. - Joining — once bonded, a validator runs the attester daemon. - Leaving — when voting power reaches 0 the sequencer drops the validator from the next bitmap, ignoring late sigs. +The design adds a dedicated x/attestation Cosmos-SDK module that intercepts every IBC message in the AnteHandler, parks it in a state-kept queue, and releases it only after ≥ ⅔ validator voting-power has submitted attestations. Validators sign a hash of the queued tx; the module tracks signatures with a compact bitmap, finalises transactions in EndBlock (executing them through the normal IBC router), rewards timely signers, and optionally jails low-participation validators. Parameters cover quorum fraction, attestation window, pruning window, and queue size, keeping the solution pluggable and light-touch on existing IBC code. + #### Reth/EVM Rollup - Stake manager contract holds the validator stake/weight and maps an address to a key. It will emit `StakeSnapshot(epoch)` events that will be consumed by the consensus client. From 2197032d9580b55f0cc15fa6a78be25a46d7070c Mon Sep 17 00:00:00 2001 From: Marko Date: Wed, 28 May 2025 15:51:21 +0200 Subject: [PATCH 05/11] Update specs/lazy-adr/adr-022-validator-network.md Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> --- specs/lazy-adr/adr-022-validator-network.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index 823d638593..f4092bc76e 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -9,7 +9,7 @@ When a single sequencer is used there is a limited design space for the token an The validator network acts as an extra security layer and soft confirmation enabling the rollup to move faster than the underlying DA layer. Secondly a validator network introduces the opportunity to do more with the token of the chain. -The original design and implementation was centered around IBC and adding a extra layer of security for counter party chains, so that the user is not solely trusting the sequencer to act correctly +The original design and implementation was centered around IBC and adding an extra layer of security for counter party chains, so that the user is not solely trusting the sequencer to act correctly ## Decision From 5a92789b16ae7dca1c4560df8e3d4ab8d6532e28 Mon Sep 17 00:00:00 2001 From: Marko Date: Wed, 28 May 2025 15:54:53 +0200 Subject: [PATCH 06/11] Update specs/lazy-adr/adr-022-validator-network.md Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> --- specs/lazy-adr/adr-022-validator-network.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index f4092bc76e..48e66cee62 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -53,7 +53,7 @@ The design adds a dedicated x/attestation Cosmos-SDK module that intercepts ever - Stake manager contract holds the validator stake/weight and maps an address to a key. It will emit `StakeSnapshot(epoch)` events that will be consumed by the consensus client. - Stake mirror listens for staking snapshot events in order to re build the validtor set. The proposer will always be the same, we do not support rotation at this time. Once the validator set is rebuilt any changes that are witnessed will be applied to the validator network. -- The EVM will work in the non blocking way. The validators will be able to join and leave as they please with the requirement that they submit attestestions of execution in order to provide a soft confiramation at with in an epoch if they would like a reward for their work. +- The EVM will work in the non blocking way. The validators will be able to join and leave as they please with the requirement that they submit attestations of execution in order to provide a soft confirmation within an epoch if they would like a reward for their work. Solidity Contract From fe9027db5b0c4d25425cab5a0bcd9bb711bb5ad9 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Wed, 28 May 2025 16:12:14 +0200 Subject: [PATCH 07/11] more changes --- specs/lazy-adr/adr-022-validator-network.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index 48e66cee62..aafb6fbce1 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -24,9 +24,10 @@ Rollkit will introduce a validator network in which there will be a set of valid • validates header → parent → state transition; • (optionally) re-executes the block using a connected full node; • signs bytesToSign = SHA-256(height || blockHash || stateRoot) with its private key. - 3. Signature return — The attester sends SubmitSignature{height, blockHash, pubKey, signature} back to the sequencer (one-way unary gRPC). - 4. Aggregation & quorum — The sequencer collects signatures until ≥ ⅔ of current bonded voting power have signed. (Optionally this step can be done async) - 5. Final block commit — Sequencer writes the quorum attestation into BlockHeader.ValidatorHash and gossips the block via IBC. + 3. Signature transaction submission — The attester sends vote as a transaction to the state machine. It will be included in subsequent blocks + 4. Aggregation & quorum — The attester module or contract collects signatures until ≥ ⅔ of current bonded voting power have signed providing a soft confirmation of the block + - If qurorom is not met at the epoch boundry, the network will halt waiting for the signatures. + 5. Final block commit — After the block is included in the DA layer it will be considered to have a hard confirmation. ### Signing schemes From 9cd520abab136deb0127db80871c667f86b72355 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Wed, 28 May 2025 16:12:42 +0200 Subject: [PATCH 08/11] fix spelling --- specs/lazy-adr/adr-022-validator-network.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index aafb6fbce1..4ca1aa8acc 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -15,7 +15,7 @@ The original design and implementation was centered around IBC and adding an ext Rollkit will introduce a validator network in which there will be a set of validators verifying execution and construction. -- The design is centered around the proposer producing blocks as fast as possible but asking for signatures after fact. This design is optimized for block production performance. The validators will need to submit there attestations as a transaction to the state machine before the end of the epoch. If a validator does not submit their attesttation within the epoch, they will not be slashed but instead they will not get a reward. +- The design is centered around the proposer producing blocks as fast as possible but asking for signatures after fact. This design is optimized for block production performance. The validators will need to submit there attestations as a transaction to the state machine before the end of the epoch. If a validator does not submit their attestation within the epoch, they will not be slashed but instead they will not get a reward. ### High-level workflow From 22bdcc9d0fe9b24afd91cf40a67fb3e9e041c08e Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Sat, 31 May 2025 12:30:44 +0200 Subject: [PATCH 09/11] amend adr --- specs/lazy-adr/adr-022-validator-network.md | 45 ++++++++++++++++++--- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index 4ca1aa8acc..fdcfd9eeb9 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -41,15 +41,48 @@ The attester layer can plug into different validator‑set providers. Below we o #### Cosmos‑SDK -For the Cosmos SDK the attester system will be located in the ABCI execution environment. +Introduce a dedicated x/network module that completely owns the CommitHash and ValidatorHash that appear in every block‑header. Rollkit remains untouched; the logic lives entirely in the ABCI application. -- The staking module is the single source of truth for membership and voting power. -- Create / Edit / Unbond msgs emit ValidatorSetUpdate events every block; sequencer & attesters rebuild the bitmap each height. -- Joining — once bonded, a validator runs the attester daemon. -- Leaving — when voting power reaches 0 the sequencer drops the validator from the next bitmap, ignoring late sigs. +Hashes produced in‑app During EndBlock, x/network gathers the attestation bitmap for height h, computes and returns them in ResponseEndBlock. -The design adds a dedicated x/attestation Cosmos-SDK module that intercepts every IBC message in the AnteHandler, parks it in a state-kept queue, and releases it only after ≥ ⅔ validator voting-power has submitted attestations. Validators sign a hash of the queued tx; the module tracks signatures with a compact bitmap, finalises transactions in EndBlock (executing them through the normal IBC router), rewards timely signers, and optionally jails low-participation validators. Parameters cover quorum fraction, attestation window, pruning window, and queue size, keeping the solution pluggable and light-touch on existing IBC code. +When a relayer queries /block or /header, the application serves the canonical valset hash and commit hash from its KV‑store, ensuring external clients see the attested header even though rollkit itself never verified the signatures. +Validatorset updates from the staking module (x/staking) remains the single source of truth for bonded power. Every block it emits a ValidatorSetUpdate event. x/network subscribes and mirrors +the active validator bitmap. On a set‑change (say at height 100) the EndBlock hook updates x/network's bitmap before computing the hashes for the next height. + +##### Flow + +```mermaid +sequenceDiagram + participant Val as Validator + participant App as x/network + participant R as Rollkit + Val->>App: MsgAttest{h, sig} + loop within epoch + App->>App: store sig, update bitmap + App->>App:EndBlock{ValidatorHash, CommitHash} + end + R->> App: Request for hashes +``` + +Missing participation at the epoch boundary x/network evaluates participation: + +- if validator power‑weighted participation < Quorum (default 2/3) ⇒ return ErrAttestationTimeout and halt new block production; +- validators whose participation < MinParticipation for the entire epoch are auto‑ejected from the attester set via an EditValidator emitted by x/network (their stake remains bonded but they cease to sign until they re‑declare). + +##### Config params + +| Param | Purpose | Default | +|------------------|-------------------------------------------|-----------| +| EpochLength | Blocks per attestation window | 100 | +| QuorumFraction | Required voting-power for soft-finality | 2/3 | +| MinParticipation | Ejection threshold inside an epoch | 1/2 | +| PruneAfter | Keep attestation records this many epochs | 7 | +| EmergencyMode | Governance switch to bypass quorum | disabled | + +In this design there is no need to queue IBC transactions as the light client update message can not be relayed to the counter party chain. + + #### Reth/EVM Rollup - Stake manager contract holds the validator stake/weight and maps an address to a key. It will emit `StakeSnapshot(epoch)` events that will be consumed by the consensus client. From fad766044546cc5fe9ef4e890dc76c68a399a839 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Wed, 25 Jun 2025 15:21:28 +0200 Subject: [PATCH 10/11] update ADR --- specs/lazy-adr/adr-022-validator-network.md | 88 +++++++++++---------- 1 file changed, 47 insertions(+), 41 deletions(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index fdcfd9eeb9..40d09d9e83 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -7,7 +7,7 @@ Status: Draft When a single sequencer is used there is a limited design space for the token and a limited set of security guarantees. The validator network offers an alternative to using a full consensus protocol, but offers security guarantees with more than one participant verifying the execution and ordering. -The validator network acts as an extra security layer and soft confirmation enabling the rollup to move faster than the underlying DA layer. Secondly a validator network introduces the opportunity to do more with the token of the chain. +The validator network acts as an extra security layer and soft confirmation enabling the rollup to move faster than the underlying DA layer with added security. Secondly a validator network introduces the opportunity to do more with the token of the chain. The original design and implementation was centered around IBC and adding an extra layer of security for counter party chains, so that the user is not solely trusting the sequencer to act correctly @@ -15,18 +15,33 @@ The original design and implementation was centered around IBC and adding an ext Rollkit will introduce a validator network in which there will be a set of validators verifying execution and construction. -- The design is centered around the proposer producing blocks as fast as possible but asking for signatures after fact. This design is optimized for block production performance. The validators will need to submit there attestations as a transaction to the state machine before the end of the epoch. If a validator does not submit their attestation within the epoch, they will not be slashed but instead they will not get a reward. +Validators sign **one Attestation per epoch** that covers every block proposed inside that +epoch. The Attestation must be broadcast as a transaction within a configurable +**SubmissionWindow** (measured in blocks and always ≤ `EpochLength`). +Missing the window does **not** incur slashing but the validator forfeits rewards for that +epoch. +If a validator fails to submit an Attestation for **NonParticipationEpochs** consecutive +epochs it is automatically removed from the active validator set (stake remains bonded +unless separate evidence triggers slashing). + +The design is centered around the proposer producing blocks as fast as possible and asking +for signatures **after the fact, once per epoch**. This maximises throughput while still +obtaining soft-finality from a multi-party validator set. ### High-level workflow 1. Block broadcast — For every height h the sequencer broadcasts the canonical BlockBundle(h) (header, transactions, state root) to all active attesters over gRPC/WebSocket. 2. Local verification — Each attester independently: - • validates header → parent → state transition; - • (optionally) re-executes the block using a connected full node; - • signs bytesToSign = SHA-256(height || blockHash || stateRoot) with its private key. - 3. Signature transaction submission — The attester sends vote as a transaction to the state machine. It will be included in subsequent blocks - 4. Aggregation & quorum — The attester module or contract collects signatures until ≥ ⅔ of current bonded voting power have signed providing a soft confirmation of the block - - If qurorom is not met at the epoch boundry, the network will halt waiting for the signatures. + • validates every block header in the epoch and the resulting state transition; + • (optionally) re-executes the blocks using a connected full node; + • after processing the last block of the epoch, what is signs is up to the execution environment. + 3. Attestation submission — The attester sends the epoch signature as a transaction + **within SubmissionWindow**. + 4. Aggregation & quorum — The attester module / contract collects epoch signatures until + ≥ ⅔ of current bonded voting power have signed, providing a soft confirmation of the + whole epoch. + - If quorum is not met by the epoch boundary, the network pauses new proposals until + quorum is reached or **EmergencyMode** governance override is enabled. 5. Final block commit — After the block is included in the DA layer it will be considered to have a hard confirmation. ### Signing schemes @@ -72,17 +87,19 @@ Missing participation at the epoch boundary x/network evaluates participation: ##### Config params -| Param | Purpose | Default | -|------------------|-------------------------------------------|-----------| -| EpochLength | Blocks per attestation window | 100 | -| QuorumFraction | Required voting-power for soft-finality | 2/3 | -| MinParticipation | Ejection threshold inside an epoch | 1/2 | -| PruneAfter | Keep attestation records this many epochs | 7 | -| EmergencyMode | Governance switch to bypass quorum | disabled | +| Param | Purpose | Default | +|------------------------|-------------------------------------------|-----------| +| EpochLength | Blocks per attestation window | 100 | +| SubmissionWindow | Epochs allowed to submit epoch attestation| 5 | +| NonParticipationEpochs | Consecutive missed epochs before ejection | 3 | +| QuorumFraction | Required voting-power for soft-finality | 2/3 | +| MinParticipation | Ejection threshold inside an epoch | 1/2 | +| PruneAfter | Keep attestation records this many epochs | 7 | +| EmergencyMode | Governance switch to bypass quorum | disabled | + +In this design there is no need to queue IBC transactions as the light client update message can not be relayed to the counter party chain. Secondly, IBC transactions are alos blocked on DA inclusion of the data and header. -In this design there is no need to queue IBC transactions as the light client update message can not be relayed to the counter party chain. - #### Reth/EVM Rollup - Stake manager contract holds the validator stake/weight and maps an address to a key. It will emit `StakeSnapshot(epoch)` events that will be consumed by the consensus client. @@ -105,33 +122,25 @@ contract StakeManager { ### Quorum and liveness - • Quorum rule: signedVotingPower ≥ 2/3 * totalVotingPower - • Timeouts -– AttesterTimeout = 2 s after broadcast. -– AggregationTimeout = 5 s; sequencer can still commit if quorum not met only in EmergencyMode (governance toggle) to avoid total halt. + • Quorum rule (per-epoch): `signedVotingPower ≥ 2/3 · totalVotingPower` + • Timers + – `SubmissionWindow` (blocks): max delay after epoch end to include an attestation. + – `AggregationTimeout` (seconds): after window closes; sequencer can advance only if + **EmergencyMode** is enabled, otherwise production halts. • Safety vs. liveness — Because verification is local and deterministic, equivocation is impossible: the worst failure mode is not reaching quorum (→ halt) which staking incentives should discourage. ## Architecture & Interfaces ```mermaid graph TD - SQ[Sequencer] -- gRPC broadcast --> A1[Attester 1] - SQ -- gRPC --> A2[Attester 2] - SQ -- gRPC --> A3[Attester N] - A1 -- SubmitSignature --> SQ - A2 -- SubmitSignature --> SQ - A3 -- SubmitSignature --> SQ - SQ -- quorum aggregate --> HB[Block h header with Attestation] - HB --> IBC[IBC Relayer] + SQ[Sequencer] -- p2p --> A1[Attester 1] + SQ -- p2p --> A2[Attester 2] + SQ -- p2p --> A3[Attester N] + A1 -- SubmitSignature Tx --> SQ + A2 -- SubmitSignature Tx --> SQ + A3 -- SubmitSignature Tx --> SQ ``` -### Sequencer additions - - • /broadcastBlock (server-stream): pushes BlockBundle(h) to every connected attester. - • /SubmitSignature (rpc): receives SignatureMsg. - • Aggregation cache: map[height]SignatureAccumulator with bitset of pubkeys. - • State hooks: listens to staking.ValidatorSetUpdate to rebuild ActiveValidatorBitmap each height. - ### Attester service • Conn manager — maintains persistent stream to /broadcastBlock and unary client to /SubmitSignature. @@ -140,8 +149,7 @@ graph TD 1. basic header checks; 2. optional re-execution (--verify-full=true flag); 3. produce signature; - 4. async submit with retries. - • Metrics / Prom: per-block verification time, submit latency, signed / missed counter. + 4. async submit transaction with signautres ## Security considerations @@ -155,6 +163,4 @@ graph TD ## Future work -- Multi-sequencer fail-over — once fast-leader-election is required we can revisit consensus (e.g., HotStuff) purely for sequencer rotation. -- Light-client proofs — expose AttestationProof object so external bridges can verify signedVotingPower without full header. -- Bundle attestation & DA availability proof to offer optimistic fast-finality bridges. +- Multi-sequencer fail-over — once fast-leader-election is required we can revisit consensus purely for sequencer rotation. From 1d3189d5c2c7c49013bec8397d55b0ffc9e7604a Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Mon, 14 Jul 2025 10:49:15 +0200 Subject: [PATCH 11/11] address comments --- specs/lazy-adr/adr-022-validator-network.md | 20 ++------------------ 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/specs/lazy-adr/adr-022-validator-network.md b/specs/lazy-adr/adr-022-validator-network.md index 40d09d9e83..5c4fff46f3 100644 --- a/specs/lazy-adr/adr-022-validator-network.md +++ b/specs/lazy-adr/adr-022-validator-network.md @@ -85,21 +85,6 @@ Missing participation at the epoch boundary x/network evaluates participation: - if validator power‑weighted participation < Quorum (default 2/3) ⇒ return ErrAttestationTimeout and halt new block production; - validators whose participation < MinParticipation for the entire epoch are auto‑ejected from the attester set via an EditValidator emitted by x/network (their stake remains bonded but they cease to sign until they re‑declare). -##### Config params - -| Param | Purpose | Default | -|------------------------|-------------------------------------------|-----------| -| EpochLength | Blocks per attestation window | 100 | -| SubmissionWindow | Epochs allowed to submit epoch attestation| 5 | -| NonParticipationEpochs | Consecutive missed epochs before ejection | 3 | -| QuorumFraction | Required voting-power for soft-finality | 2/3 | -| MinParticipation | Ejection threshold inside an epoch | 1/2 | -| PruneAfter | Keep attestation records this many epochs | 7 | -| EmergencyMode | Governance switch to bypass quorum | disabled | - -In this design there is no need to queue IBC transactions as the light client update message can not be relayed to the counter party chain. Secondly, IBC transactions are alos blocked on DA inclusion of the data and header. - - #### Reth/EVM Rollup - Stake manager contract holds the validator stake/weight and maps an address to a key. It will emit `StakeSnapshot(epoch)` events that will be consumed by the consensus client. @@ -147,9 +132,8 @@ graph TD • Verifier pipeline: 1. basic header checks; - 2. optional re-execution (--verify-full=true flag); - 3. produce signature; - 4. async submit transaction with signautres + 2. produce signature; + 3. async submit transaction with signautres ## Security considerations