Skip to content

[WIP] caps/eth.md: cell exchange #263

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

Draft
wants to merge 33 commits into
base: master
Choose a base branch
from
+124 −2
Draft

[WIP] caps/eth.md: cell exchange #263

Changes from 9 commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
e0bfa16
add: add eth70 spec
healthykim Aug 14, 2025
5ba0075
fix: omit proof messaging
healthykim Aug 15, 2025
556cc66
add: add a link to peerDAS
healthykim Aug 15, 2025
4f29887
fix: restore Transactions msg spec
healthykim Aug 15, 2025
75753f0
fix: rename ids to index
healthykim Aug 15, 2025
e558fa1
fix: specify the length of cells
healthykim Aug 15, 2025
ce56fc7
fix: integrate bitmap to hash announcement
healthykim Aug 19, 2025
1d36625
fix: change cells message
healthykim Aug 20, 2025
efe662b
chore: fix typo
healthykim Aug 20, 2025
9a8ff92
add: add explanation about bitmap granularity
healthykim Aug 20, 2025
0896be2
add: add constraint in Cells message
healthykim Aug 20, 2025
6caf1bc
add: modify intro
healthykim Aug 20, 2025
bb37e52
add: add behaviour
healthykim Aug 26, 2025
6021b98
add detailed explanation of the Cells message
healthykim Aug 26, 2025
a902ea9
clarify meaning of cells field
healthykim Aug 26, 2025
c2a1f03
clarify meaning of cells field
healthykim Aug 26, 2025
744324f
fix typo
healthykim Aug 26, 2025
eab5207
fix typo
healthykim Aug 26, 2025
9e049e7
polish intro
healthykim Aug 26, 2025
bda330c
add more information about custody set
healthykim Aug 26, 2025
cafd6d3
edit intro
healthykim Aug 26, 2025
24be46e
modify intro
healthykim Aug 29, 2025
7d162ef
clarify cell index vs. tx better
cskiraly Aug 31, 2025
390d9bc
fix typo
cskiraly Aug 31, 2025
5e476bb
improve explanation
cskiraly Aug 31, 2025
4161bd1
edit the number of cell indices set under pull behavior
healthykim Aug 31, 2025
46fffe3
clarify scope of cells field
healthykim Aug 31, 2025
c064077
fix the incorrect restriction on the number of cells that can be requ…
healthykim Aug 31, 2025
4cc7746
add parameter table and references to parameters
healthykim Sep 1, 2025
6d926b1
clarify load balancing requirements
healthykim Sep 1, 2025
2b12215
clarify the difference between p and MIN_P
healthykim Sep 1, 2025
bd2207a
fix typo
healthykim Sep 1, 2025
edb32f5
move peer disconnection to getcells from cells
healthykim Sep 1, 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
53 changes: 50 additions & 3 deletions caps/eth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Ethereum Wire Protocol (ETH)

'eth' is a protocol on the [RLPx] transport that facilitates exchange of Ethereum
blockchain information between peers. The current protocol version is **eth/69**. See end
blockchain information between peers. The current protocol version is **eth/70**. See end
Copy link

Choose a reason for hiding this comment

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

There are already eth/70 proposals in progress, so the number will be different
We can update at the end in the doc, but maybe remove from title to avoid confusion

Copy link
Author

Choose a reason for hiding this comment

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

I removed all eth/70 numbering in this PR and on doc so that we can add it back at the end.

of document for a list of changes in past protocol versions.

### Basic Operation
Expand Down Expand Up @@ -123,6 +123,24 @@ of it (either because it was previously sent or because it was informed from thi
originally). This is usually achieved by remembering a set of transaction hashes recently
relayed by the peer.

### Blob Transaction and Cell Exchange

Blob transaction carries one or more large objects called blobs, in addition to the normal
transaction payload. Blobs are not sent directly with the transaction but are exchanged
in the form of `Cell` separately between peers.
Cells are computed by splitting the blob and applying the erasure-code defined in [EIP-7594].
A cell has its `index`, according to its relative position in the erasure-coded blob.

When a blob transaction is added to a peer's pool, availability of its cell should be announced
to the network using `cells` field in the [NewPooledTransactionHashes] message.
All peers that receive the message can request the cell whose index is specified in the
`cells` using the [GetCells] message. Clients can selectively store cells according to
their local parameters.

A node should never announce availability to a peer that it can infer to already
have the associated cell. This can be achieved by remembering set of versioned hashes
and cell indices announced by each peer.

### Transaction Encoding and Validity

Transaction objects exchanged by peers have one of two encodings. In definitions across
Expand Down Expand Up @@ -418,11 +436,11 @@ block.

### NewPooledTransactionHashes (0x08)

`[txtypes: B, [txsize₁: P, txsize₂: P, ...], [txhash₁: B_32, txhash₂: B_32, ...]]`
`[txtypes: B, [txsize₁: P, txsize₂: P, ...], [txhash₁: B_32, txhash₂: B_32, ...], cells: B_16]`
Copy link

Choose a reason for hiding this comment

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

We should decide whether there is one cells bitmap for the whole message, or one cells bitmap per transaction - in the pool. In the first case, the bitmap should refer to all transactions (or all type 3 transactions) in the pool.

  • in the second case, we could have a separate bitmap for each tx. Eventually we could compress a bit by skipping bitmaps for non type3 transactions.


This message announces one or more transactions that have appeared in the network and
which have not yet been included in a block. The message payload describes a list of of
transactions, but note that it is encoded as three separate elements.
transactions, but note that it is encoded as four separate elements.

