BIP153: SENDTEMPLATE

ajtowns commented at 1:32 am on August 18, 2025: contributor

Adds a BIP for SENDTEMPLATE, GETTEMPLATE, TEMPLATE p2p messages. Discussion links:

https://delvingbitcoin.org/t/sharing-block-templates/1906

https://gnusha.org/pi/bitcoindev/aJvZwR_bPeT4LaH6@erisian.com.au/T/#u

jonatack added the label New BIP on Aug 18, 2025

jonatack commented at 4:45 pm on August 18, 2025: member

Post to bitcoindev group hasn’t made it through

fixed, published

in bip-ajtowns-sendtemplate.md:16 in a89b303492 outdated

11+  License: BSD-3-Clause
12+```
13+
14+## Abstract
15+
16+This BIP describes the use of [BIP-152 compact blocks][BIP-152] enccoding

murchandamus commented at 10:32 pm on August 18, 2025:

0This BIP describes the use of [BIP-152 compact blocks][BIP-152] encoding

in bip-ajtowns-sendtemplate.md:74 in a89b303492 outdated

69+and should be the hash of a block made up of those transactions.
70+4. The transactions making up the payload of the template should be valid
71+as a block -- for example all unconfirmed parents of a transaction should be
72+included before the transaction, and consensus limits should be respected.
73+5. A block containing the transactions making up the payload must not
74+exceed four million weight units as defined in [BIP-141][BIP-141].

murchandamus commented at 10:48 pm on August 18, 2025:

Have you considered allowing more data than just the top block? Otherwise, would you recommend that a node requests a template after each block is found for the first few new blocks after they come online? Have you considered a reconciliation-based approach akin to Erlay?

ajtowns commented at 6:04 am on August 20, 2025:

See discussion in the delving thread.

I think having two blocks of txs could make sense, but in adversarial situations it doubles the potential memory usage and it’s not immediately clear what would be a sensible way of addressing that.

My thought is that deploying a simple design and getting some real-world data to iterate on makes sense. You could update the specification to announce “SENDTEMPLATE 2” indicating you support v2, which indicates to your peers they can send you a “GETTEMPLATE 2” message requesting a 2MvB template rather than a 1MvB template, eg.

Likewise sending set differences through could make sense (and wouldn’t need the complexity of minisketch since the sender knows their own previous templates), but there’s still a lot of design space left, so getting real-world data also seems useful for resolving that. (Likewise an updated spec could allow SENDTEMPLATE 2D to indicate deltas are supported, and GETTEMPLATE 2 $hash could request a 2MvB template encoded as a delta against the previous template with hash $hash)

ajtowns commented at 5:03 am on August 21, 2025:

Changed the limit from 4M weight units to 8M weight units.

murchandamus commented at 10:54 pm on August 18, 2025: contributor

Interesting idea, thanks for sharing.

ajtowns force-pushed on Aug 20, 2025

ajtowns force-pushed on Aug 21, 2025

murchandamus commented at 7:11 pm on August 26, 2025: contributor

From an editorial perspective, this looks close to ready. I noticed that there is no Rationale section, yet. You could perhaps link to the Delving discussion as that seems to have been the most active one I saw.

ajtowns commented at 4:25 am on August 27, 2025: contributor

Updated with post-history in metadata and some rationale

murchandamus commented at 9:34 pm on August 27, 2025: contributor

Thanks, good improvements.

ajtowns commented at 8:40 am on September 1, 2025: contributor

Time to request a bip number then I guess?

murchandamus commented at 8:53 pm on September 4, 2025: contributor

Let’s call this BIP 153 then!

murchandamus renamed this:
~~BIP Draft SENDTEMPLATE~~
BIP 153 SENDTEMPLATE
on Sep 4, 2025

murchandamus renamed this:
~~BIP 153 SENDTEMPLATE~~
BIP153: SENDTEMPLATE
on Sep 4, 2025

in bip-ajtowns-sendtemplate.md:53 in 6fbdd71cd4 outdated

47+3. If a node implements this BIP, it must send the `sendtemplate`
48+message after `version` and before `verack`.
49+
50+### `gettemplate`
51+
52+1. The `gettemplate` message is defined as a message with `pchCommand ==

Roasbeef commented at 10:05 pm on September 4, 2025:

Any reason to not also allocate a message ID from the range specific in BIP 324?

The guidelines specify that if a message is sent more than once per connection then a number you be allocated (IIUC both this and the template message):

We recommend reserving 1-byte type IDs for message types that are sent more than once per direction per connection.

ajtowns commented at 10:59 pm on September 16, 2025:

(I have in my backlog an idea for having these ids get determined dynamically during initial connection negotiation, which avoids the problem of BIPs attempting to assign the same id to different messages)

in bip-ajtowns-sendtemplate.md:64 in 6fbdd71cd4 outdated

58+3. A `gettemplate` message must not be sent if a `sendtemplate` message
59+was not already received.
60+4. Upon receipt of a `gettemplate` message, a node may reply with a
61+`template` message.
62+
63+### `template`

