Skip to content

chore: update specs#2459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tac0turtle merged 7 commits into from
Jul 16, 2025
Merged

chore: update specs #2459

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e977a8f
update specs
Jul 11, 2025
144283b
remove signed data
Jul 11, 2025
04dffbd
fix link
Jul 11, 2025
32fe1d2
markdownlinting
Jul 14, 2025
e910b72
Update specs/src/specs/store.md
tac0turtle Jul 14, 2025
ab5c904
Merge branch 'main' into marko/update_specs
tac0turtle Jul 15, 2025
f2e6ba3
Merge branch 'main' into marko/update_specs
tac0turtle Jul 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -109,4 +109,4 @@ Pre-release versions: 0.x.y (anything may change)
-->

<!-- Links -->
[Unreleased]: https://github.com/rollkit/rollkit/compare/v0.0.0...HEAD
[Unreleased]: https://github.com/rollkit/rollkit/compare/v1.0.0-beta.1...HEAD
14 changes: 7 additions & 7 deletions RELEASE.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -44,39 +44,39 @@ Packages must be released in the following order to ensure dependencies are sati

These packages only depend on `core` and can be released in parallel after `core`:

2. **github.com/rollkit/rollkit/da**
1. **github.com/rollkit/rollkit/da**
- Path: `./da`
- Dependencies: `rollkit/core`

3. **github.com/rollkit/rollkit**
2. **github.com/rollkit/rollkit**
- Path: `./` (root)
- Dependencies: `rollkit/core`

4. **github.com/rollkit/rollkit/execution/evm**
3. **github.com/rollkit/rollkit/execution/evm**
- Path: `./execution/evm`
- Dependencies: `rollkit/core`

### Phase 3: Sequencer Packages

These packages depend on both `core` and the main `rollkit` package:

5. **github.com/rollkit/rollkit/sequencers/based**
1. **github.com/rollkit/rollkit/sequencers/based**
- Path: `./sequencers/based`
- Dependencies: `rollkit/core`, `rollkit`

6. **github.com/rollkit/rollkit/sequencers/single**
2. **github.com/rollkit/rollkit/sequencers/single**
- Path: `./sequencers/single`
- Dependencies: `rollkit/core`, `rollkit`

### Phase 4: Application Packages

These packages have the most dependencies and should be released last:

7. **github.com/rollkit/rollkit/apps/evm/based**
1. **github.com/rollkit/rollkit/apps/evm/based**
- Path: `./apps/evm/based`
- Dependencies: `rollkit/core`, `rollkit/da`, `rollkit/execution/evm`, `rollkit`, `rollkit/sequencers/based`

8. **github.com/rollkit/rollkit/apps/evm/single**
2. **github.com/rollkit/rollkit/apps/evm/single**
- Path: `./apps/evm/single`
- Dependencies: `rollkit/core`, `rollkit/da`, `rollkit/execution/evm`, `rollkit`, `rollkit/sequencers/single`

Expand Down
447 changes: 416 additions & 31 deletions specs/src/specs/block-manager.md
View file
Open in desktop

Large diffs are not rendered by default.

135 changes: 75 additions & 60 deletions specs/src/specs/block-validity.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -12,83 +12,96 @@ Verifying a block/header is done in 3 parts:

3. Perform verification of the new block against the previously accepted block

Rollkit uses a header/data separation architecture where headers and data can be validated independently. The system has moved from a multi-validator model to a single signer model for simplified sequencer management.

## Basic Validation

Each type contains a `.ValidateBasic()` method, which verifies that certain basic invariants hold. The `ValidateBasic()` calls are nested, starting from the `Block` struct, all the way down to each subfield.
Each type contains a `.ValidateBasic()` method, which verifies that certain basic invariants hold. The `ValidateBasic()` calls are nested for each structure.

### SignedHeader Validation

```go
SignedHeader.ValidateBasic()
// Make sure the SignedHeader's Header passes basic validation
Header.ValidateBasic()
verify ProposerAddress not nil
// Make sure the SignedHeader's signature passes basic validation
Signature.ValidateBasic()
// Ensure that someone signed the header
verify len(c.Signatures) not 0
// For based rollups (sh.Signer.IsEmpty()), pass validation
If !sh.Signer.IsEmpty():
Comment on lines +30 to +33

@coderabbitaicoderabbitaiBotJul 11, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🛠️ Refactor suggestion

Plural Signatures contradicts single-signer model

verify len(c.Signatures) not 0 still assumes a slice/array even though the spec now mandates a single Signature field. Besides the plural variable name (c) is undefined in this snippet. Replace the size check with a simple nil / empty check on sh.Signature.

- verify len(c.Signatures) not 0+ // Ensure a signature is present+ verify sh.Signature != nil
📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// Ensure that someone signed the header
verify len(c.Signatures) not 0
// For based rollups (sh.Signer.IsEmpty()), pass validation
If !sh.Signer.IsEmpty():
// Ensure that someone signed the header
// Ensure a signature is present
verify sh.Signature != nil
// For based rollups (sh.Signer.IsEmpty()), pass validation
If !sh.Signer.IsEmpty():
🤖 Prompt for AI Agents
In specs/src/specs/block-validity.md around lines 30 to 33, the code incorrectly
checks the length of a plural Signatures field on an undefined variable c, which
contradicts the updated spec that uses a single Signature field. Replace the
length check with a nil or empty check on sh.Signature instead, and ensure the
variable referenced is sh, not c.

// Verify the signer matches the proposer address
verify sh.Signer.Address == sh.ProposerAddress
// Verify signature using custom verifier if set, otherwise use default
if sh.verifier != nil:
verify sh.verifier(sh) == nil
else:
verify sh.Signature.Verify(sh.Signer.PubKey, sh.Header.MarshalBinary())
```

