Skip to content

Describe shnarfs #1742

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
alexandratran merged 4 commits into from
Oct 7, 2026
Merged

Describe shnarfs #1742

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2d71761
Describe shnarfs
alexandratran Oct 6, 2026
ad35d3b
Apply batched suggestions from code review
alexandratran Oct 7, 2026
645011b
Merge branch 'main' into shnarfs
alexandratran Oct 7, 2026
20617d5
address feedback
alexandratran Oct 7, 2026
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
4 changes: 2 additions & 2 deletions docs/protocol/architecture/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,10 +232,10 @@
4. Conflation: The coordinator groups blocks into batches.
5. Proof and blob generation: The prover generates execution proofs for batches and the coordinator combines batches into blobs;
the prover generates compression proofs.
6. Data submission: Lineth contracts define three data-submission models:
6. Data submission: Lineth contracts define three data submission models:
- Compressed data submitted as EIP-4844 blobs. Supported by the coordinator. Requires the rollup to support the `IAcceptEip4844Blobs` interface.
- Compressed data submitted as calldata. The current coordinator does not provide a calldata submitter. Requires the rollup to support the `IAcceptCalldataBlobs` interface.
- Shnarf-only submission for <GlossaryTerm term="Validium">validium</GlossaryTerm> deployments, without publishing the compressed batch data to the finalization layer. Supported by the coordinator. Requires the validium to support the `IAcceptShnarfData` interface.
- <GlossaryTerm term="Shnarf" />-only submission for <GlossaryTerm term="Validium">validium</GlossaryTerm> deployments, without publishing the compressed batch data to the finalization layer. Supported by the coordinator. Requires the validium to support the `IAcceptShnarfData` interface.

Check warning on line 238 in docs/protocol/architecture/index.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of "coordinator" (may not apply for start of sentence).

Raw Output:
{"message": "[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of \"coordinator\" (may not apply for start of sentence).", "location": {"path": "docs/protocol/architecture/index.mdx", "range": {"start": {"line": 238, "column": 213}}}, "severity": "WARNING"}
7. Finalization: The coordinator submits proofs to the finalization
layer; after verification and any configured delay, transactions reach hard finality on the selected
finalization layer.
Expand Down
32 changes: 30 additions & 2 deletions docs/protocol/architecture/smart-contracts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,11 @@
until this contract has recorded it.
The finalization contract:

- Records each data submission as a [shnarf](#data-commitments-shnarfs).

Check warning on line 25 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 25, "column": 38}}}, "severity": "WARNING"}
The contract computes that shnarf from the submitted data, except for a <GlossaryTerm term="Validium">validium</GlossaryTerm>,

Check warning on line 26 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 26, "column": 30}}}, "severity": "WARNING"}
which stores the shnarf the <GlossaryTerm term="Coordinator">coordinator</GlossaryTerm> provides.

Check warning on line 27 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of "coordinator" (may not apply for start of sentence).

Raw Output:
{"message": "[Consensys.CaseSensitive-Substitution] Consider standard format, 'Coordinator' instead of \"coordinator\" (may not apply for start of sentence).", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 27, "column": 64}}}, "severity": "WARNING"}

Check warning on line 27 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 27, "column": 20}}}, "severity": "WARNING"}
- Calls a verifier contract to check the <GlossaryTerm term="zk-SNARK" /> proof submitted for each range of blocks, and records the
resulting finalized state.
- Accepts the transaction data the network publishes, through whichever
[data submission model](./index.mdx#transaction-lifecycle) the deployment uses.
- Anchors the Merkle roots of the messages the finalized blocks sent, and verifies the rolling hash of the
messages the network received.
See [Message commitments](./bridge/canonical-message-service.mdx#message-commitments).
Expand All @@ -41,6 +42,33 @@

:::

### Data commitments (shnarfs)

Check warning on line 45 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarfs'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarfs'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 45, "column": 23}}}, "severity": "WARNING"}

Each data submission is recorded on the finalization contract as a shnarf: a single hash that commits to the

Check warning on line 47 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 47, "column": 68}}}, "severity": "WARNING"}
submitted data, the state it produces, and the submission before it.
A shnarf is the <GlossaryTerm term="Keccak">Keccak</GlossaryTerm> hash of these values concatenated:

Check warning on line 49 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 49, "column": 3}}}, "severity": "WARNING"}
Comment thread
alexandratran marked this conversation as resolved.

- The parent shnarf, which links submissions into an ordered chain

Check warning on line 51 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 51, "column": 14}}}, "severity": "WARNING"}
- A SNARK-friendly hash of the compressed data
- The final state root after the submitted data
- A data evaluation point and claim, which bind the shnarf to the submitted data

Check warning on line 54 in docs/protocol/architecture/smart-contracts.mdx

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'shnarf'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "docs/protocol/architecture/smart-contracts.mdx", "range": {"start": {"line": 54, "column": 53}}}, "severity": "WARNING"}

At finalization, the <GlossaryTerm term="zk-SNARK" /> public input includes the last finalized shnarf and the
new final shnarf.
The contract accepts the proof only when that new final shnarf matches one it has already recorded.

How the shnarf is recorded depends on the [data submission model](./index.mdx#transaction-lifecycle):

- **EIP-4844 blobs (<GlossaryTerm term="Rollup">rollup</GlossaryTerm>):** The contract computes the shnarf from
the blob posted with the submission, so the data the shnarf commits to is posted to the finalization layer.
When multiple blobs are submitted, the contract computes a shnarf for each blob, chains them together, and stores
the final shnarf.
- **Calldata:** The contract computes the shnarf from the compressed data in the submission.
The coordinator does not currently provide a calldata submitter.
- **Shnarf-only (<GlossaryTerm term="Validium">validium</GlossaryTerm>):** The coordinator computes the shnarf and
the contract records it.
The proof is still bound to the data, but the data itself is not posted to the finalization layer.

## Message service contracts

A message service contract is deployed on each chain.
Expand Down
4 changes: 4 additions & 0 deletions docs/protocol/reference/zero-knowledge-glossary.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,10 @@ The set of Linea Besu plugins responsible for ordering, building, and executing

A node that pairs a Maru validator with a Linea Besu execution client running the sequencer plugins. This pairing is what produces canonical blocks: Maru handles consensus, and Linea Besu orders, builds, and executes the block. Some materials use "validator" and "sequencer" interchangeably. Here, the validator is the Maru process, the sequencer is the Linea Besu plugin set, and the sequencer node is the two together.

### Shnarf

A hash commitment recorded on the finalization contract for each data submission. It covers the submitted data, the resulting state root, and the previous shnarf. Finalization proofs are verified against it.

### Shomei

A state manager that communicates with Linea Besu, via a corresponding plugin, to maintain and update network state using sparse Merkle trees. Shomei is the component behind Lineth's state manager.
Expand Down
2 changes: 2 additions & 0 deletions docs/stack/deployment/data-availability.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,3 +70,5 @@ Operators are responsible for the following:

- [Finalization layer](./finalization-layer.mdx): Where proofs and state commitments settle.
- [Deployment models](../evaluate/deployment-models.mdx): How rollups and validiums differ.
- [Data commitments (shnarfs)](/protocol/architecture/smart-contracts#data-commitments-shnarfs):
The hash the finalization contract records for each data submission.
4 changes: 4 additions & 0 deletions src/lib/glossary.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,10 @@
"term": "Sequencer node",
"definition": "A node that pairs a Maru validator with a Linea Besu execution client running the sequencer plugins. This pairing is what produces canonical blocks: Maru handles consensus, and Linea Besu orders, builds, and executes the block. Some materials use \"validator\" and \"sequencer\" interchangeably. Here, the validator is the Maru process, the sequencer is the Linea Besu plugin set, and the sequencer node is the two together."
},
{
"term": "Shnarf",
"definition": "A hash commitment recorded on the finalization contract for each data submission. It covers the submitted data, the resulting state root, and the previous shnarf. Finalization proofs are verified against it."
},
{
"term": "Shomei",
"definition": "A state manager that communicates with Linea Besu, via a corresponding plugin, to maintain and update network state using sparse Merkle trees. Shomei is the component behind Lineth's state manager."
Expand Down
Loading