Roasbeef commented at 10:06 pm on September 4, 2025:

blocktemplate instead? Otherwise, at a glance the semantics of the message are ambiguous.

ajtowns commented at 2:34 am on September 5, 2025:

Message type can only be 12 characters, blocktemplate has 13. I don’t think there’s anything very ambiguous about template in bitcoin even without block, however.

in bip-ajtowns-sendtemplate.md:36 in 6fbdd71cd4 outdated

30+and (b) provides a way for transactions that may have dropped out of
31+nodes' mempools to be rebroadcast across the network by third parties,
32+potentially providing better privacy than if only the nodes directly
33+involved in the transaction would rebroadcast it.
34+
35+## Specification

Roasbeef commented at 10:09 pm on September 4, 2025:

I notice there’s no p2p protocol version bump, why is that?. IIUC, this message is only useful if you’re talking with a peer that’s directly peered, or is the Bitcoin node backing a mining pool. A p2p version bump would permit nodes to seek out other nodes that meet this requirement, instead of blindly connecting out to find such nodes.

ajtowns commented at 2:38 am on September 5, 2025:

If you want to seek out peers that support a feature you need a service flag, not a protocol version. Using a pre-verack negotiation message gives you all the benefits of a protocol version bump, with less potential for contention where two bips developed at the same time both bump the protocol version to the same value.

Roasbeef commented at 1:38 am on September 6, 2025:

Ah yeah I meant service flag 😅.

The service flag would also allow for peers to find other supporting peers via DNS queries.

ajtowns commented at 10:57 pm on September 16, 2025:

I’m hopeful that it will eventually be widely supported enough not to need people to seek out supporting clients explicitly – it should be pretty low overhead to just provide templates. Also, I think you’d want something more subtle than just “does the node support this protocol” when working out who to peer with – you want templates that are about equally as diverse as miners: getting the same template from multiple peers isn’t very helpful, and getting templates that don’t match any miners also isn’t helpful. So I think it makes more sense to get some experience with the behaviour of things before speccing out best practices or new features for peer discovery.

ajtowns force-pushed on Sep 8, 2025

murchandamus commented at 9:03 pm on September 16, 2025: contributor

@ajtowns: What’s your status on this one? Are you still planning changes or waiting for some people to finish their review of this PR?

ajtowns commented at 10:54 pm on September 16, 2025: contributor

I think this is fine to merge as draft, further review/changes can happen in that state as I understand it.

in bip-0153.md:20 in 86d20db638 outdated