The nested basic validation, and validation checks, are called as follows:
### SignedData Validation

```go
Block.ValidateBasic()
// Make sure the block's SignedHeader passes basic validation
SignedHeader.ValidateBasic()
// Make sure the SignedHeader's Header passes basic validation
Header.ValidateBasic()
verify ProposerAddress not nil
// Make sure the SignedHeader's signature passes basic validation
Signature.ValidateBasic()
// Ensure that someone signed the block
verify len(c.Signatures) not 0
If sh.Validators is nil, or len(sh.Validators.Validators) is 0, assume based rollup, pass validation, and skip all remaining checks.
Validators.ValidateBasic()
// github.com/rollkit/cometbft/blob/main/types/validator.go#L37
verify sh.Validators is not nil, and len(sh.Validators.Validators) != 0
// apply basic validation to all Validators
for each validator:
validator.ValidateBasic()
validate not nil
validator.PubKey not nil
validator.Address == correct size
// apply ValidateBasic to the proposer field:
sh.Validators.Proposer.ValidateBasic()
validate not nil
validator.PubKey not nil
validator.Address == correct size
Assert that SignedHeader.Validators.Hash() == SignedHeader.AggregatorsHash
Verify SignedHeader.Signature
SignedData.ValidateBasic()
// Always passes basic validation for the Data itself
Data.ValidateBasic() // always passes
// make sure the SignedHeader's DataHash is equal to the hash of the actual data in the block.
Data.Hash() == SignedHeader.DataHash
// Make sure the signature is valid
Signature.ValidateBasic()
verify len(c.Signatures) not 0
// Verify the signer
If !sd.Signer.IsEmpty():
verify sd.Signature.Verify(sd.Signer.PubKey, sd.Data.MarshalBinary())
```

## Verification Against Previous Block
### Block Validation

Blocks are composed of SignedHeader and Data:

```go
// code does not match spec: see https://github.com/rollkit/rollkit/issues/1277
Block.Verify()
SignedHeader.Verify(untrustH *SignedHeader)
// basic validation removed in #1231, because go-header already validates it
//untrustH.ValidateBasic()
Header.Verify(untrustH *SignedHeader)
if untrustH.Height == h.Height + 1, then apply the following check:
untrstH.AggregatorsHash[:], h.NextAggregatorsHash[:]
if untrustH.Height > h.Height + 1:
soft verification failure
// We should know they're adjacent now,
// verify the link to previous.
untrustH.LastHeaderHash == h.Header.Hash()
// Verify LastCommit hash
untrustH.LastCommitHash == sh.Signature.GetCommitHash(...)
// Block validation happens by validating header and data separately
// then ensuring data hash matches
verify SignedHeader.ValidateBasic() == nil
verify Data.Hash() == SignedHeader.DataHash
```

## Verification Against Previous Block

```go
SignedHeader.Verify(untrustedHeader *SignedHeader)
// Basic validation is handled by go-header before this
Header.Verify(untrustedHeader)
// Verify height sequence
if untrustedHeader.Height != h.Height + 1:
if untrustedHeader.Height > h.Height + 1:
return soft verification failure
return error "headers are not adjacent"
// Verify the link to previous header
verify untrustedHeader.LastHeaderHash == h.Header.Hash()
// Verify LastCommit hash matches previous signature
verify untrustedHeader.LastCommitHash == sh.Signature.GetCommitHash(...)
// Note: ValidatorHash field exists for compatibility but is not validated
```

## [Data](https://github.com/rollkit/rollkit/blob/main/types/data.go#L25)
## [Data](https://github.com/rollkit/rollkit/blob/main/types/data.go)

| **Field Name** | **Valid State** | **Validation** |
|----------------|-----------------------------------------|------------------------------------|
| Data | Transaction data of the block | Data.Hash == SignedHeader.DataHash |
| Txs | Transaction data of the block | Data.Hash() == SignedHeader.DataHash |
| Metadata | Optional p2p gossiping metadata | Not validated |

## [SignedHeader](https://github.com/rollkit/rollkit/blob/main/types/signed_header.go#L16)
## [SignedHeader](https://github.com/rollkit/rollkit/blob/main/types/signed_header.go)

