Skip to content

Commit 80178ab

Browse files
tac0turtletac0turtlegraphite-app[bot]
authored
docs: (ADR) validator network (#2310)
<!-- Please read and fill out this form before submitting your PR. Please make sure you have reviewed our contributors guide before submitting your first PR. NOTE: PR titles should follow semantic commits: https://www.conventionalcommits.org/en/v1.0.0/ --> ## Overview This pr pulls the adr for the attester system into a separate pr to begin to break apart the large PR. ref #2308 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added a detailed design document outlining the validator network protocol, including workflow, architecture, validator set management options, quorum rules, security considerations, and interface specifications. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: tac0turtle <you@example.com> Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
1 parent 173fea5 commit 80178ab

1 file changed

Lines changed: 150 additions & 0 deletions

File tree

‎specs/lazy-adr/adr-022-validator-network.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# 022 Validator Network
2+
3+
Date: 2025-05-25
4+
Status: Draft
5+
6+
## Context
7+
8+
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.
9+
10+
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.
11+
12+
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
13+
14+
## Decision
15+
16+
Rollkit will introduce a validator network in which there will be a set of validators verifying execution and construction.
17+
18+
Validators sign **one Attestation per epoch** that covers every block proposed inside that
19+
epoch. The Attestation must be broadcast as a transaction within a configurable
20+
**SubmissionWindow** (measured in blocks and always ≤ `EpochLength`).
21+
Missing the window does **not** incur slashing but the validator forfeits rewards for that
22+
epoch.
23+
If a validator fails to submit an Attestation for **NonParticipationEpochs** consecutive
24+
epochs it is automatically removed from the active validator set (stake remains bonded
25+
unless separate evidence triggers slashing).
26+
27+
The design is centered around the proposer producing blocks as fast as possible and asking
28+
for signatures **after the fact, once per epoch**. This maximises throughput while still
29+
obtaining soft-finality from a multi-party validator set.
30+
31+
### High-level workflow
32+
33+
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.
34+
2. Local verification — Each attester independently:
35+
• validates every block header in the epoch and the resulting state transition;
36+
• (optionally) re-executes the blocks using a connected full node;
37+
• after processing the last block of the epoch, what is signs is up to the execution environment.
38+
3. Attestation submission — The attester sends the epoch signature as a transaction
39+
**within SubmissionWindow**.
40+
4. Aggregation & quorum — The attester module / contract collects epoch signatures until
41+
≥ ⅔ of current bonded voting power have signed, providing a soft confirmation of the
42+
whole epoch.
43+
- If quorum is not met by the epoch boundary, the network pauses new proposals until
44+
quorum is reached or **EmergencyMode** governance override is enabled.
45+
5. Final block commit — After the block is included in the DA layer it will be considered to have a hard confirmation.
46+
47+
### Signing schemes
48+
49+
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.
50+
51+
Some potential future additions could be BLS12-381 aggregate and/or a BLS threshold signature.
52+
53+
### Validator set & staking integration
54+
55+
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.
56+
57+
#### Cosmos‑SDK
58+
59+
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.
60+
61+
Hashes produced in‑app During EndBlock, x/network gathers the attestation bitmap for height h, computes and returns them in ResponseEndBlock.
62+
63+
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.
64+
65+
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
66+
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.
67+
68+
##### Flow
69+
70+
```mermaid
71+
sequenceDiagram
72+
participant Val as Validator
73+
participant App as x/network
74+
participant R as Rollkit
75+
Val->>App: MsgAttest{h, sig}
76+
loop within epoch
77+
App->>App: store sig, update bitmap
78+
App->>App:EndBlock{ValidatorHash, CommitHash}
79+
end
80+
R->> App: Request for hashes
81+
```
82+
83+
Missing participation at the epoch boundary x/network evaluates participation:
84+
85+
- if validator power‑weighted participation < Quorum (default 2/3) ⇒ return ErrAttestationTimeout and halt new block production;
86+
- 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).
87+
88+
#### Reth/EVM Rollup
89+
90+
- 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.
91+
- 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.
92+
- 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.
93+
94+
Solidity Contract
95+
96+
```sol
97+
contract StakeManager {
98+
struct Validator { uint96 power; bytes32 edKey; bytes blsKey; }
99+
mapping(address => Validator) public validators;
100+
101+
function stake(uint96 amount, bytes32 edKey, bytes calldata blsKey) external;
102+
function unstake(uint96 amount) external;
103+
function slash(address val, uint96 amt) external /* onlyEvidence */;
104+
function snapshot() external returns (bytes32 root); // called by sequencer each epoch
105+
}
106+
```
107+
108+
### Quorum and liveness
109+
110+
• Quorum rule (per-epoch): `signedVotingPower ≥ 2/3 · totalVotingPower`
111+
• Timers
112+
– `SubmissionWindow` (blocks): max delay after epoch end to include an attestation.
113+
– `AggregationTimeout` (seconds): after window closes; sequencer can advance only if
114+
**EmergencyMode** is enabled, otherwise production halts.
115+
• 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.
116+
117+
## Architecture & Interfaces
118+
119+
```mermaid
120+
graph TD
121+
SQ[Sequencer] -- p2p --> A1[Attester 1]
122+
SQ -- p2p --> A2[Attester 2]
123+
SQ -- p2p --> A3[Attester N]
124+
A1 -- SubmitSignature Tx --> SQ
125+
A2 -- SubmitSignature Tx --> SQ
126+
A3 -- SubmitSignature Tx --> SQ
127+
```
128+
129+
### Attester service
130+
131+
• Conn manager — maintains persistent stream to /broadcastBlock and unary client to /SubmitSignature.
132+
• Verifier pipeline:
133+
134+
1. basic header checks;
135+
2. produce signature;
136+
3. async submit transaction with signautres
137+
138+
## Security considerations
139+
140+
• Double-sign protection — Deterministic bytesToSign makes replay impossible; Ed25519 prevents malleability.
141+
• Slashing — Existing Cosmos evidence (MsgEvidence) for missed or duplicate signatures applies unchanged.
142+
• Sybil resistance — validator power is staked; no separate token.
143+
144+
## Consequences
145+
146+
- Increased code complexity, more to maintain
147+
148+
## Future work
149+
150+
- Multi-sequencer fail-over — once fast-leader-election is required we can revisit consensus purely for sequencer rotation.

0 commit comments

Comments
 (0)