14+```
15+
16+## Abstract
17+
18+This BIP describes the use of [BIP-152 compact blocks][BIP-152] encoding
19+for sharing block templates (ie, the next block's predicted transactions)

jonatack commented at 9:43 pm on September 17, 2025:

0for sharing block templates (i.e., the next block's predicted transactions)

ajtowns commented at 2:06 am on September 18, 2025:

“ie” is used in bips 8, 18, 21, 22, 78, 99, 115, 118, 152, 171, 301, and 325. see also https://english.stackexchange.com/questions/407270/is-ie-acceptable-or-must-it-always-be-i-e#407287

in bip-0153.md:83 in 86d20db638 outdated

78+[BIP-141][BIP-141]. Note that this is twice the block weight limit, and
79+does not include the overhead that assembling those transactions into
80+a block would involve (header, coinbase and tx count serialization),
81+so this can be slightly more than two blocks' worth of transactions.
82+6. After sending a `template` message, a node should accept a
83+`sendblocktxns` message that specify the template's `header` hash, and

jonatack commented at 11:06 pm on September 17, 2025:

0`sendblocktxns` message that specifies the template's `header` hash, and

in bip-0153.md:89 in 86d20db638 outdated

83+`sendblocktxns` message that specify the template's `header` hash, and
84+respond with a `blocktxns` message including the appropriate transaction
85+data, exactly as if it had sent a `cmpctblock` message with the same
86+payload as the `template` message. It should be able to provide such
87+transactions for a moderate amount of time after sending a template
88+(eg, five minutes). If it cannot provide a correct `blocktxns` response,

jonatack commented at 11:08 pm on September 17, 2025:

0(e.g., five minutes). If it cannot provide a correct `blocktxns` response,

ajtowns commented at 2:14 am on September 18, 2025:

Ditto for ie

in bip-0153.md:73 in 86d20db638 outdated

68+2. A `template` message may only be sent in response to a `gettemplate`
69+message.
70+3. The `header` hash included in the payload must be a unique hash,
71+and should be the hash of a block made up of those transactions.
72+4. The transactions making up the payload of the template should be
73+valid for block inclusion -- for example all unconfirmed parents of a

jonatack commented at 11:09 pm on September 17, 2025:

0valid for block inclusion -- for example, all unconfirmed parents of a

in bip-0153.md:13 in 86d20db638 outdated

 8+  Status: Draft
 9+  Type: Standards Track
10+  Created: 2025-09-05
11+  License: BSD-3-Clause
12+  Post-History: https://gnusha.org/pi/bitcoindev/aJvZwR_bPeT4LaH6@erisian.com.au/T/#u
13+                https://delvingbitcoin.org/t/sharing-block-templates/1906

jonatack commented at 11:40 pm on September 17, 2025:

Missing header: Requires: 141, 152

jonatack commented at 11:57 pm on September 17, 2025: member

I may have overlooked it, but at first glance it looks like the draft is missing important specification on how to implement the goals set forth in the Motivation section. For instance, which peers to request templates from, when/how often, and how the template data is to be used. (Perhaps also limits on memory use for storing templates and/or how this interacts with the -maxmempool limits.) Do you intend to add these to the Specification or Recommendations section, or for a separate BIP?

A few non-blocking comments follow.

in bip-0153.md:130 in 86d20db638 outdated

124+  * adding a payload to the `gettemplate` message so that peers can
125+    indicate they will accept a new encoding of the template
126+  * adding a payload to the `sendtemplate` message to indicate that the
127+    `gettemplate` payload will be accepted
128+
129+## Recommendations

Roasbeef commented at 0:20 am on September 18, 2025:

Perhaps this could use some recommendations re privacy implications?

IIRC, there was some push back augments devs re BIP 35 (mempool message), as it can be used to implement relay correlation and tagging attacks against peers. As the message enables a peer to obtain the entire mempool of another peer, it can feasibly be used by an adversary to figure out: who relayed what, which transactions may have originated directly from the node, etc.

Some related PRs from the bitcoind repo:

https://github.com/bitcoin/bitcoin/pull/27426 – an attempt to remove the command all together, but was later abandoned.
https://github.com/bitcoin/bitcoin/pull/7840 – restrcited the type of peers that bitcoind will respond to w/ responses to the mempool message (white list applied), the start of some of the inv trickle/batch re address privacy concerns

Also pool operators may want to filter out transactions that they received via out of band transaction submission.

murchandamus commented at 10:58 pm on September 29, 2025:

As the message enables a peer to obtain the entire mempool of another peer, it can feasibly be used by an adversary to figure out: who relayed what, which transactions may have originated directly from the node, etc.

Are you here talking about the mempool message or this proposal? It seems to me that the top two blocks of the mempool would be significantly more difficult/expensive to exploit for fingerprinting than the whole mempool, especially if nodes repeatedly use this new peer service to synchronize their top mempool as any new transactions that are received this way would be broadcast to peers.

ajtowns force-pushed on Sep 18, 2025

ajtowns commented at 3:10 am on September 18, 2025: contributor

I may have overlooked it, but at first glance it looks like the draft is missing important specification on how to implement the goals set forth in the Motivation section. For instance, which peers to request templates from, when/how often, and how the template data is to be used.

I see those as implementation quality issues, which would be added in the “recommendations” section, once it’s more clear what those recommendations should be.

luke-jr commented at 10:13 pm on September 18, 2025: member

I don’t see how this doesn’t have major privacy leaks, similar to the mempool message

ajtowns commented at 3:10 pm on September 26, 2025: contributor

Could the editors please clarify which of these concerns are blockers for merging this BIP in “Draft” status?

murchandamus commented at 11:05 pm on September 29, 2025: contributor

Could the editors please clarify which of these concerns are blockers for merging this BIP in “Draft” status?

I don’t perceive the stated concerns as blockers, but agree that this document should be enhanced in the future with further discussion of privacy implications. I’m gonna wait for a few days to allow time for others to comment.

ajtowns commented at 3:06 am on September 30, 2025: contributor

that this document should be enhanced in the future with further discussion of privacy implications.

That’s what the “TBA” in the otherwise empty recommendations section is for (as well as efficiency implications and potentially other things)

ajtowns commented at 2:47 am on October 2, 2025: contributor

Could the editors please clarify which of these concerns are blockers for merging this BIP in “Draft” status?

I’ve been told some editors are privately blocking merge of this PR despite being unwilling to identify any issues as blockers publicly. I don’t think that’s appropriate, or in accordance with the BIP 2 process, so I’m instead requesting this PR be merged now as-is, publishing the BIP as a draft so it can be easily referenced for further discussion and exploration.

murchandamus commented at 3:30 am on October 2, 2025: contributor

My understanding is that some fingerprinting concerns and privacy concerns have been raised here and in the Bitcoin Core pull request where this feature is being explored. According to the BIP Process, raised concerns should be addressed in the document. I expect that in the context of the feature being proposed, the frequency at which and the context in which it is used is seen as relevant information to weigh in on the utility, viability, and privacy impact. Therefore it would be helpful for readers and reviewers, if there were at least an initial sketch how often and when it would be used.

BIP153: add template sharing bip 58ebdbf3d1

ajtowns force-pushed on Oct 2, 2025

ajtowns commented at 6:17 am on October 9, 2025: contributor

This is now published as BIN25-2 so I’ll be using that repo to refine the document while it’s in draft.

BIP153: SENDTEMPLATE #1937