| **Field Name** | **Valid State** | **Validation** |
|----------------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| Header | Valid header for the block | `Header` passes `ValidateBasic()` and `Verify()` |
| Signature | 1 valid signature from the single sequencer | `Signature` passes `ValidateBasic()`, with additional checks in `SignedHeader.ValidateBasic()` |
| Validators | Array of Aggregators, must have length exactly 1. | `Validators` passes `ValidateBasic()` |
| Signature | Valid signature from the single sequencer | `Signature` passes `ValidateBasic()`, verified against signer |
| Signer | Information about who signed the header | Must match ProposerAddress if not empty (based rollup case) |
| verifier | Optional custom signature verification function | Used instead of default verification if set |

## [Header](https://github.com/rollkit/rollkit/blob/main/types/header.go#L39)
## [Header](https://github.com/rollkit/rollkit/blob/main/types/header.go)

***Note***: The `AggregatorsHash` and `NextAggregatorsHash` fields have been removed. Rollkit vA should ignore all Valset updates from the ABCI app, and always enforce that the proposer is the single sequencer set as the 1 validator in the genesis block.
***Note***: Rollkit has moved to a single signer model. The multi-validator architecture has been replaced with a simpler single sequencer approach.

| **Field Name** | **Valid State** | **Validation** |
|---------------------|--------------------------------------------------------------------------------------------|---------------------------------------|
Expand All@@ -104,12 +117,14 @@ Block.Verify()
| ConsensusHash | unused | |
| AppHash | The correct state root after executing the block's transactions against the accepted state | checked during block execution |
| LastResultsHash | Correct results from executing transactions | checked during block execution |
| ProposerAddress | Address of the expected proposer | checked in the `Verify()` step |
| Signature | Signature of the expected proposer | signature verification occurs in the `ValidateBasic()` step |
| ProposerAddress | Address of the expected proposer | Must match Signer.Address in SignedHeader |
| ValidatorHash | Compatibility field for Tendermint light client | Not validated |

## [Signer](https://github.com/rollkit/rollkit/blob/main/types/signed_header.go)

## [ValidatorSet](https://github.com/cometbft/cometbft/blob/main/types/validator_set.go#L51)
The Signer type replaces the previous ValidatorSet for single sequencer operation:

| **Field Name** | **Valid State** | **Validation** |
|--------------|-----------------------------------------------------------------|-----------------------------|
| Validators| Array of validators, each must pass `Validator.ValidateBasic()` | `Validator.ValidateBasic()` |
| Proposer| Must pass `Validator.ValidateBasic()` | `Validator.ValidateBasic()` |
|----------------|-----------------------------------------------------------------|-----------------------------|
| PubKey | Public key of the signer | Must not be nil if Signer is not empty |
| Address | Address derived from the public key | Must match ProposerAddress |
21 changes: 14 additions & 7 deletions specs/src/specs/full_node.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -32,19 +32,26 @@ The [Store] is initialized with `DefaultStore`, an implementation of the [store

### blockManager

The [Block Manager] is responsible for managing the operations related to blocks such as creating and validating blocks.
The [Block Manager] is responsible for managing block-related operations including:

- Block production (normal and lazy modes)
- Header and data submission to DA layer
- Block retrieval and synchronization
- State updates and finalization

It implements a header/data separation architecture where headers and transaction data are handled independently.

### dalc

The [Data Availability Layer Client][dalc] is used to interact with the data availability layer. It is initialized with the DA Layer and DA Config specified in the node configuration.

### hExService
### hSyncService

The [Header Sync Service] is used for syncing block headers between nodes over P2P.
The [Header Sync Service] is used for syncing signed headers between nodes over P2P. It operates independently from data sync to support light clients.

### bSyncService
### dSyncService

The [Block Sync Service] is used for syncing blocks between nodes over P2P.
The [Data Sync Service] is used for syncing transaction data between nodes over P2P. This service is only used by full nodes, not light nodes.

Comment thread
coderabbitai[bot] marked this conversation as resolved.
## Message Structure/Communication Format

Expand DownExpand Up@@ -78,7 +85,7 @@ See [full node]

[9] [Header Sync Service][Header Sync Service]

[10] [Block Sync Service][Block Sync Service]
[10] [Data Sync Service][Data Sync Service]

[full node]: https://github.com/rollkit/rollkit/blob/main/node/full.go
[genesis]: https://github.com/cometbft/cometbft/blob/main/spec/core/genesis.md
Expand All@@ -89,4 +96,4 @@ See [full node]
[Block Manager]: https://github.com/rollkit/rollkit/blob/main/block/manager.go
[dalc]: https://github.com/rollkit/rollkit/blob/main/core/da/da.go
[Header Sync Service]: https://github.com/rollkit/rollkit/blob/main/pkg/sync/sync_service.go
[Block Sync Service]: https://github.com/rollkit/rollkit/blob/main/pkg/sync/sync_service.go
[Data Sync Service]: https://github.com/rollkit/rollkit/blob/main/pkg/sync/sync_service.go
Loading
Loading