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

[qu0b]

Problem

The txsize definition is unambiguous for every transaction type except type 3, and type 3 is the only one where the number is large enough to matter.

devp2p/caps/eth.md

Lines 524 to 526 in 2c19a28

	`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.

For legacy, and for typed transactions of types 0x01, 0x02, 0x04, there is exactly one candidate byte string, everyone agrees, and go-ethereum's Transaction.MarshalBinary implements precisely what the sentence says. No change is proposed to that behaviour.

The problem is that for type 3, tx-data is not a single well-defined byte string. EIP-4844 defines a networking wrapper which is also of the form 0x03 || rlp(...), and go-ethereum's own MarshalBinary emits it whenever a sidecar is attached — which, in the pool, it always is:

// core/types/tx_blob.go:342
func (tx *BlobTx) encode(b *bytes.Buffer) error {
	switch {
	case tx.Sidecar == nil:
		return rlp.Encode(b, tx)                          // ~157 B  (bare body)
	case tx.Sidecar.Version == BlobSidecarVersion0:
		return rlp.Encode(b, &blobTxWithBlobsV0{...})      // ~131 KB (4-element wrapper)
	case tx.Sidecar.Version == BlobSidecarVersion1:
		return rlp.Encode(b, &blobTxWithBlobsV1{...})      // ~137 KB (5-element wrapper)
	}
}

So MarshalBinary — the reference implementation of "the consensus encoding" — returns three different answers for one transaction depending on runtime state. The spec sentence does not say which one txsize means, because it was written before there was more than one.

What go-ethereum actually announces is not MarshalBinary at all, but a size carried on the pool metadata (eth/protocols/eth/broadcast.go:140-144), and its own field comments name the quantity:

// core/txpool/subpool.go:89
type TxMetadata struct {
	Type            uint8
	Size            uint64 // The length of the 'rlp encoding' of a transaction (including blobs)
	SizeWithoutBlob uint64 // The length without blob data (for ETH/72 announcements)
}

Size — used on eth/68–eth/71 — is documented as including blobs, which is by definition not the consensus encoding. SizeWithoutBlob — used from eth/72 — is a third quantity again, and is computed arithmetically rather than by serializing anything (core/txpool/blobpool/blobpool.go:202-213).

So for a single-blob transaction there are three defensible readings of the current sentence, and clients have picked all three:

value	what it is	who announces it
157	bare consensus body, Sidecar == nil	Nethermind (reading the sentence literally)
6,487	eth/72 blob-elided wrapper	go-ethereum on eth/72; what it expects from an eth/72 peer
137,567	full v1 network wrapper	go-ethereum on eth/68–eth/71; what it expects from a pre-eth/72 peer

Every one of those is tx-type || tx-data for some meaning of tx-data. That is the ambiguity this PR closes.

The document also contradicts itself 35 lines later: PooledTransactions says blob data is elided from the response, and then declines to define the resulting encoding at all:

devp2p/caps/eth.md

Lines 559 to 561 in 2c19a28

	For blob transactions (type 3), the blob data is elided from the response.
	<!-- TODO: define encoding in tx section -->

This is not hypothetical

On a 7-client devnet over four days, one client implemented :524 literally and announced the consensus size on eth/72. go-ethereum expected the blob-elided size, saw a 6,330-byte discrepancy, and called dropPeer() 55,130 times — 61.5% of all announced-size disconnects on the network. That pairing was reduced to roughly one surviving link per 225 peer slots.

The client is not obviously at fault: it implemented the sentence in this document, and its in-code comment says so.

Changes

• Add a Pooled Encoding section defining the wrapped form. It is written generically ("types which define a wrapped form") rather than for type 0x03 specifically, so that a further blob-carrying type — e.g. EIP-8141, which reuses the EIP-7594 wrapper unchanged — does not invalidate it.
• Describe both the EIP-4844 version-0 and EIP-7594 version-1 wrappers. These are two independent axes that are easy to conflate: the wrapper shape follows the active fork, while blob elision follows the negotiated protocol version. go-ethereum still models both (blobTxWithBlobsV0/V1, discriminated by RLP list arity).
• Redefine txsize as the length of that encoding, stating the stable rule once and the per-type detail separately.
• State explicitly that the RLP string header framing a typed transaction inside the response list is not counted — this matches what implementations compute (Size() adds only +1 for the type byte) and would otherwise be ambiguous.
• Express the announce/serve requirement as a property of the announcer's computation at the announcement's protocol version, mirroring go-ethereum's sizeForVersion, rather than as an equality between two observed byte counts. A raw equality would make legitimate wrapper-upgrade behaviour a protocol violation.
• Fill the TODO: define encoding in tx section.
• Incidental, while in the file: disambiguate the "128 kB" rule now that two encodings are named, and record the EIP-4844 requirement that blob transactions are never broadcast via Transactions (0x02) — a rule that appears nowhere in this document today.

Forward compatibility

The structure deliberately separates a stable, encoding-agnostic invariant from per-version detail. Checked against three live drafts:

• EIP-8094 (sidecars removed from PooledTransactions entirely) — txsize collapses back to the plain consensus size; the invariant needs zero edits.
• EIP-8141 (FRAME_TX_TYPE = 0x06 carrying blobs) — covered by the generic wording.
• SSZ transactions (EIP-6404 et al.) — no SSZ EIP currently defines an announcement size or a pooled representation, so there is nothing to conflict with. Serialized length remains well-defined and cheap to compute, and EIP-7495's rename to ProgressiveContainer removed the "same value, two lengths" hazard.

Under an unambiguous definition, the 8-byte comparison tolerance in go-ethereum — commented "due to the RLP vs consensus format messyness" with TODO(karalabe): Get rid of this relaxation when clients are proven stable — could eventually be removed.

Background

Full write-up of how this was found, including the byte arithmetic and the per-client breakdown: https://panda-uploads-production.devops-539.workers.dev/panda/uploads/a7974b/teardown.html

The markdown linter (.lint/lint.sh caps/eth.md) passes.

---

Related PRs

This is one of four coordinated changes from the same investigation:

#281	the normative fix — txsize definition and the pooled encoding (this is the load-bearing one)
ethereum/EIPs#12275	non-normative signpost in EIP-8070
NethermindEth/nethermind#13049	client fix — announces the consensus size on eth/72 (61.5% of observed disconnects)
besu-eth/besu#11203	client fix — announces the pre-upgrade v0 size while serving v1 on eth/71 (21.2%). Independent of the spec question; inconsistent under any reading
lambdaclass/ethrex#7235	client fix — announces an empty-bundle size when the sidecar is gone (16.7%)
ethereum/go-ethereum#35620	corrects a comment in tx_fetcher.go claiming geth "only warn[s], but doesn't drop" while calling dropPeer — the sentence that makes this behaviour easy to misread

Suggested order: the spec change first, then the client fixes, then the EIP signpost.

Client survey

All seven execution clients on the devnet were checked against the proposed definition. The clarification breaks nobody, and two clients are already exactly conformant:

client	behaviour	verdict
erigon	announces len(txBytes) where txBytes is the same buffer it later serves	✅ conformant by construction — effectively the reference implementation of this wording
nimbus-eth1	encodes exactly what it will serve	✅ conformant by construction
go-ethereum	self-consistent; its Size() is a shortcut that coincides with the true length at blob scale	✅ conformant
reth	announces the un-elided size on eth/72	❌ — already being fixed in paradigmxyz/reth#26574
nethermind, besu, ethrex	see the table above	❌ — PRs linked

Two points that the wording above tries to make unambiguous, because they are exactly where implementations diverged:

1. The quantity is the true length of the pooled encoding, not any particular client's helper. go-ethereum's Size() computes 1 + P + S + hdr(S) where the true length is 1 + P + S + hdr(P+S); these agree only because both headers are 4 bytes at realistic blob counts. erigon's and nimbus-eth1's are structural identities and are the better model.
2. Under eth/72 the elided length still includes the wrapper-version element and the empty blobs list (0xc0). "Serialize with empty blobs" and "full size minus blob bytes" then give the same answer — which is worth stating rather than leaving implementers to rediscover.

[healthykim]

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]

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]

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]

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.

[healthykim]

It might be a good idea to use the encoding we defined here.

Suggested change

	Responses to [GetPooledTransactions] serve blob transactions in their [Pooled encoding],
	with the blob data elided. The blob data itself can be obtained only by [GetCells]. Upon
	receiving the [NewPooledTransactionHashes] message with new blob transaction hashes, the
	node begins fetching their cells. For each transaction, it first makes a probabilistic
	decision between two strategies.