The `txtypes` element is a byte array containing the announced [transaction types]. The
other two payload elements refer to the sizes and hashes of the announced transactions.
Expand All @@ -432,6 +450,10 @@ All three payload elements must contain an equal number of items.
the byte size of `tx-type || tx-data` for typed transactions, and the size of the
RLP-encoded `legacy-tx` for non-typed legacy transactions.

The `cells` element is a bitmap marking the indices of cells stored by the sending peer.
For each cell stored by the peer the corresponding bit is set. Note that blob transactions
with same cells field is being batched together.
Copy link
Member

@raulk raulk Aug 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

  • Can the schema proposed there deal with (a) max 6 blobs per tx and (b) multiple type 3 txs being announced in the same message? Or does "Note that blob transactions with same cells field is being batched together." imply that if cell availability differs across txs, we'd announce them separately?
  • I think it's safe to assume that nodes will want to sample the same cell indices for all blobs in a single type 3 tx, which makes the cells naming a bit confusing IMO, but also not a dealbreaker (technically they're columns, but also technically columns don't exist until the blobs are packed in a block).

Copy link
Author

Choose a reason for hiding this comment

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

Yes, I think we can assume that nodes will try to fetch the same indices for all transactions in most cases. That is why I designed this in a batched form. So, regarding the first question, yes, we would announce them separately, but we can easily assume that most transactions would be batched together and there would not be much fragmentation. I also agree on the naming. cell-indices, custody-indices, and mask could be candidates, but we could also just leave it as it is

Copy link
Member

@raulk raulk Aug 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Gotcha. We might want nodes to sample a few random cells from peers holding the full payload in addition to their custody set. This mechanism is a sentinel against selective data serving attacks. Otherwise an attacker could repeatedly advertise full availability while holding only the exact subset of cells they know we'll request every time.

Copy link

Choose a reason for hiding this comment

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

Since a type 3 tx can have several blobs, we should clarify whether the bitmap is at the tx or at the blob granularity.
For our current purposes, tx granularity looks fine, and then the meaning of a bit is that that the node has the corresponding cell of all blobs in the tx.

Copy link
Author

Choose a reason for hiding this comment

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

Since a type 3 tx can have several blobs, we should clarify whether the bitmap is at the tx or at the blob granularity. For our current purposes, tx granularity looks fine, and then the meaning of a bit is that that the node has the corresponding cell of all blobs in the tx.

Thank you, I added a more detailed explanation about this in the introduction.

Copy link
Author

Choose a reason for hiding this comment

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

Gotcha. We might want nodes to sample a few random cells from peers holding the full payload in addition to their custody set. This mechanism is a sentinel against selective data serving attacks. Otherwise an attacker could repeatedly advertise full availability while holding only the exact subset of cells they know we'll request every time.

I’m not sure how much random sampling would be needed given that we have the full payload node count check too, but I think it can be supported under this design. A node can select random columns and perform sampling over the transaction batch, and if an attacker skips the cell indices of the transaction they want to hide, the node would request that column from another peer and ultimately be able to drop the malicious transaction.


The recommended soft limit for this message is 4096 items (~150 KiB).

To be maximally helpful, nodes should inform peers of all transactions that they may not
Expand Down Expand Up @@ -509,8 +531,30 @@ received updates.
At the same time, client implementations must take care to not disconnect all syncing
peers purely on the basis of their BlockRangeUpdate.

### GetCells (0x12)

`[request-id: P, [txhash₁: B_32, txhash₂: B_32, ...], cells : B_16]`

This message requests the peer to return cells of the given txhashes.
The `cells` element, a bitmap, specifies indices of the requested cells.

### Cells (0x13)

`[request-id: P, [[txhash₁: B_32, [index₁: P, cell₁: B, cell₂: B, ...], [index₂: P, cell₁: B, cell₂: B, ...]], [txhash₂: B_32, [index₁: P, cell₁: B, cell₂: B, ...], [index₂: P, cell₁: B, cell₂: B, ...]], ...]]`

This is the response to [GetCells].
Each element must match the txhash and cells specified in the request.
The sender can skip any indices that are not available, so the requester can fetch them
from other peers.

## Change Log

### eth/70 ()

Version 70 changed the [NewPooledTransactionHashes] message to include custody information
which represents cell indicies sending peer has stored. New message types,
[GetCells] and [Cells] were introduced to support cell-level messaging.

### eth/69 ([EIP-7642], April 2025)

Version 69 changed the [Status] message to include information about the available block
Expand Down Expand Up @@ -624,6 +668,8 @@ Version numbers below 60 were used during the Ethereum PoC development phase.
[GetReceipts]: #getreceipts-0x0f
[Receipts]: #receipts-0x10
[BlockRangeUpdate]: #blockrangeupdate-0x11
[GetCells]: #getcells-0x12
[Cells]: #cells-0x13
[RLPx]: ../rlpx.md
[EIP-155]: https://eips.ethereum.org/EIPS/eip-155
[EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559
Expand All @@ -639,6 +685,7 @@ Version numbers below 60 were used during the Ethereum PoC development phase.
[EIP-4844]: https://eips.ethereum.org/EIPS/eip-4844
[EIP-4938]: https://eips.ethereum.org/EIPS/eip-4938
[EIP-5793]: https://eips.ethereum.org/EIPS/eip-5793
[EIP-7594]: https://eips.ethereum.org/EIPS/eip-7594
[EIP-7642]: https://eips.ethereum.org/EIPS/eip-7642
[EIP-7685]: https://eips.ethereum.org/EIPS/eip-7685
[The Merge]: https://eips.ethereum.org/EIPS/eip-3675
Expand Down