From e0bfa16f45014aaa51259bf794242b5a15306f1e Mon Sep 17 00:00:00 2001 From: healthykim Date: Fri, 15 Aug 2025 01:09:17 +0200 Subject: [PATCH 01/33] add: add eth70 spec --- caps/eth.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 85e8a0c9..e167045b 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -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 of document for a list of changes in past protocol versions. ### Basic Operation @@ -361,11 +361,13 @@ of the sending node. ### Transactions (0x02) -`[tx₁, tx₂, ...]` +`[[tx₁, tx₂, ...], custodyids: B]` Specify transactions that the peer should make sure is included on its transaction queue. The items in the list are transactions in the format described in the main Ethereum -specification. Transactions messages must contain at least one (new) transaction, empty +specification. The custodyids element is a bitmap representing which cell IDs in transaction +payloads are stored by the sending peer, with each stored cell’s index marked as 1. +Transactions messages must contain at least one (new) transaction, empty Transactions messages are discouraged and may lead to disconnection. Nodes must not resend the same transaction to a peer in the same session and must not @@ -509,8 +511,47 @@ received updates. At the same time, client implementations must take care to not disconnect all syncing peers purely on the basis of their BlockRangeUpdate. +### CellAvailability (0x12) + +`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], custodyids: B]` + +This message announces the cell availability of transaction payloads. +The list of vhash values represents the commitment hashes of payloads for which cells are available. +The custodyid element is a bitmap marking the IDs of cells in the transaction payload +stored by the sending peer, with each stored cell’s index set to 1. + +### GetCellAndProofs (0x13) + +`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], requestids: B]` + +This message request peer to return cells and proofs of the given versioned hash +of the payload commitment. +The requestids element is a bitmap representing IDs of cells required. + +### CellAndProofs (0x14) + +`[request-id: P, [[vhash₁: B_32, [cellAndProof₁: B, cellAndProof₂: B, ...]], [vhash₂: B_32, [cellAndProof₁: B, cellAndProof₂: B, ...]], ...]]` + +This is a response to GetCellAndProofs, which provides the requested cells and their proofs. +Each list element contains the versioned hash of the payload commitment that includes +the cell, the cell itself, and a proof to verify the cell’s inclusion. +Each element must match the vhash specified in the request. +The sender can skip any cells that are not available, so the requester can fetch them +from other peers. + +The cellAndProof element contains the cell data along with the proof needed to verify +that it belongs to the original payload. +While its structure can vary depending on the verification method, +it should allow the recipient to infer which cell IDs were skipped. + ## Change Log +### eth/70 () + +Version 70 added the [CellAvailability] message to exchange custody information +which represents cell IDs sending peer has stored. New message types, +[GetCellAndProofs] and [CellAndProofs] 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 @@ -624,6 +665,9 @@ Version numbers below 60 were used during the Ethereum PoC development phase. [GetReceipts]: #getreceipts-0x0f [Receipts]: #receipts-0x10 [BlockRangeUpdate]: #blockrangeupdate-0x11 +[CellAvailability]: #cellavailability-0x12 +[GetCellAndProofs]: #getcellandproofs-0x13 +[CellAndProofs]: #cellandproofs-0x14 [RLPx]: ../rlpx.md [EIP-155]: https://eips.ethereum.org/EIPS/eip-155 [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 From 5ba0075a3952a63cab100b5dea6401296a5572d4 Mon Sep 17 00:00:00 2001 From: healthykim Date: Fri, 15 Aug 2025 17:23:11 +0200 Subject: [PATCH 02/33] fix: omit proof messaging --- caps/eth.md | 72 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 48 insertions(+), 24 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index e167045b..81fc2fae 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -123,6 +123,38 @@ 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 + +Blob transaction carries one or more large objects called blobs, in addition to the normal +transaction payload. The transaction also includes metadata that allows peers to verify +blob fragments (cells) they exchange over the network. + +- `cell`: Cell is a fragment of a blob, computed by splitting the blob and applying +the erasure-code defined in EIP-7594. In an extended blob, a cell can be identified by its index. + +- Commitment: Commitment is a cryptographic value bound to a blob. It is used in inclusion +verification to ensure that any given cell is part of the original blob. + +- Proof: Proof is a cell-specific data used during the inclusion verification of associated cell. + +- Versioned hash (`vhash`): Versioned hash is the identifier for a blob, which is calculated +taking the hash of the blob's commitment, prefixed with a version byte. Peers can specify +which blob's cells they want to request. + +Note that cells are not sent with the transaction itself but are exchanged separately between peers. + +### Cell Exchange + +When a new cell is added to a peer's pool, it should be announced to the network using +the [CellAvailability] message. All peers that receive the message can request +the cell whose index is specified in the message 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 @@ -513,36 +545,28 @@ received updates. ### CellAvailability (0x12) -`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], custodyids: B]` +`[[vhash₁: B_32, vhash₂: B_32, ...], cells: B_16]` This message announces the cell availability of transaction payloads. -The list of vhash values represents the commitment hashes of payloads for which cells are available. -The custodyid element is a bitmap marking the IDs of cells in the transaction payload -stored by the sending peer, with each stored cell’s index set to 1. +The list of `vhash` values represents the commitment hashes of payloads for which cells are available. +The `cells` element is a bitmap marking the indices of cells in the transaction payload +stored by the sending peer. For each cell stored by the peer the corresponding bit is set. -### GetCellAndProofs (0x13) +### GetCells (0x13) -`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], requestids: B]` +`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], cells : B]` -This message request peer to return cells and proofs of the given versioned hash -of the payload commitment. -The requestids element is a bitmap representing IDs of cells required. +This message requests the peer to return cells of the given vhashes. +The `cells` element, a bitmap, specifies indices of the requested cells. -### CellAndProofs (0x14) +### Cells (0x14) -`[request-id: P, [[vhash₁: B_32, [cellAndProof₁: B, cellAndProof₂: B, ...]], [vhash₂: B_32, [cellAndProof₁: B, cellAndProof₂: B, ...]], ...]]` +`[request-id: P, [[vhash₁: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], [vhash₂: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], ...]]` -This is a response to GetCellAndProofs, which provides the requested cells and their proofs. -Each list element contains the versioned hash of the payload commitment that includes -the cell, the cell itself, and a proof to verify the cell’s inclusion. -Each element must match the vhash specified in the request. +This is the response to [GetCells]. +Each element must match the vhash and cells specified in the request. The sender can skip any cells that are not available, so the requester can fetch them -from other peers. - -The cellAndProof element contains the cell data along with the proof needed to verify -that it belongs to the original payload. -While its structure can vary depending on the verification method, -it should allow the recipient to infer which cell IDs were skipped. +from other peers. ## Change Log @@ -550,7 +574,7 @@ it should allow the recipient to infer which cell IDs were skipped. Version 70 added the [CellAvailability] message to exchange custody information which represents cell IDs sending peer has stored. New message types, -[GetCellAndProofs] and [CellAndProofs] were introduced to support cell-level messaging. +[GetCells] and [Cells] were introduced to support cell-level messaging. ### eth/69 ([EIP-7642], April 2025) @@ -666,8 +690,8 @@ Version numbers below 60 were used during the Ethereum PoC development phase. [Receipts]: #receipts-0x10 [BlockRangeUpdate]: #blockrangeupdate-0x11 [CellAvailability]: #cellavailability-0x12 -[GetCellAndProofs]: #getcellandproofs-0x13 -[CellAndProofs]: #cellandproofs-0x14 +[GetCells]: #getcells-0x13 +[Cells]: #cells-0x14 [RLPx]: ../rlpx.md [EIP-155]: https://eips.ethereum.org/EIPS/eip-155 [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 From 556cc66f1f2f25b414b277b11010f34aae58cce9 Mon Sep 17 00:00:00 2001 From: healthykim Date: Fri, 15 Aug 2025 17:42:05 +0200 Subject: [PATCH 03/33] add: add a link to peerDAS --- caps/eth.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 81fc2fae..9766c5a3 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -129,8 +129,8 @@ Blob transaction carries one or more large objects called blobs, in addition to transaction payload. The transaction also includes metadata that allows peers to verify blob fragments (cells) they exchange over the network. -- `cell`: Cell is a fragment of a blob, computed by splitting the blob and applying -the erasure-code defined in EIP-7594. In an extended blob, a cell can be identified by its index. +- `cell`: Cell is computed by splitting the blob and applying the erasure-code defined in +[EIP-7594]. A cell can be identified in the erasure-coded blob by its `index`. - Commitment: Commitment is a cryptographic value bound to a blob. It is used in inclusion verification to ensure that any given cell is part of the original blob. @@ -138,10 +138,10 @@ verification to ensure that any given cell is part of the original blob. - Proof: Proof is a cell-specific data used during the inclusion verification of associated cell. - Versioned hash (`vhash`): Versioned hash is the identifier for a blob, which is calculated -taking the hash of the blob's commitment, prefixed with a version byte. Peers can specify -which blob's cells they want to request. +taking the hash of the blob's commitment, prefixed with a version byte. -Note that cells are not sent with the transaction itself but are exchanged separately between peers. +Note that blobs are not sent directly with the transaction but are exchanged in the form of +cells separately between peers. ### Cell Exchange @@ -154,7 +154,6 @@ 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 @@ -707,6 +706,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 From 4f29887eb3c72e0b3634673c42ff59f35f932ead Mon Sep 17 00:00:00 2001 From: healthykim Date: Fri, 15 Aug 2025 17:44:40 +0200 Subject: [PATCH 04/33] fix: restore Transactions msg spec --- caps/eth.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 9766c5a3..9dfc81ce 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -392,13 +392,11 @@ of the sending node. ### Transactions (0x02) -`[[tx₁, tx₂, ...], custodyids: B]` +`[tx₁, tx₂, ...]` Specify transactions that the peer should make sure is included on its transaction queue. The items in the list are transactions in the format described in the main Ethereum -specification. The custodyids element is a bitmap representing which cell IDs in transaction -payloads are stored by the sending peer, with each stored cell’s index marked as 1. -Transactions messages must contain at least one (new) transaction, empty +specification. Transactions messages must contain at least one (new) transaction, empty Transactions messages are discouraged and may lead to disconnection. Nodes must not resend the same transaction to a peer in the same session and must not From 75753f06c6f780fab771012cdd13bceeeb2cca0a Mon Sep 17 00:00:00 2001 From: healthykim Date: Fri, 15 Aug 2025 17:45:21 +0200 Subject: [PATCH 05/33] fix: rename ids to index --- caps/eth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caps/eth.md b/caps/eth.md index 9dfc81ce..b98c25a9 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -570,7 +570,7 @@ from other peers. ### eth/70 () Version 70 added the [CellAvailability] message to exchange custody information -which represents cell IDs sending peer has stored. New message types, +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) From e558fa102f80d87ce88eeeb8f3b24b15f535414c Mon Sep 17 00:00:00 2001 From: healthykim Date: Fri, 15 Aug 2025 18:13:25 +0200 Subject: [PATCH 06/33] fix: specify the length of cells --- caps/eth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caps/eth.md b/caps/eth.md index b98c25a9..864c49fa 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -551,7 +551,7 @@ stored by the sending peer. For each cell stored by the peer the corresponding b ### GetCells (0x13) -`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], cells : B]` +`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], cells : B_16]` This message requests the peer to return cells of the given vhashes. The `cells` element, a bitmap, specifies indices of the requested cells. From ce56fc7862196737aea07afc85c3d46277c11b50 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 19 Aug 2025 15:54:37 +0200 Subject: [PATCH 07/33] fix: integrate bitmap to hash announcement --- caps/eth.md | 72 ++++++++++++++++++++--------------------------------- 1 file changed, 27 insertions(+), 45 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 864c49fa..b19909ac 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -123,32 +123,19 @@ 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 +### Blob Transaction and Cell Exchange Blob transaction carries one or more large objects called blobs, in addition to the normal -transaction payload. The transaction also includes metadata that allows peers to verify -blob fragments (cells) they exchange over the network. +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. -- `cell`: Cell is computed by splitting the blob and applying the erasure-code defined in -[EIP-7594]. A cell can be identified in the erasure-coded blob by its `index`. - -- Commitment: Commitment is a cryptographic value bound to a blob. It is used in inclusion -verification to ensure that any given cell is part of the original blob. - -- Proof: Proof is a cell-specific data used during the inclusion verification of associated cell. - -- Versioned hash (`vhash`): Versioned hash is the identifier for a blob, which is calculated -taking the hash of the blob's commitment, prefixed with a version byte. - -Note that blobs are not sent directly with the transaction but are exchanged in the form of -cells separately between peers. - -### Cell Exchange - -When a new cell is added to a peer's pool, it should be announced to the network using -the [CellAvailability] message. All peers that receive the message can request -the cell whose index is specified in the message using the [GetCells] message. -Clients can selectively store cells according to their local parameters. +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 @@ -449,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]` 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. @@ -463,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. + 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 @@ -540,36 +531,28 @@ received updates. At the same time, client implementations must take care to not disconnect all syncing peers purely on the basis of their BlockRangeUpdate. -### CellAvailability (0x12) - -`[[vhash₁: B_32, vhash₂: B_32, ...], cells: B_16]` - -This message announces the cell availability of transaction payloads. -The list of `vhash` values represents the commitment hashes of payloads for which cells are available. -The `cells` element is a bitmap marking the indices of cells in the transaction payload -stored by the sending peer. For each cell stored by the peer the corresponding bit is set. - -### GetCells (0x13) +### GetCells (0x12) -`[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...], cells : B_16]` +`[request-id: P, [txhash₁: B_32, txhash₂: B_32, ...], cells : B_16]` -This message requests the peer to return cells of the given vhashes. +This message requests the peer to return cells of the given txhashes. The `cells` element, a bitmap, specifies indices of the requested cells. -### Cells (0x14) +### Cells (0x13) -`[request-id: P, [[vhash₁: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], [vhash₂: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], ...]]` +`[request-id: P, [[txhash₁: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], [txhash₂: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], ...]]` This is the response to [GetCells]. -Each element must match the vhash and cells specified in the request. -The sender can skip any cells that are not available, so the requester can fetch them +Each element must match the txhash and cells specified in the request. The `cellₙ` field +is an rlp encoded array that contains the cells for all blobs included in the transaction. +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 added the [CellAvailability] message to exchange custody information +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. @@ -686,9 +669,8 @@ Version numbers below 60 were used during the Ethereum PoC development phase. [GetReceipts]: #getreceipts-0x0f [Receipts]: #receipts-0x10 [BlockRangeUpdate]: #blockrangeupdate-0x11 -[CellAvailability]: #cellavailability-0x12 -[GetCells]: #getcells-0x13 -[Cells]: #cells-0x14 +[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 From 1d36625fc76d124137c7c19736f695f161c2a5d2 Mon Sep 17 00:00:00 2001 From: healthykim Date: Wed, 20 Aug 2025 12:36:01 +0200 Subject: [PATCH 08/33] fix: change cells message --- caps/eth.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index b19909ac..d07a6f44 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -540,11 +540,10 @@ The `cells` element, a bitmap, specifies indices of the requested cells. ### Cells (0x13) -`[request-id: P, [[txhash₁: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], [txhash₂: B_32, [index₁: P, cell₁: B], [index₂: P, cell₂: B, ...]], ...]]` +`[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 `cellₙ` field -is an rlp encoded array that contains the cells for all blobs included in the transaction. +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. From efe662be56d3c663953a526c781f9068938427f6 Mon Sep 17 00:00:00 2001 From: healthykim Date: Wed, 20 Aug 2025 12:44:39 +0200 Subject: [PATCH 09/33] chore: fix typo --- caps/eth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caps/eth.md b/caps/eth.md index d07a6f44..5eeb4f71 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -540,7 +540,7 @@ 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, ...]], ...]]` +`[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. From 9a8ff92c49dc809c3a51e886936495374808cb8d Mon Sep 17 00:00:00 2001 From: healthykim Date: Wed, 20 Aug 2025 15:09:00 +0200 Subject: [PATCH 10/33] add: add explanation about bitmap granularity --- caps/eth.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 5eeb4f71..13e342b7 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -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/70**. See end +blockchain information between peers. The current protocol version is **eth/69**. See end of document for a list of changes in past protocol versions. ### Basic Operation @@ -131,11 +131,13 @@ 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. +When a blob transaction is added to a peer's pool, availability of its cells should be +announced to the network using the cells field in the [NewPooledTransactionHashes] message. +If a bit in `cells` is set, it indicates that the peer holds the corresponding cell for all +blobs included in the announced transactions. +All peers that receive the message can then request the cells whose indices are +specified in the cells field 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 @@ -549,7 +551,7 @@ from other peers. ## Change Log -### eth/70 () +### eth/ () Version 70 changed the [NewPooledTransactionHashes] message to include custody information which represents cell indicies sending peer has stored. New message types, From 0896be283151c41e01674caeab49d7b64f547ffe Mon Sep 17 00:00:00 2001 From: healthykim Date: Wed, 20 Aug 2025 15:10:29 +0200 Subject: [PATCH 11/33] add: add constraint in Cells message --- caps/eth.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 13e342b7..6ac64235 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -132,10 +132,10 @@ Cells are computed by splitting the blob and applying the erasure-code defined i 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 cells should be -announced to the network using the cells field in the [NewPooledTransactionHashes] message. -If a bit in `cells` is set, it indicates that the peer holds the corresponding cell for all -blobs included in the announced transactions. -All peers that receive the message can then request the cells whose indices are +announced to the network using the `cells` field in the [NewPooledTransactionHashes] message. +The granularity of the `cells` is at the transaction level. If a bit is set, it indicates +that the peer holds the corresponding cell for all blobs included in the announced +transactions. All peers that receive the message can then request the cells whose indices are specified in the cells field using the [GetCells] message. Clients can selectively store cells according to their local parameters. @@ -537,7 +537,7 @@ received updates. `[request-id: P, [txhash₁: B_32, txhash₂: B_32, ...], cells : B_16]` -This message requests the peer to return cells of the given txhashes. +This message requests the peer to return cell data of the given txhashes. The `cells` element, a bitmap, specifies indices of the requested cells. ### Cells (0x13) @@ -547,7 +547,9 @@ The `cells` element, a bitmap, specifies indices of the requested cells. 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. +from other peers. Skipping is allowed only at the index level. The sender must return the +corresponding cells for all blobs included in the transaction and cannot skip cells belonging +to specific blobs. ## Change Log From 6caf1bc0cb9627813c150efe4a247e9c36ad6144 Mon Sep 17 00:00:00 2001 From: healthykim Date: Wed, 20 Aug 2025 15:21:31 +0200 Subject: [PATCH 12/33] add: modify intro --- caps/eth.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 6ac64235..e4f244a4 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -126,16 +126,17 @@ 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. +transaction payload. Blobs are not sent directly with the transaction. Instead, they are +split into cells using the erasure code defined in [EIP-7594], and these cells are exchanged +separately between peers. Since a transaction can carry multiple blobs, cell exchange is +handled at the transaction level, which means that cells in the same transaction should be +delivered together. When a blob transaction is added to a peer's pool, availability of its cells should be announced to the network using the `cells` field in the [NewPooledTransactionHashes] message. -The granularity of the `cells` is at the transaction level. If a bit is set, it indicates -that the peer holds the corresponding cell for all blobs included in the announced -transactions. All peers that receive the message can then request the cells whose indices are +If a bit is set, it indicates that the peer holds the corresponding cell for all blobs +included in the announced transactions. +All peers that receive the message can then request the cells whose indices are specified in the cells field using the [GetCells] message. Clients can selectively store cells according to their local parameters. From bb37e52c389611d2a9658d234baf6d1460d9bb70 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 14:03:47 +0200 Subject: [PATCH 13/33] add: add behaviour --- caps/eth.md | 73 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 52 insertions(+), 21 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index e4f244a4..803ef289 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -125,24 +125,55 @@ 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. Instead, they are -split into cells using the erasure code defined in [EIP-7594], and these cells are exchanged -separately between peers. Since a transaction can carry multiple blobs, cell exchange is -handled at the transaction level, which means that cells in the same transaction should be -delivered together. - -When a blob transaction is added to a peer's pool, availability of its cells should be -announced to the network using the `cells` field in the [NewPooledTransactionHashes] message. -If a bit is set, it indicates that the peer holds the corresponding cell for all blobs -included in the announced transactions. -All peers that receive the message can then request the cells whose indices are -specified in the cells field 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. +Blob transactions contain one or more 128 KiB fixed-size objects called blobs. Blobs can be +split into cells using the erasure code defined in [EIP-7594]. The size of a cell is +currently defined as 2 KiB, which means each blob consists of 128 cells encoded with a 1/2 +code rate. A cell is identified within the erasure-coded blob by its order (index). + +Blobs also include metadata such as cell proofs and a commitment required to verify whether +a cell belongs to the blob data. + +- Commitment: A cryptographic value bound to a blob, used in inclusion verification to +ensure that any given cell is part of the original blob. + +- Proof: A cell-specific proof used during inclusion verification of the corresponding cell. + +Blob transaction exchange must be initiated exclusively through the +[NewPooledTransactionHashes] message. The peer must also announce the availability of its +cells using the cells field in the message. If a bit in the field is set, it indicates that +the peer holds the corresponding cell for all blobs included in the announced transactions. + +Responses to [GetPooledTransactions] for blob transactions include the traditional transaction payload and blob metadata. However, the blob data itself can only be obtained +as cells via [GetCells]. Since a transaction can carry multiple blobs, cell exchange is +handled at the transaction level, meaning that all cells within the same transaction must +be delivered together. + +Upon receiving the [NewPooledTransactionHashes] message with new blob transaction hashes, +the node begins fetching cells in parallel with transaction fetching. The node first makes +a probabilistic decision. If it decides to fetch full blobs with probability $p$, it +requests them using the [GetCells] message, setting more than 50% of the total cell indices +to 1 in the cells field. The recommended probability $p$ is 0.15. + +If it decides not to fetch full blobs, it must instead request its custody cells from peers +that announced overlapping availability, using the [GetCells] message, but only after +observing N (TBD) distinct full-availability announcements. Custody cells are the cells +whose indices belong to the custody index set of the associated consensus node ID. The node +must also request an excess of N random columns in addition to its custody set to mitigate +targeted and selective data attacks. A node must announce availability only after obtaining +all of its custody cells. + +A node must request no more than 4 (TBD) columns per peer per transaction. It should never +announce availability to a peer if it can infer that the peer already holds the +corresponding cell. This can be achieved by tracking the set of transaction hashes and cell +indices announced by each peer. + +To manage uplink bandwidth usage, a node may disconnect peers that issue excessive +requests. This can be enforced by monitoring factors such as the number of requested cells +over a given period. A client connected to a supernode that stores the entire custody set +should distribute its requests as evenly as possible. To avoid being banned by the peer, it +must also respect a probability parameter $p$. With probability $p$, it should request 50% +of the data from a single peer, and with probability $1 – p$, it should request subsets of +cells collectively from multiple peers. ### Transaction Encoding and Validity @@ -548,9 +579,9 @@ The `cells` element, a bitmap, specifies indices of the requested cells. 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. Skipping is allowed only at the index level. The sender must return the -corresponding cells for all blobs included in the transaction and cannot skip cells belonging -to specific blobs. +from other peers. However, skipping is allowed only at the index level. +The sender must return the corresponding cells for all blobs included in the transaction +and cannot skip cells belonging to specific blobs. ## Change Log From 6021b98a131dff93764a0dca24da212548320aa8 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 16:41:24 +0200 Subject: [PATCH 14/33] add detailed explanation of the Cells message --- caps/eth.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 803ef289..113f17ad 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -486,7 +486,8 @@ 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. +with same cells field is being batched together. This field is only meaningful for blob +transactions included in the message. The recommended soft limit for this message is 4096 items (~150 KiB). @@ -571,17 +572,28 @@ received updates. This message requests the peer to return cell data of the given txhashes. The `cells` element, a bitmap, specifies indices of the requested cells. +To prevent greedy peer from abusing the bandwidth and incentivize collective fetch, +a node should either set 4 bits ($1-p$) or 64 bits ($p$) on `cells` field. + ### 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, ...]], ...]]` +`[request-id: P, [[txhash₁: B_32, [index₁: P, cell₁: B_2048, cell₂: B_2048, ...], [index₂: P, cell₁: B_2048, cell₂: B_2048, ...]], [txhash₂: B_32, [index₁: P, cell₁: B_2048, cell₂: B_2048, ...], [index₂: P, cell₁: B_2048, cell₂: B_2048, ...]], ...]]` + +This is the response to [GetCells]. + +Each transaction hash is followed by one or more pairs consisting of an index and the +corresponding cells. The index specifies the position of a cell within a blob. +Blob transaction can contain multiple blobs, and the same index is applied to all of +them. If an index is included in the response, one cell must be returned from each +blob of the transaction at that index. The cells are listed in the order in which the +blobs appear in the transaction. + +A peer may omit entire transactions or entire indices if they are unavailable or +constrained. However, if an index is included for a transaction, cells for all blobs +of that transaction at that index must be returned. -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. However, skipping is allowed only at the index level. -The sender must return the corresponding cells for all blobs included in the transaction -and cannot skip cells belonging to specific blobs. +A peer may respond with an empty list if none of the requested cells are available. ## Change Log From a902ea9a8ab986ba07918f31fb4e036172d89922 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 16:45:04 +0200 Subject: [PATCH 15/33] clarify meaning of cells field --- caps/eth.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 113f17ad..15aef660 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -485,9 +485,9 @@ the byte size of `tx-type || tx-data` for typed transactions, and the size of th 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. This field is only meaningful for blob -transactions included in the message. +For each cell stored by the peer the corresponding bit is set. +This field is only relevant when the transaction hash refers to a blob transaction. +Blob transactions with identical cells values may be batched together in the same message. The recommended soft limit for this message is 4096 items (~150 KiB). @@ -572,8 +572,8 @@ received updates. This message requests the peer to return cell data of the given txhashes. The `cells` element, a bitmap, specifies indices of the requested cells. -To prevent greedy peer from abusing the bandwidth and incentivize collective fetch, -a node should either set 4 bits ($1-p$) or 64 bits ($p$) on `cells` field. +To prevent greedy peers from abusing the bandwidth and to encourage collective fetch, +a node should either set 4 bits ($1-p$) or 64 bits ($p$) in the cells field. ### Cells (0x13) From c2a1f03ff9d35b2bd8c0b1c27963be13159e15a4 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 16:56:44 +0200 Subject: [PATCH 16/33] clarify meaning of cells field --- caps/eth.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 15aef660..d2a2566a 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -484,10 +484,12 @@ 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. -This field is only relevant when the transaction hash refers to a blob transaction. -Blob transactions with identical cells values may be batched together in the same message. +The cells element is a bitmap marking which cell indices can be fetched from the sending +peer. For each bit set to one, the peer stores the cell at that index in all blobs of the +transaction. A bit must be set only if the peer has the cell at that index in all blobs of +the transaction. This field is only relevant for those entries that refer to blob +transactions. Blob transactions with the same cells value may be announced together in a +batch within this message. The recommended soft limit for this message is 4096 items (~150 KiB). From 744324fc30a286c146820c5237e63e1d95ad5c53 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 17:00:01 +0200 Subject: [PATCH 17/33] fix typo --- caps/eth.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index d2a2566a..e2cf3efb 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -484,7 +484,7 @@ 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 which cell indices can be fetched from the sending +The `cells` element is a bitmap marking which cell indices can be fetched from the sending peer. For each bit set to one, the peer stores the cell at that index in all blobs of the transaction. A bit must be set only if the peer has the cell at that index in all blobs of the transaction. This field is only relevant for those entries that refer to blob @@ -572,10 +572,14 @@ received updates. `[request-id: P, [txhash₁: B_32, txhash₂: B_32, ...], cells : B_16]` -This message requests the peer to return cell data of the given txhashes. -The `cells` element, a bitmap, specifies indices of the requested cells. -To prevent greedy peers from abusing the bandwidth and to encourage collective fetch, -a node should either set 4 bits ($1-p$) or 64 bits ($p$) in the cells field. +This message requests the peer to return cell data of the given transaction hashes. +The cells element is a bitmap specifying which cell indices are requested. For each bit +set, the requester asks for the cell at that index from all blobs of the corresponding +transaction. + +A node should either set 4 bits (with probability $1–p$) or 64 bits (with probability $p$) +in the cells field. This mechanism prevents a greedy peer from abusing bandwidth and +encourages collective fetch behavior. ### Cells (0x13) From eab520785bd9251c1e49feebd2f766cb67cbfad4 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 17:00:18 +0200 Subject: [PATCH 18/33] fix typo --- caps/eth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caps/eth.md b/caps/eth.md index e2cf3efb..1725e92b 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -579,7 +579,7 @@ transaction. A node should either set 4 bits (with probability $1–p$) or 64 bits (with probability $p$) in the cells field. This mechanism prevents a greedy peer from abusing bandwidth and -encourages collective fetch behavior. +encourages collective fetch. ### Cells (0x13) From 9e049e736a5c0949dbdde192a045fc0f5c098ffb Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 19:40:47 +0200 Subject: [PATCH 19/33] polish intro --- caps/eth.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 1725e92b..4adce1ed 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -123,27 +123,34 @@ 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. +For additional rules for blob transactions, refer to the [blob transaction and cell exchange] +section. + ### Blob Transaction and Cell Exchange +This section describes additional constraints and node behaviours that apply only to blob +transactions, in addition to the ordinary transaction exchange. + Blob transactions contain one or more 128 KiB fixed-size objects called blobs. Blobs can be split into cells using the erasure code defined in [EIP-7594]. The size of a cell is -currently defined as 2 KiB, which means each blob consists of 128 cells encoded with a 1/2 -code rate. A cell is identified within the erasure-coded blob by its order (index). +currently defined as 2 KiB and each blob consists of 128 cells encoded with a 1/2 +code rate. A cell is identified within the erasure-coded blob by its index. -Blobs also include metadata such as cell proofs and a commitment required to verify whether -a cell belongs to the blob data. +Blob transactions also include metadata such as proofs and commitments required to verify +whether a cell belongs to the blob data. - Commitment: A cryptographic value bound to a blob, used in inclusion verification to ensure that any given cell is part of the original blob. -- Proof: A cell-specific proof used during inclusion verification of the corresponding cell. +- Proof: A cell-specific data used during inclusion verification of the corresponding cell. -Blob transaction exchange must be initiated exclusively through the +Blob transaction exchange must be initiated only through the [NewPooledTransactionHashes] message. The peer must also announce the availability of its -cells using the cells field in the message. If a bit in the field is set, it indicates that +cells using the `cells` field in the message. If a bit in the field is set, it indicates that the peer holds the corresponding cell for all blobs included in the announced transactions. -Responses to [GetPooledTransactions] for blob transactions include the traditional transaction payload and blob metadata. However, the blob data itself can only be obtained +Responses to [GetPooledTransactions] for blob transactions include the traditional transaction +payload and blob metadata. However, the blob data itself can only be obtained as cells via [GetCells]. Since a transaction can carry multiple blobs, cell exchange is handled at the transaction level, meaning that all cells within the same transaction must be delivered together. @@ -488,7 +495,7 @@ The `cells` element is a bitmap marking which cell indices can be fetched from t peer. For each bit set to one, the peer stores the cell at that index in all blobs of the transaction. A bit must be set only if the peer has the cell at that index in all blobs of the transaction. This field is only relevant for those entries that refer to blob -transactions. Blob transactions with the same cells value may be announced together in a +transactions. Blob transactions with the same `cells` field may be announced together in a batch within this message. The recommended soft limit for this message is 4096 items (~150 KiB). @@ -708,6 +715,7 @@ Version numbers below 60 were used during the Ethereum PoC development phase. [block propagation]: #block-propagation [state synchronization]: #state-synchronization-aka-fast-sync-snap-sync [snap protocol]: ./snap.md +[blob transaction and cell exchange]: #blob-transaction-and-cell-exchange [Status]: #status-0x00 [NewBlockHashes]: #newblockhashes-0x01 [Transactions]: #transactions-0x02 From bda330ce737df94f2e5ca9cb57c591ff8e36f2bd Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 19:57:02 +0200 Subject: [PATCH 20/33] add more information about custody set --- caps/eth.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 4adce1ed..331385c4 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -174,12 +174,12 @@ announce availability to a peer if it can infer that the peer already holds the corresponding cell. This can be achieved by tracking the set of transaction hashes and cell indices announced by each peer. -To manage uplink bandwidth usage, a node may disconnect peers that issue excessive -requests. This can be enforced by monitoring factors such as the number of requested cells -over a given period. A client connected to a supernode that stores the entire custody set -should distribute its requests as evenly as possible. To avoid being banned by the peer, it -must also respect a probability parameter $p$. With probability $p$, it should request 50% -of the data from a single peer, and with probability $1 – p$, it should request subsets of +To manage uplink bandwidth usage, a node may disconnect peers that send excessive +requests. This can be enforced by monitoring metrics such as the number of requested cells +over a given period. A client that want to store the entire blob should distribute +its requests as evenly as possible. To avoid being banned by its peer, it +must also respect a probability parameter $p$. With probability $p$, it can request 50% +of the data from a single peer, but with probability $1 – p$, it should request subsets of cells collectively from multiple peers. ### Transaction Encoding and Validity From cafd6d3427047ef888448cc0118104988b65e874 Mon Sep 17 00:00:00 2001 From: healthykim Date: Tue, 26 Aug 2025 19:57:43 +0200 Subject: [PATCH 21/33] edit intro --- caps/eth.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 331385c4..3a5edb5e 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -164,23 +164,19 @@ to 1 in the cells field. The recommended probability $p$ is 0.15. If it decides not to fetch full blobs, it must instead request its custody cells from peers that announced overlapping availability, using the [GetCells] message, but only after observing N (TBD) distinct full-availability announcements. Custody cells are the cells -whose indices belong to the custody index set of the associated consensus node ID. The node -must also request an excess of N random columns in addition to its custody set to mitigate +whose indices belong to the custody index set of the associated consensus node ID. In practice, +this information can be delievered using engine API from consensus layer. The node +must also request an excess of N random indices in addition to its custody set to mitigate targeted and selective data attacks. A node must announce availability only after obtaining all of its custody cells. -A node must request no more than 4 (TBD) columns per peer per transaction. It should never -announce availability to a peer if it can infer that the peer already holds the -corresponding cell. This can be achieved by tracking the set of transaction hashes and cell -indices announced by each peer. - -To manage uplink bandwidth usage, a node may disconnect peers that send excessive -requests. This can be enforced by monitoring metrics such as the number of requested cells -over a given period. A client that want to store the entire blob should distribute -its requests as evenly as possible. To avoid being banned by its peer, it -must also respect a probability parameter $p$. With probability $p$, it can request 50% -of the data from a single peer, but with probability $1 – p$, it should request subsets of -cells collectively from multiple peers. +A node must specify no more than 4 (TBD) indices per request. To manage uplink bandwidth usage, +a node may disconnect peers that send excessive requests. This can be enforced by monitoring +metrics such as the number of requested cells over a given period. +A client that wants to store every blobs should distribute its requests as evenly as possible. +To avoid being banned by its peer, it must also respect a probability parameter $p$. +With probability $p$, it can request 50% of the data from a single peer, but with probability +$1 – p$, it should request those cells collectively from multiple peers. ### Transaction Encoding and Validity From 24be46e15ee6e6593eae6dc778f1413213b5f2fd Mon Sep 17 00:00:00 2001 From: healthykim Date: Fri, 29 Aug 2025 10:37:17 +0200 Subject: [PATCH 22/33] modify intro --- caps/eth.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 3a5edb5e..9cbcedc5 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -123,9 +123,6 @@ 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. -For additional rules for blob transactions, refer to the [blob transaction and cell exchange] -section. - ### Blob Transaction and Cell Exchange This section describes additional constraints and node behaviours that apply only to blob @@ -170,9 +167,6 @@ must also request an excess of N random indices in addition to its custody set t targeted and selective data attacks. A node must announce availability only after obtaining all of its custody cells. -A node must specify no more than 4 (TBD) indices per request. To manage uplink bandwidth usage, -a node may disconnect peers that send excessive requests. This can be enforced by monitoring -metrics such as the number of requested cells over a given period. A client that wants to store every blobs should distribute its requests as evenly as possible. To avoid being banned by its peer, it must also respect a probability parameter $p$. With probability $p$, it can request 50% of the data from a single peer, but with probability @@ -604,6 +598,9 @@ of that transaction at that index must be returned. A peer may respond with an empty list if none of the requested cells are available. +To manage uplink bandwidth usage, a node may disconnect peers that send excessive requests. +This can be enforced by monitoring metrics such as the number of requested cells over a given +period. ## Change Log ### eth/ () @@ -711,7 +708,6 @@ Version numbers below 60 were used during the Ethereum PoC development phase. [block propagation]: #block-propagation [state synchronization]: #state-synchronization-aka-fast-sync-snap-sync [snap protocol]: ./snap.md -[blob transaction and cell exchange]: #blob-transaction-and-cell-exchange [Status]: #status-0x00 [NewBlockHashes]: #newblockhashes-0x01 [Transactions]: #transactions-0x02 From 7d162efb4a25ad1c62ab2391e148f668dc57ec38 Mon Sep 17 00:00:00 2001 From: Csaba Kiraly Date: Sun, 31 Aug 2025 17:52:27 +0200 Subject: [PATCH 23/33] clarify cell index vs. tx better Signed-off-by: Csaba Kiraly --- caps/eth.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 9cbcedc5..1a92d4a4 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -128,10 +128,13 @@ relayed by the peer. This section describes additional constraints and node behaviours that apply only to blob transactions, in addition to the ordinary transaction exchange. -Blob transactions contain one or more 128 KiB fixed-size objects called blobs. Blobs can be -split into cells using the erasure code defined in [EIP-7594]. The size of a cell is +A blob transaction contains one or more 128 KiB fixed-size objects called blob. Blobs can +be split into cells using the erasure code defined in [EIP-7594]. The size of a cell is currently defined as 2 KiB and each blob consists of 128 cells encoded with a 1/2 -code rate. A cell is identified within the erasure-coded blob by its index. +code rate. A cell is identified within the erasure-coded blob by its index. Protocol +messages index cells at the transaction level. Such an index refers to the corresponding +cell of each blob in the given transaction. This is similar to (but not to be confused with) +the notion of column in [EIP-7594]. Blob transactions also include metadata such as proofs and commitments required to verify whether a cell belongs to the blob data. @@ -148,9 +151,7 @@ the peer holds the corresponding cell for all blobs included in the announced tr Responses to [GetPooledTransactions] for blob transactions include the traditional transaction payload and blob metadata. However, the blob data itself can only be obtained -as cells via [GetCells]. Since a transaction can carry multiple blobs, cell exchange is -handled at the transaction level, meaning that all cells within the same transaction must -be delivered together. +as cells via [GetCells]. Upon receiving the [NewPooledTransactionHashes] message with new blob transaction hashes, the node begins fetching cells in parallel with transaction fetching. The node first makes From 390d9bcac17a8321e719a4eed3f6b523acaf107e Mon Sep 17 00:00:00 2001 From: Csaba Kiraly Date: Sun, 31 Aug 2025 17:52:43 +0200 Subject: [PATCH 24/33] fix typo Signed-off-by: Csaba Kiraly --- caps/eth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caps/eth.md b/caps/eth.md index 1a92d4a4..5bef8825 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -163,7 +163,7 @@ If it decides not to fetch full blobs, it must instead request its custody cells that announced overlapping availability, using the [GetCells] message, but only after observing N (TBD) distinct full-availability announcements. Custody cells are the cells whose indices belong to the custody index set of the associated consensus node ID. In practice, -this information can be delievered using engine API from consensus layer. The node +this information can be delivered using engine API from consensus layer. The node must also request an excess of N random indices in addition to its custody set to mitigate targeted and selective data attacks. A node must announce availability only after obtaining all of its custody cells. From 5e476bb8fe8058de6d6026ba3d0c715c16054325 Mon Sep 17 00:00:00 2001 From: Csaba Kiraly Date: Sun, 31 Aug 2025 17:57:11 +0200 Subject: [PATCH 25/33] improve explanation Signed-off-by: Csaba Kiraly --- caps/eth.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 5bef8825..37712e8b 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -170,8 +170,9 @@ all of its custody cells. A client that wants to store every blobs should distribute its requests as evenly as possible. To avoid being banned by its peer, it must also respect a probability parameter $p$. -With probability $p$, it can request 50% of the data from a single peer, but with probability -$1 – p$, it should request those cells collectively from multiple peers. +With probability $p$, it can request half of the cells of a blob transaction from a single +peer, but with probability $1 – p$, it should request those cells collectively from multiple +peers. ### Transaction Encoding and Validity From 4161bd1b6abc9f0fada7585be74a721808311875 Mon Sep 17 00:00:00 2001 From: healthykim Date: Sun, 31 Aug 2025 22:53:14 +0200 Subject: [PATCH 26/33] edit the number of cell indices set under pull behavior --- caps/eth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caps/eth.md b/caps/eth.md index 37712e8b..1f7a9ab5 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -156,7 +156,7 @@ as cells via [GetCells]. Upon receiving the [NewPooledTransactionHashes] message with new blob transaction hashes, the node begins fetching cells in parallel with transaction fetching. The node first makes a probabilistic decision. If it decides to fetch full blobs with probability $p$, it -requests them using the [GetCells] message, setting more than 50% of the total cell indices +requests them using the [GetCells] message, setting half of the total cell indices to 1 in the cells field. The recommended probability $p$ is 0.15. If it decides not to fetch full blobs, it must instead request its custody cells from peers From 46fffe332b3468627aff09d1edb4d60d1f297e92 Mon Sep 17 00:00:00 2001 From: healthykim Date: Mon, 1 Sep 2025 01:00:51 +0200 Subject: [PATCH 27/33] clarify scope of cells field --- caps/eth.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 1f7a9ab5..32a89de3 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -484,9 +484,9 @@ the byte size of `tx-type || tx-data` for typed transactions, and the size of th RLP-encoded `legacy-tx` for non-typed legacy transactions. The `cells` element is a bitmap marking which cell indices can be fetched from the sending -peer. For each bit set to one, the peer stores the cell at that index in all blobs of the -transaction. A bit must be set only if the peer has the cell at that index in all blobs of -the transaction. This field is only relevant for those entries that refer to blob +peer. For each bit set to one, the peer stores the cells at that index in every blob of +all blob transactions included in the announcemnt. +This field is only relevant for those entries that refer to blob transactions. Blob transactions with the same `cells` field may be announced together in a batch within this message. @@ -573,8 +573,8 @@ received updates. This message requests the peer to return cell data of the given transaction hashes. The cells element is a bitmap specifying which cell indices are requested. For each bit -set, the requester asks for the cell at that index from all blobs of the corresponding -transaction. +set, the requester asks for the cell at that index from every blob of all transactions +specified by the list of txhash. A node should either set 4 bits (with probability $1–p$) or 64 bits (with probability $p$) in the cells field. This mechanism prevents a greedy peer from abusing bandwidth and From c0640773d8f01aea3ae423dc8a80494bd76c8c4d Mon Sep 17 00:00:00 2001 From: healthykim Date: Mon, 1 Sep 2025 01:14:20 +0200 Subject: [PATCH 28/33] fix the incorrect restriction on the number of cells that can be requested per transaction --- caps/eth.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 32a89de3..92d391ab 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -576,9 +576,9 @@ The cells element is a bitmap specifying which cell indices are requested. For e set, the requester asks for the cell at that index from every blob of all transactions specified by the list of txhash. -A node should either set 4 bits (with probability $1–p$) or 64 bits (with probability $p$) -in the cells field. This mechanism prevents a greedy peer from abusing bandwidth and -encourages collective fetch. +A node should either set at most 4 bits (with probability $1–p$) or exactly 64 bits +(with probability $p$) in the cells field. +This mechanism prevents a greedy peer from abusing bandwidth and encourages collective fetch. ### Cells (0x13) From 4cc7746b9d59b14847d1eeb613e3e81e6a17a7f8 Mon Sep 17 00:00:00 2001 From: healthykim Date: Mon, 1 Sep 2025 02:24:44 +0200 Subject: [PATCH 29/33] add parameter table and references to parameters --- caps/eth.md | 45 +++++++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 92d391ab..e5ef507d 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -129,7 +129,7 @@ This section describes additional constraints and node behaviours that apply onl transactions, in addition to the ordinary transaction exchange. A blob transaction contains one or more 128 KiB fixed-size objects called blob. Blobs can -be split into cells using the erasure code defined in [EIP-7594]. The size of a cell is +be split into cells using the erasure code defined in [EIP-7594]. The size of a cell is currently defined as 2 KiB and each blob consists of 128 cells encoded with a 1/2 code rate. A cell is identified within the erasure-coded blob by its index. Protocol messages index cells at the transaction level. Such an index refers to the corresponding @@ -155,25 +155,43 @@ as cells via [GetCells]. Upon receiving the [NewPooledTransactionHashes] message with new blob transaction hashes, the node begins fetching cells in parallel with transaction fetching. The node first makes -a probabilistic decision. If it decides to fetch full blobs with probability $p$, it -requests them using the [GetCells] message, setting half of the total cell indices -to 1 in the cells field. The recommended probability $p$ is 0.15. +a probabilistic decision. + +If it decides to fetch full blobs with probability $p$, +it requests them using the [GetCells] message, setting half of the total cell indices to 1 +in the cells field. +Note that $p$ should be greater than or equal to `MIN_P`. If it decides not to fetch full blobs, it must instead request its custody cells from peers that announced overlapping availability, using the [GetCells] message, but only after -observing N (TBD) distinct full-availability announcements. Custody cells are the cells -whose indices belong to the custody index set of the associated consensus node ID. In practice, -this information can be delivered using engine API from consensus layer. The node -must also request an excess of N random indices in addition to its custody set to mitigate -targeted and selective data attacks. A node must announce availability only after obtaining -all of its custody cells. +observing `AVAILABILITY_THRESHOLD` distinct full-availability announcements. +Custody cells are the cells whose indices belong to the custody index set of the associated +consensus node ID. +In practice, this information can be delivered using engine API from consensus layer. The node +must also request an excess of `EXCESSIVE_SAMPLE_SIZE` random indices in addition to its +custody set to mitigate targeted and selective data attacks. +A node must announce availability only after obtaining all of its custody cells. + +For ease of explanation, in the former case the node is said to perform the provider role +for a given transaction, and in the latter case it is said to perform the sampler role. A client that wants to store every blobs should distribute its requests as evenly as possible. -To avoid being banned by its peer, it must also respect a probability parameter $p$. +To avoid being banned by its peer, it must also respect a probability parameter `MIN_P`. With probability $p$, it can request half of the cells of a blob transaction from a single -peer, but with probability $1 – p$, it should request those cells collectively from multiple +peer, but with probability 1 – `MIN_P`, it should request those cells collectively from multiple peers. +#### Constants + +| **Name** | **Value** | **Note** | +|---------|------|---------------------------------------------------------------------------------| +| `NUMBER_OF_CELLS` | 128 | Number of cells in an extended blob, as defined in [EIP-7594] | +| `MIN_P` | 0.15 | Minimum recommended probability to fetch the full blobs for a given transaction | +| `MAX_CELLS_PER_PARTIAL_REQUEST` | 4 (TBD) | Maximum number of cells per [GetCells] request as a sampler | +| `CELLS_PER_FULL_REQUEST` | 64 | Number of cells per [GetCells] request as a provider | +| `AVAILABILITY_THRESHOLD` | 4 (TBD) | Minimum number of peers required to confirm blob availability as a sampler | +| `EXCESSIVE_SAMPLE_SIZE` | 4 (TBD) | Number of additional cells requested beyond the custody set | + ### Transaction Encoding and Validity Transaction objects exchanged by peers have one of two encodings. In definitions across @@ -576,11 +594,10 @@ The cells element is a bitmap specifying which cell indices are requested. For e set, the requester asks for the cell at that index from every blob of all transactions specified by the list of txhash. -A node should either set at most 4 bits (with probability $1–p$) or exactly 64 bits +A node should either set at most `MAX_CELLS_PER_PARTIAL_REQUEST` bits (with probability $1–p$) or exactly `CELLS_PER_FULL_REQUEST` bits (with probability $p$) in the cells field. This mechanism prevents a greedy peer from abusing bandwidth and encourages collective fetch. - ### Cells (0x13) `[request-id: P, [[txhash₁: B_32, [index₁: P, cell₁: B_2048, cell₂: B_2048, ...], [index₂: P, cell₁: B_2048, cell₂: B_2048, ...]], [txhash₂: B_32, [index₁: P, cell₁: B_2048, cell₂: B_2048, ...], [index₂: P, cell₁: B_2048, cell₂: B_2048, ...]], ...]]` From 6d926b125d5662ac6b57e6722f2de503c246013e Mon Sep 17 00:00:00 2001 From: healthykim Date: Mon, 1 Sep 2025 02:30:06 +0200 Subject: [PATCH 30/33] clarify load balancing requirements --- caps/eth.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index e5ef507d..9568a26b 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -176,8 +176,9 @@ For ease of explanation, in the former case the node is said to perform the prov for a given transaction, and in the latter case it is said to perform the sampler role. A client that wants to store every blobs should distribute its requests as evenly as possible. -To avoid being banned by its peer, it must also respect a probability parameter `MIN_P`. -With probability $p$, it can request half of the cells of a blob transaction from a single +It must also respect `MIN_P`, which means that over a given period the ratio of requests for +half of the cell indices must not exceed `MIN_P` of its total requests. +With probability `MIN_P`, it can request half of the cells of a blob transaction from a single peer, but with probability 1 – `MIN_P`, it should request those cells collectively from multiple peers. From 2b122152c746d71cc225a0b8b708779038ea7373 Mon Sep 17 00:00:00 2001 From: healthykim Date: Mon, 1 Sep 2025 02:41:36 +0200 Subject: [PATCH 31/33] clarify the difference between p and MIN_P --- caps/eth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caps/eth.md b/caps/eth.md index 9568a26b..034fd5e8 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -160,7 +160,7 @@ a probabilistic decision. If it decides to fetch full blobs with probability $p$, it requests them using the [GetCells] message, setting half of the total cell indices to 1 in the cells field. -Note that $p$ should be greater than or equal to `MIN_P`. +Note that $p$ is a local parameter greater than or equal to `MIN_P`. If it decides not to fetch full blobs, it must instead request its custody cells from peers that announced overlapping availability, using the [GetCells] message, but only after From bd2207afa7119da9c93bfa316d41f16d9fef5883 Mon Sep 17 00:00:00 2001 From: healthykim Date: Mon, 1 Sep 2025 03:01:58 +0200 Subject: [PATCH 32/33] fix typo --- caps/eth.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/caps/eth.md b/caps/eth.md index 034fd5e8..90233e6a 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -191,7 +191,7 @@ peers. | `MAX_CELLS_PER_PARTIAL_REQUEST` | 4 (TBD) | Maximum number of cells per [GetCells] request as a sampler | | `CELLS_PER_FULL_REQUEST` | 64 | Number of cells per [GetCells] request as a provider | | `AVAILABILITY_THRESHOLD` | 4 (TBD) | Minimum number of peers required to confirm blob availability as a sampler | -| `EXCESSIVE_SAMPLE_SIZE` | 4 (TBD) | Number of additional cells requested beyond the custody set | +| `EXCESSIVE_SAMPLE_SIZE` | 4 (TBD) | Number of additional cells sampled beyond the custody set | ### Transaction Encoding and Validity @@ -591,12 +591,12 @@ received updates. `[request-id: P, [txhash₁: B_32, txhash₂: B_32, ...], cells : B_16]` This message requests the peer to return cell data of the given transaction hashes. -The cells element is a bitmap specifying which cell indices are requested. For each bit +The `cells` element is a bitmap specifying which cell indices are requested. For each bit set, the requester asks for the cell at that index from every blob of all transactions specified by the list of txhash. -A node should either set at most `MAX_CELLS_PER_PARTIAL_REQUEST` bits (with probability $1–p$) or exactly `CELLS_PER_FULL_REQUEST` bits -(with probability $p$) in the cells field. +A node should either set at most `MAX_CELLS_PER_PARTIAL_REQUEST` bits (with probability $1–$`MIN_P`) +or exactly `CELLS_PER_FULL_REQUEST` bits (with probability `MIN_P`) in the cells field. This mechanism prevents a greedy peer from abusing bandwidth and encourages collective fetch. ### Cells (0x13) @@ -618,9 +618,6 @@ of that transaction at that index must be returned. A peer may respond with an empty list if none of the requested cells are available. -To manage uplink bandwidth usage, a node may disconnect peers that send excessive requests. -This can be enforced by monitoring metrics such as the number of requested cells over a given -period. ## Change Log ### eth/ () From edb32f52a25b3f9cf161959cdb6489f5bedb2990 Mon Sep 17 00:00:00 2001 From: healthykim Date: Mon, 1 Sep 2025 03:03:04 +0200 Subject: [PATCH 33/33] move peer disconnection to getcells from cells --- caps/eth.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/caps/eth.md b/caps/eth.md index 90233e6a..1acef721 100644 --- a/caps/eth.md +++ b/caps/eth.md @@ -599,6 +599,10 @@ A node should either set at most `MAX_CELLS_PER_PARTIAL_REQUEST` bits (with prob or exactly `CELLS_PER_FULL_REQUEST` bits (with probability `MIN_P`) in the cells field. This mechanism prevents a greedy peer from abusing bandwidth and encourages collective fetch. +To manage uplink bandwidth usage, a node may disconnect peers that send excessive requests. +This can be enforced by monitoring metrics such as the number of requested cells over a given +period. + ### Cells (0x13) `[request-id: P, [[txhash₁: B_32, [index₁: P, cell₁: B_2048, cell₂: B_2048, ...], [index₂: P, cell₁: B_2048, cell₂: B_2048, ...]], [txhash₂: B_32, [index₁: P, cell₁: B_2048, cell₂: B_2048, ...], [index₂: P, cell₁: B_2048, cell₂: B_2048, ...]], ...]]`