Skip to content

caps/eth: define the pooled transaction encoding and fix the txsize definition #281

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

Open
qu0b wants to merge 1 commit into
base: master
Choose a base branch
from
Open

caps/eth: define the pooled transaction encoding and fix the txsize definition #281

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
75 changes: 62 additions & 13 deletions caps/eth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,8 +173,9 @@ observing `AVAILABILITY_THRESHOLD` distinct full-availability announcements.

### Transaction Encoding and Validity

Transaction objects exchanged by peers have one of two encodings. In definitions across
this specification, we refer to transactions of either encoding using the identifier `txₙ`.
Transaction objects exchanged by peers may be encoded in more than one way. In definitions
across this specification, we refer to transactions as they appear in blocks using the
identifier `txₙ`.

tx = {legacy-tx, typed-tx}

Expand All @@ -197,6 +198,38 @@ transaction type (`tx-type`) and the remaining bytes are opaque type-specific da

typed-tx = tx-type || tx-data

#### Pooled Encoding

Certain transaction types carry auxiliary data which is required to validate the
transaction in the pool, but which is not part of the transaction as it appears in a
block. Transactions of such a type therefore have a second, 'pooled' encoding, used by
[PooledTransactions]. In definitions across this specification, we refer to transactions
in this encoding using the identifier `pooled-txₙ`.
Comment on lines +206 to +207

@healthykim healthykim Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I am not sure whether it is a good idea to bind the encoding to a specific message type. For example, in EIP 8077, we are considering the idea of sending type 3 transactions directly via Transactions.

@qu0b qu0b Sep 2, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

yeah, I also am septical regarding this point. Do you have any example on how this might be done more clearly? maybe just revise the current spec wording to ammend it slightly to handle the blob transaction annoncement. Theres the "TODO" in there so instead of handling a more general case we can just handle the specific case.

@healthykim healthykim Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

What about defining net-tx = { tx, wrapped-tx }? i.e. the wrapped encoding for transaction types that define one, and otherwise make it identical to tx` (the consensus encoding).

[PooledTransactions] would become [request-id: P, [net-tx₁, net-tx₂, ...]], and the same for[Transactions], but we could add an additional restriction there saying that type-3 transactions must not be sent using this message type. This could be removed after 8077

@healthykim healthykim Sep 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Hi, are you still working on this ? What I meant was that we might use the pooled-tx type for Transactions after 8077, so handling the general case seems better with that in mind. I just wasn't sure whether the type name was somehow tied to a specific message type's name. But since it can also refer to transactions in the txpool, I think it's fine as is.


For a transaction whose `tx-type` defines no wrapped form, the pooled encoding is
identical to `tx`. Types which do define one — currently only type `0x03`, introduced by
[EIP-4844] — are encoded as:

wrapped-tx = tx-type || rlp([
tx-payload-body,
wrapper-version: P,
blobs: [blob₁: B_131072, blob₂: B_131072, ...],
commitments: [commitment₁: B_48, commitment₂: B_48, ...],
proofs: [proof₁: B_48, proof₂: B_48, ...],
])

`tx-payload-body` is the transaction's `tx-data` decoded as an RLP list. `wrapper-version`
selects the meaning of `proofs` and is defined by [EIP-7594]; the current version is `1`,
for which `proofs` contains `CELLS_PER_EXT_BLOB` cell proofs per blob. On chains where
[EIP-7594] is not active, the version-0 wrapper defined by [EIP-4844] is used instead: it
omits the `wrapper-version` element and carries one blob proof per blob. The two forms are
distinguished by the number of elements in the RLP list.

The `blobs` element is the empty list in [PooledTransactions] responses from `eth/72`
onwards; blob data is obtained through [GetCells] instead. See [EIP-8070]. Note that the
resulting encoding still contains the `wrapper-version` element and an empty `blobs` list,
so its length is not simply the length of the blob data subtracted from the unelided form.

Transactions must be validated when they are received. Validity depends on the Ethereum
chain state. The specific kind of validity this specification is concerned with is not
whether the transaction can be executed successfully by the EVM, but only whether it is
Expand Down Expand Up @@ -226,7 +259,7 @@ from their signature.
current account nonce are valid, and to which degree 'nonce gaps' are acceptable.

Implementations may enforce other validation rules for transactions. For example, it is
common practice to reject encoded transactions larger than 128 kB.
common practice to reject transactions whose `tx` encoding is larger than 128 kB.

Unless noted otherwise, implementations must not disconnect peers for sending invalid
transactions, and should simply discard them instead. This is because the peer might be
Expand Down Expand Up @@ -462,6 +495,10 @@ relay transactions to a peer they received that transaction from. In practice th
often implemented by keeping a per-peer bloom filter or set of transaction hashes which
have already been sent or received.

Transactions of a type which defines a wrapped [pooled encoding] must not be sent in this
message. Per [EIP-4844], such transactions are only ever announced with
[NewPooledTransactionHashes] and served on request via [GetPooledTransactions].

### GetBlockHeaders (0x03)

`[request-id: P, [startblock: {P, B_32}, limit: P, skip: P, reverse: {0, 1}]]`
Expand Down Expand Up @@ -521,9 +558,25 @@ The `txtypes` element is a byte array containing the announced [transaction type
other two payload elements refer to the sizes and hashes of the announced transactions.
All three payload elements must contain an equal number of items.

`txsizeₙ` refers to the length of the 'consensus encoding' of a typed transaction, i.e.
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.
`txsizeₙ` is the byte length of the announced transaction in the [pooled encoding], on the
protocol version negotiated for this connection. It is the length of:

- the RLP encoding of `legacy-tx`, for legacy transactions;
- `tx-type || tx-data`, for typed transactions whose type defines no wrapped form;
- the whole `wrapped-tx`, for types which do.

The RLP string header which frames a typed transaction as an element of the enclosing
[PooledTransactions] list is not counted.

A peer must announce the size of the transaction it holds. A receiver may recompute
`txsizeₙ` from a transaction it has been served — evaluating it at the protocol version on
which the announcement was made, which need not be the version it was delivered on — and
may disconnect a peer whose announcement disagrees. Announcing a transaction and then
declining to serve it is not a disagreement; see [PooledTransactions].

`txsizeₙ` accounts only for the [PooledTransactions] response. Data fetched separately, in
particular cells fetched via [GetCells] from `eth/72` onwards, is not included; the `cells`
element signals that availability instead.

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 cells at that index in every blob of
Expand All @@ -550,15 +603,10 @@ must not be considered a protocol violation.

### PooledTransactions (0x0a)

`[request-id: P, [tx₁, tx₂...]]`
`[request-id: P, [pooled-tx₁, pooled-tx₂, ...]]`

This is the response to GetPooledTransactions, returning the requested transactions from
the local pool. The items in the list are transactions in the format described in the main
Ethereum specification.

For blob transactions (type 3), the blob data is elided from the response.

<!-- TODO: define encoding in tx section -->
the local pool, in the [pooled encoding].

The transactions must be in same order as in the request, but it is OK to skip
transactions which are not available. This way, if the response size limit is reached,
Expand Down Expand Up @@ -832,6 +880,7 @@ Version numbers below 60 were used during the Ethereum PoC development phase.
[NewPooledTransactionHashes]: #newpooledtransactionhashes-0x08
[GetPooledTransactions]: #getpooledtransactions-0x09
[PooledTransactions]: #pooledtransactions-0x0a
[pooled encoding]: #pooled-encoding
[GetReceipts]: #getreceipts-0x0f
[Receipts]: #receipts-0x10
[BlockRangeUpdate]: #blockrangeupdate-0x11
Expand Down