From 256b3305eea556233b88ddfd226731a7aa766e7b Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Tue, 6 Oct 2026 16:45:26 -0400
Subject: [PATCH 01/19] sv2: define the job-validation messages and setup flag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire layer for the TDP job-validation extension
(docs/sv2-job-validation-draft.md §3-5): the four ValidateCustomJob
messages (0x77-0x7a) as binary_sv2 structs, and SetupConnection flag
bit 0 (REQUIRES_JOB_VALIDATION). Setup now accepts that bit and echoes
it in SetupConnection.Success; any other set bit is still rejected with
unsupported-feature-flags.

The messages are `pub` because the rbitcoin-test journey decodes TDP
frames cross-crate (as it does the SRI types today) and they have no
in-crate reader yet; the dispatch handlers follow in the next step.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/lib.rs            |   1 +
 crates/rbitcoin-sv2/src/listener_tests.rs |  28 +++--
 crates/rbitcoin-sv2/src/messages.rs       | 118 ++++++++++++++++++++++
 crates/rbitcoin-sv2/src/session.rs        |   8 +-
 4 files changed, 144 insertions(+), 11 deletions(-)
 create mode 100644 crates/rbitcoin-sv2/src/messages.rs

diff --git a/crates/rbitcoin-sv2/src/lib.rs b/crates/rbitcoin-sv2/src/lib.rs
index 6197509c3..8589b9ec1 100644
--- a/crates/rbitcoin-sv2/src/lib.rs
+++ b/crates/rbitcoin-sv2/src/lib.rs
@@ -3,6 +3,7 @@
 //! Noise_NX over TCP is the only transport. Plan and constraints:
 //! `docs/sv2-template-provider.md`.
 
+pub mod messages;
 mod session;
 mod template;
 pub mod testutil;
diff --git a/crates/rbitcoin-sv2/src/listener_tests.rs b/crates/rbitcoin-sv2/src/listener_tests.rs
index d524700a1..27537a280 100644
--- a/crates/rbitcoin-sv2/src/listener_tests.rs
+++ b/crates/rbitcoin-sv2/src/listener_tests.rs
@@ -1,3 +1,4 @@
+use crate::messages::REQUIRES_JOB_VALIDATION;
 use crate::test_chain::shared_regtest;
 use crate::testutil::TpClient;
 use crate::{
@@ -40,6 +41,12 @@ async fn expect_error(c: &mut TpClient, flags: u32, code: &str) {
     );
 }
 
+async fn expect_success(c: &mut TpClient) -> SetupConnectionSuccess {
+    let mut f = c.recv().await.expect("setup reply");
+    assert_eq!(f.msg_type, MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS);
+    binary_sv2::from_bytes(&mut f.payload).expect("decode")
+}
+
 #[tokio::test]
 async fn setup_connection_success_errors_and_session_cap() {
     let tc = shared_regtest(0);
@@ -63,9 +70,7 @@ async fn setup_connection_success_errors_and_session_cap() {
     for _ in 0..MAX_SESSIONS {
         let mut c = TpClient::connect(addr, pk).await.expect("handshake");
         c.setup_connection(TDP, 2, 2, 0).await.unwrap();
-        let mut f = c.recv().await.expect("setup reply");
-        assert_eq!(f.msg_type, MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS);
-        let ok: SetupConnectionSuccess = binary_sv2::from_bytes(&mut f.payload).expect("decode");
+        let ok = expect_success(&mut c).await;
         assert_eq!((ok.used_version, ok.flags), (2, 0));
         live.push(c);
     }
@@ -84,6 +89,16 @@ async fn setup_connection_success_errors_and_session_cap() {
     }
     drop(live);
 
+    let mut c = connect_when_free(addr, pk).await;
+    c.setup_connection(TDP, 2, 2, REQUIRES_JOB_VALIDATION)
+        .await
+        .unwrap();
+    assert_eq!(
+        expect_success(&mut c).await.flags,
+        REQUIRES_JOB_VALIDATION,
+        "REQUIRES_JOB_VALIDATION is accepted and echoed"
+    );
+
     let mut c = connect_when_free(addr, pk).await;
     c.setup_connection(TDP, 2, 2, 0b101).await.unwrap();
     expect_error(&mut c, 0b101, "unsupported-feature-flags").await;
@@ -129,9 +144,7 @@ async fn authority_key_prints_in_key_utils_base58check() {
         .await
         .expect("handshake against the printed key");
     c.setup_connection(TDP, 2, 2, 0).await.unwrap();
-    let mut f = c.recv().await.expect("setup reply");
-    assert_eq!(f.msg_type, MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS);
-    let _: SetupConnectionSuccess = binary_sv2::from_bytes(&mut f.payload).expect("decode");
+    expect_success(&mut c).await;
     tp.shutdown().await;
 }
 
@@ -174,8 +187,7 @@ async fn silent_sockets_are_dropped_at_the_setup_deadline() {
 
     let mut c = connect_when_free(addr, pk).await;
     c.setup_connection(TDP, 2, 2, 0).await.unwrap();
-    let f = c.recv().await.expect("setup reply");
-    assert_eq!(f.msg_type, MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS);
+    expect_success(&mut c).await;
     tp.shutdown().await;
 }
 
diff --git a/crates/rbitcoin-sv2/src/messages.rs b/crates/rbitcoin-sv2/src/messages.rs
new file mode 100644
index 000000000..cdeaabd0f
--- /dev/null
+++ b/crates/rbitcoin-sv2/src/messages.rs
@@ -0,0 +1,118 @@
+//! Job-validation extension to TDP (`docs/sv2-job-validation-draft.md` §3–5):
+//! the `SetupConnection` flag and the four `ValidateCustomJob` messages a
+//! Job Declarator Server uses to have this TP check a custom job.
+
+use binary_sv2::{Deserialize, Seq064K, Serialize, Str0255, B016M, B064K, U256};
+
+/// `SetupConnection.flags` bit 0: the client intends to send
+/// [`ValidateCustomJob`]. The only TDP flag this TP accepts.
+pub const REQUIRES_JOB_VALIDATION: u32 = 1 << 0;
+
+pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB: u8 = 0x77;
+pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS: u8 = 0x78;
+pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS: u8 = 0x79;
+pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR: u8 = 0x7a;
+
+/// Client → TP: is this custom job a consensus-valid block on the TP tip?
+/// `transaction_list` carries the txs a prior
+/// [`ValidateCustomJobMissingTransactions`] asked for, in that order.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+pub struct ValidateCustomJob<'decoder> {
+    pub request_id: u32,
+    pub prev_hash: U256<'decoder>,
+    pub version: u32,
+    pub coinbase_tx: B064K<'decoder>,
+    pub wtxid_list: Seq064K<'decoder, U256<'decoder>>,
+    pub transaction_list: Seq064K<'decoder, B016M<'decoder>>,
+}
+
+/// TP → client: 0-indexed positions in `wtxid_list` the TP cannot resolve.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+pub struct ValidateCustomJobMissingTransactions<'decoder> {
+    pub request_id: u32,
+    pub unknown_tx_position_list: Seq064K<'decoder, u16>,
+}
+
+/// TP → client: the job is valid and retained under `template_id`, which
+/// shares the `NewTemplate.template_id` namespace.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+pub struct ValidateCustomJobSuccess {
+    pub request_id: u32,
+    pub template_id: u64,
+    pub fees: u64,
+}
+
+/// TP → client: the job was not validated.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+pub struct ValidateCustomJobError<'decoder> {
+    pub request_id: u32,
+    pub error_code: Str0255<'decoder>,
+    pub error_details: B064K<'decoder>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use binary_sv2::{Seq064K, Str0255, B016M, B064K, U256};
+    use std::fmt::Debug;
+
+    /// Encode with the codec `NoiseWriter::send` frames and decode with the
+    /// one `Session::on_frame` uses.
+    fn round_trip<'a, T>(msg: T, bytes: &'a mut Vec<u8>)
+    where
+        T: Clone
+            + PartialEq
+            + Debug
+            + binary_sv2::Serialize
+            + binary_sv2::GetSize
+            + binary_sv2::Deserialize<'a>,
+    {
+        *bytes = binary_sv2::to_bytes(msg.clone()).expect("encode");
+        let back: T = binary_sv2::from_bytes(bytes).expect("decode");
+        assert_eq!(back, msg);
+    }
+
+    #[test]
+    fn job_validation_messages_round_trip() {
+        let (h1, h2, h3) = ([1u8; 32], [2u8; 32], [3u8; 32]);
+        let (coinbase, tx, details) = ([0xc0u8; 100], [0xeeu8; 300], [1u8, 2, 3]);
+        let mut bytes = Vec::new();
+        round_trip(
+            ValidateCustomJob {
+                request_id: 7,
+                prev_hash: U256::from(&h1),
+                version: 0x2000_0000,
+                coinbase_tx: B064K::try_from(&coinbase[..]).unwrap(),
+                wtxid_list: Seq064K::new(vec![U256::from(&h2), U256::from(&h3)]).unwrap(),
+                transaction_list: Seq064K::new(vec![B016M::try_from(&tx[..]).unwrap()]).unwrap(),
+            },
+            &mut bytes,
+        );
+        let mut bytes = Vec::new();
+        round_trip(
+            ValidateCustomJobMissingTransactions {
+                request_id: 7,
+                unknown_tx_position_list: Seq064K::new(vec![0u16, 5, u16::MAX]).unwrap(),
+            },
+            &mut bytes,
+        );
+        let mut bytes = Vec::new();
+        round_trip(
+            ValidateCustomJobSuccess {
+                request_id: 7,
+                template_id: u64::MAX,
+                fees: 12_345,
+            },
+            &mut bytes,
+        );
+        let mut bytes = Vec::new();
+        round_trip(
+            ValidateCustomJobError {
+                request_id: 7,
+                error_code: Str0255::try_from("stale-prevhash").unwrap(),
+                error_details: B064K::try_from(&details[..]).unwrap(),
+            },
+            &mut bytes,
+        );
+    }
+}
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index c9c00c236..b7ab2f2d1 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -1,5 +1,6 @@
 //! One TDP session: Noise handshake, `SetupConnection`, then TDP messages.
 
+use crate::messages::REQUIRES_JOB_VALIDATION;
 use crate::template;
 use crate::transport::{Frame, NoiseConn, NoiseWriter};
 use crate::Sv2TpStats;
@@ -527,8 +528,9 @@ fn setup_error(m: &SetupConnection) -> Option<(u32, &'static str)> {
     if !(m.min_version..=m.max_version).contains(&TDP_VERSION) {
         return Some((0, ERROR_CODE_SETUP_CONNECTION_PROTOCOL_VERSION_MISMATCH));
     }
-    // TDP defines no SetupConnection flags: every set bit is unsupported.
-    if m.flags != 0 {
+    // sv2-job-validation-draft §3 defines bit 0; every other set bit is
+    // unsupported.
+    if m.flags & !REQUIRES_JOB_VALIDATION != 0 {
         return Some((
             m.flags,
             ERROR_CODE_SETUP_CONNECTION_UNSUPPORTED_FEATURE_FLAGS,
@@ -557,7 +559,7 @@ async fn on_setup(conn: &mut NoiseConn, mut frame: Frame) -> io::Result<bool> {
     }
     let reply = SetupConnectionSuccess {
         used_version: TDP_VERSION,
-        flags: 0,
+        flags: setup.flags,
     };
     conn.send(MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS, reply)
         .await?;

From 2ccd4c474136afb7b4ae17806625cdc08a33d493 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Tue, 6 Oct 2026 16:52:33 -0400
Subject: [PATCH 02/19] sv2: size the client frame cap per message type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ValidateCustomJob (docs/sv2-job-validation-draft.md §4.1) carries a full
wtxid list and the missing transactions, so it cannot fit the 64 KiB cap
sized for SubmitSolution. The reader now bounds every client frame at the
ValidateCustomJob maximum while reading (40 fixed bytes, a B064K coinbase,
65535 wtxids, and a block's worth of B016M txs: 6_359_306 bytes), then
applies the per-type cap once the frame is whole, so every other client
message still closes the session past 65557 bytes.

codec_sv2 7.0.0 decrypts the header into a private buffer and never
exposes it mid-frame, so the type is only known with the whole frame.
Seeing it earlier would mean replacing NoiseDecoder's transport path with
our own chunked decrypt loop; the per-session RAM bound is the same
either way, since a client can always pick 0x77. Named RAM trade: one
in-flight client frame of ≤ ~6.4 MB per session, ≤ ~51 MB at MAX_SESSIONS.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/listener_tests.rs | 54 ++++++++++----
 crates/rbitcoin-sv2/src/transport.rs      | 87 +++++++++++++++++++----
 2 files changed, 115 insertions(+), 26 deletions(-)

diff --git a/crates/rbitcoin-sv2/src/listener_tests.rs b/crates/rbitcoin-sv2/src/listener_tests.rs
index 27537a280..c1a40eeb2 100644
--- a/crates/rbitcoin-sv2/src/listener_tests.rs
+++ b/crates/rbitcoin-sv2/src/listener_tests.rs
@@ -1,6 +1,7 @@
-use crate::messages::REQUIRES_JOB_VALIDATION;
+use crate::messages::{MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, REQUIRES_JOB_VALIDATION};
 use crate::test_chain::shared_regtest;
 use crate::testutil::TpClient;
+use crate::transport::MAX_VALIDATE_CUSTOM_JOB_PAYLOAD;
 use crate::{
     run_sv2_tp, Sv2TpConfig, FEE_DELTA, MAX_SESSIONS, MAX_STALE_GRACE, MAX_TEMPLATE_INTERVAL,
     MIN_TEMPLATE_INTERVAL, SETUP_TIMEOUT, TEMPLATE_INTERVAL, WRITE_TIMEOUT,
@@ -13,7 +14,9 @@ use std::io;
 use std::net::SocketAddr;
 use std::sync::Arc;
 use std::time::{Duration, Instant};
-use template_distribution_sv2::MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR;
+use template_distribution_sv2::{
+    MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR, MESSAGE_TYPE_SUBMIT_SOLUTION,
+};
 
 const TDP: u8 = 2;
 
@@ -34,10 +37,15 @@ async fn expect_error(c: &mut TpClient, flags: u32, code: &str) {
     let e: SetupConnectionError = binary_sv2::from_bytes(&mut f.payload).expect("decode");
     assert_eq!(e.flags, flags);
     assert_eq!(e.error_code.as_utf8_or_hex(), code);
+    assert_closed(c, "SetupConnection.Error").await;
+}
+
+async fn assert_closed(c: &mut TpClient, what: &str) {
     let closed = tokio::time::timeout(Duration::from_secs(5), c.recv()).await;
     assert!(
         matches!(closed, Ok(Err(_))),
-        "connection must close after SetupConnection.Error"
+        "{what} must close the session, got {:?}",
+        closed.map(|r| r.map(|f| f.msg_type))
     );
 }
 
@@ -313,8 +321,9 @@ async fn client_that_stops_reading_is_dropped_at_the_write_deadline() {
     tp.shutdown().await;
 }
 
-/// The largest legitimate client frame (a `SubmitSolution` with a full
-/// `B064K` coinbase) keeps the session; a larger frame closes it.
+/// Each client message type has its own payload cap: the largest legitimate
+/// `SubmitSolution` and a `ValidateCustomJob` well past it keep the session;
+/// a frame over the cap for its type closes it.
 #[tokio::test]
 async fn oversized_client_frame_closes_the_session() {
     let tc = shared_regtest(0);
@@ -347,14 +356,35 @@ async fn oversized_client_frame_closes_the_session() {
         .expect("open after a max-size SubmitSolution");
     assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
 
-    let _ = c.send_bytes(0xff, &vec![0u8; 1 << 20]).await;
+    // No handler yet: a ValidateCustomJob under its own cap is read and ignored.
+    let big = vec![0u8; 200 << 10];
+    c.send_bytes(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, &big)
+        .await
+        .unwrap();
+    c.request_transaction_data(1).await.unwrap();
+    let f = c
+        .recv()
+        .await
+        .expect("open after a 200 KiB ValidateCustomJob");
+    assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
+
+    let _ = c.send_bytes(MESSAGE_TYPE_SUBMIT_SOLUTION, &big).await;
     c.request_transaction_data(1).await.ok();
-    let closed = tokio::time::timeout(Duration::from_secs(5), c.recv()).await;
-    assert!(
-        matches!(closed, Ok(Err(_))),
-        "an oversized frame must close the session, got {:?}",
-        closed.map(|r| r.map(|f| f.msg_type))
-    );
+    assert_closed(&mut c, "a 200 KiB SubmitSolution").await;
+
+    let mut c = TpClient::connect(tp.local_addr, tp.authority_pubkey)
+        .await
+        .expect("handshake");
+    c.setup_connection(TDP, 2, 2, 0).await.unwrap();
+    c.recv().await.expect("setup reply");
+    let _ = c
+        .send_bytes(
+            MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
+            &vec![0u8; MAX_VALIDATE_CUSTOM_JOB_PAYLOAD + 1],
+        )
+        .await;
+    c.request_transaction_data(1).await.ok();
+    assert_closed(&mut c, "a ValidateCustomJob over its cap").await;
     tp.shutdown().await;
 }
 
diff --git a/crates/rbitcoin-sv2/src/transport.rs b/crates/rbitcoin-sv2/src/transport.rs
index 393142722..6b7b62725 100644
--- a/crates/rbitcoin-sv2/src/transport.rs
+++ b/crates/rbitcoin-sv2/src/transport.rs
@@ -1,11 +1,13 @@
 //! Noise_NX transport over one TCP stream: handshake, then encrypted SV2 frames.
 
+use crate::messages::MESSAGE_TYPE_VALIDATE_CUSTOM_JOB;
 use binary_sv2::{GetSize, Serialize};
 use codec_sv2::{
     Decoded, Decrypted, Handshake, MessageFrame, NoiseDecoder, NoiseEncoder, TransportDecryptState,
     TransportEncryptState, ENCRYPTED_SV2_FRAME_HEADER_SIZE, SV2_FRAME_PLAINTEXT_CHUNK_SIZE,
 };
 use noise_sv2::{Initiator, Responder, AEAD_MAC_LEN};
+use rbitcoin_consensus::MAX_BLOCK_WEIGHT;
 use std::io;
 use std::time::Duration;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
@@ -18,11 +20,32 @@ pub struct Frame {
     pub payload: Vec<u8>,
 }
 
-/// Largest client→TP payload. The largest TDP client message is
-/// `SubmitSolution`: 20 fixed bytes plus a `B064K` coinbase (2-byte length,
+/// Largest client→TP payload for every message but `ValidateCustomJob`:
+/// `SubmitSolution`, 20 fixed bytes plus a `B064K` coinbase (2-byte length,
 /// ≤ 65535 bytes). The 24-bit frame length would otherwise let a client
 /// make the session buffer ~16 MB per frame.
-pub(crate) const MAX_CLIENT_PAYLOAD: usize = 20 + 2 + u16::MAX as usize;
+const MAX_CLIENT_PAYLOAD: usize = 20 + 2 + u16::MAX as usize;
+
+/// Largest `ValidateCustomJob` payload: 40 fixed bytes, a `B064K` coinbase,
+/// a full `SEQ0_64K[U256]` wtxid list, and a `SEQ0_64K[B016M]` transaction
+/// list whose txs together fit a block (weight is never below serialized
+/// size) with a 3-byte length each.
+///
+/// RAM trade (CONTRIBUTING 9): a session buffers one in-flight client frame
+/// of at most this size (~6.4 MB), so at `MAX_SESSIONS` client frames hold
+/// ≤ ~51 MB on top of template retention (lib.rs).
+pub(crate) const MAX_VALIDATE_CUSTOM_JOB_PAYLOAD: usize = {
+    const SEQ: usize = u16::MAX as usize;
+    4 + 32 + 4 + (2 + SEQ) + (2 + SEQ * 32) + (2 + SEQ * 3 + MAX_BLOCK_WEIGHT as usize)
+};
+
+/// Payload cap by client message type.
+const fn client_payload_cap(msg_type: u8) -> usize {
+    match msg_type {
+        MESSAGE_TYPE_VALIDATE_CUSTOM_JOB => MAX_VALIDATE_CUSTOM_JOB_PAYLOAD,
+        _ => MAX_CLIENT_PAYLOAD,
+    }
+}
 
 /// Encrypted bytes on the wire for a frame carrying `payload` bytes.
 const fn encrypted_frame_len(payload: usize) -> usize {
@@ -31,6 +54,33 @@ const fn encrypted_frame_len(payload: usize) -> usize {
         + payload.div_ceil(SV2_FRAME_PLAINTEXT_CHUNK_SIZE) * AEAD_MAC_LEN
 }
 
+fn no_cap(_: u8) -> usize {
+    usize::MAX
+}
+
+/// Size bounds on the frames one direction carries.
+#[derive(Clone, Copy)]
+struct FrameCap {
+    /// Encrypted bytes one frame may take, counted while it is read.
+    max_frame: usize,
+    /// Payload cap by message type, applied once the frame is whole.
+    payload: fn(u8) -> usize,
+}
+
+impl FrameCap {
+    /// Client→TP: the largest client message while reading, then
+    /// [`client_payload_cap`] for the type.
+    const CLIENT: Self = Self {
+        max_frame: encrypted_frame_len(MAX_VALIDATE_CUSTOM_JOB_PAYLOAD),
+        payload: client_payload_cap,
+    };
+    /// TP→client: the 24-bit frame length only.
+    const UNBOUNDED: Self = Self {
+        max_frame: usize::MAX,
+        payload: no_cap,
+    };
+}
+
 pub(crate) struct NoiseConn {
     reader: NoiseReader,
     writer: NoiseWriter,
@@ -44,8 +94,7 @@ pub(crate) struct NoiseReader {
     // `next_transport_frame` consumes the state; a failed round leaves `None`
     // and the connection must close (codec_sv2 nonce rule).
     rx: Option<TransportDecryptState>,
-    /// Encrypted bytes one frame may take; see [`MAX_CLIENT_PAYLOAD`].
-    max_frame: usize,
+    cap: FrameCap,
     /// Encrypted bytes read so far for the frame being decoded.
     frame_read: usize,
 }
@@ -90,7 +139,6 @@ impl NoiseConn {
             .write_all(encoder.encode_handshake(reply).as_ref())
             .await?;
         let (tx, rx) = transport.split();
-        let max_frame = encrypted_frame_len(MAX_CLIENT_PAYLOAD);
         Ok(Self::new(
             stream,
             encoder,
@@ -98,7 +146,7 @@ impl NoiseConn {
             tx,
             rx,
             write_timeout,
-            max_frame,
+            FrameCap::CLIENT,
         ))
     }
 
@@ -129,7 +177,6 @@ impl NoiseConn {
             .try_into()
             .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "sv2: handshake size"))?;
         let (tx, rx) = sent.step_2(reply).map_err(codec_err)?.split();
-        // TP→client frames are bounded by the 24-bit frame length only.
         Ok(Self::new(
             stream,
             encoder,
@@ -137,7 +184,7 @@ impl NoiseConn {
             tx,
             rx,
             write_timeout,
-            usize::MAX,
+            FrameCap::UNBOUNDED,
         ))
     }
 
@@ -148,7 +195,7 @@ impl NoiseConn {
         tx: TransportEncryptState,
         rx: TransportDecryptState,
         write_timeout: Duration,
-        max_frame: usize,
+        cap: FrameCap,
     ) -> Self {
         let (read, write) = stream.into_split();
         Self {
@@ -156,7 +203,7 @@ impl NoiseConn {
                 stream: read,
                 decoder,
                 rx: Some(rx),
-                max_frame,
+                cap,
                 frame_read: 0,
             },
             writer: NoiseWriter {
@@ -230,9 +277,21 @@ impl NoiseReader {
                 Decrypted::Frame(mut frame, state) => {
                     self.rx = Some(state);
                     self.frame_read = 0;
+                    let msg_type = frame.header().msg_type();
+                    let payload = frame.payload();
+                    // codec_sv2 decrypts the header into a private buffer, so
+                    // the type is only visible with the whole frame: the
+                    // running count bounds every frame at the largest client
+                    // message, and the per-type cap applies here.
+                    if payload.len() > (self.cap.payload)(msg_type) {
+                        return Err(io::Error::new(
+                            io::ErrorKind::InvalidData,
+                            "sv2: frame over the size cap",
+                        ));
+                    }
                     return Ok(Frame {
-                        msg_type: frame.header().msg_type(),
-                        payload: frame.payload().to_vec(),
+                        msg_type,
+                        payload: payload.to_vec(),
                     });
                 }
                 Decrypted::Incomplete(n, state) => {
@@ -243,7 +302,7 @@ impl NoiseReader {
                     // the running count closes an oversized frame before the
                     // chunk that would exceed the cap is read.
                     self.frame_read += n;
-                    if self.frame_read > self.max_frame {
+                    if self.frame_read > self.cap.max_frame {
                         return Err(io::Error::new(
                             io::ErrorKind::InvalidData,
                             "sv2: frame over the size cap",

From 1290428ed676e30f47464ca99093d961f5fd9a8c Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Tue, 6 Oct 2026 17:21:00 -0400
Subject: [PATCH 03/19] sv2: validate a declared custom job through the
 template provider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/sv2-job-validation-draft.md §4.1–4.3: on a session that negotiated
REQUIRES_JOB_VALIDATION, a ValidateCustomJob whose wtxids are all in the
mempool is resolved, assembled under a header on the tip (time ≥ MTP + 1,
expected nBits, nonce 0, merkle root over the placeholder coinbase and the
declared txids) and run through ChainHub::check_block_proposal. Ok(fees)
retains the job under the next template id, exactly like a built template,
and answers Success{request_id, template_id, fees}; a reject string answers
Error{error_code}. Without the flag the message is still ignored.

The tip read (height, prev hash, time, bits) moves out of template::build
into template::next_header so both paths share it, and Template splits
into the NewTemplate coinbase split over a Job: what a session retains
under a template id for SubmitSolution and RequestTransactionData, so a
validated job carries no dead NewTemplate fields. CPU trade: one full
proposal check per request on the blocking pool (no scripts, no PoW).

A wtxid not in the mempool still drops the request; MissingTransactions
follows in the next step.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/job.rs            |  80 ++++++++++
 crates/rbitcoin-sv2/src/lib.rs            |   1 +
 crates/rbitcoin-sv2/src/session.rs        | 119 +++++++++++----
 crates/rbitcoin-sv2/src/template.rs       |  91 +++++++----
 crates/rbitcoin-sv2/src/template_tests.rs | 175 +++++++++++++++++++++-
 crates/rbitcoin-sv2/src/testutil.rs       |   7 +-
 6 files changed, 414 insertions(+), 59 deletions(-)
 create mode 100644 crates/rbitcoin-sv2/src/job.rs

diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
new file mode 100644
index 000000000..b6cf35a24
--- /dev/null
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -0,0 +1,80 @@
+//! Custom job validation for a Job Declarator Server
+//! (docs/sv2-job-validation.md §4): resolve the declared wtxids, check the
+//! job as a block proposal on the tip, and shape it for retention.
+
+use crate::messages::ValidateCustomJob;
+use crate::template::{self, Job};
+use bitcoin::hashes::Hash;
+use bitcoin::{block, Block, BlockHash, Transaction, TxMerkleNode, Wtxid};
+use rbitcoin_net::ChainHub;
+use std::io;
+use std::sync::Arc;
+
+pub(crate) enum Verdict {
+    /// Consensus-valid on the tip: the fee total and the job to retain.
+    Valid { fees: u64, job: Job },
+    /// `ValidateCustomJob.Error.error_code`: a Core reject string or one of
+    /// the draft's own codes.
+    Rejected(String),
+}
+
+/// Reads the store and the mempool: blocking region only. `None`: the
+/// payload is not a `ValidateCustomJob`.
+pub(crate) fn validate(
+    chain: &ChainHub,
+    mut payload: Vec<u8>,
+) -> io::Result<Option<(u32, Verdict)>> {
+    let Ok(m) = binary_sv2::from_bytes::<ValidateCustomJob>(&mut payload) else {
+        return Ok(None);
+    };
+    Ok(Some((m.request_id, check(chain, &m)?)))
+}
+
+fn check(chain: &ChainHub, m: &ValidateCustomJob) -> io::Result<Verdict> {
+    let Ok(coinbase) = bitcoin::consensus::deserialize::<Transaction>(m.coinbase_tx.as_ref())
+    else {
+        return Ok(Verdict::Rejected("bad-cb-decode".into()));
+    };
+    let mut txs = Vec::with_capacity(m.wtxid_list.len());
+    for w in m.wtxid_list.iter() {
+        let w: [u8; 32] = w.as_ref().try_into().expect("U256 is 32 bytes");
+        let Some(tx) = chain
+            .mempool()
+            .and_then(|mp| mp.get_tx_by_wtxid(&Wtxid::from_byte_array(w)))
+        else {
+            return Err(io::Error::other(
+                "sv2: ValidateCustomJob wtxid not in the mempool",
+            ));
+        };
+        txs.push(tx);
+    }
+    let next = template::next_header(chain)?;
+    let mut leaves = Vec::with_capacity(1 + txs.len());
+    leaves.push(coinbase.compute_txid().to_byte_array());
+    leaves.extend(txs.iter().map(|tx| tx.compute_txid().to_byte_array()));
+    let header = block::Header {
+        version: block::Version::from_consensus(m.version as i32),
+        prev_blockhash: BlockHash::from_byte_array(next.prev_hash),
+        merkle_root: TxMerkleNode::from_byte_array(rbitcoin_store::merkle_root_from_txids(&leaves)),
+        time: next.time,
+        bits: next.bits,
+        nonce: 0,
+    };
+    let mut txdata = Vec::with_capacity(1 + txs.len());
+    txdata.push(coinbase);
+    txdata.extend(txs);
+    let mut block = Block { header, txdata };
+    // CPU trade (CONTRIBUTING 9): one full proposal check per request
+    // (every spend against the chain, structure, weight, sigops, coinbase
+    // value; no scripts, no PoW), on the blocking pool. A JDS sends one per
+    // declaration; a flood costs blocking threads, not the reactor.
+    let fees = match chain.check_block_proposal(&block) {
+        Ok(fees) => fees,
+        Err(code) => return Ok(Verdict::Rejected(code)),
+    };
+    let txs = block.txdata.split_off(1).into_iter().map(Arc::new).collect();
+    Ok(Verdict::Valid {
+        fees,
+        job: next.job(rbitcoin_store::merkle_branch(&leaves, 0), txs),
+    })
+}
diff --git a/crates/rbitcoin-sv2/src/lib.rs b/crates/rbitcoin-sv2/src/lib.rs
index 8589b9ec1..f88506cc5 100644
--- a/crates/rbitcoin-sv2/src/lib.rs
+++ b/crates/rbitcoin-sv2/src/lib.rs
@@ -3,6 +3,7 @@
 //! Noise_NX over TCP is the only transport. Plan and constraints:
 //! `docs/sv2-template-provider.md`.
 
+mod job;
 pub mod messages;
 mod session;
 mod template;
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index b7ab2f2d1..dc74f9f54 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -1,6 +1,11 @@
 //! One TDP session: Noise handshake, `SetupConnection`, then TDP messages.
 
-use crate::messages::REQUIRES_JOB_VALIDATION;
+use crate::job::{self, Verdict};
+use crate::messages::{
+    ValidateCustomJobError, ValidateCustomJobSuccess, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
+    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS,
+    REQUIRES_JOB_VALIDATION,
+};
 use crate::template;
 use crate::transport::{Frame, NoiseConn, NoiseWriter};
 use crate::Sv2TpStats;
@@ -75,25 +80,28 @@ struct Templates {
     sent_bits: Option<(u32, [u8; 32])>,
     /// A template was built since the last tip event.
     built_since_tip: bool,
+    /// `coinbase_tx_value_remaining` of the last `NewTemplate` sent; the fee
+    /// delta is against it, not against a validated job retained after it.
+    last_value_remaining: Option<u64>,
     retained: VecDeque<Retained>,
 }
 
 struct Retained {
     id: u64,
-    t: template::Template,
+    job: template::Job,
     prev_sent: (u32, Instant),
     /// Set once the tip moves on.
     retire_at: Option<Instant>,
 }
 
 impl Templates {
-    fn retain(&mut self, id: u64, t: template::Template, prev_sent: (u32, Instant)) {
+    fn retain(&mut self, id: u64, job: template::Job, prev_sent: (u32, Instant)) {
         if self.retained.len() == MAX_RETAINED {
             self.retained.pop_front();
         }
         self.retained.push_back(Retained {
             id,
-            t,
+            job,
             prev_sent,
             retire_at: None,
         });
@@ -144,9 +152,9 @@ pub(crate) async fn serve(
     let setup = async {
         let mut conn = NoiseConn::accept(stream, responder, write_timeout).await?;
         let frame = conn.recv().await?;
-        Ok::<_, io::Error>(on_setup(&mut conn, frame).await?.then_some(conn))
+        Ok::<_, io::Error>(on_setup(&mut conn, frame).await?.map(|flags| (conn, flags)))
     };
-    let Some(conn) = tokio::time::timeout_at(deadline, setup)
+    let Some((conn, flags)) = tokio::time::timeout_at(deadline, setup)
         .await
         .map_err(|_| missed_setup_deadline())??
     else {
@@ -171,6 +179,7 @@ pub(crate) async fn serve(
         stale_grace,
         fee_push,
         stats,
+        job_validation: flags & REQUIRES_JOB_VALIDATION != 0,
         constraints: None,
         templates: Templates::default(),
         built_at: None,
@@ -198,6 +207,8 @@ struct Session {
     stale_grace: Duration,
     fee_push: FeePush,
     stats: Arc<Sv2TpStats>,
+    /// `SetupConnection` negotiated `REQUIRES_JOB_VALIDATION`.
+    job_validation: bool,
     /// Last `CoinbaseOutputConstraints`: `(max_additional_size, sigops)`.
     constraints: Option<(u32, u16)>,
     templates: Templates,
@@ -308,6 +319,9 @@ impl Session {
                 on_request_transaction_data(&mut self.conn, frame, &self.templates).await?;
             }
             MESSAGE_TYPE_SUBMIT_SOLUTION => self.on_submit_solution(frame).await?,
+            MESSAGE_TYPE_VALIDATE_CUSTOM_JOB if self.job_validation => {
+                self.on_validate_custom_job(frame).await?;
+            }
             t => rbitcoin_log::info!("sv2: ignoring message {t:#x}"),
         }
         Ok(true)
@@ -348,12 +362,12 @@ impl Session {
                 return Ok(());
             }
         };
-        let Some(last) = self.templates.retained.back() else {
+        let Some(last) = self.templates.last_value_remaining else {
             return Ok(());
         };
         // Same prev hash, same height: value_remaining differs by fees only.
-        if self.templates.current_prev == Some(t.prev_hash)
-            && t.value_remaining >= last.t.value_remaining.saturating_add(self.fee_push.delta)
+        if self.templates.current_prev == Some(t.job.prev_hash)
+            && t.value_remaining >= last.saturating_add(self.fee_push.delta)
         {
             self.send(t).await?;
         }
@@ -400,18 +414,19 @@ impl Session {
         self.templates.last_id += 1;
         let template_id = self.templates.last_id;
         // sv2-spec 07 §7.3: a template on a new prev hash is future, then activated.
-        let new_prev = self.templates.current_prev != Some(t.prev_hash);
+        let new_prev = self.templates.current_prev != Some(t.job.prev_hash);
         // §7.4: nBits comes once per prev hash. On min-difficulty networks the
         // build's bits follow the clock; a solution on this template is hashed
         // with the bits the client was sent.
         if let Some((n_bits, target)) = self.templates.sent_bits.filter(|_| !new_prev) {
-            t.n_bits = n_bits;
-            t.target = target;
+            t.job.n_bits = n_bits;
+            t.job.target = target;
         }
         let msg = t
             .to_message(template_id, new_prev)
             .map_err(|e| io::Error::other(format!("sv2 NewTemplate: {e:?}")))?;
         self.conn.send(MESSAGE_TYPE_NEW_TEMPLATE, msg).await?;
+        self.templates.last_value_remaining = Some(t.value_remaining);
         let sent = Instant::now();
         self.built_at = Some(sent);
         self.fee_check_at = Some(sent + self.fee_push.interval);
@@ -421,16 +436,16 @@ impl Session {
                 .send(MESSAGE_TYPE_SET_NEW_PREV_HASH, t.to_prev_hash(template_id))
                 .await?;
             let now = Instant::now();
-            self.templates.current_prev = Some(t.prev_hash);
-            self.templates.prev_sent = Some((t.header_timestamp, now));
-            self.templates.sent_bits = Some((t.n_bits, t.target));
+            self.templates.current_prev = Some(t.job.prev_hash);
+            self.templates.prev_sent = Some((t.job.header_timestamp, now));
+            self.templates.sent_bits = Some((t.job.n_bits, t.job.target));
             self.templates.start_grace(now + self.stale_grace);
         }
         let prev_sent = self
             .templates
             .prev_sent
             .ok_or_else(|| io::Error::other("sv2: template before SetNewPrevHash"))?;
-        self.templates.retain(template_id, t, prev_sent);
+        self.templates.retain(template_id, t.job, prev_sent);
         Ok(())
     }
 
@@ -468,15 +483,15 @@ impl Session {
         // and hash of every template tx plus ChainHub's connect path.
         let root = rbitcoin_store::merkle_root_from_branch(
             coinbase.compute_txid().to_byte_array(),
-            &r.t.merkle_path,
+            &r.job.merkle_path,
             0,
         );
         let header = block::Header {
             version: block::Version::from_consensus(m.version as i32),
-            prev_blockhash: BlockHash::from_byte_array(r.t.prev_hash),
+            prev_blockhash: BlockHash::from_byte_array(r.job.prev_hash),
             merkle_root: TxMerkleNode::from_byte_array(root),
             time: m.header_timestamp,
-            bits: CompactTarget::from_consensus(r.t.n_bits),
+            bits: CompactTarget::from_consensus(r.job.n_bits),
             nonce: m.header_nonce,
         };
         if header.validate_pow(header.target()).is_err() {
@@ -501,9 +516,9 @@ impl Session {
                 m.header_timestamp
             );
         }
-        let mut txdata = Vec::with_capacity(1 + r.t.txs.len());
+        let mut txdata = Vec::with_capacity(1 + r.job.txs.len());
         txdata.push(coinbase);
-        txdata.extend(r.t.txs.iter().map(|tx| Transaction::clone(tx)));
+        txdata.extend(r.job.txs.iter().map(|tx| Transaction::clone(tx)));
         let block = Block { header, txdata };
         let hash = block.block_hash();
         let c = Arc::clone(&self.chain);
@@ -519,6 +534,52 @@ impl Session {
         }
         Ok(())
     }
+
+    /// docs/sv2-job-validation.md §4: a valid job is retained under the next
+    /// template id and answered `Success`; a rejected one answers `Error`.
+    async fn on_validate_custom_job(&mut self, frame: Frame) -> io::Result<()> {
+        let c = Arc::clone(&self.chain);
+        let verdict = tokio::task::spawn_blocking(move || {
+            let _g = BlockingRegion::enter();
+            job::validate(&c, frame.payload)
+        })
+        .await
+        .map_err(io::Error::other)??;
+        let Some((request_id, verdict)) = verdict else {
+            rbitcoin_log::info!("sv2: undecodable ValidateCustomJob");
+            return Ok(());
+        };
+        let wire = |e: binary_sv2::Error| io::Error::other(format!("sv2 ValidateCustomJob: {e:?}"));
+        match verdict {
+            Verdict::Valid { fees, job } => {
+                self.templates.last_id += 1;
+                let template_id = self.templates.last_id;
+                let prev_sent = self
+                    .templates
+                    .prev_sent
+                    .unwrap_or((job.header_timestamp, Instant::now()));
+                self.templates.retain(template_id, job, prev_sent);
+                let reply = ValidateCustomJobSuccess {
+                    request_id,
+                    template_id,
+                    fees,
+                };
+                self.conn
+                    .send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, reply)
+                    .await
+            }
+            Verdict::Rejected(code) => {
+                let reply = ValidateCustomJobError {
+                    request_id,
+                    error_code: Str0255::try_from(code.as_str()).map_err(wire)?,
+                    error_details: B064K::try_from(&[][..]).map_err(wire)?,
+                };
+                self.conn
+                    .send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, reply)
+                    .await
+            }
+        }
+    }
 }
 
 fn setup_error(m: &SetupConnection) -> Option<(u32, &'static str)> {
@@ -539,15 +600,15 @@ fn setup_error(m: &SetupConnection) -> Option<(u32, &'static str)> {
     None
 }
 
-/// `false`: close the session.
-async fn on_setup(conn: &mut NoiseConn, mut frame: Frame) -> io::Result<bool> {
+/// The negotiated flags; `None`: close the session.
+async fn on_setup(conn: &mut NoiseConn, mut frame: Frame) -> io::Result<Option<u32>> {
     if frame.msg_type != MESSAGE_TYPE_SETUP_CONNECTION {
         rbitcoin_log::info!("sv2: message {:#x} before SetupConnection", frame.msg_type);
-        return Ok(false);
+        return Ok(None);
     }
     let Ok(setup) = binary_sv2::from_bytes::<SetupConnection>(&mut frame.payload) else {
         rbitcoin_log::info!("sv2: undecodable SetupConnection");
-        return Ok(false);
+        return Ok(None);
     };
     if let Some((flags, code)) = setup_error(&setup) {
         let error_code = Str0255::try_from(code)
@@ -555,7 +616,7 @@ async fn on_setup(conn: &mut NoiseConn, mut frame: Frame) -> io::Result<bool> {
         let reply = SetupConnectionError { flags, error_code };
         conn.send(MESSAGE_TYPE_SETUP_CONNECTION_ERROR, reply)
             .await?;
-        return Ok(false);
+        return Ok(None);
     }
     let reply = SetupConnectionSuccess {
         used_version: TDP_VERSION,
@@ -563,7 +624,7 @@ async fn on_setup(conn: &mut NoiseConn, mut frame: Frame) -> io::Result<bool> {
     };
     conn.send(MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS, reply)
         .await?;
-    Ok(true)
+    Ok(Some(setup.flags))
 }
 
 /// An id this session was sent but no longer retains is stale; any other
@@ -578,7 +639,7 @@ async fn on_request_transaction_data(
         rbitcoin_log::info!("sv2: undecodable RequestTransactionData");
         return Ok(());
     };
-    let Some(Retained { t, .. }) = templates.get(template_id) else {
+    let Some(Retained { job, .. }) = templates.get(template_id) else {
         let code = if template_id <= templates.last_id {
             ERROR_CODE_REQUEST_TRANSACTION_DATA_STALE_TEMPLATE_ID
         } else {
@@ -593,7 +654,7 @@ async fn on_request_transaction_data(
             .send(MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR, reply)
             .await;
     };
-    let raw: Vec<Vec<u8>> = t
+    let raw: Vec<Vec<u8>> = job
         .txs
         .iter()
         .map(|tx| bitcoin::consensus::encode::serialize(tx.as_ref()))
diff --git a/crates/rbitcoin-sv2/src/template.rs b/crates/rbitcoin-sv2/src/template.rs
index 80f5fa8bd..dec31be31 100644
--- a/crates/rbitcoin-sv2/src/template.rs
+++ b/crates/rbitcoin-sv2/src/template.rs
@@ -4,7 +4,7 @@
 use binary_sv2::{Seq0255, B0255, B064K, U256};
 use bitcoin::consensus::encode::serialize;
 use bitcoin::hashes::Hash;
-use bitcoin::{Amount, ScriptBuf, Target, Transaction, TxOut};
+use bitcoin::{Amount, CompactTarget, ScriptBuf, Target, Transaction, TxOut};
 use rbitcoin_consensus::{
     bip34_height_script, block_subsidy, expected_next_bits, median_time_past,
     witness_commitment_script, MAX_BLOCK_WEIGHT,
@@ -24,12 +24,20 @@ pub(crate) const WITNESS_RESERVED_VALUE: [u8; 32] = [0u8; 32];
 const COINBASE_BASE_WU: u64 = 1168;
 const MIN_COINBASE_RESERVE_WU: u64 = 2000;
 
+/// A `NewTemplate`: the coinbase split the client completes, over a [`Job`].
 pub(crate) struct Template {
     pub version: u32,
     pub coinbase_prefix: Vec<u8>,
     pub value_remaining: u64,
     /// The witness commitment output, serialized with no count prefix.
     pub coinbase_outputs: Vec<u8>,
+    pub job: Job,
+}
+
+/// What a session retains under a template id, for a built template or a
+/// validated custom job: the header fields a `SubmitSolution` is assembled
+/// with and the txs `RequestTransactionData` returns.
+pub(crate) struct Job {
     pub merkle_path: Vec<[u8; 32]>,
     pub prev_hash: [u8; 32],
     pub header_timestamp: u32,
@@ -60,29 +68,45 @@ impl Template {
             coinbase_tx_outputs_count: 1,
             coinbase_tx_outputs: B064K::try_from(&self.coinbase_outputs[..])?,
             coinbase_tx_locktime: 0,
-            merkle_path: Seq0255::new(self.merkle_path.iter().map(U256::from).collect())?,
+            merkle_path: Seq0255::new(self.job.merkle_path.iter().map(U256::from).collect())?,
         })
     }
 
     pub fn to_prev_hash(&self, template_id: u64) -> SetNewPrevHash<'_> {
         SetNewPrevHash {
             template_id,
-            prev_hash: U256::from(&self.prev_hash),
-            header_timestamp: self.header_timestamp,
-            n_bits: self.n_bits,
-            target: U256::from(&self.target),
+            prev_hash: U256::from(&self.job.prev_hash),
+            header_timestamp: self.job.header_timestamp,
+            n_bits: self.job.n_bits,
+            target: U256::from(&self.job.target),
         }
     }
 }
 
-/// Template on the current tip for one client's coinbase constraints. The
-/// client's sigops replace the default reserve (Core `BlockAssembler`).
-/// Takes the mempool lock and reads the store: blocking region only.
-pub(crate) fn build(
-    chain: &ChainHub,
-    max_additional_size: u32,
-    max_additional_sigops: u16,
-) -> io::Result<Template> {
+/// Header fields the tip fixes for the next block. Reads the store:
+/// blocking region only.
+pub(crate) struct NextHeader {
+    pub height: u32,
+    pub prev_hash: [u8; 32],
+    /// MTP + 1, or the node clock when later.
+    pub time: u32,
+    pub bits: CompactTarget,
+}
+
+impl NextHeader {
+    pub fn job(&self, merkle_path: Vec<[u8; 32]>, txs: Vec<Arc<Transaction>>) -> Job {
+        Job {
+            merkle_path,
+            prev_hash: self.prev_hash,
+            header_timestamp: self.time,
+            n_bits: self.bits.to_consensus(),
+            target: Target::from_compact(self.bits).to_le_bytes(),
+            txs,
+        }
+    }
+}
+
+pub(crate) fn next_header(chain: &ChainHub) -> io::Result<NextHeader> {
     let tip = chain
         .query
         .tip_height()
@@ -94,14 +118,27 @@ pub(crate) fn build(
     let mtp = median_time_past(&chain.query, tip)
         .map_err(|e| io::Error::other(format!("sv2: tip MTP: {e}")))?;
     let height = tip.0 + 1;
-    let header_timestamp = mtp.saturating_add(1).max(chain.clock.now_secs() as u32);
-    let bits = expected_next_bits(
-        &chain.query,
-        &chain.params,
-        Height(height),
-        header_timestamp,
-    )
-    .map_err(|e| io::Error::other(format!("sv2: next bits: {e}")))?;
+    let time = mtp.saturating_add(1).max(chain.clock.now_secs() as u32);
+    let bits = expected_next_bits(&chain.query, &chain.params, Height(height), time)
+        .map_err(|e| io::Error::other(format!("sv2: next bits: {e}")))?;
+    Ok(NextHeader {
+        height,
+        prev_hash: header.block_hash().to_byte_array(),
+        time,
+        bits,
+    })
+}
+
+/// Template on the current tip for one client's coinbase constraints. The
+/// client's sigops replace the default reserve (Core `BlockAssembler`).
+/// Takes the mempool lock and reads the store: blocking region only.
+pub(crate) fn build(
+    chain: &ChainHub,
+    max_additional_size: u32,
+    max_additional_sigops: u16,
+) -> io::Result<Template> {
+    let next = next_header(chain)?;
+    let height = next.height;
     let reserve =
         (COINBASE_BASE_WU + 4 * u64::from(max_additional_size)).max(MIN_COINBASE_RESERVE_WU);
     let budget = SelectBudget {
@@ -130,11 +167,9 @@ pub(crate) fn build(
         coinbase_prefix: bip34_height_script(height),
         value_remaining: (block_subsidy(height, &chain.params) as u64).saturating_add(fees),
         coinbase_outputs: serialize(&commitment),
-        merkle_path: rbitcoin_store::merkle_branch(&leaves, 0),
-        prev_hash: header.block_hash().to_byte_array(),
-        header_timestamp,
-        n_bits: bits.to_consensus(),
-        target: Target::from_compact(bits).to_le_bytes(),
-        txs: selected.into_iter().map(|(tx, _)| tx).collect(),
+        job: next.job(
+            rbitcoin_store::merkle_branch(&leaves, 0),
+            selected.into_iter().map(|(tx, _)| tx).collect(),
+        ),
     })
 }
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index d6e670af9..c5ade0716 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1,6 +1,11 @@
+use crate::messages::{
+    ValidateCustomJob, ValidateCustomJobSuccess, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
+    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, REQUIRES_JOB_VALIDATION,
+};
 use crate::test_chain::{padded_chain_with, shared_regtest, TestChain};
 use crate::testutil::TpClient;
 use crate::{run_sv2_tp, Sv2TpConfig, FEE_DELTA, SETUP_TIMEOUT, TEMPLATE_INTERVAL, WRITE_TIMEOUT};
+use binary_sv2::{Seq064K, B016M, B064K, U256};
 use bitcoin::consensus::encode::serialize;
 use bitcoin::hashes::{sha256d, Hash};
 use bitcoin::{
@@ -18,7 +23,8 @@ use rbitcoin_store::merkle_root_from_txids;
 use std::sync::Arc;
 use std::time::Duration;
 use template_distribution_sv2::{
-    NewTemplate, SetNewPrevHash, MESSAGE_TYPE_NEW_TEMPLATE, MESSAGE_TYPE_SET_NEW_PREV_HASH,
+    NewTemplate, RequestTransactionDataSuccess, SetNewPrevHash, MESSAGE_TYPE_NEW_TEMPLATE,
+    MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS, MESSAGE_TYPE_SET_NEW_PREV_HASH,
 };
 
 const MAX_BLOCK_WEIGHT: u64 = 4_000_000;
@@ -1098,3 +1104,170 @@ async fn idle_session_checks_each_interval_and_does_not_rebuild() {
     drop(c);
     tp.shutdown().await;
 }
+
+/// A live TP on `tc` with one session past `SetupConnection(flags)`.
+async fn connect_tp(tc: &TestChain, flags: u32) -> (crate::Sv2TpHandle, TpClient) {
+    let tp = run_sv2_tp(Sv2TpConfig {
+        listen: "127.0.0.1:0".parse().unwrap(),
+        chain: Arc::clone(&tc.chain),
+        authority_secret: [7; 32],
+        cert_validity: Duration::from_secs(3600),
+        stale_grace: Duration::from_secs(10),
+        setup_timeout: SETUP_TIMEOUT,
+        write_timeout: WRITE_TIMEOUT,
+        fee_delta: FEE_DELTA,
+        template_interval: TEMPLATE_INTERVAL,
+    })
+    .await
+    .expect("listen");
+    let mut c = TpClient::connect(tp.local_addr, tp.authority_pubkey)
+        .await
+        .expect("handshake");
+    c.setup_connection(2, 2, 2, flags).await.unwrap();
+    c.recv().await.expect("setup reply");
+    (tp, c)
+}
+
+/// A JDS-shaped placeholder coinbase: BIP34 height then 8 extranonce bytes,
+/// one payout, and the witness commitment over `txs` with a zero reserved
+/// value in the witness.
+fn job_coinbase(height: u32, payout: u64, txs: &[&Transaction]) -> Transaction {
+    let mut script_sig = bip34_height_script(height);
+    script_sig.extend_from_slice(&[0u8; 8]);
+    Transaction {
+        version: Version::TWO,
+        lock_time: LockTime::ZERO,
+        input: vec![TxIn {
+            previous_output: OutPoint::null(),
+            script_sig: ScriptBuf::from_bytes(script_sig),
+            sequence: Sequence::MAX,
+            witness: Witness::from_slice(&[[0u8; 32]]),
+        }],
+        output: vec![
+            TxOut {
+                value: Amount::from_sat(payout),
+                script_pubkey: ScriptBuf::from_bytes(vec![OP_TRUE]),
+            },
+            TxOut {
+                value: Amount::ZERO,
+                script_pubkey: ScriptBuf::from_bytes(witness_commitment_script(
+                    txs.iter().map(|tx| tx.compute_wtxid().to_byte_array()),
+                    &[0u8; 32],
+                )),
+            },
+        ],
+    }
+}
+
+/// One `ValidateCustomJob` as owned fields, so a test can bend any of them.
+struct Job {
+    request_id: u32,
+    prev_hash: [u8; 32],
+    version: u32,
+    coinbase: Vec<u8>,
+    wtxids: Vec<[u8; 32]>,
+    supplied: Vec<Vec<u8>>,
+}
+
+impl Job {
+    fn on_tip(
+        tc: &TestChain,
+        request_id: u32,
+        coinbase: &Transaction,
+        declared: &[&Transaction],
+    ) -> Self {
+        Job {
+            request_id,
+            prev_hash: tc
+                .chain
+                .tip_header()
+                .expect("tip")
+                .block_hash()
+                .to_byte_array(),
+            version: tc.chain.gbt_block_version() as u32,
+            coinbase: serialize(coinbase),
+            wtxids: declared
+                .iter()
+                .map(|tx| tx.compute_wtxid().to_byte_array())
+                .collect(),
+            supplied: Vec::new(),
+        }
+    }
+
+    async fn send(&self, c: &mut TpClient) {
+        let msg = ValidateCustomJob {
+            request_id: self.request_id,
+            prev_hash: U256::from(&self.prev_hash),
+            version: self.version,
+            coinbase_tx: B064K::try_from(&self.coinbase[..]).unwrap(),
+            wtxid_list: Seq064K::new(self.wtxids.iter().map(U256::from).collect()).unwrap(),
+            transaction_list: Seq064K::new(
+                self.supplied
+                    .iter()
+                    .map(|t| B016M::try_from(&t[..]).unwrap())
+                    .collect(),
+            )
+            .unwrap(),
+        };
+        c.send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, msg).await.unwrap();
+    }
+}
+
+async fn expect_job_success(c: &mut TpClient) -> ValidateCustomJobSuccess {
+    let mut f = recv_in_time(c).await;
+    assert_eq!(
+        f.msg_type, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS,
+        "{:?}",
+        f.payload
+    );
+    binary_sv2::from_bytes(&mut f.payload).expect("decode")
+}
+
+/// The retained job answers `RequestTransactionData` with the declared txs
+/// in block order, exactly like a built template.
+async fn expect_retained(c: &mut TpClient, template_id: u64, txs: &[&Transaction]) {
+    c.request_transaction_data(template_id).await.unwrap();
+    let mut f = recv_in_time(c).await;
+    assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS);
+    let d: RequestTransactionDataSuccess = binary_sv2::from_bytes(&mut f.payload).unwrap();
+    assert_eq!(d.template_id, template_id);
+    let got: Vec<Vec<u8>> = d
+        .transaction_list
+        .iter()
+        .map(|t| t.as_ref().to_vec())
+        .collect();
+    let want: Vec<Vec<u8>> = txs.iter().map(serialize).collect();
+    assert_eq!(got, want, "retained txs in declared order");
+}
+
+/// docs/sv2-job-validation.md §4.1–4.3: a job on the tip whose txs are all
+/// in the mempool and whose coinbase pays subsidy + fees is answered
+/// `Success` with the next template id and the declared fee sum, and is
+/// retained like a template.
+#[tokio::test(flavor = "multi_thread")]
+async fn validate_custom_job_prices_and_retains_the_declared_job() {
+    let tc = shared_regtest(2);
+    mock_live_tip(&tc);
+    let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
+    let a = spend(tc.coinbases[0], 3_000, cheap.clone());
+    let b = spend(tc.coinbases[1], 2_000, cheap);
+    for tx in [&a, &b] {
+        tc.mempool.accept_tx(tx).expect("mempool accept");
+    }
+    let (tp, mut c) = connect_tp(&tc, REQUIRES_JOB_VALIDATION).await;
+    c.coinbase_output_constraints(0, 0).await.unwrap();
+    let last = expect_template(&mut c, &tc, &[&a, &b], true).await;
+
+    let height = tc.chain.query.tip_height().unwrap().0 + 1;
+    let subsidy = block_subsidy(height, &tc.chain.params) as u64;
+    let coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
+    Job::on_tip(&tc, 9, &coinbase, &[&a, &b]).send(&mut c).await;
+    let ok = expect_job_success(&mut c).await;
+    assert_eq!(
+        (ok.request_id, ok.template_id, ok.fees),
+        (9, last + 1, 5_000)
+    );
+    expect_retained(&mut c, ok.template_id, &[&a, &b]).await;
+
+    tp.shutdown().await;
+}
diff --git a/crates/rbitcoin-sv2/src/testutil.rs b/crates/rbitcoin-sv2/src/testutil.rs
index e6c7a7cb1..49574f652 100644
--- a/crates/rbitcoin-sv2/src/testutil.rs
+++ b/crates/rbitcoin-sv2/src/testutil.rs
@@ -1,7 +1,7 @@
 //! Test-only TDP client: a Noise initiator pinned to the TP's authority key.
 
 use crate::transport::{Frame, NoiseConn};
-use binary_sv2::{Str0255, B016M, B064K};
+use binary_sv2::{GetSize, Serialize, Str0255, B016M, B064K};
 use common_messages_sv2::{Protocol, SetupConnection, MESSAGE_TYPE_SETUP_CONNECTION};
 use std::io;
 use std::net::SocketAddr;
@@ -122,6 +122,11 @@ impl TpClient {
         self.conn.send(MESSAGE_TYPE_SUBMIT_SOLUTION, msg).await
     }
 
+    /// Send any SV2 message under `msg_type`.
+    pub async fn send<T: Serialize + GetSize>(&mut self, msg_type: u8, msg: T) -> io::Result<()> {
+        self.conn.send(msg_type, msg).await
+    }
+
     /// Send `payload` as one `B016M` field under an arbitrary message type.
     pub async fn send_bytes(&mut self, msg_type: u8, payload: &[u8]) -> io::Result<()> {
         let msg = B016M::try_from(payload)

From 34cb98998d78eba42c58a0c49ed836b5f1215843 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Tue, 6 Oct 2026 17:23:27 -0400
Subject: [PATCH 04/19] sv2: report and accept missing transactions in custom
 job validation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/sv2-job-validation-draft.md §4.1–4.2: each declared wtxid is resolved
against transaction_list first, then the mempool. Any still unknown answer
ValidateCustomJob.MissingTransactions{request_id, positions} with the
0-indexed positions in wtxid_list, so a JDS relays them as
ProvideMissingTransactions unchanged. The TP keeps no state across the
round trip: the second request repeats the job with the txs filled in, and
the supplied txs are retained with the job in block order so SubmitSolution
assembles the same block the check passed.

A supplied tx is matched to its slot by sha256d of the bytes as sent (the
wtxid of that serialization), so no transaction is decoded before it is
known to be declared; a declared blob that does not decode is
bad-missing-tx. The step-4 placeholder (close the session on an unknown
wtxid) is gone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/job.rs            | 44 +++++++++++++++++-----
 crates/rbitcoin-sv2/src/session.rs        | 16 ++++++--
 crates/rbitcoin-sv2/src/template_tests.rs | 45 ++++++++++++++++++++++-
 3 files changed, 91 insertions(+), 14 deletions(-)

diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index b6cf35a24..d786a9c3c 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -4,13 +4,17 @@
 
 use crate::messages::ValidateCustomJob;
 use crate::template::{self, Job};
-use bitcoin::hashes::Hash;
+use bitcoin::hashes::{sha256d, Hash};
 use bitcoin::{block, Block, BlockHash, Transaction, TxMerkleNode, Wtxid};
 use rbitcoin_net::ChainHub;
+use std::collections::HashMap;
 use std::io;
 use std::sync::Arc;
 
 pub(crate) enum Verdict {
+    /// 0-indexed positions in `wtxid_list` neither the mempool nor
+    /// `transaction_list` resolves.
+    Missing(Vec<u16>),
     /// Consensus-valid on the tip: the fee total and the job to retain.
     Valid { fees: u64, job: Job },
     /// `ValidateCustomJob.Error.error_code`: a Core reject string or one of
@@ -35,18 +39,38 @@ fn check(chain: &ChainHub, m: &ValidateCustomJob) -> io::Result<Verdict> {
     else {
         return Ok(Verdict::Rejected("bad-cb-decode".into()));
     };
+    // The wtxid is the hash of the serialization as sent, so a supplied tx
+    // is matched to its slot without decoding it.
+    let supplied: HashMap<[u8; 32], &[u8]> = m
+        .transaction_list
+        .iter()
+        .map(|raw| {
+            (
+                sha256d::Hash::hash(raw.as_ref()).to_byte_array(),
+                raw.as_ref(),
+            )
+        })
+        .collect();
     let mut txs = Vec::with_capacity(m.wtxid_list.len());
-    for w in m.wtxid_list.iter() {
+    let mut missing = Vec::new();
+    for (pos, w) in m.wtxid_list.iter().enumerate() {
         let w: [u8; 32] = w.as_ref().try_into().expect("U256 is 32 bytes");
-        let Some(tx) = chain
-            .mempool()
-            .and_then(|mp| mp.get_tx_by_wtxid(&Wtxid::from_byte_array(w)))
-        else {
-            return Err(io::Error::other(
-                "sv2: ValidateCustomJob wtxid not in the mempool",
-            ));
+        let tx = match supplied.get(&w) {
+            Some(raw) => match bitcoin::consensus::deserialize::<Transaction>(raw) {
+                Ok(tx) => Some(tx),
+                Err(_) => return Ok(Verdict::Rejected("bad-missing-tx".into())),
+            },
+            None => chain
+                .mempool()
+                .and_then(|mp| mp.get_tx_by_wtxid(&Wtxid::from_byte_array(w))),
         };
-        txs.push(tx);
+        match tx {
+            Some(tx) => txs.push(tx),
+            None => missing.push(u16::try_from(pos).expect("Seq064K holds at most 65535")),
+        }
+    }
+    if !missing.is_empty() {
+        return Ok(Verdict::Missing(missing));
     }
     let next = template::next_header(chain)?;
     let mut leaves = Vec::with_capacity(1 + txs.len());
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index dc74f9f54..33a82c7b0 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -2,9 +2,10 @@
 
 use crate::job::{self, Verdict};
 use crate::messages::{
-    ValidateCustomJobError, ValidateCustomJobSuccess, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
-    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS,
-    REQUIRES_JOB_VALIDATION,
+    ValidateCustomJobError, ValidateCustomJobMissingTransactions, ValidateCustomJobSuccess,
+    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR,
+    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS,
+    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, REQUIRES_JOB_VALIDATION,
 };
 use crate::template;
 use crate::transport::{Frame, NoiseConn, NoiseWriter};
@@ -551,6 +552,15 @@ impl Session {
         };
         let wire = |e: binary_sv2::Error| io::Error::other(format!("sv2 ValidateCustomJob: {e:?}"));
         match verdict {
+            Verdict::Missing(positions) => {
+                let reply = ValidateCustomJobMissingTransactions {
+                    request_id,
+                    unknown_tx_position_list: Seq064K::new(positions).map_err(wire)?,
+                };
+                self.conn
+                    .send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS, reply)
+                    .await
+            }
             Verdict::Valid { fees, job } => {
                 self.templates.last_id += 1;
                 let template_id = self.templates.last_id;
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index c5ade0716..8c78f5f8d 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1,5 +1,6 @@
 use crate::messages::{
-    ValidateCustomJob, ValidateCustomJobSuccess, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
+    ValidateCustomJob, ValidateCustomJobMissingTransactions, ValidateCustomJobSuccess,
+    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS,
     MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, REQUIRES_JOB_VALIDATION,
 };
 use crate::test_chain::{padded_chain_with, shared_regtest, TestChain};
@@ -1271,3 +1272,45 @@ async fn validate_custom_job_prices_and_retains_the_declared_job() {
 
     tp.shutdown().await;
 }
+
+/// §4.1–4.2: a wtxid the TP cannot resolve answers `MissingTransactions`
+/// with its 0-indexed position; the same job resent with that tx in
+/// `transaction_list` validates, and the supplied tx is retained with it.
+#[tokio::test(flavor = "multi_thread")]
+async fn validate_custom_job_asks_for_and_accepts_missing_transactions() {
+    let tc = shared_regtest(2);
+    mock_live_tip(&tc);
+    let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
+    let a = spend(tc.coinbases[0], 3_000, cheap.clone());
+    let b = spend(tc.coinbases[1], 2_000, cheap);
+    tc.mempool.accept_tx(&a).expect("mempool accept");
+    let (tp, mut c) = connect_tp(&tc, REQUIRES_JOB_VALIDATION).await;
+    c.coinbase_output_constraints(0, 0).await.unwrap();
+    let last = expect_template(&mut c, &tc, &[&a], true).await;
+
+    let height = tc.chain.query.tip_height().unwrap().0 + 1;
+    let subsidy = block_subsidy(height, &tc.chain.params) as u64;
+    let coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
+    let mut job = Job::on_tip(&tc, 4, &coinbase, &[&a, &b]);
+    job.send(&mut c).await;
+    let mut f = recv_in_time(&mut c).await;
+    assert_eq!(
+        f.msg_type,
+        MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS
+    );
+    let m: ValidateCustomJobMissingTransactions =
+        binary_sv2::from_bytes(&mut f.payload).expect("decode");
+    assert_eq!(m.request_id, 4);
+    assert_eq!(m.unknown_tx_position_list.into_inner(), vec![1u16]);
+
+    job.supplied = vec![serialize(&b)];
+    job.send(&mut c).await;
+    let ok = expect_job_success(&mut c).await;
+    assert_eq!(
+        (ok.request_id, ok.template_id, ok.fees),
+        (4, last + 1, 5_000)
+    );
+    expect_retained(&mut c, ok.template_id, &[&a, &b]).await;
+
+    tp.shutdown().await;
+}

From 75f9dd393f4239979dd2724ea32394057cb29a29 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Tue, 6 Oct 2026 17:27:02 -0400
Subject: [PATCH 05/19] sv2: reject stale, duplicated, and unrequested
 custom-job inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/sv2-job-validation-draft.md §4.1 and §4.4: everything in a
ValidateCustomJob comes from a JDC, so the draft's own codes run in order
before any mempool lookup or transaction decode: the node in IBD answers
job-validation-unavailable (the same gate that holds templates), a
prev_hash off the tip stale-prevhash, a repeated wtxid duplicate-wtxid, a
supplied transaction whose hash is not in wtxid_list bad-missing-tx (also a
declared blob that does not decode), an undecodable coinbase bad-cb-decode,
and only then the proposal check's own reject string (bad-cb-amount for an
overpaying coinbase). A 32-byte wtxid is never amplified into a copy the job
did not declare. Nothing is retained and no template id is taken on an
error: the next id still answers template-id-not-found.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/job.rs            | 34 +++++++--
 crates/rbitcoin-sv2/src/template_tests.rs | 85 ++++++++++++++++++++++-
 2 files changed, 109 insertions(+), 10 deletions(-)

diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index d786a9c3c..794d412a7 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -7,7 +7,7 @@ use crate::template::{self, Job};
 use bitcoin::hashes::{sha256d, Hash};
 use bitcoin::{block, Block, BlockHash, Transaction, TxMerkleNode, Wtxid};
 use rbitcoin_net::ChainHub;
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 use std::io;
 use std::sync::Arc;
 
@@ -34,11 +34,25 @@ pub(crate) fn validate(
     Ok(Some((m.request_id, check(chain, &m)?)))
 }
 
+/// §4.1 and §4.4, in order. The draft's own codes run before any mempool
+/// lookup or transaction decode, so a 32-byte wtxid is never amplified into
+/// a copy or an allocation the job did not declare.
 fn check(chain: &ChainHub, m: &ValidateCustomJob) -> io::Result<Verdict> {
-    let Ok(coinbase) = bitcoin::consensus::deserialize::<Transaction>(m.coinbase_tx.as_ref())
-    else {
-        return Ok(Verdict::Rejected("bad-cb-decode".into()));
-    };
+    let rejected = |code: &str| Ok(Verdict::Rejected(code.into()));
+    // Same gate as the templates: a stale tip validates nothing.
+    if chain.in_ibd() {
+        return rejected("job-validation-unavailable");
+    }
+    let next = template::next_header(chain)?;
+    if m.prev_hash.as_ref() != next.prev_hash {
+        return rejected("stale-prevhash");
+    }
+    let mut declared = HashSet::with_capacity(m.wtxid_list.len());
+    for w in m.wtxid_list.iter() {
+        if !declared.insert(w.as_ref()) {
+            return rejected("duplicate-wtxid");
+        }
+    }
     // The wtxid is the hash of the serialization as sent, so a supplied tx
     // is matched to its slot without decoding it.
     let supplied: HashMap<[u8; 32], &[u8]> = m
@@ -51,6 +65,13 @@ fn check(chain: &ChainHub, m: &ValidateCustomJob) -> io::Result<Verdict> {
             )
         })
         .collect();
+    if supplied.keys().any(|w| !declared.contains(&w[..])) {
+        return rejected("bad-missing-tx");
+    }
+    let Ok(coinbase) = bitcoin::consensus::deserialize::<Transaction>(m.coinbase_tx.as_ref())
+    else {
+        return rejected("bad-cb-decode");
+    };
     let mut txs = Vec::with_capacity(m.wtxid_list.len());
     let mut missing = Vec::new();
     for (pos, w) in m.wtxid_list.iter().enumerate() {
@@ -58,7 +79,7 @@ fn check(chain: &ChainHub, m: &ValidateCustomJob) -> io::Result<Verdict> {
         let tx = match supplied.get(&w) {
             Some(raw) => match bitcoin::consensus::deserialize::<Transaction>(raw) {
                 Ok(tx) => Some(tx),
-                Err(_) => return Ok(Verdict::Rejected("bad-missing-tx".into())),
+                Err(_) => return rejected("bad-missing-tx"),
             },
             None => chain
                 .mempool()
@@ -72,7 +93,6 @@ fn check(chain: &ChainHub, m: &ValidateCustomJob) -> io::Result<Verdict> {
     if !missing.is_empty() {
         return Ok(Verdict::Missing(missing));
     }
-    let next = template::next_header(chain)?;
     let mut leaves = Vec::with_capacity(1 + txs.len());
     leaves.push(coinbase.compute_txid().to_byte_array());
     leaves.extend(txs.iter().map(|tx| tx.compute_txid().to_byte_array()));
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index 8c78f5f8d..d86143dd0 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1,6 +1,7 @@
 use crate::messages::{
-    ValidateCustomJob, ValidateCustomJobMissingTransactions, ValidateCustomJobSuccess,
-    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS,
+    ValidateCustomJob, ValidateCustomJobError, ValidateCustomJobMissingTransactions,
+    ValidateCustomJobSuccess, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
+    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS,
     MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, REQUIRES_JOB_VALIDATION,
 };
 use crate::test_chain::{padded_chain_with, shared_regtest, TestChain};
@@ -24,7 +25,8 @@ use rbitcoin_store::merkle_root_from_txids;
 use std::sync::Arc;
 use std::time::Duration;
 use template_distribution_sv2::{
-    NewTemplate, RequestTransactionDataSuccess, SetNewPrevHash, MESSAGE_TYPE_NEW_TEMPLATE,
+    NewTemplate, RequestTransactionDataError, RequestTransactionDataSuccess, SetNewPrevHash,
+    MESSAGE_TYPE_NEW_TEMPLATE, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR,
     MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS, MESSAGE_TYPE_SET_NEW_PREV_HASH,
 };
 
@@ -1214,6 +1216,14 @@ impl Job {
     }
 }
 
+async fn expect_job_error(c: &mut TpClient, request_id: u32, code: &str) {
+    let mut f = recv_in_time(c).await;
+    assert_eq!(f.msg_type, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, "{code}");
+    let e: ValidateCustomJobError = binary_sv2::from_bytes(&mut f.payload).expect("decode");
+    assert_eq!(e.request_id, request_id);
+    assert_eq!(e.error_code.as_utf8_or_hex(), code);
+}
+
 async fn expect_job_success(c: &mut TpClient) -> ValidateCustomJobSuccess {
     let mut f = recv_in_time(c).await;
     assert_eq!(
@@ -1314,3 +1324,72 @@ async fn validate_custom_job_asks_for_and_accepts_missing_transactions() {
 
     tp.shutdown().await;
 }
+
+/// §4.1 and §4.4: everything in a job comes from a JDC. The checks run in
+/// order before any mempool lookup or transaction decode: a prev hash off
+/// the tip, a repeated wtxid, a supplied tx nobody declared (or one that
+/// does not decode), an undecodable coinbase, then the proposal check's own
+/// reject string. While the tip is stale (IBD) every job is
+/// `job-validation-unavailable`. Nothing is retained on an error.
+#[tokio::test(flavor = "multi_thread")]
+async fn validate_custom_job_rejects_untrusted_input_in_order() {
+    let tc = shared_regtest(2);
+    let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
+    let a = spend(tc.coinbases[0], 3_000, cheap.clone());
+    let b = spend(tc.coinbases[1], 2_000, cheap);
+    for tx in [&a, &b] {
+        tc.mempool.accept_tx(tx).expect("mempool accept");
+    }
+    let (tp, mut c) = connect_tp(&tc, REQUIRES_JOB_VALIDATION).await;
+    let height = tc.chain.query.tip_height().unwrap().0 + 1;
+    let subsidy = block_subsidy(height, &tc.chain.params) as u64;
+    let coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
+
+    // The padded tip is far in the past: the node is in IBD.
+    Job::on_tip(&tc, 1, &coinbase, &[&a, &b]).send(&mut c).await;
+    expect_job_error(&mut c, 1, "job-validation-unavailable").await;
+    mock_live_tip(&tc);
+    c.coinbase_output_constraints(0, 0).await.unwrap();
+    let last = expect_template(&mut c, &tc, &[&a, &b], true).await;
+
+    let mut stale = Job::on_tip(&tc, 2, &coinbase, &[&a, &b]);
+    stale.prev_hash = [0xab; 32];
+    stale.send(&mut c).await;
+    expect_job_error(&mut c, 2, "stale-prevhash").await;
+
+    Job::on_tip(&tc, 3, &coinbase, &[&a, &a]).send(&mut c).await;
+    expect_job_error(&mut c, 3, "duplicate-wtxid").await;
+
+    let mut undeclared = Job::on_tip(&tc, 4, &coinbase, &[&a]);
+    undeclared.supplied = vec![serialize(&b)];
+    undeclared.send(&mut c).await;
+    expect_job_error(&mut c, 4, "bad-missing-tx").await;
+
+    let blob = vec![0xee; 40];
+    let mut garbage = Job::on_tip(&tc, 5, &coinbase, &[]);
+    garbage.wtxids = vec![sha256d::Hash::hash(&blob).to_byte_array()];
+    garbage.supplied = vec![blob];
+    garbage.send(&mut c).await;
+    expect_job_error(&mut c, 5, "bad-missing-tx").await;
+
+    let mut bad_cb = Job::on_tip(&tc, 6, &coinbase, &[&a, &b]);
+    bad_cb.coinbase = vec![0xcc; 20];
+    bad_cb.send(&mut c).await;
+    expect_job_error(&mut c, 6, "bad-cb-decode").await;
+
+    let fat = job_coinbase(height, subsidy + 5_001, &[&a, &b]);
+    Job::on_tip(&tc, 7, &fat, &[&a, &b]).send(&mut c).await;
+    expect_job_error(&mut c, 7, "bad-cb-amount").await;
+
+    c.request_transaction_data(last + 1).await.unwrap();
+    let mut f = recv_in_time(&mut c).await;
+    assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
+    let e: RequestTransactionDataError = binary_sv2::from_bytes(&mut f.payload).unwrap();
+    assert_eq!(
+        e.error_code.as_utf8_or_hex(),
+        "template-id-not-found",
+        "a rejected job must not take a template id"
+    );
+
+    tp.shutdown().await;
+}

From a0dec2aa75c5716a9d8d69ab58cb47aab25c3755 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Tue, 6 Oct 2026 17:28:43 -0400
Subject: [PATCH 06/19] test: pin a solution for a validated custom job
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/sv2-job-validation-draft.md §4.5: a SubmitSolution on the template id
from ValidateCustomJob.Success is assembled from the retained job and the
JDS's final coinbase (the extranonce where the placeholder stood), checked
against the job's target, and accepted through ChainHub::accept_block like
one for a pushed template; the tip advances to it. No production change:
a validated job is retained as the same Job a built template is, so
on_submit_solution already serves it. The journey pins that.

first_template takes the setup flags and connects through connect_tp, so
the solution journeys share one session bootstrap.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/template_tests.rs | 115 ++++++++++++++++------
 1 file changed, 86 insertions(+), 29 deletions(-)

diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index d86143dd0..9c2f17bea 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -433,31 +433,18 @@ struct FirstTemplate {
     coinbase: Vec<u8>,
 }
 
-async fn first_template(tc: &TestChain) -> FirstTemplate {
-    first_template_every(tc, TEMPLATE_INTERVAL).await
+async fn first_template(tc: &TestChain, flags: u32) -> FirstTemplate {
+    first_template_every(tc, flags, TEMPLATE_INTERVAL).await
 }
 
 /// [`first_template`] on a session that checks fees every `template_interval`.
-async fn first_template_every(tc: &TestChain, template_interval: Duration) -> FirstTemplate {
+async fn first_template_every(
+    tc: &TestChain,
+    flags: u32,
+    template_interval: Duration,
+) -> FirstTemplate {
     mock_live_tip(tc);
-    let tp = run_sv2_tp(Sv2TpConfig {
-        listen: "127.0.0.1:0".parse().unwrap(),
-        chain: Arc::clone(&tc.chain),
-        authority_secret: [7; 32],
-        cert_validity: Duration::from_secs(3600),
-        stale_grace: Duration::from_secs(10),
-        setup_timeout: SETUP_TIMEOUT,
-        write_timeout: WRITE_TIMEOUT,
-        fee_delta: FEE_DELTA,
-        template_interval,
-    })
-    .await
-    .expect("listen");
-    let mut c = TpClient::connect(tp.local_addr, tp.authority_pubkey)
-        .await
-        .expect("handshake");
-    c.setup_connection(2, 2, 2, 0).await.unwrap();
-    c.recv().await.expect("setup reply");
+    let (tp, mut c) = connect_tp_every(tc, flags, template_interval).await;
     c.coinbase_output_constraints(0, 0).await.unwrap();
 
     let mut f = recv_in_time(&mut c).await;
@@ -525,7 +512,7 @@ async fn submit_solution_checks_pow_before_accept() {
         version,
         mut header,
         coinbase,
-    } = first_template(&tc).await;
+    } = first_template(&tc, 0).await;
     let tip = header.prev_blockhash;
 
     while header.validate_pow(header.target()).is_ok() {
@@ -575,7 +562,7 @@ async fn submit_solution_without_coinbase_witness_is_accepted() {
         version,
         mut header,
         coinbase,
-    } = first_template(&tc).await;
+    } = first_template(&tc, 0).await;
     let mut bare: Transaction = bitcoin::consensus::deserialize(&coinbase).unwrap();
     bare.input[0].witness = Witness::new();
     while header.validate_pow(header.target()).is_err() {
@@ -612,7 +599,7 @@ async fn submit_solution_without_witness_commitment_is_accepted() {
         version,
         mut header,
         coinbase,
-    } = first_template(&tc).await;
+    } = first_template(&tc, 0).await;
     let mut bare: Transaction = bitcoin::consensus::deserialize(&coinbase).unwrap();
     bare.input[0].witness = Witness::new();
     bare.output.truncate(1);
@@ -654,7 +641,7 @@ async fn submit_solution_ahead_of_the_rolled_time_is_accepted() {
         version,
         mut header,
         coinbase,
-    } = first_template(&tc).await;
+    } = first_template(&tc, 0).await;
     header.time += 5;
     while header.validate_pow(header.target()).is_err() {
         header.nonce += 1;
@@ -790,7 +777,7 @@ async fn same_prev_hash_template_keeps_the_sent_bits() {
         version,
         mut header,
         coinbase,
-    } = first_template(&tc).await;
+    } = first_template(&tc, 0).await;
 
     let spacing = tc.chain.params.btc.pow_target_spacing as u32;
     tc.chain
@@ -932,7 +919,7 @@ async fn fee_pushes_keep_older_same_tip_templates_solvable() {
         version,
         mut header,
         coinbase,
-    } = first_template_every(&tc, interval).await;
+    } = first_template_every(&tc, 0, interval).await;
 
     let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
     let mut txs = (0..3)
@@ -1094,7 +1081,7 @@ async fn fee_pushes_stay_an_interval_apart_under_steady_admission() {
 async fn idle_session_checks_each_interval_and_does_not_rebuild() {
     let tc = shared_regtest(0);
     let interval = Duration::from_millis(250);
-    let FirstTemplate { tp, c, .. } = first_template_every(&tc, interval).await;
+    let FirstTemplate { tp, c, .. } = first_template_every(&tc, 0, interval).await;
     let stats = tp.stats();
     assert_eq!(stats.builds.totals().0, 1, "the first template");
     tokio::time::sleep(4 * interval + interval / 2).await;
@@ -1110,6 +1097,15 @@ async fn idle_session_checks_each_interval_and_does_not_rebuild() {
 
 /// A live TP on `tc` with one session past `SetupConnection(flags)`.
 async fn connect_tp(tc: &TestChain, flags: u32) -> (crate::Sv2TpHandle, TpClient) {
+    connect_tp_every(tc, flags, TEMPLATE_INTERVAL).await
+}
+
+/// [`connect_tp`] on a TP that checks fees every `template_interval`.
+async fn connect_tp_every(
+    tc: &TestChain,
+    flags: u32,
+    template_interval: Duration,
+) -> (crate::Sv2TpHandle, TpClient) {
     let tp = run_sv2_tp(Sv2TpConfig {
         listen: "127.0.0.1:0".parse().unwrap(),
         chain: Arc::clone(&tc.chain),
@@ -1119,7 +1115,7 @@ async fn connect_tp(tc: &TestChain, flags: u32) -> (crate::Sv2TpHandle, TpClient
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
         fee_delta: FEE_DELTA,
-        template_interval: TEMPLATE_INTERVAL,
+        template_interval,
     })
     .await
     .expect("listen");
@@ -1393,3 +1389,64 @@ async fn validate_custom_job_rejects_untrusted_input_in_order() {
 
     tp.shutdown().await;
 }
+
+/// §4.5: a `SubmitSolution` on a validated job's template id is assembled
+/// from the retained job and the JDS's final coinbase (extranonce in place
+/// of the placeholder) and accepted like one for a pushed template.
+#[tokio::test(flavor = "multi_thread")]
+async fn submit_solution_for_a_validated_job_becomes_the_tip() {
+    let tc = shared_regtest(2);
+    let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
+    let a = spend(tc.coinbases[0], 3_000, cheap.clone());
+    let b = spend(tc.coinbases[1], 2_000, cheap);
+    for tx in [&a, &b] {
+        tc.mempool.accept_tx(tx).expect("mempool accept");
+    }
+    let FirstTemplate {
+        tp,
+        mut c,
+        template_id: last,
+        version,
+        header: sent,
+        ..
+    } = first_template(&tc, REQUIRES_JOB_VALIDATION).await;
+    let height = tc.chain.query.tip_height().unwrap().0 + 1;
+    let subsidy = block_subsidy(height, &tc.chain.params) as u64;
+    let mut coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
+    Job::on_tip(&tc, 1, &coinbase, &[&a, &b]).send(&mut c).await;
+    let ok = expect_job_success(&mut c).await;
+    assert_eq!(ok.template_id, last + 1);
+
+    let mut script_sig = bip34_height_script(height);
+    script_sig.extend_from_slice(&[0x42; 8]);
+    coinbase.input[0].script_sig = ScriptBuf::from_bytes(script_sig);
+    let mut leaves = vec![coinbase.compute_txid().to_byte_array()];
+    leaves.extend([&a, &b].iter().map(|tx| tx.compute_txid().to_byte_array()));
+    let mut header = bitcoin::block::Header {
+        merkle_root: bitcoin::TxMerkleNode::from_byte_array(merkle_root_from_txids(&leaves)),
+        ..sent
+    };
+    while header.validate_pow(header.target()).is_err() {
+        header.nonce += 1;
+    }
+    c.submit_solution(
+        ok.template_id,
+        version,
+        header.time,
+        header.nonce,
+        &serialize(&coinbase),
+    )
+    .await
+    .unwrap();
+    let f = recv_in_time(&mut c).await;
+    assert_eq!(
+        f.msg_type, MESSAGE_TYPE_NEW_TEMPLATE,
+        "the new tip's template"
+    );
+    assert_eq!(
+        tc.chain.tip_header().unwrap().block_hash(),
+        header.block_hash()
+    );
+
+    tp.shutdown().await;
+}

From 548d8d34b8f265d2f1b6a49527bcbfe6be2c7260 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Tue, 6 Oct 2026 17:33:32 -0400
Subject: [PATCH 07/19] docs: plan D, job validation spec draft, changelog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/sv2-template-provider.md gains Plan D (custom job validation over
TDP) with D1–D7 as executed, the named RAM and CPU trades, and its risks
(no script execution on supplied txs, no operator opt-out, Success.flags
echo, retention shared with templates). The plan table, the SetupConnection
flag constraint, the per-type client frame cap, and Out of scope (the JDS
role stays out; its node backend is served) are brought current. The draft
spec is copied unchanged as docs/sv2-job-validation.md and owns the wire
contract until it lands upstream (docs/README.md row); the operator doc,
the COMPAT row, and a changelog.d fragment name the flag and what it
enables, plus getblocktemplate proposal mode now answering bad-cb-amount.

messages is crate-private: no other crate reads it, and crate pub is the
cross-crate graph only.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 COMPAT.md                           |   2 +-
 changelog.d/sv2-job-validation.md   |  15 ++
 crates/rbitcoin-sv2/src/lib.rs      |   2 +-
 crates/rbitcoin-sv2/src/messages.rs |  20 +-
 crates/rbitcoin-sv2/src/session.rs  |   2 +-
 docs/README.md                      |   3 +-
 docs/operator/interfaces.md         |   7 +
 docs/sv2-job-validation.md          | 367 ++++++++++++++++++++++++++++
 docs/sv2-template-provider.md       | 223 ++++++++++++++++-
 9 files changed, 614 insertions(+), 27 deletions(-)
 create mode 100644 changelog.d/sv2-job-validation.md
 create mode 100644 docs/sv2-job-validation.md

diff --git a/COMPAT.md b/COMPAT.md
index a72415040..61beab277 100644
--- a/COMPAT.md
+++ b/COMPAT.md
@@ -72,7 +72,7 @@ Full `/tx/:txid` JSON still has `vin[]`. Electrum has no outspend-vin surface.
 | Package submit | RPC `submitpackage` / Esplora `POST /txs/package` (no P2P package command) | BIP331 wire |
 | Pruning / GUI | Unpruned: `seqsigwit.body`. `--prune-seqsigwit`: watermark + `NETWORK_LIMITED`, kept witness is 288 height files under `store/seqsigwit.window/` plus a RAM cap (`--prune-seqsigwit-ram-threshold-bytes`, `0` = files only). Not a rolling stem. Not Core `-prune` of headers/txout | Supported |
 | Mining template RPC | `getblocktemplate` / `getmininginfo` / `prioritisetransaction` (selector; no stratum) | GBT + stratum / pool stack |
-| SV2 Template Distribution | In-process TDP v2 server over Noise NX (`--sv2-tp-listen`, default off): `NewTemplate` / `SetNewPrevHash` per tip, `NewTemplate` on a same-tip fee gain (`--sv2-tp-fee-delta`, `--sv2-tp-template-interval`, sv2-tp defaults), `RequestTransactionData`, `SubmitSolution` → block accept. No templates during IBD; every template on the tip kept, up to 64 per session. No plaintext, no pool / JD roles | No TDP in Core; sv2-apps `bitcoin-core-sv2` bridges Core's IPC mining interface to TDP |
+| SV2 Template Distribution | In-process TDP v2 server over Noise NX (`--sv2-tp-listen`, default off): `NewTemplate` / `SetNewPrevHash` per tip, `NewTemplate` on a same-tip fee gain (`--sv2-tp-fee-delta`, `--sv2-tp-template-interval`, sv2-tp defaults), `RequestTransactionData`, `SubmitSolution` → block accept; `ValidateCustomJob` for a Job Declarator Server's node backend (proposed TDP messages, sv2-spec#217, `SetupConnection` flag bit 0). No templates during IBD; every template on the tip kept, up to 64 per session. No plaintext, no pool / JD roles | No TDP in Core; sv2-apps `bitcoin-core-sv2` bridges Core's IPC mining interface to TDP |
 | Wallets | Electrum clients (requires `--sh-index`) | Descriptor + legacy |
 | Scripthash index | Optional (`--sh-index`, default **off**); bulk at tip when on | External ElectrumX / Fulcrum; Core `-txindex` is different (txid→block) |
 | JSON-RPC | Documented **subset** ([`docs/rpc.md`](./docs/rpc.md)); Bearer token or opt-in Core cookie (`--rpc-cookie-file`), no `--rpcuser` / `--rpcpassword`; `rbitcoin-cli`. `--rpc-work-queue` defaults to **16** (HTTP occupancy, 503 when full; **0** is that default); a JSON-RPC array is one POST | Full Core RPC; `-rpcworkqueue` is in-flight HTTP jobs (503) |
diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
new file mode 100644
index 000000000..f0e1b8580
--- /dev/null
+++ b/changelog.d/sv2-job-validation.md
@@ -0,0 +1,15 @@
+Added
+
+- **SV2 TP: custom job validation for Job Declarator Servers.** A TDP
+  client that sets `SetupConnection` flag bit 0 (`REQUIRES_JOB_VALIDATION`)
+  can send `ValidateCustomJob` (proposed TDP messages 0x77–0x7a,
+  sv2-spec#217). The node resolves the declared wtxids against its mempool,
+  asks for the ones it lacks, checks the job as a block on its tip, and
+  answers the fee total with a template id that `SubmitSolution` accepts
+  like one of the node's own templates. Stale, duplicated, or undeclared
+  input is refused before anything is decoded.
+
+Changed
+
+- **`getblocktemplate` proposal mode rejects an overpaying coinbase** with
+  `bad-cb-amount`, as Bitcoin Core does.
diff --git a/crates/rbitcoin-sv2/src/lib.rs b/crates/rbitcoin-sv2/src/lib.rs
index f88506cc5..be7fe4632 100644
--- a/crates/rbitcoin-sv2/src/lib.rs
+++ b/crates/rbitcoin-sv2/src/lib.rs
@@ -4,7 +4,7 @@
 //! `docs/sv2-template-provider.md`.
 
 mod job;
-pub mod messages;
+mod messages;
 mod session;
 mod template;
 pub mod testutil;
diff --git a/crates/rbitcoin-sv2/src/messages.rs b/crates/rbitcoin-sv2/src/messages.rs
index cdeaabd0f..17a850f64 100644
--- a/crates/rbitcoin-sv2/src/messages.rs
+++ b/crates/rbitcoin-sv2/src/messages.rs
@@ -1,4 +1,4 @@
-//! Job-validation extension to TDP (`docs/sv2-job-validation-draft.md` §3–5):
+//! Job-validation extension to TDP (`docs/sv2-job-validation.md` §3–5):
 //! the `SetupConnection` flag and the four `ValidateCustomJob` messages a
 //! Job Declarator Server uses to have this TP check a custom job.
 
@@ -6,18 +6,18 @@ use binary_sv2::{Deserialize, Seq064K, Serialize, Str0255, B016M, B064K, U256};
 
 /// `SetupConnection.flags` bit 0: the client intends to send
 /// [`ValidateCustomJob`]. The only TDP flag this TP accepts.
-pub const REQUIRES_JOB_VALIDATION: u32 = 1 << 0;
+pub(crate) const REQUIRES_JOB_VALIDATION: u32 = 1 << 0;
 
-pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB: u8 = 0x77;
-pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS: u8 = 0x78;
-pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS: u8 = 0x79;
-pub const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR: u8 = 0x7a;
+pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB: u8 = 0x77;
+pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS: u8 = 0x78;
+pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS: u8 = 0x79;
+pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR: u8 = 0x7a;
 
 /// Client → TP: is this custom job a consensus-valid block on the TP tip?
 /// `transaction_list` carries the txs a prior
 /// [`ValidateCustomJobMissingTransactions`] asked for, in that order.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub struct ValidateCustomJob<'decoder> {
+pub(crate) struct ValidateCustomJob<'decoder> {
     pub request_id: u32,
     pub prev_hash: U256<'decoder>,
     pub version: u32,
@@ -28,7 +28,7 @@ pub struct ValidateCustomJob<'decoder> {
 
 /// TP → client: 0-indexed positions in `wtxid_list` the TP cannot resolve.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub struct ValidateCustomJobMissingTransactions<'decoder> {
+pub(crate) struct ValidateCustomJobMissingTransactions<'decoder> {
     pub request_id: u32,
     pub unknown_tx_position_list: Seq064K<'decoder, u16>,
 }
@@ -36,7 +36,7 @@ pub struct ValidateCustomJobMissingTransactions<'decoder> {
 /// TP → client: the job is valid and retained under `template_id`, which
 /// shares the `NewTemplate.template_id` namespace.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub struct ValidateCustomJobSuccess {
+pub(crate) struct ValidateCustomJobSuccess {
     pub request_id: u32,
     pub template_id: u64,
     pub fees: u64,
@@ -44,7 +44,7 @@ pub struct ValidateCustomJobSuccess {
 
 /// TP → client: the job was not validated.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub struct ValidateCustomJobError<'decoder> {
+pub(crate) struct ValidateCustomJobError<'decoder> {
     pub request_id: u32,
     pub error_code: Str0255<'decoder>,
     pub error_details: B064K<'decoder>,
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index 33a82c7b0..a59dfe9af 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -599,7 +599,7 @@ fn setup_error(m: &SetupConnection) -> Option<(u32, &'static str)> {
     if !(m.min_version..=m.max_version).contains(&TDP_VERSION) {
         return Some((0, ERROR_CODE_SETUP_CONNECTION_PROTOCOL_VERSION_MISMATCH));
     }
-    // sv2-job-validation-draft §3 defines bit 0; every other set bit is
+    // docs/sv2-job-validation.md §3 defines bit 0; every other set bit is
     // unsupported.
     if m.flags & !REQUIRES_JOB_VALIDATION != 0 {
         return Some((
diff --git a/docs/README.md b/docs/README.md
index 4b7bdf2ab..5abe3e602 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -51,7 +51,8 @@ into `AGENTS.md`.
 | [`core-functional.md`](./core-functional.md) | Core v31.1 functional harness. |
 | [`overlay-functional.md`](./overlay-functional.md) | Private Tor / i2pd / cjdns mesh harness (labeled / nightly). |
 | [`how-we-plan.md`](./how-we-plan.md) | Agent contract (cycle, Agent RAM, keep-compiling), then human rationale. |
-| [`sv2-template-provider.md`](./sv2-template-provider.md) | SV2 Template Distribution Protocol server roadmap (**Q-64**): Step 0 finding and plans A–C. Live flags/COMPAT rows land in OPERATOR/COMPAT with the plan that ships them. |
+| [`sv2-template-provider.md`](./sv2-template-provider.md) | SV2 Template Distribution Protocol server roadmap (**Q-64**): Step 0 finding and plans A–D. Live flags/COMPAT rows land in OPERATOR/COMPAT with the plan that ships them. |
+| [`sv2-job-validation.md`](./sv2-job-validation.md) | Proposed TDP messages for JDS job validation (`ValidateCustomJob`, sv2-spec#217); owner of the wire contract until it lands upstream. Plan D in `sv2-template-provider.md` is the implementation. |
 | [`releases.md`](./releases.md) | Tag `vX.Y.Z`, `vX.Y.x` patch line, `.99` bump, Highlights / GitHub notes. |
 | [`code-shape.md`](./code-shape.md) | Control flow, types, naming, composition (CONTRIBUTING principle 10). Named extracts: quality.md **Q-61** (Completed). Clippy: no workspace `allow` list; leftover lints are site-local with a reason. |
 | [`quality.md`](./quality.md) | Living quality roadmap (Open + Won't-fix + Parked + Protect). |
diff --git a/docs/operator/interfaces.md b/docs/operator/interfaces.md
index 599762447..98647a3a8 100644
--- a/docs/operator/interfaces.md
+++ b/docs/operator/interfaces.md
@@ -305,6 +305,13 @@ template build per session. An undecodable
 that misses the template target is logged and dropped. A `header_timestamp`
 outside the sv2 rolling window (a miner clock running ahead) is logged and
 still submitted; block validation applies the consensus time rules.
+A client that sets `SetupConnection` flag bit 0 (`REQUIRES_JOB_VALIDATION`)
+can send `ValidateCustomJob` (proposed TDP messages, sv2-spec#217): the node
+checks a Job Declarator Server's declared job as a block on its tip (no proof
+of work; no script checks beyond what mempool admission already ran), asks for
+the transactions it lacks, and retains a valid job under a template id that
+`SubmitSolution` accepts. Without the flag the messages are ignored. There is
+no operator switch; the flag is per session.
 
 There is no client authentication. Noise NX proves the TP's authority key
 to the client, not the client to the TP, so anyone who can reach the port
diff --git a/docs/sv2-job-validation.md b/docs/sv2-job-validation.md
new file mode 100644
index 000000000..7bdf9a8f1
--- /dev/null
+++ b/docs/sv2-job-validation.md
@@ -0,0 +1,367 @@
+# Stratum V2: Custom Job Validation over the Template Distribution Protocol
+
+Draft for discussion on [sv2-spec#217](https://github.com/stratum-mining/sv2-spec/issues/217).
+Written as new core Template Distribution Protocol (TDP) messages so it can be
+folded into `07-Template-Distribution-Protocol.md` and `08-Message-Types.md`.
+Section 6 lists the open questions, including the extension alternative.
+
+Terms like "MUST," "MUST NOT," "REQUIRED," etc., follow RFC2119 standards.
+
+## 0. Abstract
+
+Under Full-Template mode a Job Declarator Server (JDS) has to check that a
+Custom Job declared by a Job Declarator Client (JDC) would produce a valid
+block, and later propagate the block when JDC sends `PushSolution`. The
+specification leaves how JDS talks to its Bitcoin node undefined ("RPCs (or
+similar)", Section 6.1).
+
+This document adds four TDP messages and one `SetupConnection` flag so that a
+JDS can validate a declared Custom Job, and later submit its solution, through
+any Template Provider (TP) over the authenticated TDP connection it already
+uses. The exchange mirrors the flow the Job Declaration Protocol already
+imposes on JDS: look transactions up by `wtxid`, ask JDC for the ones nobody
+has, validate, and submit the solution by reference.
+
+## 1. Motivation
+
+- Section 6.1 names the JDS-to-node link but does not specify it. The
+  reference implementation (`sv2-apps`) validates Custom Jobs only through
+  Bitcoin Core's multiprocess IPC mining interface (`checkBlock`,
+  `getTransactionsByWitnessID`). A Pool configured with a standalone TP
+  (`Sv2Tp`) refuses to run a JDS. Nodes that are not Bitcoin Core, and Bitcoin
+  Core nodes on another host, cannot back a JDS today.
+- An earlier JSON-RPC JDS backend (`getrawmempool` polling, `getrawtransaction`,
+  `submitblock`) was removed in `sv2-apps#299` because of polling cost and
+  lock contention. A push-based, binary, authenticated channel already exists
+  between JDS and TP: TDP.
+- The Bitcoin Core and SRI developers have converged on a node-side flow for
+  this problem (`TxCollection`, bitcoin/bitcoin#35671, discussed in
+  `sv2-apps#609`): collect transactions by `wtxid`, report the unknown ones,
+  add the missing ones, validate, then submit the solution by reference
+  without resending the block. This proposal is that flow expressed as TDP
+  messages, so `sv2-tp` can serve it on top of Core IPC, and a node with a
+  native TP can serve it directly.
+- Validation by `wtxid` position lets JDS relay `ProvideMissingTransactions`
+  and `ProvideMissingTransactions.Success` payloads between JDC and TP without
+  parsing them, as Sections 6.4.7 and 6.4.8 already require.
+
+## 2. Overview
+
+```
+JDC                      JDS                             TP
+ |-- DeclareMiningJob --->|                               |
+ |                        |-- ValidateCustomJob --------->|  wtxid_list, coinbase, no txs
+ |                        |<- ValidateCustomJob.MissingTransactions   (only if TP lacks some)
+ |<- ProvideMissingTransactions                           |
+ |-- ProvideMissingTransactions.Success ->|               |
+ |                        |-- ValidateCustomJob --------->|  same job + transaction_list
+ |                        |<- ValidateCustomJob.Success --|  template_id, fees
+ |<- DeclareMiningJob.Success             |               |
+ ...
+ |-- PushSolution ------->|                               |
+ |                        |-- SubmitSolution(template_id)>|  existing 7.8 message
+```
+
+- `ValidateCustomJob` is stateless on the server side across the
+  missing-transactions round trip: the second request repeats the job and adds
+  the transactions. The TP MUST NOT require any state from the first request.
+- `ValidateCustomJob.Success` assigns a `template_id` from the same namespace as
+  `NewTemplate.template_id`. The solution is then sent with the existing
+  `SubmitSolution` message (Section 7.8). No new submission message is needed.
+- A JDS connection is an ordinary TDP client. It MUST still open with
+  `CoinbaseOutputConstraints` (Section 7.2) and will receive `NewTemplate` and
+  `SetNewPrevHash` messages, which it MAY ignore or use to prefetch
+  transaction data for its own cache.
+
+## 3. `SetupConnection` Flags for Template Distribution Protocol
+
+Replaces the text of Section 7.1 ("No flags are yet defined").
+
+Flags usable in `SetupConnection.flags` and `SetupConnection.Error.flags`
+(Client -> Server):
+
+| Field Name              | Bit | Description                                                                                                                                 |
+| ----------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| REQUIRES_JOB_VALIDATION | 0   | The client intends to send `ValidateCustomJob`. A server that does not support it MUST reply `SetupConnection.Error` with `unsupported-feature-flags`. |
+
+Flags in `SetupConnection.Success.flags` (Server -> Client):
+
+| Field Name              | Bit | Description                                                                 |
+| ----------------------- | --- | --------------------------------------------------------------------------- |
+| REQUIRES_JOB_VALIDATION | 0   | Set when the server accepted the client's `REQUIRES_JOB_VALIDATION` request |
+
+A client MUST NOT send `ValidateCustomJob` on a connection where this flag was
+not set and accepted.
+
+## 4. Messages
+
+### 4.1 `ValidateCustomJob` (Client -> Server)
+
+Asks the Template Provider whether a Custom Job, declared to the client via
+`DeclareMiningJob`, would produce a consensus-valid block on top of the
+server's current chain tip.
+
+| Field Name       | Data Type        | Description                                                                                                                                                                                                                                                                              |
+| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| request_id       | U32              | Unique identifier for pairing the response                                                                                                                                                                                                                                               |
+| prev_hash        | U256             | Hash of the block the Custom Job builds on, as it would appear in the block header                                                                                                                                                                                                      |
+| version          | U32              | Block header version field as declared in `DeclareMiningJob.version`. BIP323 general-purpose bits are ignored by the server                                                                                                                                                              |
+| coinbase_tx      | B0_64K           | Full serialized coinbase transaction, with the extranonce region filled with placeholder bytes of the correct length. If the coinbase is a SegWit transaction, BIP141 fields (marker, flag, witness count, witness length, witness reserved value) MUST NOT be stripped                 |
+| wtxid_list       | SEQ0_64K[U256]   | `wtxid` of every transaction in the Custom Job, in block order, excluding the coinbase. Copied from `DeclareMiningJob.wtxid_list`                                                                                                                                                         |
+| transaction_list | SEQ0_64K[B0_16M] | Full transactions the server reported in `ValidateCustomJob.MissingTransactions`, in the order they were requested. Empty on the first request. Each transaction MUST be relayed exactly as received from JDC in `ProvideMissingTransactions.Success`, without parsing or re-encoding    |
+
+The client derives the extranonce length as the scriptSig length encoded in
+`DeclareMiningJob.coinbase_tx_prefix` minus the scriptSig bytes present in the
+prefix. This assumes the extranonce is the final part of the scriptSig, so
+`coinbase_tx_suffix` begins at `nSequence`. That is how `NewExtendedMiningJob`
+splits the coinbase in practice and what the reference JDS already assumes,
+but the Job Declaration Protocol does not state it; see Section 6. The
+placeholder value is irrelevant: the server does not
+check the merkle root or proof of work, and every other coinbase check (size,
+weight, BIP34 height push, output values, witness commitment) is independent
+of the extranonce bytes.
+
+The server resolves each `wtxid` against its mempool and against
+`transaction_list`. If any transaction is still unknown, it MUST reply
+`ValidateCustomJob.MissingTransactions`. Otherwise it MUST validate the job as
+a block on top of `prev_hash` with the following rules, and reply either
+`ValidateCustomJob.Success` or `ValidateCustomJob.Error`:
+
+- `prev_hash` MUST equal the server's current chain tip. Otherwise the server
+  MUST reply with error code `stale-prevhash`. The server MUST NOT accept a
+  job on a tip it has already left.
+- `wtxid_list` MUST contain no duplicates, and every entry of
+  `transaction_list` MUST hash to a `wtxid` that the server reported missing.
+  Otherwise reply `duplicate-wtxid` or `bad-missing-tx`. These checks MUST run
+  before any transaction is decoded or copied.
+- The server MUST apply every consensus check it would apply to a received
+  block except the proof-of-work check and the merkle-root check. This
+  includes: transaction validity and input availability against the UTXO set
+  and the mempool, transaction ordering, block weight and sigop limits with
+  `coinbase_tx` counted as sent, coinbase scriptSig length and BIP34 height,
+  coinbase output value not exceeding subsidy plus fees, and the BIP141
+  witness commitment computed over `wtxid_list` with the witness reserved
+  value taken from `coinbase_tx`. This is the check performed by
+  `getblocktemplate` in `proposal` mode and by Bitcoin Core's IPC
+  `checkBlock` with `checkMerkleRoot=false` and `checkPow=false`.
+- The server MUST NOT reject a consensus-valid job on local policy grounds
+  (standardness, minimum relay fee, mempool limits). Policy belongs to the
+  Pool, which can use `ValidateCustomJob.Success.fees` for it.
+- The server MUST set `nBits` from its own view of the chain and MAY use its
+  current time for `nTime` when it needs a header for contextual checks. The
+  client does not supply them.
+
+### 4.2 `ValidateCustomJob.MissingTransactions` (Server -> Client)
+
+The server does not know some of the transactions in `wtxid_list`. The client
+is expected to obtain them from JDC via `ProvideMissingTransactions` and send
+a new `ValidateCustomJob` with `transaction_list` filled.
+
+| Field Name               | Data Type     | Description                                                                                                                                                    |
+| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| request_id               | U32           | Identifier of the original `ValidateCustomJob` request                                                                                                           |
+| unknown_tx_position_list | SEQ0_64K[U16] | Positions in `wtxid_list` of the transactions the server lacks, 0-indexed, not including the coinbase. Same encoding as `ProvideMissingTransactions.unknown_tx_position_list` |
+
+The positions are relative to `wtxid_list`, which is a copy of
+`DeclareMiningJob.wtxid_list`, so the client can copy this field into
+`ProvideMissingTransactions.unknown_tx_position_list` unchanged, and copy
+`ProvideMissingTransactions.Success.transaction_list` into
+`ValidateCustomJob.transaction_list` unchanged.
+
+A server MAY reply `ValidateCustomJob.MissingTransactions` to a request whose
+`transaction_list` is non-empty, for example when a transaction left its
+mempool between the two requests. A client SHOULD bound how many times it
+retries one declaration.
+
+### 4.3 `ValidateCustomJob.Success` (Server -> Client)
+
+The job is consensus-valid on the server's current tip. The server has stored
+the job and will accept a `SubmitSolution` for it.
+
+| Field Name  | Data Type | Description                                                                                                                                                                            |
+| ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| request_id  | U32       | Identifier of the original `ValidateCustomJob` request                                                                                                                                  |
+| template_id | U64       | Server's identification of the validated job. Drawn from the same strictly increasing namespace as `NewTemplate.template_id`, so it can be used in `SubmitSolution` and `RequestTransactionData` |
+| fees        | U64       | Sum of the fees of the transactions in `wtxid_list`, in satoshis                                                                                                                       |
+
+The server MUST retain the validated job (its `wtxid_list`, the transactions
+it received in `transaction_list`, and `coinbase_tx` for size accounting)
+until a newer `ValidateCustomJob.Success` is sent on the same connection or
+the connection closes, whichever comes first. This matches the guarantee JDS
+gives JDC in Section 6.4.9: `PushSolution` is only guaranteed to be valid for
+the most recent declaration. The server SHOULD retain jobs validated against
+the previous tip for a short grace period after a tip change, as it does for
+its own templates.
+
+### 4.4 `ValidateCustomJob.Error` (Server -> Client)
+
+The job was not validated. The client decides what to tell JDC; it SHOULD map
+consensus rejections to `DeclareMiningJob.Error` and SHOULD NOT treat
+`stale-prevhash` on a tip the client has not yet seen as a JDC fault.
+
+| Field Name    | Data Type | Description                                            |
+| ------------- | --------- | ------------------------------------------------------ |
+| request_id    | U32       | Identifier of the original `ValidateCustomJob` request   |
+| error_code    | STR0_255  | Human-readable error code(s)                           |
+| error_details | B0_64K    | Optional data providing further details to given error |
+
+Recommended `error_code` values, in addition to the node's own BIP22-style
+rejection strings (`bad-txns-inputs-missingorspent`, `bad-cb-length`,
+`bad-witness-merkle-match`, `bad-blk-weight`, and so on):
+
+| error_code                | Meaning                                                              |
+| ------------------------- | -------------------------------------------------------------------- |
+| stale-prevhash            | `prev_hash` is not the server's current tip                           |
+| duplicate-wtxid           | `wtxid_list` contains the same `wtxid` more than once                |
+| bad-missing-tx            | An entry of `transaction_list` does not hash to a requested `wtxid`  |
+| job-validation-unavailable | The server cannot validate now (for example, initial block download) |
+
+### 4.5 `SubmitSolution` for validated jobs
+
+When the client receives `PushSolution` from JDC it MUST reconstruct the full
+coinbase (`coinbase_tx_prefix` || `extranonce` || `coinbase_tx_suffix`) and
+send `SubmitSolution` (Section 7.8) with `template_id` set to the value from
+`ValidateCustomJob.Success`, and `version`, `ntime`, `nonce` and `coinbase_tx`
+from the solution.
+
+The server MUST treat such a `SubmitSolution` as it treats one for its own
+templates: assemble the block from the retained job and the submitted
+coinbase, validate it fully, including proof of work and merkle root, and
+attempt to propagate it. `SubmitSolution.ntime` MUST satisfy the `ntime_start`
+rule of Section 7.8 relative to the latest `SetNewPrevHash` the server sent on
+this connection.
+
+A server MAY also answer `RequestTransactionData` for a validated job's
+`template_id`, returning the full transaction set in block order.
+
+## 5. Message Types
+
+Additions to Section 8, Template Distribution Protocol:
+
+| Message Type (8-bit) | channel_msg bit | Message Name                            |
+| -------------------- | --------------- | --------------------------------------- |
+| 0x77                 | 0               | ValidateCustomJob                       |
+| 0x78                 | 0               | ValidateCustomJob.MissingTransactions   |
+| 0x79                 | 0               | ValidateCustomJob.Success               |
+| 0x7a                 | 0               | ValidateCustomJob.Error                 |
+
+All four are core messages and carry `extension_type = 0x0000`.
+
+## 6. Design notes and open questions
+
+- **Core messages or an extension.** Issue 217 proposes a core TDP message.
+  The same four messages could instead be extension `0x0003`, negotiated with
+  `RequestExtensions` (extension `0x0001`) and framed with
+  `extension_type = 0x0003`. The `SetupConnection` flag in Section 3 gives
+  negotiation without requiring extension `0x0001` in TPs, which is why the
+  draft uses it. The field tables are identical either way.
+- **Extranonce position.** Section 4.1's placeholder construction needs the
+  extranonce to be the tail of the scriptSig. Either the Job Declaration
+  Protocol should state that `DeclareMiningJob.coinbase_tx_suffix` begins at
+  `nSequence`, or `DeclareMiningJob` should carry the extranonce size. The
+  reference JDS has the same dependency today when it rebuilds the coinbase
+  for Core's `checkBlock` (`sv2-apps#645`).
+- **Coinbase-only mode.** Out of scope. In Coinbase-only mode neither Pool nor
+  JDS learns the transaction set, so a node has nothing to validate beyond the
+  coinbase, which `SetCustomMiningJob` already carries to the Pool. A
+  zero-knowledge extension could later reuse `ValidateCustomJob.Success.fees`
+  as the quantity being proven.
+- **Node load.** Full block validation without proof of work is CPU-heavy and
+  in Bitcoin Core currently serialises on `cs_main`, so validations on a node
+  that also produces the Pool's templates can delay block processing
+  (`sv2-apps#120`). A server MAY process `ValidateCustomJob` requests
+  sequentially and MAY bound the number queued per connection; operators
+  SHOULD run a dedicated TP for job validation. A client SHOULD apply a
+  timeout before falling back.
+- **Untrusted input.** Everything in `ValidateCustomJob` originates from a
+  JDC. The server MUST enforce the `duplicate-wtxid` and `bad-missing-tx`
+  checks and the block weight limit before decoding or storing transactions,
+  so that a 32-byte `wtxid` cannot be amplified into a large allocation
+  (`sv2-apps#796`, `#795`).
+- **Why `fees` is in `Success`.** The Pool needs the fee revenue of a Custom
+  Job to compare the declared coinbase value against what the template is
+  worth (`sv2-apps#610`). The server computes it while checking the coinbase
+  output value, so returning it costs nothing.
+- **Why positions, not `wtxid`s, in `MissingTransactions`.** Section 6.4.7
+  uses positions, so the JDS relays the list unchanged. A `wtxid` list would
+  force the JDS to translate.
+- **Why no separate `SubmitBlock`.** The server already holds the validated
+  transaction set; resending up to 4 MB at block-find time only adds latency.
+  Reusing `SubmitSolution` is also what `TxCollection.makeTemplate` followed by
+  `BlockTemplate.submitSolution` does in Bitcoin Core.
+
+## 7. Implementation notes
+
+### 7.1 JDS
+
+| JDP event                            | TDP action                                                                    |
+| ------------------------------------ | ----------------------------------------------------------------------------- |
+| `DeclareMiningJob`                   | `ValidateCustomJob` with `wtxid_list` copied, `coinbase_tx` from prefix + placeholder + suffix, empty `transaction_list` |
+| `ValidateCustomJob.MissingTransactions` | `ProvideMissingTransactions` with the position list copied                  |
+| `ProvideMissingTransactions.Success` | `ValidateCustomJob` again with `transaction_list` copied                       |
+| `ValidateCustomJob.Success`          | `DeclareMiningJob.Success`; store `template_id` with the declaration           |
+| `ValidateCustomJob.Error`            | `DeclareMiningJob.Error` with the error code                                  |
+| `PushSolution`                       | `SubmitSolution(template_id, version, ntime, nonce, coinbase_tx)`              |
+
+No mempool mirror is needed on the JDS side. In `sv2-apps` this is a second
+`JobValidationEngine` implementation next to `BitcoinCoreIPCEngine`, and the
+Pool's "`[jds]` requires `BitcoinCoreIpc`" startup check becomes "requires
+`BitcoinCoreIpc` or a TP that accepted `REQUIRES_JOB_VALIDATION`".
+
+### 7.2 Template Provider on Bitcoin Core (`sv2-tp`)
+
+`ValidateCustomJob` maps onto `getTransactionsByWitnessID` (Core v32) for the
+lookup and `checkBlock(checkMerkleRoot=false, checkPow=false)` for validation,
+or onto `TxCollection` (`collectTxs`, `unknownTxPos`, `addMissingTxs`,
+`makeTemplate`) once bitcoin/bitcoin#35671 lands. `SubmitSolution` for a
+validated job maps onto `submitBlock` or `BlockTemplate.submitSolution`.
+
+### 7.3 Template Provider in a node
+
+A node with a native TP serves this from its own mempool lookup, block
+assembler and block acceptance path. For rbitcoin that is `rbitcoin-sv2` plus
+the `getblocktemplate` proposal check and the `submitblock` path, with no new
+dependency.
+
+## 8. Prior art
+
+- [sv2-spec#217](https://github.com/stratum-mining/sv2-spec/issues/217):
+  "consider adding a new TDP message for custom job validation" (plebhash,
+  2026-08-31, open, no comments). Proposes message `X`, `X.Error` triggering
+  `ProvideMissingTransactions`, `X.Success` gating `DeclareMiningJob.Success`,
+  and asks whether Coinbase-only mode could use it. This draft is a concrete
+  answer to it.
+- [sv2-spec#170](https://github.com/stratum-mining/sv2-spec/issues/170)
+  (closed): `DeclareMiningJob` moved from `txid` to `wtxid` so JDS cannot match
+  a transaction with a different witness. Names `getblocktemplate` `proposal`
+  and Core's `checkBlock()` as the two ways JDS checks a block.
+- [sv2-apps#120](https://github.com/stratum-mining/sv2-apps/issues/120)
+  (closed by #299): the thread where `checkBlock()` was chosen as the JDS
+  validation tool. Sjors: `checkBlock()` holds `cs_main`, so calls serialise
+  and should not run on the node that produces default templates. Also
+  records that `libbitcoinkernel` was considered and rejected.
+- [sv2-apps#268](https://github.com/stratum-mining/sv2-apps/issues/268) and
+  [bitcoin/bitcoin#34020](https://github.com/bitcoin/bitcoin/pull/34020)
+  (merged 2026-07-07, Core v32): `getTransactionsByWitnessID`, lookup by
+  `wtxid` with empty slots for unknown transactions.
+- [sv2-apps#609](https://github.com/stratum-mining/sv2-apps/issues/609) and
+  [bitcoin/bitcoin#35671](https://github.com/bitcoin/bitcoin/pull/35671)
+  (open): `TxCollection`. The combined flow written up there (collect by
+  `wtxid`, report unknown positions, add missing, `makeTemplate`, submit the
+  solution by reference) is the flow Sections 2 and 4 encode. The thread also
+  records the hazard of server-side state across the missing-transactions
+  round trip, which is why `ValidateCustomJob` is stateless until `Success`.
+- [sv2-apps#299](https://github.com/stratum-mining/sv2-apps/pull/299): JDS
+  refactor that removed the JSON-RPC backend and folded JDS into the Pool.
+  [sv2-apps#26](https://github.com/stratum-mining/sv2-apps/issues/26) gives the
+  reasons: per-second RPC polling and lock contention.
+- [sv2-apps#597](https://github.com/stratum-mining/sv2-apps/issues/597),
+  [#610](https://github.com/stratum-mining/sv2-apps/issues/610),
+  [#645](https://github.com/stratum-mining/sv2-apps/issues/645),
+  [#795](https://github.com/stratum-mining/sv2-apps/issues/795),
+  [#796](https://github.com/stratum-mining/sv2-apps/issues/796): JDS
+  hardening issues that shaped Section 4.1's rules (stale detection by
+  `prev_hash` only, payout versus fees, coinbase prefix reconstruction,
+  staging supplied transactions, duplicate `wtxid` amplification).
+- `06-Job-Declaration-Protocol.md` Section 6.1 ("RPCs (or similar)") and
+  Sections 6.4.7 to 6.4.9, whose encodings this draft copies.
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index e34bb5ec6..e7293b980 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -10,6 +10,7 @@ Cycle and step shape: [agent contract](./how-we-plan.md#agent-contract).
 | **A** | Landed. GBT and `generate` build from `MempoolHub::select_block_template` | none |
 | **B** | Landed. A Job Declarator Client mines a block through the node's TP | `--sv2-tp-listen`, `--sv2-tp-authority-sec` / `--sv2-tp-authority-sec-file`, `--sv2-tp-cert-validity`, `--sv2-tp-stale-grace` |
 | **C** | Landed. Templates refresh on fee gain with the tip unchanged | `--sv2-tp-fee-delta`, `--sv2-tp-template-interval` |
+| **D** | A Job Declarator Server validates custom jobs and submits their solutions through the TP ([`sv2-job-validation.md`](./sv2-job-validation.md)) | none (per-session `SetupConnection` flag) |
 
 B was not split further: a listener that serves templates without
 tip-change push or `SubmitSolution` makes miners work stale tips or lose
@@ -95,13 +96,18 @@ Do not copy them here.
 - Write deadline is per write call, not per frame, so a slow reader still
   receives a multi-MB `RequestTransactionData.Success`. The 30 s close is
   the operator page above.
-- Client frame cap: a client→TP payload over `MAX_CLIENT_PAYLOAD`
+- Client frame cap, per message type: a `ValidateCustomJob` payload over
+  `MAX_VALIDATE_CUSTOM_JOB_PAYLOAD` (~6.4 MB: 40 fixed bytes, a `B064K`
+  coinbase, 65535 wtxids, and a block's worth of `B016M` txs) closes the
+  session; every other client payload closes past `MAX_CLIENT_PAYLOAD`
   (65557 bytes: `SubmitSolution`'s 20 fixed bytes plus a full `B064K`
-  coinbase, the largest TDP client message) closes the session. codec_sv2
-  keeps the decrypted header length private and reads a frame one chunk at
-  a time, so the reader counts encrypted bytes per frame and closes before
-  reading the chunk that would pass the cap. A session buffers at most
-  ~64 KiB of client frame instead of the ~16 MB the 24-bit length allows.
+  coinbase). codec_sv2 decrypts the header into a private buffer and reads
+  a frame one chunk at a time, so the type is only known with the whole
+  frame: the reader counts encrypted bytes per frame against the larger
+  cap and closes before reading the chunk that would pass it, then applies
+  the per-type cap once the frame is whole. Named RAM trade: one in-flight
+  client frame of ≤ ~6.4 MB per session, ≤ ~51 MB at `MAX_SESSIONS`,
+  instead of the ~16 MB the 24-bit length allows.
 - Per-session budget: weight `MAX_BLOCK_WEIGHT − max(1168 +
   4·coinbase_output_max_additional_size, 2000)` WU (sv2-spec 07 §7.1);
   sigops start at `coinbase_output_max_additional_sigops` (Core
@@ -109,9 +115,10 @@ Do not copy them here.
   reserve). Each client sizes its own templates.
 - Noise is the only mode (mandatory for remote TDP). No plaintext operator
   flag; tests drive the shipped Noise path.
-- TDP defines no `SetupConnection` flags: nonzero `flags` →
-  `SetupConnection.Error` echoing the full unsupported set; `protocol != 2`
-  or no version-2 overlap → Error and close.
+- The only `SetupConnection` flag is `REQUIRES_JOB_VALIDATION` (bit 0,
+  Plan D), echoed in `Success.flags`; any other set bit →
+  `SetupConnection.Error` echoing the full set; `protocol != 2` or no
+  version-2 overlap → Error and close.
 - `template_id` strictly increasing per session.
 - Coinbase split (sv2-spec 07 §7.2): `coinbase_prefix` is the BIP34 height
   push (≤ 8 bytes, start of scriptSig); `coinbase_tx_value_remaining` =
@@ -146,10 +153,12 @@ Do not copy them here.
 
 ## Out of scope
 
-Mining Protocol server (channels), Job Declaration **Server**, SV1↔SV2
-translator proxy, Job Declarator Client, weak-block targets below nBits,
-extension negotiation, per-IP metering/rate limits. None of these ship;
-nothing here precludes a later JD-server plan.
+Mining Protocol server (channels), Job Declaration **Server** (Plan D
+serves its node backend — job validation and solution submission over
+TDP — not the JDP role itself), SV1↔SV2 translator proxy, Job Declarator
+Client, weak-block targets below nBits, extension negotiation, per-IP
+metering/rate limits. None of these ship; nothing here precludes a later
+JD-server plan.
 
 Core's IPC mining interface (`waitNext`) is also out: TDP push covers
 these clients, and polling clients already have GBT longpoll and the
@@ -559,6 +568,194 @@ when fees rise enough to matter, throttled. Requires Plan B.
 
 ---
 
+## Plan D — Custom job validation (TDP `ValidateCustomJob`)
+
+**Goal:** a Job Declarator Server in Full-Template mode checks a JDC's
+`DeclareMiningJob` against this node over the TDP connection it already
+holds, fetches the transactions the node lacks, and submits the found block
+by `template_id`. Wire contract: [`sv2-job-validation.md`](./sv2-job-validation.md)
+(proposed TDP messages 0x77–0x7a and `SetupConnection` flag bit 0, for
+sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
+`REQUIRES_JOB_VALIDATION`.
+
+### D1 — Block proposal check on `ChainHub`
+
+- **Contract:** `ChainHub::check_block_proposal(&Block) -> Result<u64,
+  String>` is Core `TestBlockValidity` for a GBT proposal or an SV2 job:
+  prev must be the tip (`inconclusive-not-best-prevblk`), `bad-diffbits`,
+  `time-too-old` / `time-too-new`, every spend against the block and the
+  confirmed chain, then structure (merkle, weight, sigops, BIP34 height,
+  witness commitment) and the coinbase priced at subsidy + fees
+  (`bad-cb-amount`, after CheckBlock as in Core's ConnectBlock). `Ok` is
+  the fee total. No PoW, no scripts, no UTXO write.
+- **Red:** `cargo test -p rbitcoin-net --lib check_block_proposal` — tip
+  child passes, other parent rejects, `bad-cb-amount` after structure,
+  `Ok(fees)`; `rbitcoin-rpc` `methods_tests` pins GBT proposal mode
+  answering `bad-cb-amount`.
+- **Green:** the check moves from the RPC crate onto the hub (a move:
+  `check_block_proposal_with` keeps the explicit-inputs form for callers
+  with a `Query` but no hub); the spend loop then returns Σ(inputs −
+  outputs).
+- **Verify:** both filters.
+
+### D2 — Messages and the setup flag
+
+- **Contract:** `messages.rs` carries `ValidateCustomJob`,
+  `.MissingTransactions`, `.Success`, `.Error` (0x77–0x7a) as binary_sv2
+  structs, and `REQUIRES_JOB_VALIDATION`. Setup accepts bit 0 and echoes
+  it; any other set bit is still `unsupported-feature-flags`.
+- **Red:** `job_validation_messages_round_trip`;
+  `setup_connection_success_errors_and_session_cap` gains the flag case.
+- **Green:** the structs and the mask in `setup_error`.
+
+### D3 — Client frame cap per message type
+
+- **Contract:** the [Constraints](#constraints-all-plans) frame cap, per
+  type. `ValidateCustomJob` may carry a block's worth of transactions;
+  every other client type still closes past 65557 bytes.
+- **Red:** `oversized_client_frame_closes_the_session` — a 200 KiB
+  `ValidateCustomJob` keeps the session, a 200 KiB `SubmitSolution` and a
+  `ValidateCustomJob` over its cap close it.
+- **Green:** `FrameCap { max_frame, payload: fn(u8) -> usize }`: read
+  against the largest client message, apply the per-type cap once whole.
+- **RAM trade:** one in-flight client frame of ≤ ~6.4 MB per session,
+  ≤ ~51 MB at `MAX_SESSIONS`.
+
+### D4 — ValidateCustomJob happy path
+
+- **Contract:** on a session that negotiated the flag, a
+  `ValidateCustomJob` whose `prev_hash` is the tip, whose `wtxid_list` is
+  all in the mempool, and whose placeholder coinbase pays ≤ subsidy + fees
+  is answered `Success{request_id, template_id, fees}`: `template_id` is
+  the next id in the session's counter, `fees` the sum over the declared
+  txs. The job is retained exactly like a template, so
+  `RequestTransactionData` returns the declared txs in block order and
+  `SubmitSolution` finds it. Without the flag the message is ignored (the
+  D3 journey already pins that).
+- **Red:** `validate_custom_job_prices_and_retains_the_declared_job` —
+  two legacy spends with known fees in the mempool, a JDS-shaped coinbase
+  (BIP34 push + 8 placeholder bytes, payout = subsidy + fees, witness
+  commitment with a zero reserved value); `Success` with `fees` = 5 000
+  and `template_id` = last `NewTemplate` id + 1; the retained txs read
+  back. Red was a reply timeout (the message fell through to "ignoring").
+- **Green:** `job::validate` under `spawn_blocking` + `BlockingRegion`:
+  decode, resolve each wtxid with `MempoolHub::get_tx_by_wtxid`, header
+  `{version, tip, merkle root over the coinbase txid + declared txids,
+  time = max(now, MTP + 1), expected nBits, nonce 0}`,
+  `check_block_proposal`, `Ok(fees)` → retained under `last_id + 1`,
+  `Success`; a reject string → `Error{error_code}`. `Session` gains
+  `job_validation` from the setup flags (its first read is the dispatch
+  arm).
+- **Refactor:** the tip read (height, prev hash, time, bits) moves out of
+  `template::build` into `template::next_header` (a move; both paths call
+  it). `Template` splits into the `NewTemplate` coinbase split over a
+  `Job` — what a session retains under a template id (`merkle_path`,
+  `prev_hash`, `header_timestamp`, `n_bits`, `target`, `txs`) — so a
+  validated job carries no dead `NewTemplate` fields. The test client
+  gains a typed `send`.
+- **CPU trade:** one full proposal check per request on the blocking pool
+  (every spend against the chain, structure, weight, sigops, coinbase
+  value; no scripts, no PoW). A JDS sends one per declaration; a flood
+  costs blocking threads, not the reactor, and D3 bounds its RAM.
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
+
+### D5a — MissingTransactions round trip
+
+- **Contract:** a wtxid neither the mempool nor `transaction_list`
+  resolves → `MissingTransactions{request_id, unknown_tx_position_list}`
+  (0-indexed positions in `wtxid_list`); the same job resent with those
+  txs in `transaction_list` validates and the supplied txs are retained
+  with it. The TP keeps no state across the round trip.
+- **Red:** `validate_custom_job_asks_for_and_accepts_missing_transactions`
+  — one of two spends not in the mempool → `[1]`; resend with it
+  supplied → `Success` with the full fee sum and both txs retained. Red
+  was the session closing (D4's placeholder treated an unknown wtxid as
+  an error).
+- **Green:** resolution consults `transaction_list` first, keyed by
+  sha256d of the bytes as sent (the wtxid of that serialization, so no
+  decode before the slot is known), then the mempool; unknown positions
+  are collected and answered.
+- **Verify:** same filter.
+
+### D5b — Untrusted-input rejections
+
+- **Contract:** `Error.error_code` in this order, before any mempool
+  lookup or transaction decode: `job-validation-unavailable` while
+  `in_ibd()` (the template gate), `stale-prevhash`, `duplicate-wtxid`,
+  `bad-missing-tx` (a supplied tx whose hash is not in `wtxid_list`, or a
+  declared blob that does not decode), `bad-cb-decode` (this TP's code;
+  the draft has none for an undecodable coinbase), then the proposal
+  check's reject string (`bad-cb-amount` for an overpaying coinbase).
+  Nothing is retained and no id is taken on an error.
+- **Red:** `validate_custom_job_rejects_untrusted_input_in_order` — seven
+  sends on one session, then `RequestTransactionData(last + 1)` answers
+  `template-id-not-found`. Red was `Success` for the first send.
+- **Green:** the checks in `job::check`, ahead of resolution.
+- **Verify:** same filter.
+
+### D6 — SubmitSolution against a validated job
+
+- **Contract:** after `Success`, a `SubmitSolution{template_id, version,
+  ntime, nonce, coinbase_tx}` whose coinbase has the extranonce where the
+  placeholder stood and whose header meets the target is assembled from
+  the retained job, accepted through `ChainHub::accept_block`, and
+  becomes the tip, exactly like a solution for a pushed template.
+- **Red:** `submit_solution_for_a_validated_job_becomes_the_tip`. It
+  passed with no production change (a validated job is retained as the
+  same `Job` a built template is) and is kept as the pin; `first_template`
+  takes the setup flags and connects through `connect_tp`.
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib submit_solution`.
+
+### D7 — Docs and tidy
+
+- `messages` is crate-private (no other crate reads it yet; the
+  `rbitcoin-test` journey that will needs the re-export then). The draft
+  is copied unchanged as [`sv2-job-validation.md`](./sv2-job-validation.md)
+  and owns the wire contract until it lands upstream. Operator lines in
+  `docs/operator/interfaces.md`, the COMPAT row, and a `changelog.d`
+  fragment.
+
+### Test budget
+
+Units: the messages round trip, `rbitcoin-net` `check_block_proposal_*`,
+`rbitcoin-rpc` GBT proposal `bad-cb-amount`. Journeys in `rbitcoin-sv2`
+`template_tests`: four, each one TP and one session on the shared regtest
+pad. No `rbitcoin-test` node journey yet (follow-up with a JDS client).
+
+### Risks / follow-ups
+
+- No script execution in the proposal check: mempool txs were
+  script-checked at accept; `transaction_list` txs are not. A JDC can
+  declare a job with an invalid-script tx that validates here and fails
+  at `accept_block`. Core's `TestBlockValidity` runs scripts; running
+  `confirm_scripts_phase` on the supplied txs only is the follow-up.
+- No operator opt-out flag: any client that can reach the port may set
+  the flag and cost one proposal check per request. Bind to loopback or
+  firewall the port (the same advice as for templates).
+- `SetupConnection.Success.flags` echoes the request flags verbatim.
+- Retention shares the `MAX_RETAINED` (3) slots with templates: on one
+  tip a JDS session that also receives constraints rebuilds (or Plan C
+  pushes) can see a validated job evicted before its solution arrives.
+  The draft asks for retention until a newer `Success` or close; a slot
+  per kind, or a larger cap for flagged sessions, is a follow-up.
+- A job is retained with the nBits its validation header used. On
+  min-difficulty networks that can differ from the sent
+  `SetNewPrevHash.n_bits` (the Plan B risk); mainnet and signet bits
+  depend only on the prev hash.
+- `transaction_list` matching hashes the bytes as sent: a legacy tx
+  relayed in segwit-marker form hashes differently from its wtxid and is
+  `bad-missing-tx`. The draft requires the bytes exactly as JDC sent
+  them, which is the serialization the wtxid was computed over.
+- The IBD gate (`job-validation-unavailable`) and `bad-cb-decode` are
+  this TP's choices within the draft's "recommended" list and should
+  follow the upstream text once it settles.
+- No policy is applied (the draft forbids it); `fees` lets the pool
+  price the declared coinbase.
+- The JDS role itself, and a `rbitcoin-test` journey driving a JDS
+  client, stay out.
+
+---
+
 ## Test budget
 
 Units in `rbitcoin-mempool` (budgeted selection), `rbitcoin-store`

From 59549abb0e635abaa39d20166504065873d60926 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Wed, 7 Oct 2026 12:07:14 -0400
Subject: [PATCH 08/19] sv2: rename job validation to ProposeTemplate per
 sv2-spec#239

The RFC in sv2-spec discussion #239 (plebhash, 2026-10-06) supersedes
issue #217 and names the TDP message `ProposeTemplate`; its replies are
`.MissingTransactions`, `.Success`, and `.Error`. Pure rename of the
structs, message-type consts, the frame cap, the session handler, the
journey names, log strings, the spec draft's message names, Plan D, the
operator doc, the COMPAT row, and the changelog fragment. No behaviour
change; the field changes the RFC asks for follow in the next commit.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 COMPAT.md                                 |  2 +-
 changelog.d/sv2-job-validation.md         |  2 +-
 crates/rbitcoin-sv2/src/job.rs            | 10 +--
 crates/rbitcoin-sv2/src/listener_tests.rs | 18 +++---
 crates/rbitcoin-sv2/src/messages.rs       | 30 ++++-----
 crates/rbitcoin-sv2/src/session.rs        | 30 ++++-----
 crates/rbitcoin-sv2/src/template_tests.rs | 32 +++++-----
 crates/rbitcoin-sv2/src/transport.rs      | 12 ++--
 docs/README.md                            |  2 +-
 docs/operator/interfaces.md               |  2 +-
 docs/sv2-job-validation.md                | 76 +++++++++++------------
 docs/sv2-template-provider.md             | 24 +++----
 12 files changed, 120 insertions(+), 120 deletions(-)

diff --git a/COMPAT.md b/COMPAT.md
index 61beab277..8f737e44d 100644
--- a/COMPAT.md
+++ b/COMPAT.md
@@ -72,7 +72,7 @@ Full `/tx/:txid` JSON still has `vin[]`. Electrum has no outspend-vin surface.
 | Package submit | RPC `submitpackage` / Esplora `POST /txs/package` (no P2P package command) | BIP331 wire |
 | Pruning / GUI | Unpruned: `seqsigwit.body`. `--prune-seqsigwit`: watermark + `NETWORK_LIMITED`, kept witness is 288 height files under `store/seqsigwit.window/` plus a RAM cap (`--prune-seqsigwit-ram-threshold-bytes`, `0` = files only). Not a rolling stem. Not Core `-prune` of headers/txout | Supported |
 | Mining template RPC | `getblocktemplate` / `getmininginfo` / `prioritisetransaction` (selector; no stratum) | GBT + stratum / pool stack |
-| SV2 Template Distribution | In-process TDP v2 server over Noise NX (`--sv2-tp-listen`, default off): `NewTemplate` / `SetNewPrevHash` per tip, `NewTemplate` on a same-tip fee gain (`--sv2-tp-fee-delta`, `--sv2-tp-template-interval`, sv2-tp defaults), `RequestTransactionData`, `SubmitSolution` → block accept; `ValidateCustomJob` for a Job Declarator Server's node backend (proposed TDP messages, sv2-spec#217, `SetupConnection` flag bit 0). No templates during IBD; every template on the tip kept, up to 64 per session. No plaintext, no pool / JD roles | No TDP in Core; sv2-apps `bitcoin-core-sv2` bridges Core's IPC mining interface to TDP |
+| SV2 Template Distribution | In-process TDP v2 server over Noise NX (`--sv2-tp-listen`, default off): `NewTemplate` / `SetNewPrevHash` per tip, `NewTemplate` on a same-tip fee gain (`--sv2-tp-fee-delta`, `--sv2-tp-template-interval`, sv2-tp defaults), `RequestTransactionData`, `SubmitSolution` → block accept; `ProposeTemplate` for a Job Declarator Server's node backend (proposed TDP messages, sv2-spec#217, `SetupConnection` flag bit 0). No templates during IBD; every template on the tip kept, up to 64 per session. No plaintext, no pool / JD roles | No TDP in Core; sv2-apps `bitcoin-core-sv2` bridges Core's IPC mining interface to TDP |
 | Wallets | Electrum clients (requires `--sh-index`) | Descriptor + legacy |
 | Scripthash index | Optional (`--sh-index`, default **off**); bulk at tip when on | External ElectrumX / Fulcrum; Core `-txindex` is different (txid→block) |
 | JSON-RPC | Documented **subset** ([`docs/rpc.md`](./docs/rpc.md)); Bearer token or opt-in Core cookie (`--rpc-cookie-file`), no `--rpcuser` / `--rpcpassword`; `rbitcoin-cli`. `--rpc-work-queue` defaults to **16** (HTTP occupancy, 503 when full; **0** is that default); a JSON-RPC array is one POST | Full Core RPC; `-rpcworkqueue` is in-flight HTTP jobs (503) |
diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
index f0e1b8580..f50387b7e 100644
--- a/changelog.d/sv2-job-validation.md
+++ b/changelog.d/sv2-job-validation.md
@@ -2,7 +2,7 @@ Added
 
 - **SV2 TP: custom job validation for Job Declarator Servers.** A TDP
   client that sets `SetupConnection` flag bit 0 (`REQUIRES_JOB_VALIDATION`)
-  can send `ValidateCustomJob` (proposed TDP messages 0x77–0x7a,
+  can send `ProposeTemplate` (proposed TDP messages 0x77–0x7a,
   sv2-spec#217). The node resolves the declared wtxids against its mempool,
   asks for the ones it lacks, checks the job as a block on its tip, and
   answers the fee total with a template id that `SubmitSolution` accepts
diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index 794d412a7..d7872bbab 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -2,7 +2,7 @@
 //! (docs/sv2-job-validation.md §4): resolve the declared wtxids, check the
 //! job as a block proposal on the tip, and shape it for retention.
 
-use crate::messages::ValidateCustomJob;
+use crate::messages::ProposeTemplate;
 use crate::template::{self, Job};
 use bitcoin::hashes::{sha256d, Hash};
 use bitcoin::{block, Block, BlockHash, Transaction, TxMerkleNode, Wtxid};
@@ -17,18 +17,18 @@ pub(crate) enum Verdict {
     Missing(Vec<u16>),
     /// Consensus-valid on the tip: the fee total and the job to retain.
     Valid { fees: u64, job: Job },
-    /// `ValidateCustomJob.Error.error_code`: a Core reject string or one of
+    /// `ProposeTemplate.Error.error_code`: a Core reject string or one of
     /// the draft's own codes.
     Rejected(String),
 }
 
 /// Reads the store and the mempool: blocking region only. `None`: the
-/// payload is not a `ValidateCustomJob`.
+/// payload is not a `ProposeTemplate`.
 pub(crate) fn validate(
     chain: &ChainHub,
     mut payload: Vec<u8>,
 ) -> io::Result<Option<(u32, Verdict)>> {
-    let Ok(m) = binary_sv2::from_bytes::<ValidateCustomJob>(&mut payload) else {
+    let Ok(m) = binary_sv2::from_bytes::<ProposeTemplate>(&mut payload) else {
         return Ok(None);
     };
     Ok(Some((m.request_id, check(chain, &m)?)))
@@ -37,7 +37,7 @@ pub(crate) fn validate(
 /// §4.1 and §4.4, in order. The draft's own codes run before any mempool
 /// lookup or transaction decode, so a 32-byte wtxid is never amplified into
 /// a copy or an allocation the job did not declare.
-fn check(chain: &ChainHub, m: &ValidateCustomJob) -> io::Result<Verdict> {
+fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
     let rejected = |code: &str| Ok(Verdict::Rejected(code.into()));
     // Same gate as the templates: a stale tip validates nothing.
     if chain.in_ibd() {
diff --git a/crates/rbitcoin-sv2/src/listener_tests.rs b/crates/rbitcoin-sv2/src/listener_tests.rs
index c1a40eeb2..f186e5159 100644
--- a/crates/rbitcoin-sv2/src/listener_tests.rs
+++ b/crates/rbitcoin-sv2/src/listener_tests.rs
@@ -1,7 +1,7 @@
-use crate::messages::{MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, REQUIRES_JOB_VALIDATION};
+use crate::messages::{MESSAGE_TYPE_PROPOSE_TEMPLATE, REQUIRES_JOB_VALIDATION};
 use crate::test_chain::shared_regtest;
 use crate::testutil::TpClient;
-use crate::transport::MAX_VALIDATE_CUSTOM_JOB_PAYLOAD;
+use crate::transport::MAX_PROPOSE_TEMPLATE_PAYLOAD;
 use crate::{
     run_sv2_tp, Sv2TpConfig, FEE_DELTA, MAX_SESSIONS, MAX_STALE_GRACE, MAX_TEMPLATE_INTERVAL,
     MIN_TEMPLATE_INTERVAL, SETUP_TIMEOUT, TEMPLATE_INTERVAL, WRITE_TIMEOUT,
@@ -322,7 +322,7 @@ async fn client_that_stops_reading_is_dropped_at_the_write_deadline() {
 }
 
 /// Each client message type has its own payload cap: the largest legitimate
-/// `SubmitSolution` and a `ValidateCustomJob` well past it keep the session;
+/// `SubmitSolution` and a `ProposeTemplate` well past it keep the session;
 /// a frame over the cap for its type closes it.
 #[tokio::test]
 async fn oversized_client_frame_closes_the_session() {
@@ -356,16 +356,16 @@ async fn oversized_client_frame_closes_the_session() {
         .expect("open after a max-size SubmitSolution");
     assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
 
-    // No handler yet: a ValidateCustomJob under its own cap is read and ignored.
+    // No handler yet: a ProposeTemplate under its own cap is read and ignored.
     let big = vec![0u8; 200 << 10];
-    c.send_bytes(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, &big)
+    c.send_bytes(MESSAGE_TYPE_PROPOSE_TEMPLATE, &big)
         .await
         .unwrap();
     c.request_transaction_data(1).await.unwrap();
     let f = c
         .recv()
         .await
-        .expect("open after a 200 KiB ValidateCustomJob");
+        .expect("open after a 200 KiB ProposeTemplate");
     assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
 
     let _ = c.send_bytes(MESSAGE_TYPE_SUBMIT_SOLUTION, &big).await;
@@ -379,12 +379,12 @@ async fn oversized_client_frame_closes_the_session() {
     c.recv().await.expect("setup reply");
     let _ = c
         .send_bytes(
-            MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
-            &vec![0u8; MAX_VALIDATE_CUSTOM_JOB_PAYLOAD + 1],
+            MESSAGE_TYPE_PROPOSE_TEMPLATE,
+            &vec![0u8; MAX_PROPOSE_TEMPLATE_PAYLOAD + 1],
         )
         .await;
     c.request_transaction_data(1).await.ok();
-    assert_closed(&mut c, "a ValidateCustomJob over its cap").await;
+    assert_closed(&mut c, "a ProposeTemplate over its cap").await;
     tp.shutdown().await;
 }
 
diff --git a/crates/rbitcoin-sv2/src/messages.rs b/crates/rbitcoin-sv2/src/messages.rs
index 17a850f64..9862e974b 100644
--- a/crates/rbitcoin-sv2/src/messages.rs
+++ b/crates/rbitcoin-sv2/src/messages.rs
@@ -1,23 +1,23 @@
 //! Job-validation extension to TDP (`docs/sv2-job-validation.md` §3–5):
-//! the `SetupConnection` flag and the four `ValidateCustomJob` messages a
+//! the `SetupConnection` flag and the four `ProposeTemplate` messages a
 //! Job Declarator Server uses to have this TP check a custom job.
 
 use binary_sv2::{Deserialize, Seq064K, Serialize, Str0255, B016M, B064K, U256};
 
 /// `SetupConnection.flags` bit 0: the client intends to send
-/// [`ValidateCustomJob`]. The only TDP flag this TP accepts.
+/// [`ProposeTemplate`]. The only TDP flag this TP accepts.
 pub(crate) const REQUIRES_JOB_VALIDATION: u32 = 1 << 0;
 
-pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB: u8 = 0x77;
-pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS: u8 = 0x78;
-pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS: u8 = 0x79;
-pub(crate) const MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR: u8 = 0x7a;
+pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE: u8 = 0x77;
+pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS: u8 = 0x78;
+pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS: u8 = 0x79;
+pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR: u8 = 0x7a;
 
 /// Client → TP: is this custom job a consensus-valid block on the TP tip?
 /// `transaction_list` carries the txs a prior
-/// [`ValidateCustomJobMissingTransactions`] asked for, in that order.
+/// [`ProposeTemplateMissingTransactions`] asked for, in that order.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub(crate) struct ValidateCustomJob<'decoder> {
+pub(crate) struct ProposeTemplate<'decoder> {
     pub request_id: u32,
     pub prev_hash: U256<'decoder>,
     pub version: u32,
@@ -28,7 +28,7 @@ pub(crate) struct ValidateCustomJob<'decoder> {
 
 /// TP → client: 0-indexed positions in `wtxid_list` the TP cannot resolve.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub(crate) struct ValidateCustomJobMissingTransactions<'decoder> {
+pub(crate) struct ProposeTemplateMissingTransactions<'decoder> {
     pub request_id: u32,
     pub unknown_tx_position_list: Seq064K<'decoder, u16>,
 }
@@ -36,7 +36,7 @@ pub(crate) struct ValidateCustomJobMissingTransactions<'decoder> {
 /// TP → client: the job is valid and retained under `template_id`, which
 /// shares the `NewTemplate.template_id` namespace.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub(crate) struct ValidateCustomJobSuccess {
+pub(crate) struct ProposeTemplateSuccess {
     pub request_id: u32,
     pub template_id: u64,
     pub fees: u64,
@@ -44,7 +44,7 @@ pub(crate) struct ValidateCustomJobSuccess {
 
 /// TP → client: the job was not validated.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub(crate) struct ValidateCustomJobError<'decoder> {
+pub(crate) struct ProposeTemplateError<'decoder> {
     pub request_id: u32,
     pub error_code: Str0255<'decoder>,
     pub error_details: B064K<'decoder>,
@@ -78,7 +78,7 @@ mod tests {
         let (coinbase, tx, details) = ([0xc0u8; 100], [0xeeu8; 300], [1u8, 2, 3]);
         let mut bytes = Vec::new();
         round_trip(
-            ValidateCustomJob {
+            ProposeTemplate {
                 request_id: 7,
                 prev_hash: U256::from(&h1),
                 version: 0x2000_0000,
@@ -90,7 +90,7 @@ mod tests {
         );
         let mut bytes = Vec::new();
         round_trip(
-            ValidateCustomJobMissingTransactions {
+            ProposeTemplateMissingTransactions {
                 request_id: 7,
                 unknown_tx_position_list: Seq064K::new(vec![0u16, 5, u16::MAX]).unwrap(),
             },
@@ -98,7 +98,7 @@ mod tests {
         );
         let mut bytes = Vec::new();
         round_trip(
-            ValidateCustomJobSuccess {
+            ProposeTemplateSuccess {
                 request_id: 7,
                 template_id: u64::MAX,
                 fees: 12_345,
@@ -107,7 +107,7 @@ mod tests {
         );
         let mut bytes = Vec::new();
         round_trip(
-            ValidateCustomJobError {
+            ProposeTemplateError {
                 request_id: 7,
                 error_code: Str0255::try_from("stale-prevhash").unwrap(),
                 error_details: B064K::try_from(&details[..]).unwrap(),
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index a59dfe9af..ef49db1f3 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -2,10 +2,10 @@
 
 use crate::job::{self, Verdict};
 use crate::messages::{
-    ValidateCustomJobError, ValidateCustomJobMissingTransactions, ValidateCustomJobSuccess,
-    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR,
-    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS,
-    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, REQUIRES_JOB_VALIDATION,
+    ProposeTemplateError, ProposeTemplateMissingTransactions, ProposeTemplateSuccess,
+    MESSAGE_TYPE_PROPOSE_TEMPLATE, MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR,
+    MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
+    REQUIRES_JOB_VALIDATION,
 };
 use crate::template;
 use crate::transport::{Frame, NoiseConn, NoiseWriter};
@@ -320,8 +320,8 @@ impl Session {
                 on_request_transaction_data(&mut self.conn, frame, &self.templates).await?;
             }
             MESSAGE_TYPE_SUBMIT_SOLUTION => self.on_submit_solution(frame).await?,
-            MESSAGE_TYPE_VALIDATE_CUSTOM_JOB if self.job_validation => {
-                self.on_validate_custom_job(frame).await?;
+            MESSAGE_TYPE_PROPOSE_TEMPLATE if self.job_validation => {
+                self.on_propose_template(frame).await?;
             }
             t => rbitcoin_log::info!("sv2: ignoring message {t:#x}"),
         }
@@ -538,7 +538,7 @@ impl Session {
 
     /// docs/sv2-job-validation.md §4: a valid job is retained under the next
     /// template id and answered `Success`; a rejected one answers `Error`.
-    async fn on_validate_custom_job(&mut self, frame: Frame) -> io::Result<()> {
+    async fn on_propose_template(&mut self, frame: Frame) -> io::Result<()> {
         let c = Arc::clone(&self.chain);
         let verdict = tokio::task::spawn_blocking(move || {
             let _g = BlockingRegion::enter();
@@ -547,18 +547,18 @@ impl Session {
         .await
         .map_err(io::Error::other)??;
         let Some((request_id, verdict)) = verdict else {
-            rbitcoin_log::info!("sv2: undecodable ValidateCustomJob");
+            rbitcoin_log::info!("sv2: undecodable ProposeTemplate");
             return Ok(());
         };
-        let wire = |e: binary_sv2::Error| io::Error::other(format!("sv2 ValidateCustomJob: {e:?}"));
+        let wire = |e: binary_sv2::Error| io::Error::other(format!("sv2 ProposeTemplate: {e:?}"));
         match verdict {
             Verdict::Missing(positions) => {
-                let reply = ValidateCustomJobMissingTransactions {
+                let reply = ProposeTemplateMissingTransactions {
                     request_id,
                     unknown_tx_position_list: Seq064K::new(positions).map_err(wire)?,
                 };
                 self.conn
-                    .send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS, reply)
+                    .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, reply)
                     .await
             }
             Verdict::Valid { fees, job } => {
@@ -569,23 +569,23 @@ impl Session {
                     .prev_sent
                     .unwrap_or((job.header_timestamp, Instant::now()));
                 self.templates.retain(template_id, job, prev_sent);
-                let reply = ValidateCustomJobSuccess {
+                let reply = ProposeTemplateSuccess {
                     request_id,
                     template_id,
                     fees,
                 };
                 self.conn
-                    .send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, reply)
+                    .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS, reply)
                     .await
             }
             Verdict::Rejected(code) => {
-                let reply = ValidateCustomJobError {
+                let reply = ProposeTemplateError {
                     request_id,
                     error_code: Str0255::try_from(code.as_str()).map_err(wire)?,
                     error_details: B064K::try_from(&[][..]).map_err(wire)?,
                 };
                 self.conn
-                    .send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, reply)
+                    .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR, reply)
                     .await
             }
         }
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index 9c2f17bea..973349126 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1,8 +1,8 @@
 use crate::messages::{
-    ValidateCustomJob, ValidateCustomJobError, ValidateCustomJobMissingTransactions,
-    ValidateCustomJobSuccess, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB,
-    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS,
-    MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS, REQUIRES_JOB_VALIDATION,
+    ProposeTemplate, ProposeTemplateError, ProposeTemplateMissingTransactions,
+    ProposeTemplateSuccess, MESSAGE_TYPE_PROPOSE_TEMPLATE, MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR,
+    MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
+    REQUIRES_JOB_VALIDATION,
 };
 use crate::test_chain::{padded_chain_with, shared_regtest, TestChain};
 use crate::testutil::TpClient;
@@ -1158,7 +1158,7 @@ fn job_coinbase(height: u32, payout: u64, txs: &[&Transaction]) -> Transaction {
     }
 }
 
-/// One `ValidateCustomJob` as owned fields, so a test can bend any of them.
+/// One `ProposeTemplate` as owned fields, so a test can bend any of them.
 struct Job {
     request_id: u32,
     prev_hash: [u8; 32],
@@ -1194,7 +1194,7 @@ impl Job {
     }
 
     async fn send(&self, c: &mut TpClient) {
-        let msg = ValidateCustomJob {
+        let msg = ProposeTemplate {
             request_id: self.request_id,
             prev_hash: U256::from(&self.prev_hash),
             version: self.version,
@@ -1208,22 +1208,22 @@ impl Job {
             )
             .unwrap(),
         };
-        c.send(MESSAGE_TYPE_VALIDATE_CUSTOM_JOB, msg).await.unwrap();
+        c.send(MESSAGE_TYPE_PROPOSE_TEMPLATE, msg).await.unwrap();
     }
 }
 
 async fn expect_job_error(c: &mut TpClient, request_id: u32, code: &str) {
     let mut f = recv_in_time(c).await;
-    assert_eq!(f.msg_type, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_ERROR, "{code}");
-    let e: ValidateCustomJobError = binary_sv2::from_bytes(&mut f.payload).expect("decode");
+    assert_eq!(f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR, "{code}");
+    let e: ProposeTemplateError = binary_sv2::from_bytes(&mut f.payload).expect("decode");
     assert_eq!(e.request_id, request_id);
     assert_eq!(e.error_code.as_utf8_or_hex(), code);
 }
 
-async fn expect_job_success(c: &mut TpClient) -> ValidateCustomJobSuccess {
+async fn expect_job_success(c: &mut TpClient) -> ProposeTemplateSuccess {
     let mut f = recv_in_time(c).await;
     assert_eq!(
-        f.msg_type, MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_SUCCESS,
+        f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
         "{:?}",
         f.payload
     );
@@ -1252,7 +1252,7 @@ async fn expect_retained(c: &mut TpClient, template_id: u64, txs: &[&Transaction
 /// `Success` with the next template id and the declared fee sum, and is
 /// retained like a template.
 #[tokio::test(flavor = "multi_thread")]
-async fn validate_custom_job_prices_and_retains_the_declared_job() {
+async fn propose_template_prices_and_retains_the_declared_job() {
     let tc = shared_regtest(2);
     mock_live_tip(&tc);
     let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
@@ -1283,7 +1283,7 @@ async fn validate_custom_job_prices_and_retains_the_declared_job() {
 /// with its 0-indexed position; the same job resent with that tx in
 /// `transaction_list` validates, and the supplied tx is retained with it.
 #[tokio::test(flavor = "multi_thread")]
-async fn validate_custom_job_asks_for_and_accepts_missing_transactions() {
+async fn propose_template_asks_for_and_accepts_missing_transactions() {
     let tc = shared_regtest(2);
     mock_live_tip(&tc);
     let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
@@ -1302,9 +1302,9 @@ async fn validate_custom_job_asks_for_and_accepts_missing_transactions() {
     let mut f = recv_in_time(&mut c).await;
     assert_eq!(
         f.msg_type,
-        MESSAGE_TYPE_VALIDATE_CUSTOM_JOB_MISSING_TRANSACTIONS
+        MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS
     );
-    let m: ValidateCustomJobMissingTransactions =
+    let m: ProposeTemplateMissingTransactions =
         binary_sv2::from_bytes(&mut f.payload).expect("decode");
     assert_eq!(m.request_id, 4);
     assert_eq!(m.unknown_tx_position_list.into_inner(), vec![1u16]);
@@ -1328,7 +1328,7 @@ async fn validate_custom_job_asks_for_and_accepts_missing_transactions() {
 /// reject string. While the tip is stale (IBD) every job is
 /// `job-validation-unavailable`. Nothing is retained on an error.
 #[tokio::test(flavor = "multi_thread")]
-async fn validate_custom_job_rejects_untrusted_input_in_order() {
+async fn propose_template_rejects_untrusted_input_in_order() {
     let tc = shared_regtest(2);
     let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
     let a = spend(tc.coinbases[0], 3_000, cheap.clone());
diff --git a/crates/rbitcoin-sv2/src/transport.rs b/crates/rbitcoin-sv2/src/transport.rs
index 6b7b62725..07533486c 100644
--- a/crates/rbitcoin-sv2/src/transport.rs
+++ b/crates/rbitcoin-sv2/src/transport.rs
@@ -1,6 +1,6 @@
 //! Noise_NX transport over one TCP stream: handshake, then encrypted SV2 frames.
 
-use crate::messages::MESSAGE_TYPE_VALIDATE_CUSTOM_JOB;
+use crate::messages::MESSAGE_TYPE_PROPOSE_TEMPLATE;
 use binary_sv2::{GetSize, Serialize};
 use codec_sv2::{
     Decoded, Decrypted, Handshake, MessageFrame, NoiseDecoder, NoiseEncoder, TransportDecryptState,
@@ -20,13 +20,13 @@ pub struct Frame {
     pub payload: Vec<u8>,
 }
 
-/// Largest client→TP payload for every message but `ValidateCustomJob`:
+/// Largest client→TP payload for every message but `ProposeTemplate`:
 /// `SubmitSolution`, 20 fixed bytes plus a `B064K` coinbase (2-byte length,
 /// ≤ 65535 bytes). The 24-bit frame length would otherwise let a client
 /// make the session buffer ~16 MB per frame.
 const MAX_CLIENT_PAYLOAD: usize = 20 + 2 + u16::MAX as usize;
 
-/// Largest `ValidateCustomJob` payload: 40 fixed bytes, a `B064K` coinbase,
+/// Largest `ProposeTemplate` payload: 40 fixed bytes, a `B064K` coinbase,
 /// a full `SEQ0_64K[U256]` wtxid list, and a `SEQ0_64K[B016M]` transaction
 /// list whose txs together fit a block (weight is never below serialized
 /// size) with a 3-byte length each.
@@ -34,7 +34,7 @@ const MAX_CLIENT_PAYLOAD: usize = 20 + 2 + u16::MAX as usize;
 /// RAM trade (CONTRIBUTING 9): a session buffers one in-flight client frame
 /// of at most this size (~6.4 MB), so at `MAX_SESSIONS` client frames hold
 /// ≤ ~51 MB on top of template retention (lib.rs).
-pub(crate) const MAX_VALIDATE_CUSTOM_JOB_PAYLOAD: usize = {
+pub(crate) const MAX_PROPOSE_TEMPLATE_PAYLOAD: usize = {
     const SEQ: usize = u16::MAX as usize;
     4 + 32 + 4 + (2 + SEQ) + (2 + SEQ * 32) + (2 + SEQ * 3 + MAX_BLOCK_WEIGHT as usize)
 };
@@ -42,7 +42,7 @@ pub(crate) const MAX_VALIDATE_CUSTOM_JOB_PAYLOAD: usize = {
 /// Payload cap by client message type.
 const fn client_payload_cap(msg_type: u8) -> usize {
     match msg_type {
-        MESSAGE_TYPE_VALIDATE_CUSTOM_JOB => MAX_VALIDATE_CUSTOM_JOB_PAYLOAD,
+        MESSAGE_TYPE_PROPOSE_TEMPLATE => MAX_PROPOSE_TEMPLATE_PAYLOAD,
         _ => MAX_CLIENT_PAYLOAD,
     }
 }
@@ -71,7 +71,7 @@ impl FrameCap {
     /// Client→TP: the largest client message while reading, then
     /// [`client_payload_cap`] for the type.
     const CLIENT: Self = Self {
-        max_frame: encrypted_frame_len(MAX_VALIDATE_CUSTOM_JOB_PAYLOAD),
+        max_frame: encrypted_frame_len(MAX_PROPOSE_TEMPLATE_PAYLOAD),
         payload: client_payload_cap,
     };
     /// TP→client: the 24-bit frame length only.
diff --git a/docs/README.md b/docs/README.md
index 5abe3e602..61b92b17c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -52,7 +52,7 @@ into `AGENTS.md`.
 | [`overlay-functional.md`](./overlay-functional.md) | Private Tor / i2pd / cjdns mesh harness (labeled / nightly). |
 | [`how-we-plan.md`](./how-we-plan.md) | Agent contract (cycle, Agent RAM, keep-compiling), then human rationale. |
 | [`sv2-template-provider.md`](./sv2-template-provider.md) | SV2 Template Distribution Protocol server roadmap (**Q-64**): Step 0 finding and plans A–D. Live flags/COMPAT rows land in OPERATOR/COMPAT with the plan that ships them. |
-| [`sv2-job-validation.md`](./sv2-job-validation.md) | Proposed TDP messages for JDS job validation (`ValidateCustomJob`, sv2-spec#217); owner of the wire contract until it lands upstream. Plan D in `sv2-template-provider.md` is the implementation. |
+| [`sv2-job-validation.md`](./sv2-job-validation.md) | Proposed TDP messages for JDS job validation (`ProposeTemplate`, sv2-spec#217); owner of the wire contract until it lands upstream. Plan D in `sv2-template-provider.md` is the implementation. |
 | [`releases.md`](./releases.md) | Tag `vX.Y.Z`, `vX.Y.x` patch line, `.99` bump, Highlights / GitHub notes. |
 | [`code-shape.md`](./code-shape.md) | Control flow, types, naming, composition (CONTRIBUTING principle 10). Named extracts: quality.md **Q-61** (Completed). Clippy: no workspace `allow` list; leftover lints are site-local with a reason. |
 | [`quality.md`](./quality.md) | Living quality roadmap (Open + Won't-fix + Parked + Protect). |
diff --git a/docs/operator/interfaces.md b/docs/operator/interfaces.md
index 98647a3a8..14b6e9167 100644
--- a/docs/operator/interfaces.md
+++ b/docs/operator/interfaces.md
@@ -306,7 +306,7 @@ that misses the template target is logged and dropped. A `header_timestamp`
 outside the sv2 rolling window (a miner clock running ahead) is logged and
 still submitted; block validation applies the consensus time rules.
 A client that sets `SetupConnection` flag bit 0 (`REQUIRES_JOB_VALIDATION`)
-can send `ValidateCustomJob` (proposed TDP messages, sv2-spec#217): the node
+can send `ProposeTemplate` (proposed TDP messages, sv2-spec#217): the node
 checks a Job Declarator Server's declared job as a block on its tip (no proof
 of work; no script checks beyond what mempool admission already ran), asks for
 the transactions it lacks, and retains a valid job under a template id that
diff --git a/docs/sv2-job-validation.md b/docs/sv2-job-validation.md
index 7bdf9a8f1..07bb97b58 100644
--- a/docs/sv2-job-validation.md
+++ b/docs/sv2-job-validation.md
@@ -50,22 +50,22 @@ has, validate, and submit the solution by reference.
 ```
 JDC                      JDS                             TP
  |-- DeclareMiningJob --->|                               |
- |                        |-- ValidateCustomJob --------->|  wtxid_list, coinbase, no txs
- |                        |<- ValidateCustomJob.MissingTransactions   (only if TP lacks some)
+ |                        |-- ProposeTemplate --------->|  wtxid_list, coinbase, no txs
+ |                        |<- ProposeTemplate.MissingTransactions   (only if TP lacks some)
  |<- ProvideMissingTransactions                           |
  |-- ProvideMissingTransactions.Success ->|               |
- |                        |-- ValidateCustomJob --------->|  same job + transaction_list
- |                        |<- ValidateCustomJob.Success --|  template_id, fees
+ |                        |-- ProposeTemplate --------->|  same job + transaction_list
+ |                        |<- ProposeTemplate.Success --|  template_id, fees
  |<- DeclareMiningJob.Success             |               |
  ...
  |-- PushSolution ------->|                               |
  |                        |-- SubmitSolution(template_id)>|  existing 7.8 message
 ```
 
-- `ValidateCustomJob` is stateless on the server side across the
+- `ProposeTemplate` is stateless on the server side across the
   missing-transactions round trip: the second request repeats the job and adds
   the transactions. The TP MUST NOT require any state from the first request.
-- `ValidateCustomJob.Success` assigns a `template_id` from the same namespace as
+- `ProposeTemplate.Success` assigns a `template_id` from the same namespace as
   `NewTemplate.template_id`. The solution is then sent with the existing
   `SubmitSolution` message (Section 7.8). No new submission message is needed.
 - A JDS connection is an ordinary TDP client. It MUST still open with
@@ -82,7 +82,7 @@ Flags usable in `SetupConnection.flags` and `SetupConnection.Error.flags`
 
 | Field Name              | Bit | Description                                                                                                                                 |
 | ----------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| REQUIRES_JOB_VALIDATION | 0   | The client intends to send `ValidateCustomJob`. A server that does not support it MUST reply `SetupConnection.Error` with `unsupported-feature-flags`. |
+| REQUIRES_JOB_VALIDATION | 0   | The client intends to send `ProposeTemplate`. A server that does not support it MUST reply `SetupConnection.Error` with `unsupported-feature-flags`. |
 
 Flags in `SetupConnection.Success.flags` (Server -> Client):
 
@@ -90,12 +90,12 @@ Flags in `SetupConnection.Success.flags` (Server -> Client):
 | ----------------------- | --- | --------------------------------------------------------------------------- |
 | REQUIRES_JOB_VALIDATION | 0   | Set when the server accepted the client's `REQUIRES_JOB_VALIDATION` request |
 
-A client MUST NOT send `ValidateCustomJob` on a connection where this flag was
+A client MUST NOT send `ProposeTemplate` on a connection where this flag was
 not set and accepted.
 
 ## 4. Messages
 
-### 4.1 `ValidateCustomJob` (Client -> Server)
+### 4.1 `ProposeTemplate` (Client -> Server)
 
 Asks the Template Provider whether a Custom Job, declared to the client via
 `DeclareMiningJob`, would produce a consensus-valid block on top of the
@@ -108,7 +108,7 @@ server's current chain tip.
 | version          | U32              | Block header version field as declared in `DeclareMiningJob.version`. BIP323 general-purpose bits are ignored by the server                                                                                                                                                              |
 | coinbase_tx      | B0_64K           | Full serialized coinbase transaction, with the extranonce region filled with placeholder bytes of the correct length. If the coinbase is a SegWit transaction, BIP141 fields (marker, flag, witness count, witness length, witness reserved value) MUST NOT be stripped                 |
 | wtxid_list       | SEQ0_64K[U256]   | `wtxid` of every transaction in the Custom Job, in block order, excluding the coinbase. Copied from `DeclareMiningJob.wtxid_list`                                                                                                                                                         |
-| transaction_list | SEQ0_64K[B0_16M] | Full transactions the server reported in `ValidateCustomJob.MissingTransactions`, in the order they were requested. Empty on the first request. Each transaction MUST be relayed exactly as received from JDC in `ProvideMissingTransactions.Success`, without parsing or re-encoding    |
+| transaction_list | SEQ0_64K[B0_16M] | Full transactions the server reported in `ProposeTemplate.MissingTransactions`, in the order they were requested. Empty on the first request. Each transaction MUST be relayed exactly as received from JDC in `ProvideMissingTransactions.Success`, without parsing or re-encoding    |
 
 The client derives the extranonce length as the scriptSig length encoded in
 `DeclareMiningJob.coinbase_tx_prefix` minus the scriptSig bytes present in the
@@ -123,9 +123,9 @@ of the extranonce bytes.
 
 The server resolves each `wtxid` against its mempool and against
 `transaction_list`. If any transaction is still unknown, it MUST reply
-`ValidateCustomJob.MissingTransactions`. Otherwise it MUST validate the job as
+`ProposeTemplate.MissingTransactions`. Otherwise it MUST validate the job as
 a block on top of `prev_hash` with the following rules, and reply either
-`ValidateCustomJob.Success` or `ValidateCustomJob.Error`:
+`ProposeTemplate.Success` or `ProposeTemplate.Error`:
 
 - `prev_hash` MUST equal the server's current chain tip. Otherwise the server
   MUST reply with error code `stale-prevhash`. The server MUST NOT accept a
@@ -146,54 +146,54 @@ a block on top of `prev_hash` with the following rules, and reply either
   `checkBlock` with `checkMerkleRoot=false` and `checkPow=false`.
 - The server MUST NOT reject a consensus-valid job on local policy grounds
   (standardness, minimum relay fee, mempool limits). Policy belongs to the
-  Pool, which can use `ValidateCustomJob.Success.fees` for it.
+  Pool, which can use `ProposeTemplate.Success.fees` for it.
 - The server MUST set `nBits` from its own view of the chain and MAY use its
   current time for `nTime` when it needs a header for contextual checks. The
   client does not supply them.
 
-### 4.2 `ValidateCustomJob.MissingTransactions` (Server -> Client)
+### 4.2 `ProposeTemplate.MissingTransactions` (Server -> Client)
 
 The server does not know some of the transactions in `wtxid_list`. The client
 is expected to obtain them from JDC via `ProvideMissingTransactions` and send
-a new `ValidateCustomJob` with `transaction_list` filled.
+a new `ProposeTemplate` with `transaction_list` filled.
 
 | Field Name               | Data Type     | Description                                                                                                                                                    |
 | ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| request_id               | U32           | Identifier of the original `ValidateCustomJob` request                                                                                                           |
+| request_id               | U32           | Identifier of the original `ProposeTemplate` request                                                                                                           |
 | unknown_tx_position_list | SEQ0_64K[U16] | Positions in `wtxid_list` of the transactions the server lacks, 0-indexed, not including the coinbase. Same encoding as `ProvideMissingTransactions.unknown_tx_position_list` |
 
 The positions are relative to `wtxid_list`, which is a copy of
 `DeclareMiningJob.wtxid_list`, so the client can copy this field into
 `ProvideMissingTransactions.unknown_tx_position_list` unchanged, and copy
 `ProvideMissingTransactions.Success.transaction_list` into
-`ValidateCustomJob.transaction_list` unchanged.
+`ProposeTemplate.transaction_list` unchanged.
 
-A server MAY reply `ValidateCustomJob.MissingTransactions` to a request whose
+A server MAY reply `ProposeTemplate.MissingTransactions` to a request whose
 `transaction_list` is non-empty, for example when a transaction left its
 mempool between the two requests. A client SHOULD bound how many times it
 retries one declaration.
 
-### 4.3 `ValidateCustomJob.Success` (Server -> Client)
+### 4.3 `ProposeTemplate.Success` (Server -> Client)
 
 The job is consensus-valid on the server's current tip. The server has stored
 the job and will accept a `SubmitSolution` for it.
 
 | Field Name  | Data Type | Description                                                                                                                                                                            |
 | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| request_id  | U32       | Identifier of the original `ValidateCustomJob` request                                                                                                                                  |
+| request_id  | U32       | Identifier of the original `ProposeTemplate` request                                                                                                                                  |
 | template_id | U64       | Server's identification of the validated job. Drawn from the same strictly increasing namespace as `NewTemplate.template_id`, so it can be used in `SubmitSolution` and `RequestTransactionData` |
 | fees        | U64       | Sum of the fees of the transactions in `wtxid_list`, in satoshis                                                                                                                       |
 
 The server MUST retain the validated job (its `wtxid_list`, the transactions
 it received in `transaction_list`, and `coinbase_tx` for size accounting)
-until a newer `ValidateCustomJob.Success` is sent on the same connection or
+until a newer `ProposeTemplate.Success` is sent on the same connection or
 the connection closes, whichever comes first. This matches the guarantee JDS
 gives JDC in Section 6.4.9: `PushSolution` is only guaranteed to be valid for
 the most recent declaration. The server SHOULD retain jobs validated against
 the previous tip for a short grace period after a tip change, as it does for
 its own templates.
 
-### 4.4 `ValidateCustomJob.Error` (Server -> Client)
+### 4.4 `ProposeTemplate.Error` (Server -> Client)
 
 The job was not validated. The client decides what to tell JDC; it SHOULD map
 consensus rejections to `DeclareMiningJob.Error` and SHOULD NOT treat
@@ -201,7 +201,7 @@ consensus rejections to `DeclareMiningJob.Error` and SHOULD NOT treat
 
 | Field Name    | Data Type | Description                                            |
 | ------------- | --------- | ------------------------------------------------------ |
-| request_id    | U32       | Identifier of the original `ValidateCustomJob` request   |
+| request_id    | U32       | Identifier of the original `ProposeTemplate` request   |
 | error_code    | STR0_255  | Human-readable error code(s)                           |
 | error_details | B0_64K    | Optional data providing further details to given error |
 
@@ -221,7 +221,7 @@ rejection strings (`bad-txns-inputs-missingorspent`, `bad-cb-length`,
 When the client receives `PushSolution` from JDC it MUST reconstruct the full
 coinbase (`coinbase_tx_prefix` || `extranonce` || `coinbase_tx_suffix`) and
 send `SubmitSolution` (Section 7.8) with `template_id` set to the value from
-`ValidateCustomJob.Success`, and `version`, `ntime`, `nonce` and `coinbase_tx`
+`ProposeTemplate.Success`, and `version`, `ntime`, `nonce` and `coinbase_tx`
 from the solution.
 
 The server MUST treat such a `SubmitSolution` as it treats one for its own
@@ -240,10 +240,10 @@ Additions to Section 8, Template Distribution Protocol:
 
 | Message Type (8-bit) | channel_msg bit | Message Name                            |
 | -------------------- | --------------- | --------------------------------------- |
-| 0x77                 | 0               | ValidateCustomJob                       |
-| 0x78                 | 0               | ValidateCustomJob.MissingTransactions   |
-| 0x79                 | 0               | ValidateCustomJob.Success               |
-| 0x7a                 | 0               | ValidateCustomJob.Error                 |
+| 0x77                 | 0               | ProposeTemplate                       |
+| 0x78                 | 0               | ProposeTemplate.MissingTransactions   |
+| 0x79                 | 0               | ProposeTemplate.Success               |
+| 0x7a                 | 0               | ProposeTemplate.Error                 |
 
 All four are core messages and carry `extension_type = 0x0000`.
 
@@ -264,16 +264,16 @@ All four are core messages and carry `extension_type = 0x0000`.
 - **Coinbase-only mode.** Out of scope. In Coinbase-only mode neither Pool nor
   JDS learns the transaction set, so a node has nothing to validate beyond the
   coinbase, which `SetCustomMiningJob` already carries to the Pool. A
-  zero-knowledge extension could later reuse `ValidateCustomJob.Success.fees`
+  zero-knowledge extension could later reuse `ProposeTemplate.Success.fees`
   as the quantity being proven.
 - **Node load.** Full block validation without proof of work is CPU-heavy and
   in Bitcoin Core currently serialises on `cs_main`, so validations on a node
   that also produces the Pool's templates can delay block processing
-  (`sv2-apps#120`). A server MAY process `ValidateCustomJob` requests
+  (`sv2-apps#120`). A server MAY process `ProposeTemplate` requests
   sequentially and MAY bound the number queued per connection; operators
   SHOULD run a dedicated TP for job validation. A client SHOULD apply a
   timeout before falling back.
-- **Untrusted input.** Everything in `ValidateCustomJob` originates from a
+- **Untrusted input.** Everything in `ProposeTemplate` originates from a
   JDC. The server MUST enforce the `duplicate-wtxid` and `bad-missing-tx`
   checks and the block weight limit before decoding or storing transactions,
   so that a 32-byte `wtxid` cannot be amplified into a large allocation
@@ -296,11 +296,11 @@ All four are core messages and carry `extension_type = 0x0000`.
 
 | JDP event                            | TDP action                                                                    |
 | ------------------------------------ | ----------------------------------------------------------------------------- |
-| `DeclareMiningJob`                   | `ValidateCustomJob` with `wtxid_list` copied, `coinbase_tx` from prefix + placeholder + suffix, empty `transaction_list` |
-| `ValidateCustomJob.MissingTransactions` | `ProvideMissingTransactions` with the position list copied                  |
-| `ProvideMissingTransactions.Success` | `ValidateCustomJob` again with `transaction_list` copied                       |
-| `ValidateCustomJob.Success`          | `DeclareMiningJob.Success`; store `template_id` with the declaration           |
-| `ValidateCustomJob.Error`            | `DeclareMiningJob.Error` with the error code                                  |
+| `DeclareMiningJob`                   | `ProposeTemplate` with `wtxid_list` copied, `coinbase_tx` from prefix + placeholder + suffix, empty `transaction_list` |
+| `ProposeTemplate.MissingTransactions` | `ProvideMissingTransactions` with the position list copied                  |
+| `ProvideMissingTransactions.Success` | `ProposeTemplate` again with `transaction_list` copied                       |
+| `ProposeTemplate.Success`          | `DeclareMiningJob.Success`; store `template_id` with the declaration           |
+| `ProposeTemplate.Error`            | `DeclareMiningJob.Error` with the error code                                  |
 | `PushSolution`                       | `SubmitSolution(template_id, version, ntime, nonce, coinbase_tx)`              |
 
 No mempool mirror is needed on the JDS side. In `sv2-apps` this is a second
@@ -310,7 +310,7 @@ Pool's "`[jds]` requires `BitcoinCoreIpc`" startup check becomes "requires
 
 ### 7.2 Template Provider on Bitcoin Core (`sv2-tp`)
 
-`ValidateCustomJob` maps onto `getTransactionsByWitnessID` (Core v32) for the
+`ProposeTemplate` maps onto `getTransactionsByWitnessID` (Core v32) for the
 lookup and `checkBlock(checkMerkleRoot=false, checkPow=false)` for validation,
 or onto `TxCollection` (`collectTxs`, `unknownTxPos`, `addMissingTxs`,
 `makeTemplate`) once bitcoin/bitcoin#35671 lands. `SubmitSolution` for a
@@ -350,7 +350,7 @@ dependency.
   `wtxid`, report unknown positions, add missing, `makeTemplate`, submit the
   solution by reference) is the flow Sections 2 and 4 encode. The thread also
   records the hazard of server-side state across the missing-transactions
-  round trip, which is why `ValidateCustomJob` is stateless until `Success`.
+  round trip, which is why `ProposeTemplate` is stateless until `Success`.
 - [sv2-apps#299](https://github.com/stratum-mining/sv2-apps/pull/299): JDS
   refactor that removed the JSON-RPC backend and folded JDS into the Pool.
   [sv2-apps#26](https://github.com/stratum-mining/sv2-apps/issues/26) gives the
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index e7293b980..4617608fa 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -96,8 +96,8 @@ Do not copy them here.
 - Write deadline is per write call, not per frame, so a slow reader still
   receives a multi-MB `RequestTransactionData.Success`. The 30 s close is
   the operator page above.
-- Client frame cap, per message type: a `ValidateCustomJob` payload over
-  `MAX_VALIDATE_CUSTOM_JOB_PAYLOAD` (~6.4 MB: 40 fixed bytes, a `B064K`
+- Client frame cap, per message type: a `ProposeTemplate` payload over
+  `MAX_PROPOSE_TEMPLATE_PAYLOAD` (~6.4 MB: 40 fixed bytes, a `B064K`
   coinbase, 65535 wtxids, and a block's worth of `B016M` txs) closes the
   session; every other client payload closes past `MAX_CLIENT_PAYLOAD`
   (65557 bytes: `SubmitSolution`'s 20 fixed bytes plus a full `B064K`
@@ -568,7 +568,7 @@ when fees rise enough to matter, throttled. Requires Plan B.
 
 ---
 
-## Plan D — Custom job validation (TDP `ValidateCustomJob`)
+## Plan D — Custom job validation (TDP `ProposeTemplate`)
 
 **Goal:** a Job Declarator Server in Full-Template mode checks a JDC's
 `DeclareMiningJob` against this node over the TDP connection it already
@@ -600,7 +600,7 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
 
 ### D2 — Messages and the setup flag
 
-- **Contract:** `messages.rs` carries `ValidateCustomJob`,
+- **Contract:** `messages.rs` carries `ProposeTemplate`,
   `.MissingTransactions`, `.Success`, `.Error` (0x77–0x7a) as binary_sv2
   structs, and `REQUIRES_JOB_VALIDATION`. Setup accepts bit 0 and echoes
   it; any other set bit is still `unsupported-feature-flags`.
@@ -611,20 +611,20 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
 ### D3 — Client frame cap per message type
 
 - **Contract:** the [Constraints](#constraints-all-plans) frame cap, per
-  type. `ValidateCustomJob` may carry a block's worth of transactions;
+  type. `ProposeTemplate` may carry a block's worth of transactions;
   every other client type still closes past 65557 bytes.
 - **Red:** `oversized_client_frame_closes_the_session` — a 200 KiB
-  `ValidateCustomJob` keeps the session, a 200 KiB `SubmitSolution` and a
-  `ValidateCustomJob` over its cap close it.
+  `ProposeTemplate` keeps the session, a 200 KiB `SubmitSolution` and a
+  `ProposeTemplate` over its cap close it.
 - **Green:** `FrameCap { max_frame, payload: fn(u8) -> usize }`: read
   against the largest client message, apply the per-type cap once whole.
 - **RAM trade:** one in-flight client frame of ≤ ~6.4 MB per session,
   ≤ ~51 MB at `MAX_SESSIONS`.
 
-### D4 — ValidateCustomJob happy path
+### D4 — ProposeTemplate happy path
 
 - **Contract:** on a session that negotiated the flag, a
-  `ValidateCustomJob` whose `prev_hash` is the tip, whose `wtxid_list` is
+  `ProposeTemplate` whose `prev_hash` is the tip, whose `wtxid_list` is
   all in the mempool, and whose placeholder coinbase pays ≤ subsidy + fees
   is answered `Success{request_id, template_id, fees}`: `template_id` is
   the next id in the session's counter, `fees` the sum over the declared
@@ -632,7 +632,7 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
   `RequestTransactionData` returns the declared txs in block order and
   `SubmitSolution` finds it. Without the flag the message is ignored (the
   D3 journey already pins that).
-- **Red:** `validate_custom_job_prices_and_retains_the_declared_job` —
+- **Red:** `propose_template_prices_and_retains_the_declared_job` —
   two legacy spends with known fees in the mempool, a JDS-shaped coinbase
   (BIP34 push + 8 placeholder bytes, payout = subsidy + fees, witness
   commitment with a zero reserved value); `Success` with `fees` = 5 000
@@ -666,7 +666,7 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
   (0-indexed positions in `wtxid_list`); the same job resent with those
   txs in `transaction_list` validates and the supplied txs are retained
   with it. The TP keeps no state across the round trip.
-- **Red:** `validate_custom_job_asks_for_and_accepts_missing_transactions`
+- **Red:** `propose_template_asks_for_and_accepts_missing_transactions`
   — one of two spends not in the mempool → `[1]`; resend with it
   supplied → `Success` with the full fee sum and both txs retained. Red
   was the session closing (D4's placeholder treated an unknown wtxid as
@@ -687,7 +687,7 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
   the draft has none for an undecodable coinbase), then the proposal
   check's reject string (`bad-cb-amount` for an overpaying coinbase).
   Nothing is retained and no id is taken on an error.
-- **Red:** `validate_custom_job_rejects_untrusted_input_in_order` — seven
+- **Red:** `propose_template_rejects_untrusted_input_in_order` — seven
   sends on one session, then `RequestTransactionData(last + 1)` answers
   `template-id-not-found`. Red was `Success` for the first send.
 - **Green:** the checks in `job::check`, ahead of resolution.

From 136fe241a71314c388f2e62751eddf1ed9be9e64 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Wed, 7 Oct 2026 12:13:11 -0400
Subject: [PATCH 09/19] sv2: carry the DeclareMiningJob subset in
 ProposeTemplate and return the validated tip
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

sv2-spec discussion #239: `ProposeTemplate` carries what a JDS already has
from `DeclareMiningJob` and nothing it would have to invent: `request_id`,
`version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`,
`excess_data` (opaque to this TP), plus our `transaction_list`. There is no
`prev_hash` in the request (`DeclareMiningJob` has none); the TP validates
on its own current tip and `ProposeTemplate.Success` names that tip as
`prev_hash` next to `template_id` and `fees`, so the JDS can match it to
`PushSolution.prev_hash`.

The TP now builds the placeholder coinbase. `job::extranonce_len` parses
the prefix (version, BIP144 marker and flag when present, an input count
that MUST be 1, the prevout, the scriptSig length L and the P bytes present;
2 ≤ L ≤ 100, P ≤ L) and the coinbase is prefix ‖ zeros(L − P) ‖ suffix,
decoded as before. A prefix that does not parse, or a result that does not
decode, answers `bad-cb-decode`. `stale-prevhash` is gone: a declaration
from before the tip moved fails the proposal check on its own
(`bad-cb-height` for its BIP34 push), which the ordered-rejections journey
now pins, together with a prefix carrying more scriptSig bytes than its
length declares, a two-input prefix, and a truncated suffix. Every
`Success` is checked against the tip. The untrusted-input order is
unchanged: duplicate-wtxid, bad-missing-tx, coinbase assembly and decode,
resolution, then the proposal check.

`MAX_PROPOSE_TEMPLATE_PAYLOAD` is re-priced for three `B064K` fields
(~6.5 MB per in-flight frame, ~52 MB at `MAX_SESSIONS`).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/job.rs            |  94 ++++++++++++-
 crates/rbitcoin-sv2/src/messages.rs       |  26 ++--
 crates/rbitcoin-sv2/src/session.rs        |   4 +-
 crates/rbitcoin-sv2/src/template_tests.rs | 158 +++++++++++++---------
 crates/rbitcoin-sv2/src/transport.rs      |  14 +-
 5 files changed, 211 insertions(+), 85 deletions(-)

diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index d7872bbab..f46dc7cc0 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -4,6 +4,7 @@
 
 use crate::messages::ProposeTemplate;
 use crate::template::{self, Job};
+use bitcoin::consensus::encode::{deserialize_partial, VarInt};
 use bitcoin::hashes::{sha256d, Hash};
 use bitcoin::{block, Block, BlockHash, Transaction, TxMerkleNode, Wtxid};
 use rbitcoin_net::ChainHub;
@@ -44,9 +45,6 @@ fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
         return rejected("job-validation-unavailable");
     }
     let next = template::next_header(chain)?;
-    if m.prev_hash.as_ref() != next.prev_hash {
-        return rejected("stale-prevhash");
-    }
     let mut declared = HashSet::with_capacity(m.wtxid_list.len());
     for w in m.wtxid_list.iter() {
         if !declared.insert(w.as_ref()) {
@@ -68,8 +66,17 @@ fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
     if supplied.keys().any(|w| !declared.contains(&w[..])) {
         return rejected("bad-missing-tx");
     }
-    let Ok(coinbase) = bitcoin::consensus::deserialize::<Transaction>(m.coinbase_tx.as_ref())
-    else {
+    let Some(extranonce) = extranonce_len(m.coinbase_tx_prefix.as_ref()) else {
+        return rejected("bad-cb-decode");
+    };
+    let zeros = vec![0u8; extranonce];
+    let raw = [
+        m.coinbase_tx_prefix.as_ref(),
+        &zeros[..],
+        m.coinbase_tx_suffix.as_ref(),
+    ]
+    .concat();
+    let Ok(coinbase) = bitcoin::consensus::deserialize::<Transaction>(&raw) else {
         return rejected("bad-cb-decode");
     };
     let mut txs = Vec::with_capacity(m.wtxid_list.len());
@@ -122,3 +129,80 @@ fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
         job: next.job(rbitcoin_store::merkle_branch(&leaves, 0), txs),
     })
 }
+
+/// §4.1: `coinbase_tx_prefix` ends inside the scriptSig and
+/// `coinbase_tx_suffix` starts at nSequence, so the extranonce is the
+/// scriptSig length the prefix declares minus the scriptSig bytes it
+/// carries. `None`: not one input, a length outside the coinbase bounds
+/// (2..=100), or fewer bytes declared than present.
+fn extranonce_len(prefix: &[u8]) -> Option<usize> {
+    let mut at = 4;
+    // BIP144: a zero where the input count would be, then flag 1.
+    if prefix.get(4..6) == Some(&[0u8, 1][..]) {
+        at += 2;
+    }
+    let (inputs, n) = compact_size(prefix.get(at..)?)?;
+    if inputs != 1 {
+        return None;
+    }
+    at += n + 36;
+    let (len, n) = compact_size(prefix.get(at..)?)?;
+    at += n;
+    if !(2..=100).contains(&len) {
+        return None;
+    }
+    (len as usize).checked_sub(prefix.len() - at)
+}
+
+fn compact_size(bytes: &[u8]) -> Option<(u64, usize)> {
+    let (v, n) = deserialize_partial::<VarInt>(bytes).ok()?;
+    Some((v.0, n))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::extranonce_len;
+
+    fn prefix(segwit: bool, inputs: u8, len: u8, present: usize) -> Vec<u8> {
+        let mut p = vec![2, 0, 0, 0];
+        if segwit {
+            p.extend([0, 1]);
+        }
+        p.push(inputs);
+        p.extend([0; 32]);
+        p.extend([0xff; 4]);
+        p.push(len);
+        p.resize(p.len() + present, 0x51);
+        p
+    }
+
+    #[test]
+    fn extranonce_is_the_declared_script_sig_length_past_the_prefix() {
+        assert_eq!(extranonce_len(&prefix(false, 1, 11, 3)), Some(8));
+        assert_eq!(extranonce_len(&prefix(true, 1, 11, 3)), Some(8));
+        assert_eq!(extranonce_len(&prefix(true, 1, 3, 3)), Some(0));
+        assert_eq!(extranonce_len(&prefix(true, 1, 100, 0)), Some(100));
+        assert_eq!(extranonce_len(&prefix(true, 2, 11, 3)), None, "two inputs");
+        assert_eq!(
+            extranonce_len(&prefix(true, 1, 2, 3)),
+            None,
+            "shorter than present"
+        );
+        assert_eq!(
+            extranonce_len(&prefix(true, 1, 101, 0)),
+            None,
+            "over the coinbase max"
+        );
+        assert_eq!(
+            extranonce_len(&prefix(true, 1, 1, 0)),
+            None,
+            "under the coinbase min"
+        );
+        assert_eq!(
+            extranonce_len(&prefix(true, 1, 11, 3)[..40]),
+            None,
+            "truncated"
+        );
+        assert_eq!(extranonce_len(&[]), None);
+    }
+}
diff --git a/crates/rbitcoin-sv2/src/messages.rs b/crates/rbitcoin-sv2/src/messages.rs
index 9862e974b..f2ddd9e09 100644
--- a/crates/rbitcoin-sv2/src/messages.rs
+++ b/crates/rbitcoin-sv2/src/messages.rs
@@ -14,15 +14,19 @@ pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS: u8 = 0x79;
 pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR: u8 = 0x7a;
 
 /// Client → TP: is this custom job a consensus-valid block on the TP tip?
+/// The `DeclareMiningJob` subset a node needs, relayed unchanged: the
+/// coinbase split around the extranonce and the declared wtxids.
 /// `transaction_list` carries the txs a prior
 /// [`ProposeTemplateMissingTransactions`] asked for, in that order.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
 pub(crate) struct ProposeTemplate<'decoder> {
     pub request_id: u32,
-    pub prev_hash: U256<'decoder>,
     pub version: u32,
-    pub coinbase_tx: B064K<'decoder>,
+    pub coinbase_tx_prefix: B064K<'decoder>,
+    pub coinbase_tx_suffix: B064K<'decoder>,
     pub wtxid_list: Seq064K<'decoder, U256<'decoder>>,
+    /// Opaque to the TP (TDP 7.6 semantics belong to the Pool).
+    pub excess_data: B064K<'decoder>,
     pub transaction_list: Seq064K<'decoder, B016M<'decoder>>,
 }
 
@@ -33,12 +37,13 @@ pub(crate) struct ProposeTemplateMissingTransactions<'decoder> {
     pub unknown_tx_position_list: Seq064K<'decoder, u16>,
 }
 
-/// TP → client: the job is valid and retained under `template_id`, which
-/// shares the `NewTemplate.template_id` namespace.
+/// TP → client: the job is valid on the tip `prev_hash` and retained under
+/// `template_id`, which shares the `NewTemplate.template_id` namespace.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub(crate) struct ProposeTemplateSuccess {
+pub(crate) struct ProposeTemplateSuccess<'decoder> {
     pub request_id: u32,
     pub template_id: u64,
+    pub prev_hash: U256<'decoder>,
     pub fees: u64,
 }
 
@@ -75,15 +80,17 @@ mod tests {
     #[test]
     fn job_validation_messages_round_trip() {
         let (h1, h2, h3) = ([1u8; 32], [2u8; 32], [3u8; 32]);
-        let (coinbase, tx, details) = ([0xc0u8; 100], [0xeeu8; 300], [1u8, 2, 3]);
+        let (prefix, suffix, tx, details) =
+            ([0xc0u8; 50], [0xc1u8; 100], [0xeeu8; 300], [1u8, 2, 3]);
         let mut bytes = Vec::new();
         round_trip(
             ProposeTemplate {
                 request_id: 7,
-                prev_hash: U256::from(&h1),
                 version: 0x2000_0000,
-                coinbase_tx: B064K::try_from(&coinbase[..]).unwrap(),
+                coinbase_tx_prefix: B064K::try_from(&prefix[..]).unwrap(),
+                coinbase_tx_suffix: B064K::try_from(&suffix[..]).unwrap(),
                 wtxid_list: Seq064K::new(vec![U256::from(&h2), U256::from(&h3)]).unwrap(),
+                excess_data: B064K::try_from(&details[..]).unwrap(),
                 transaction_list: Seq064K::new(vec![B016M::try_from(&tx[..]).unwrap()]).unwrap(),
             },
             &mut bytes,
@@ -101,6 +108,7 @@ mod tests {
             ProposeTemplateSuccess {
                 request_id: 7,
                 template_id: u64::MAX,
+                prev_hash: U256::from(&h1),
                 fees: 12_345,
             },
             &mut bytes,
@@ -109,7 +117,7 @@ mod tests {
         round_trip(
             ProposeTemplateError {
                 request_id: 7,
-                error_code: Str0255::try_from("stale-prevhash").unwrap(),
+                error_code: Str0255::try_from("bad-cb-decode").unwrap(),
                 error_details: B064K::try_from(&details[..]).unwrap(),
             },
             &mut bytes,
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index ef49db1f3..6af962132 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -10,7 +10,7 @@ use crate::messages::{
 use crate::template;
 use crate::transport::{Frame, NoiseConn, NoiseWriter};
 use crate::Sv2TpStats;
-use binary_sv2::{Seq064K, Str0255, B016M, B064K};
+use binary_sv2::{Seq064K, Str0255, B016M, B064K, U256};
 use bitcoin::hashes::Hash;
 use bitcoin::{block, Block, BlockHash, CompactTarget, Transaction, TxMerkleNode, Witness};
 use common_messages_sv2::{
@@ -568,10 +568,12 @@ impl Session {
                     .templates
                     .prev_sent
                     .unwrap_or((job.header_timestamp, Instant::now()));
+                let prev_hash = job.prev_hash;
                 self.templates.retain(template_id, job, prev_sent);
                 let reply = ProposeTemplateSuccess {
                     request_id,
                     template_id,
+                    prev_hash: U256::from(&prev_hash),
                     fees,
                 };
                 self.conn
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index 973349126..13bbc3d67 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1127,12 +1127,14 @@ async fn connect_tp_every(
     (tp, c)
 }
 
-/// A JDS-shaped placeholder coinbase: BIP34 height then 8 extranonce bytes,
-/// one payout, and the witness commitment over `txs` with a zero reserved
-/// value in the witness.
+const EXTRANONCE_LEN: usize = 8;
+
+/// A JDS-shaped coinbase: BIP34 height then the extranonce, one payout, and
+/// the witness commitment over `txs` with a zero reserved value in the
+/// witness.
 fn job_coinbase(height: u32, payout: u64, txs: &[&Transaction]) -> Transaction {
     let mut script_sig = bip34_height_script(height);
-    script_sig.extend_from_slice(&[0u8; 8]);
+    script_sig.extend_from_slice(&[0u8; EXTRANONCE_LEN]);
     Transaction {
         version: Version::TWO,
         lock_time: LockTime::ZERO,
@@ -1158,33 +1160,37 @@ fn job_coinbase(height: u32, payout: u64, txs: &[&Transaction]) -> Transaction {
     }
 }
 
+/// Where a segwit coinbase's scriptSig starts in its serialization: version,
+/// BIP144 marker and flag, the one-input count, the null prevout, and the
+/// one-byte scriptSig length.
+const SCRIPT_SIG_AT: usize = 4 + 2 + 1 + 36 + 1;
+
 /// One `ProposeTemplate` as owned fields, so a test can bend any of them.
 struct Job {
     request_id: u32,
-    prev_hash: [u8; 32],
     version: u32,
-    coinbase: Vec<u8>,
+    coinbase_prefix: Vec<u8>,
+    coinbase_suffix: Vec<u8>,
     wtxids: Vec<[u8; 32]>,
     supplied: Vec<Vec<u8>>,
 }
 
 impl Job {
-    fn on_tip(
+    /// The `DeclareMiningJob` split a JDS relays: the prefix ends where the
+    /// extranonce starts (the scriptSig tail), the suffix starts at nSequence.
+    fn declare(
         tc: &TestChain,
         request_id: u32,
         coinbase: &Transaction,
         declared: &[&Transaction],
     ) -> Self {
+        let raw = serialize(coinbase);
+        let split = SCRIPT_SIG_AT + coinbase.input[0].script_sig.len() - EXTRANONCE_LEN;
         Job {
             request_id,
-            prev_hash: tc
-                .chain
-                .tip_header()
-                .expect("tip")
-                .block_hash()
-                .to_byte_array(),
             version: tc.chain.gbt_block_version() as u32,
-            coinbase: serialize(coinbase),
+            coinbase_prefix: raw[..split].to_vec(),
+            coinbase_suffix: raw[split + EXTRANONCE_LEN..].to_vec(),
             wtxids: declared
                 .iter()
                 .map(|tx| tx.compute_wtxid().to_byte_array())
@@ -1196,10 +1202,11 @@ impl Job {
     async fn send(&self, c: &mut TpClient) {
         let msg = ProposeTemplate {
             request_id: self.request_id,
-            prev_hash: U256::from(&self.prev_hash),
             version: self.version,
-            coinbase_tx: B064K::try_from(&self.coinbase[..]).unwrap(),
+            coinbase_tx_prefix: B064K::try_from(&self.coinbase_prefix[..]).unwrap(),
+            coinbase_tx_suffix: B064K::try_from(&self.coinbase_suffix[..]).unwrap(),
             wtxid_list: Seq064K::new(self.wtxids.iter().map(U256::from).collect()).unwrap(),
+            excess_data: B064K::try_from(&[][..]).unwrap(),
             transaction_list: Seq064K::new(
                 self.supplied
                     .iter()
@@ -1220,14 +1227,28 @@ async fn expect_job_error(c: &mut TpClient, request_id: u32, code: &str) {
     assert_eq!(e.error_code.as_utf8_or_hex(), code);
 }
 
-async fn expect_job_success(c: &mut TpClient) -> ProposeTemplateSuccess {
+/// `Success` names the tip the job was validated on, next to the id it is
+/// retained under and the declared fee sum.
+async fn expect_job_success(
+    c: &mut TpClient,
+    tc: &TestChain,
+    request_id: u32,
+    template_id: u64,
+    fees: u64,
+) {
     let mut f = recv_in_time(c).await;
     assert_eq!(
         f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
         "{:?}",
         f.payload
     );
-    binary_sv2::from_bytes(&mut f.payload).expect("decode")
+    let ok: ProposeTemplateSuccess = binary_sv2::from_bytes(&mut f.payload).expect("decode");
+    let tip = tc.chain.tip_header().expect("tip").block_hash();
+    assert_eq!(
+        (ok.request_id, ok.template_id, ok.fees),
+        (request_id, template_id, fees)
+    );
+    assert_eq!(ok.prev_hash.as_ref(), tip.as_byte_array(), "validated tip");
 }
 
 /// The retained job answers `RequestTransactionData` with the declared txs
@@ -1247,10 +1268,10 @@ async fn expect_retained(c: &mut TpClient, template_id: u64, txs: &[&Transaction
     assert_eq!(got, want, "retained txs in declared order");
 }
 
-/// docs/sv2-job-validation.md §4.1–4.3: a job on the tip whose txs are all
-/// in the mempool and whose coinbase pays subsidy + fees is answered
-/// `Success` with the next template id and the declared fee sum, and is
-/// retained like a template.
+/// docs/sv2-job-validation.md §4.1–4.3: a job whose txs are all in the
+/// mempool and whose coinbase pays subsidy + fees is answered `Success` with
+/// the next template id, the declared fee sum, and the tip it was validated
+/// on, and is retained like a template.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_prices_and_retains_the_declared_job() {
     let tc = shared_regtest(2);
@@ -1268,13 +1289,11 @@ async fn propose_template_prices_and_retains_the_declared_job() {
     let height = tc.chain.query.tip_height().unwrap().0 + 1;
     let subsidy = block_subsidy(height, &tc.chain.params) as u64;
     let coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
-    Job::on_tip(&tc, 9, &coinbase, &[&a, &b]).send(&mut c).await;
-    let ok = expect_job_success(&mut c).await;
-    assert_eq!(
-        (ok.request_id, ok.template_id, ok.fees),
-        (9, last + 1, 5_000)
-    );
-    expect_retained(&mut c, ok.template_id, &[&a, &b]).await;
+    Job::declare(&tc, 9, &coinbase, &[&a, &b])
+        .send(&mut c)
+        .await;
+    expect_job_success(&mut c, &tc, 9, last + 1, 5_000).await;
+    expect_retained(&mut c, last + 1, &[&a, &b]).await;
 
     tp.shutdown().await;
 }
@@ -1297,7 +1316,7 @@ async fn propose_template_asks_for_and_accepts_missing_transactions() {
     let height = tc.chain.query.tip_height().unwrap().0 + 1;
     let subsidy = block_subsidy(height, &tc.chain.params) as u64;
     let coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
-    let mut job = Job::on_tip(&tc, 4, &coinbase, &[&a, &b]);
+    let mut job = Job::declare(&tc, 4, &coinbase, &[&a, &b]);
     job.send(&mut c).await;
     let mut f = recv_in_time(&mut c).await;
     assert_eq!(
@@ -1311,22 +1330,20 @@ async fn propose_template_asks_for_and_accepts_missing_transactions() {
 
     job.supplied = vec![serialize(&b)];
     job.send(&mut c).await;
-    let ok = expect_job_success(&mut c).await;
-    assert_eq!(
-        (ok.request_id, ok.template_id, ok.fees),
-        (4, last + 1, 5_000)
-    );
-    expect_retained(&mut c, ok.template_id, &[&a, &b]).await;
+    expect_job_success(&mut c, &tc, 4, last + 1, 5_000).await;
+    expect_retained(&mut c, last + 1, &[&a, &b]).await;
 
     tp.shutdown().await;
 }
 
 /// §4.1 and §4.4: everything in a job comes from a JDC. The checks run in
-/// order before any mempool lookup or transaction decode: a prev hash off
-/// the tip, a repeated wtxid, a supplied tx nobody declared (or one that
-/// does not decode), an undecodable coinbase, then the proposal check's own
-/// reject string. While the tip is stale (IBD) every job is
-/// `job-validation-unavailable`. Nothing is retained on an error.
+/// order before any mempool lookup or transaction decode: a repeated wtxid,
+/// a supplied tx nobody declared (or one that does not decode), a coinbase
+/// prefix that does not parse or a coinbase that does not decode, then the
+/// proposal check's own reject string: a declaration from before the tip
+/// moved fails its BIP34 height, an overpaying coinbase its amount. While
+/// the tip is stale (IBD) every job is `job-validation-unavailable`.
+/// Nothing is retained on an error.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_rejects_untrusted_input_in_order() {
     let tc = shared_regtest(2);
@@ -1342,40 +1359,54 @@ async fn propose_template_rejects_untrusted_input_in_order() {
     let coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
 
     // The padded tip is far in the past: the node is in IBD.
-    Job::on_tip(&tc, 1, &coinbase, &[&a, &b]).send(&mut c).await;
+    Job::declare(&tc, 1, &coinbase, &[&a, &b])
+        .send(&mut c)
+        .await;
     expect_job_error(&mut c, 1, "job-validation-unavailable").await;
     mock_live_tip(&tc);
     c.coinbase_output_constraints(0, 0).await.unwrap();
     let last = expect_template(&mut c, &tc, &[&a, &b], true).await;
 
-    let mut stale = Job::on_tip(&tc, 2, &coinbase, &[&a, &b]);
-    stale.prev_hash = [0xab; 32];
-    stale.send(&mut c).await;
-    expect_job_error(&mut c, 2, "stale-prevhash").await;
-
-    Job::on_tip(&tc, 3, &coinbase, &[&a, &a]).send(&mut c).await;
-    expect_job_error(&mut c, 3, "duplicate-wtxid").await;
+    Job::declare(&tc, 2, &coinbase, &[&a, &a])
+        .send(&mut c)
+        .await;
+    expect_job_error(&mut c, 2, "duplicate-wtxid").await;
 
-    let mut undeclared = Job::on_tip(&tc, 4, &coinbase, &[&a]);
+    let mut undeclared = Job::declare(&tc, 3, &coinbase, &[&a]);
     undeclared.supplied = vec![serialize(&b)];
     undeclared.send(&mut c).await;
-    expect_job_error(&mut c, 4, "bad-missing-tx").await;
+    expect_job_error(&mut c, 3, "bad-missing-tx").await;
 
     let blob = vec![0xee; 40];
-    let mut garbage = Job::on_tip(&tc, 5, &coinbase, &[]);
+    let mut garbage = Job::declare(&tc, 4, &coinbase, &[]);
     garbage.wtxids = vec![sha256d::Hash::hash(&blob).to_byte_array()];
     garbage.supplied = vec![blob];
     garbage.send(&mut c).await;
-    expect_job_error(&mut c, 5, "bad-missing-tx").await;
+    expect_job_error(&mut c, 4, "bad-missing-tx").await;
 
-    let mut bad_cb = Job::on_tip(&tc, 6, &coinbase, &[&a, &b]);
-    bad_cb.coinbase = vec![0xcc; 20];
-    bad_cb.send(&mut c).await;
+    // More scriptSig bytes than the length the prefix declares.
+    let mut short_sig = Job::declare(&tc, 5, &coinbase, &[&a, &b]);
+    short_sig.coinbase_prefix.extend_from_slice(&[0; 16]);
+    short_sig.send(&mut c).await;
+    expect_job_error(&mut c, 5, "bad-cb-decode").await;
+
+    let mut two_inputs = Job::declare(&tc, 6, &coinbase, &[&a, &b]);
+    two_inputs.coinbase_prefix[4 + 2] = 2;
+    two_inputs.send(&mut c).await;
     expect_job_error(&mut c, 6, "bad-cb-decode").await;
 
+    let mut bad_cb = Job::declare(&tc, 7, &coinbase, &[&a, &b]);
+    bad_cb.coinbase_suffix.truncate(3);
+    bad_cb.send(&mut c).await;
+    expect_job_error(&mut c, 7, "bad-cb-decode").await;
+
+    let old = job_coinbase(height - 1, subsidy + 5_000, &[&a, &b]);
+    Job::declare(&tc, 8, &old, &[&a, &b]).send(&mut c).await;
+    expect_job_error(&mut c, 8, "bad-cb-height").await;
+
     let fat = job_coinbase(height, subsidy + 5_001, &[&a, &b]);
-    Job::on_tip(&tc, 7, &fat, &[&a, &b]).send(&mut c).await;
-    expect_job_error(&mut c, 7, "bad-cb-amount").await;
+    Job::declare(&tc, 9, &fat, &[&a, &b]).send(&mut c).await;
+    expect_job_error(&mut c, 9, "bad-cb-amount").await;
 
     c.request_transaction_data(last + 1).await.unwrap();
     let mut f = recv_in_time(&mut c).await;
@@ -1413,12 +1444,13 @@ async fn submit_solution_for_a_validated_job_becomes_the_tip() {
     let height = tc.chain.query.tip_height().unwrap().0 + 1;
     let subsidy = block_subsidy(height, &tc.chain.params) as u64;
     let mut coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
-    Job::on_tip(&tc, 1, &coinbase, &[&a, &b]).send(&mut c).await;
-    let ok = expect_job_success(&mut c).await;
-    assert_eq!(ok.template_id, last + 1);
+    Job::declare(&tc, 1, &coinbase, &[&a, &b])
+        .send(&mut c)
+        .await;
+    expect_job_success(&mut c, &tc, 1, last + 1, 5_000).await;
 
     let mut script_sig = bip34_height_script(height);
-    script_sig.extend_from_slice(&[0x42; 8]);
+    script_sig.extend_from_slice(&[0x42; EXTRANONCE_LEN]);
     coinbase.input[0].script_sig = ScriptBuf::from_bytes(script_sig);
     let mut leaves = vec![coinbase.compute_txid().to_byte_array()];
     leaves.extend([&a, &b].iter().map(|tx| tx.compute_txid().to_byte_array()));
@@ -1430,7 +1462,7 @@ async fn submit_solution_for_a_validated_job_becomes_the_tip() {
         header.nonce += 1;
     }
     c.submit_solution(
-        ok.template_id,
+        last + 1,
         version,
         header.time,
         header.nonce,
diff --git a/crates/rbitcoin-sv2/src/transport.rs b/crates/rbitcoin-sv2/src/transport.rs
index 07533486c..62612bf5d 100644
--- a/crates/rbitcoin-sv2/src/transport.rs
+++ b/crates/rbitcoin-sv2/src/transport.rs
@@ -26,17 +26,17 @@ pub struct Frame {
 /// make the session buffer ~16 MB per frame.
 const MAX_CLIENT_PAYLOAD: usize = 20 + 2 + u16::MAX as usize;
 
-/// Largest `ProposeTemplate` payload: 40 fixed bytes, a `B064K` coinbase,
-/// a full `SEQ0_64K[U256]` wtxid list, and a `SEQ0_64K[B016M]` transaction
-/// list whose txs together fit a block (weight is never below serialized
-/// size) with a 3-byte length each.
+/// Largest `ProposeTemplate` payload: 8 fixed bytes, three `B064K` fields
+/// (coinbase prefix, suffix, excess data), a full `SEQ0_64K[U256]` wtxid
+/// list, and a `SEQ0_64K[B016M]` transaction list whose txs together fit a
+/// block (weight is never below serialized size) with a 3-byte length each.
 ///
 /// RAM trade (CONTRIBUTING 9): a session buffers one in-flight client frame
-/// of at most this size (~6.4 MB), so at `MAX_SESSIONS` client frames hold
-/// ≤ ~51 MB on top of template retention (lib.rs).
+/// of at most this size (~6.5 MB), so at `MAX_SESSIONS` client frames hold
+/// ≤ ~52 MB on top of template retention (lib.rs).
 pub(crate) const MAX_PROPOSE_TEMPLATE_PAYLOAD: usize = {
     const SEQ: usize = u16::MAX as usize;
-    4 + 32 + 4 + (2 + SEQ) + (2 + SEQ * 32) + (2 + SEQ * 3 + MAX_BLOCK_WEIGHT as usize)
+    4 + 4 + 3 * (2 + SEQ) + (2 + SEQ * 32) + (2 + SEQ * 3 + MAX_BLOCK_WEIGHT as usize)
 };
 
 /// Payload cap by client message type.

From 925f684399980e126ac4e0ad0d5ab3855d20b6ac Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Wed, 7 Oct 2026 12:15:41 -0400
Subject: [PATCH 10/19] docs: align the job validation draft and plan D with
 sv2-spec#239
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/sv2-job-validation.md now names discussion #239 as the venue (#217
stays as the origin): §2 flow and the no-`prev_hash` rationale, §4.1 field
table with `coinbase_tx_prefix` / `coinbase_tx_suffix` / `excess_data` and
the placeholder derivation moved to the server side (E = L − P, the bounds,
`bad-cb-decode`), the stale-prevhash rule replaced by how a stale
declaration surfaces, §4.3 `prev_hash`, §4.4 table without `stale-prevhash`
and with `bad-cb-decode`, §4.5 and §7.1 JDS mapping (relay the
DeclareMiningJob fields unchanged; keep `Success.prev_hash` for the
`PushSolution.prev_hash` check), §6 and §8 with #239. Plan D gains D8 and
D9 for the rename and the field change, the frame cap is re-priced
(~6.5 MB / ~52 MB), and the extranonce-tail assumption is listed as a
TP-side risk. The changelog fragment, operator doc, COMPAT row, and docs
index follow the wire.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 COMPAT.md                         |   2 +-
 changelog.d/sv2-job-validation.md |  12 ++-
 docs/README.md                    |   2 +-
 docs/operator/interfaces.md       |  11 ++-
 docs/sv2-job-validation.md        | 150 ++++++++++++++++++------------
 docs/sv2-template-provider.md     |  74 ++++++++++++---
 6 files changed, 169 insertions(+), 82 deletions(-)

diff --git a/COMPAT.md b/COMPAT.md
index 8f737e44d..161f24730 100644
--- a/COMPAT.md
+++ b/COMPAT.md
@@ -72,7 +72,7 @@ Full `/tx/:txid` JSON still has `vin[]`. Electrum has no outspend-vin surface.
 | Package submit | RPC `submitpackage` / Esplora `POST /txs/package` (no P2P package command) | BIP331 wire |
 | Pruning / GUI | Unpruned: `seqsigwit.body`. `--prune-seqsigwit`: watermark + `NETWORK_LIMITED`, kept witness is 288 height files under `store/seqsigwit.window/` plus a RAM cap (`--prune-seqsigwit-ram-threshold-bytes`, `0` = files only). Not a rolling stem. Not Core `-prune` of headers/txout | Supported |
 | Mining template RPC | `getblocktemplate` / `getmininginfo` / `prioritisetransaction` (selector; no stratum) | GBT + stratum / pool stack |
-| SV2 Template Distribution | In-process TDP v2 server over Noise NX (`--sv2-tp-listen`, default off): `NewTemplate` / `SetNewPrevHash` per tip, `NewTemplate` on a same-tip fee gain (`--sv2-tp-fee-delta`, `--sv2-tp-template-interval`, sv2-tp defaults), `RequestTransactionData`, `SubmitSolution` → block accept; `ProposeTemplate` for a Job Declarator Server's node backend (proposed TDP messages, sv2-spec#217, `SetupConnection` flag bit 0). No templates during IBD; every template on the tip kept, up to 64 per session. No plaintext, no pool / JD roles | No TDP in Core; sv2-apps `bitcoin-core-sv2` bridges Core's IPC mining interface to TDP |
+| SV2 Template Distribution | In-process TDP v2 server over Noise NX (`--sv2-tp-listen`, default off): `NewTemplate` / `SetNewPrevHash` per tip, `NewTemplate` on a same-tip fee gain (`--sv2-tp-fee-delta`, `--sv2-tp-template-interval`, sv2-tp defaults), `RequestTransactionData`, `SubmitSolution` → block accept; `ProposeTemplate` for a Job Declarator Server's node backend (proposed TDP messages, sv2-spec discussion #239, `SetupConnection` flag bit 0). No templates during IBD; every template on the tip kept, up to 64 per session. No plaintext, no pool / JD roles | No TDP in Core; sv2-apps `bitcoin-core-sv2` bridges Core's IPC mining interface to TDP |
 | Wallets | Electrum clients (requires `--sh-index`) | Descriptor + legacy |
 | Scripthash index | Optional (`--sh-index`, default **off**); bulk at tip when on | External ElectrumX / Fulcrum; Core `-txindex` is different (txid→block) |
 | JSON-RPC | Documented **subset** ([`docs/rpc.md`](./docs/rpc.md)); Bearer token or opt-in Core cookie (`--rpc-cookie-file`), no `--rpcuser` / `--rpcpassword`; `rbitcoin-cli`. `--rpc-work-queue` defaults to **16** (HTTP occupancy, 503 when full; **0** is that default); a JSON-RPC array is one POST | Full Core RPC; `-rpcworkqueue` is in-flight HTTP jobs (503) |
diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
index f50387b7e..e83e85b7c 100644
--- a/changelog.d/sv2-job-validation.md
+++ b/changelog.d/sv2-job-validation.md
@@ -2,11 +2,13 @@ Added
 
 - **SV2 TP: custom job validation for Job Declarator Servers.** A TDP
   client that sets `SetupConnection` flag bit 0 (`REQUIRES_JOB_VALIDATION`)
-  can send `ProposeTemplate` (proposed TDP messages 0x77–0x7a,
-  sv2-spec#217). The node resolves the declared wtxids against its mempool,
-  asks for the ones it lacks, checks the job as a block on its tip, and
-  answers the fee total with a template id that `SubmitSolution` accepts
-  like one of the node's own templates. Stale, duplicated, or undeclared
+  can send `ProposeTemplate` (proposed TDP messages 0x77–0x7a, sv2-spec
+  discussion #239) with the `DeclareMiningJob` fields relayed unchanged.
+  The node rebuilds the placeholder coinbase from the declared prefix and
+  suffix, resolves the declared wtxids against its mempool, asks for the
+  ones it lacks, checks the job as a block on its tip, and answers the fee
+  total and that tip with a template id that `SubmitSolution` accepts like
+  one of the node's own templates. Duplicated, undeclared, or malformed
   input is refused before anything is decoded.
 
 Changed
diff --git a/docs/README.md b/docs/README.md
index 61b92b17c..f869a1329 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -52,7 +52,7 @@ into `AGENTS.md`.
 | [`overlay-functional.md`](./overlay-functional.md) | Private Tor / i2pd / cjdns mesh harness (labeled / nightly). |
 | [`how-we-plan.md`](./how-we-plan.md) | Agent contract (cycle, Agent RAM, keep-compiling), then human rationale. |
 | [`sv2-template-provider.md`](./sv2-template-provider.md) | SV2 Template Distribution Protocol server roadmap (**Q-64**): Step 0 finding and plans A–D. Live flags/COMPAT rows land in OPERATOR/COMPAT with the plan that ships them. |
-| [`sv2-job-validation.md`](./sv2-job-validation.md) | Proposed TDP messages for JDS job validation (`ProposeTemplate`, sv2-spec#217); owner of the wire contract until it lands upstream. Plan D in `sv2-template-provider.md` is the implementation. |
+| [`sv2-job-validation.md`](./sv2-job-validation.md) | Proposed TDP messages for JDS job validation (`ProposeTemplate`, sv2-spec discussion #239); owner of the wire contract until it lands upstream. Plan D in `sv2-template-provider.md` is the implementation. |
 | [`releases.md`](./releases.md) | Tag `vX.Y.Z`, `vX.Y.x` patch line, `.99` bump, Highlights / GitHub notes. |
 | [`code-shape.md`](./code-shape.md) | Control flow, types, naming, composition (CONTRIBUTING principle 10). Named extracts: quality.md **Q-61** (Completed). Clippy: no workspace `allow` list; leftover lints are site-local with a reason. |
 | [`quality.md`](./quality.md) | Living quality roadmap (Open + Won't-fix + Parked + Protect). |
diff --git a/docs/operator/interfaces.md b/docs/operator/interfaces.md
index 14b6e9167..7fd21b08e 100644
--- a/docs/operator/interfaces.md
+++ b/docs/operator/interfaces.md
@@ -306,11 +306,12 @@ that misses the template target is logged and dropped. A `header_timestamp`
 outside the sv2 rolling window (a miner clock running ahead) is logged and
 still submitted; block validation applies the consensus time rules.
 A client that sets `SetupConnection` flag bit 0 (`REQUIRES_JOB_VALIDATION`)
-can send `ProposeTemplate` (proposed TDP messages, sv2-spec#217): the node
-checks a Job Declarator Server's declared job as a block on its tip (no proof
-of work; no script checks beyond what mempool admission already ran), asks for
-the transactions it lacks, and retains a valid job under a template id that
-`SubmitSolution` accepts. Without the flag the messages are ignored. There is
+can send `ProposeTemplate` (proposed TDP messages, sv2-spec discussion #239):
+the node checks a Job Declarator Server's declared job as a block on its tip
+(no proof of work; no script checks beyond what mempool admission already
+ran), asks for the transactions it lacks, and retains a valid job under a
+template id that `SubmitSolution` accepts, naming the tip it validated on.
+Without the flag the messages are ignored. There is
 no operator switch; the flag is per session.
 
 There is no client authentication. Noise NX proves the TP's authority key
diff --git a/docs/sv2-job-validation.md b/docs/sv2-job-validation.md
index 07bb97b58..cca8f62b9 100644
--- a/docs/sv2-job-validation.md
+++ b/docs/sv2-job-validation.md
@@ -1,7 +1,9 @@
 # Stratum V2: Custom Job Validation over the Template Distribution Protocol
 
-Draft for discussion on [sv2-spec#217](https://github.com/stratum-mining/sv2-spec/issues/217).
-Written as new core Template Distribution Protocol (TDP) messages so it can be
+Draft for [sv2-spec discussion #239](https://github.com/stratum-mining/sv2-spec/discussions/239)
+(`ProposeTemplate`, plebhash, 2026-10-06), which supersedes
+[sv2-spec#217](https://github.com/stratum-mining/sv2-spec/issues/217), where
+this started. Written as new core Template Distribution Protocol (TDP) messages so it can be
 folded into `07-Template-Distribution-Protocol.md` and `08-Message-Types.md`.
 Section 6 lists the open questions, including the extension alternative.
 
@@ -18,9 +20,10 @@ similar)", Section 6.1).
 This document adds four TDP messages and one `SetupConnection` flag so that a
 JDS can validate a declared Custom Job, and later submit its solution, through
 any Template Provider (TP) over the authenticated TDP connection it already
-uses. The exchange mirrors the flow the Job Declaration Protocol already
-imposes on JDS: look transactions up by `wtxid`, ask JDC for the ones nobody
-has, validate, and submit the solution by reference.
+uses. The request carries the subset of `DeclareMiningJob` a node needs,
+relayed unchanged. The exchange mirrors the flow the Job Declaration Protocol
+already imposes on JDS: look transactions up by `wtxid`, ask JDC for the ones
+nobody has, validate, and submit the solution by reference.
 
 ## 1. Motivation
 
@@ -50,12 +53,12 @@ has, validate, and submit the solution by reference.
 ```
 JDC                      JDS                             TP
  |-- DeclareMiningJob --->|                               |
- |                        |-- ProposeTemplate --------->|  wtxid_list, coinbase, no txs
+ |                        |-- ProposeTemplate --------->|  version, coinbase prefix/suffix, wtxid_list, no txs
  |                        |<- ProposeTemplate.MissingTransactions   (only if TP lacks some)
  |<- ProvideMissingTransactions                           |
  |-- ProvideMissingTransactions.Success ->|               |
  |                        |-- ProposeTemplate --------->|  same job + transaction_list
- |                        |<- ProposeTemplate.Success --|  template_id, fees
+ |                        |<- ProposeTemplate.Success --|  template_id, prev_hash, fees
  |<- DeclareMiningJob.Success             |               |
  ...
  |-- PushSolution ------->|                               |
@@ -65,6 +68,10 @@ JDC                      JDS                             TP
 - `ProposeTemplate` is stateless on the server side across the
   missing-transactions round trip: the second request repeats the job and adds
   the transactions. The TP MUST NOT require any state from the first request.
+- `ProposeTemplate` carries no `prev_hash`: `DeclareMiningJob` has none, so a
+  JDS cannot supply one without guessing. The TP validates against its own
+  current tip and names that tip in `ProposeTemplate.Success.prev_hash`, which
+  the JDS keeps to check `PushSolution.prev_hash` against.
 - `ProposeTemplate.Success` assigns a `template_id` from the same namespace as
   `NewTemplate.template_id`. The solution is then sent with the existing
   `SubmitSolution` message (Section 7.8). No new submission message is needed.
@@ -101,35 +108,44 @@ Asks the Template Provider whether a Custom Job, declared to the client via
 `DeclareMiningJob`, would produce a consensus-valid block on top of the
 server's current chain tip.
 
-| Field Name       | Data Type        | Description                                                                                                                                                                                                                                                                              |
-| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| request_id       | U32              | Unique identifier for pairing the response                                                                                                                                                                                                                                               |
-| prev_hash        | U256             | Hash of the block the Custom Job builds on, as it would appear in the block header                                                                                                                                                                                                      |
-| version          | U32              | Block header version field as declared in `DeclareMiningJob.version`. BIP323 general-purpose bits are ignored by the server                                                                                                                                                              |
-| coinbase_tx      | B0_64K           | Full serialized coinbase transaction, with the extranonce region filled with placeholder bytes of the correct length. If the coinbase is a SegWit transaction, BIP141 fields (marker, flag, witness count, witness length, witness reserved value) MUST NOT be stripped                 |
-| wtxid_list       | SEQ0_64K[U256]   | `wtxid` of every transaction in the Custom Job, in block order, excluding the coinbase. Copied from `DeclareMiningJob.wtxid_list`                                                                                                                                                         |
-| transaction_list | SEQ0_64K[B0_16M] | Full transactions the server reported in `ProposeTemplate.MissingTransactions`, in the order they were requested. Empty on the first request. Each transaction MUST be relayed exactly as received from JDC in `ProvideMissingTransactions.Success`, without parsing or re-encoding    |
-
-The client derives the extranonce length as the scriptSig length encoded in
-`DeclareMiningJob.coinbase_tx_prefix` minus the scriptSig bytes present in the
-prefix. This assumes the extranonce is the final part of the scriptSig, so
-`coinbase_tx_suffix` begins at `nSequence`. That is how `NewExtendedMiningJob`
-splits the coinbase in practice and what the reference JDS already assumes,
-but the Job Declaration Protocol does not state it; see Section 6. The
-placeholder value is irrelevant: the server does not
-check the merkle root or proof of work, and every other coinbase check (size,
-weight, BIP34 height push, output values, witness commitment) is independent
-of the extranonce bytes.
+| Field Name         | Data Type        | Description                                                                                                                                                                                                                                                                              |
+| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| request_id         | U32              | Unique identifier for pairing the response                                                                                                                                                                                                                                               |
+| version            | U32              | Block header version field as declared in `DeclareMiningJob.version`. BIP323 general-purpose bits are ignored by the server                                                                                                                                                              |
+| coinbase_tx_prefix | B0_64K           | `DeclareMiningJob.coinbase_tx_prefix` unchanged: the serialized coinbase up to and including the scriptSig bytes before the extranonce                                                                                                                                                   |
+| coinbase_tx_suffix | B0_64K           | `DeclareMiningJob.coinbase_tx_suffix` unchanged: the serialized coinbase from the input's `nSequence` on. If the coinbase is a SegWit transaction, BIP141 fields (marker and flag in the prefix; witness count, witness length, witness reserved value in the suffix) MUST NOT be stripped |
+| wtxid_list         | SEQ0_64K[U256]   | `wtxid` of every transaction in the Custom Job, in block order, excluding the coinbase. Copied from `DeclareMiningJob.wtxid_list`                                                                                                                                                         |
+| excess_data        | B0_64K           | `DeclareMiningJob.excess_data` unchanged. Opaque to the server; its meaning is between JDC and Pool (Section 7.6)                                                                                                                                                                         |
+| transaction_list   | SEQ0_64K[B0_16M] | Full transactions the server reported in `ProposeTemplate.MissingTransactions`, in the order they were requested. Empty on the first request. Each transaction MUST be relayed exactly as received from JDC in `ProvideMissingTransactions.Success`, without parsing or re-encoding    |
+
+The server reconstructs a placeholder coinbase as `coinbase_tx_prefix` ||
+`E` zero bytes || `coinbase_tx_suffix`, where `E` is the scriptSig length
+the prefix encodes minus the scriptSig bytes the prefix carries: parse the
+version (4 bytes), the BIP144 marker `0x00` and flag `0x01` when present, the
+input count (MUST be 1), the 36-byte prevout, and the scriptSig length `L` as
+a CompactSize, leaving `P` bytes; `E = L - P`. The server MUST require
+`2 <= L <= 100` and `P <= L`, and MUST reply `bad-cb-decode` when the prefix
+does not parse this way or the reconstructed bytes do not decode as a
+transaction. This assumes the extranonce is the final part of the scriptSig,
+so `coinbase_tx_suffix` begins at `nSequence`. That is how
+`NewExtendedMiningJob` splits the coinbase in practice and what the reference
+JDS already assumes, but the Job Declaration Protocol does not state it; see
+Section 6. The placeholder value is irrelevant: the server does not check the
+merkle root or proof of work, and every other coinbase check (size, weight,
+BIP34 height push, output values, witness commitment) is independent of the
+extranonce bytes.
 
 The server resolves each `wtxid` against its mempool and against
 `transaction_list`. If any transaction is still unknown, it MUST reply
 `ProposeTemplate.MissingTransactions`. Otherwise it MUST validate the job as
-a block on top of `prev_hash` with the following rules, and reply either
-`ProposeTemplate.Success` or `ProposeTemplate.Error`:
-
-- `prev_hash` MUST equal the server's current chain tip. Otherwise the server
-  MUST reply with error code `stale-prevhash`. The server MUST NOT accept a
-  job on a tip it has already left.
+a block on top of its current chain tip with the following rules, and reply
+either `ProposeTemplate.Success` or `ProposeTemplate.Error`:
+
+- The server validates against its own current tip and reports that tip in
+  `ProposeTemplate.Success.prev_hash`. There is no stale-tip error code: a
+  job declared for a tip the server has since left fails the checks below on
+  its own, normally the BIP34 height push (`bad-cb-height`) or an input the
+  new tip spent; a job that still passes on the new tip is valid there.
 - `wtxid_list` MUST contain no duplicates, and every entry of
   `transaction_list` MUST hash to a `wtxid` that the server reported missing.
   Otherwise reply `duplicate-wtxid` or `bad-missing-tx`. These checks MUST run
@@ -138,10 +154,10 @@ a block on top of `prev_hash` with the following rules, and reply either
   block except the proof-of-work check and the merkle-root check. This
   includes: transaction validity and input availability against the UTXO set
   and the mempool, transaction ordering, block weight and sigop limits with
-  `coinbase_tx` counted as sent, coinbase scriptSig length and BIP34 height,
-  coinbase output value not exceeding subsidy plus fees, and the BIP141
-  witness commitment computed over `wtxid_list` with the witness reserved
-  value taken from `coinbase_tx`. This is the check performed by
+  the reconstructed coinbase counted, coinbase scriptSig length and BIP34
+  height, coinbase output value not exceeding subsidy plus fees, and the
+  BIP141 witness commitment computed over `wtxid_list` with the witness
+  reserved value taken from `coinbase_tx_suffix`. This is the check performed by
   `getblocktemplate` in `proposal` mode and by Bitcoin Core's IPC
   `checkBlock` with `checkMerkleRoot=false` and `checkPow=false`.
 - The server MUST NOT reject a consensus-valid job on local policy grounds
@@ -182,10 +198,12 @@ the job and will accept a `SubmitSolution` for it.
 | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | request_id  | U32       | Identifier of the original `ProposeTemplate` request                                                                                                                                  |
 | template_id | U64       | Server's identification of the validated job. Drawn from the same strictly increasing namespace as `NewTemplate.template_id`, so it can be used in `SubmitSolution` and `RequestTransactionData` |
+| prev_hash   | U256      | Hash of the server's chain tip the job was validated on, as it would appear in the block header. The client keeps it to compare against `PushSolution.prev_hash`                      |
 | fees        | U64       | Sum of the fees of the transactions in `wtxid_list`, in satoshis                                                                                                                       |
 
 The server MUST retain the validated job (its `wtxid_list`, the transactions
-it received in `transaction_list`, and `coinbase_tx` for size accounting)
+it received in `transaction_list`, and the reconstructed coinbase for size
+accounting)
 until a newer `ProposeTemplate.Success` is sent on the same connection or
 the connection closes, whichever comes first. This matches the guarantee JDS
 gives JDC in Section 6.4.9: `PushSolution` is only guaranteed to be valid for
@@ -196,8 +214,10 @@ its own templates.
 ### 4.4 `ProposeTemplate.Error` (Server -> Client)
 
 The job was not validated. The client decides what to tell JDC; it SHOULD map
-consensus rejections to `DeclareMiningJob.Error` and SHOULD NOT treat
-`stale-prevhash` on a tip the client has not yet seen as a JDC fault.
+consensus rejections to `DeclareMiningJob.Error` and SHOULD NOT treat the
+rejection of a job declared on a tip the server has since left (a
+`bad-cb-height` for a job the client knows was built on the previous
+`ProposeTemplate.Success.prev_hash`) as a JDC fault.
 
 | Field Name    | Data Type | Description                                            |
 | ------------- | --------- | ------------------------------------------------------ |
@@ -211,16 +231,18 @@ rejection strings (`bad-txns-inputs-missingorspent`, `bad-cb-length`,
 
 | error_code                | Meaning                                                              |
 | ------------------------- | -------------------------------------------------------------------- |
-| stale-prevhash            | `prev_hash` is not the server's current tip                           |
 | duplicate-wtxid           | `wtxid_list` contains the same `wtxid` more than once                |
 | bad-missing-tx            | An entry of `transaction_list` does not hash to a requested `wtxid`  |
+| bad-cb-decode             | `coinbase_tx_prefix` does not parse as one input with a scriptSig length covering the bytes present, or the reconstructed coinbase does not decode |
 | job-validation-unavailable | The server cannot validate now (for example, initial block download) |
 
 ### 4.5 `SubmitSolution` for validated jobs
 
-When the client receives `PushSolution` from JDC it MUST reconstruct the full
-coinbase (`coinbase_tx_prefix` || `extranonce` || `coinbase_tx_suffix`) and
-send `SubmitSolution` (Section 7.8) with `template_id` set to the value from
+When the client receives `PushSolution` from JDC it SHOULD check
+`PushSolution.prev_hash` against the `ProposeTemplate.Success.prev_hash`
+stored with the declaration, then MUST reconstruct the full coinbase
+(`coinbase_tx_prefix` || `extranonce` || `coinbase_tx_suffix`) and send
+`SubmitSolution` (Section 7.8) with `template_id` set to the value from
 `ProposeTemplate.Success`, and `version`, `ntime`, `nonce` and `coinbase_tx`
 from the solution.
 
@@ -255,12 +277,18 @@ All four are core messages and carry `extension_type = 0x0000`.
   `extension_type = 0x0003`. The `SetupConnection` flag in Section 3 gives
   negotiation without requiring extension `0x0001` in TPs, which is why the
   draft uses it. The field tables are identical either way.
-- **Extranonce position.** Section 4.1's placeholder construction needs the
-  extranonce to be the tail of the scriptSig. Either the Job Declaration
-  Protocol should state that `DeclareMiningJob.coinbase_tx_suffix` begins at
-  `nSequence`, or `DeclareMiningJob` should carry the extranonce size. The
-  reference JDS has the same dependency today when it rebuilds the coinbase
-  for Core's `checkBlock` (`sv2-apps#645`).
+- **Extranonce position.** The server-side placeholder construction in
+  Section 4.1 needs the extranonce to be the tail of the scriptSig. Either
+  the Job Declaration Protocol should state that
+  `DeclareMiningJob.coinbase_tx_suffix` begins at `nSequence`, or
+  `DeclareMiningJob` should carry the extranonce size. The reference JDS has
+  the same dependency today when it rebuilds the coinbase for Core's
+  `checkBlock` (`sv2-apps#645`).
+- **No `prev_hash` in the request.** `DeclareMiningJob` carries none, so a
+  JDS would have to guess one; the request would also go stale in flight. The
+  server validates on its own tip and names it in `Success` (discussion #239).
+  A declaration from before a tip change is caught by the BIP34 height push,
+  not by a dedicated code.
 - **Coinbase-only mode.** Out of scope. In Coinbase-only mode neither Pool nor
   JDS learns the transaction set, so a node has nothing to validate beyond the
   coinbase, which `SetCustomMiningJob` already carries to the Pool. A
@@ -296,12 +324,12 @@ All four are core messages and carry `extension_type = 0x0000`.
 
 | JDP event                            | TDP action                                                                    |
 | ------------------------------------ | ----------------------------------------------------------------------------- |
-| `DeclareMiningJob`                   | `ProposeTemplate` with `wtxid_list` copied, `coinbase_tx` from prefix + placeholder + suffix, empty `transaction_list` |
+| `DeclareMiningJob`                   | `ProposeTemplate` with `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`, `excess_data` copied unchanged, empty `transaction_list` |
 | `ProposeTemplate.MissingTransactions` | `ProvideMissingTransactions` with the position list copied                  |
 | `ProvideMissingTransactions.Success` | `ProposeTemplate` again with `transaction_list` copied                       |
-| `ProposeTemplate.Success`          | `DeclareMiningJob.Success`; store `template_id` with the declaration           |
+| `ProposeTemplate.Success`          | `DeclareMiningJob.Success`; store `template_id` and `prev_hash` with the declaration |
 | `ProposeTemplate.Error`            | `DeclareMiningJob.Error` with the error code                                  |
-| `PushSolution`                       | `SubmitSolution(template_id, version, ntime, nonce, coinbase_tx)`              |
+| `PushSolution`                       | Check `prev_hash` against the stored one, then `SubmitSolution(template_id, version, ntime, nonce, coinbase_tx)` |
 
 No mempool mirror is needed on the JDS side. In `sv2-apps` this is a second
 `JobValidationEngine` implementation next to `BitcoinCoreIPCEngine`, and the
@@ -325,12 +353,18 @@ dependency.
 
 ## 8. Prior art
 
+- [sv2-spec discussion #239](https://github.com/stratum-mining/sv2-spec/discussions/239):
+  "RFC: `ProposeTemplate`" (plebhash, 2026-10-06), supersedes #217. Names the
+  message and carries the subset of `DeclareMiningJob` a node needs
+  (`request_id`, `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`,
+  `wtxid_list`, `excess_data`), with no `prev_hash`. This draft follows it
+  and adds the missing-transactions reply, `transaction_list` on the repeated
+  request, and `prev_hash` and `fees` in `Success`.
 - [sv2-spec#217](https://github.com/stratum-mining/sv2-spec/issues/217):
   "consider adding a new TDP message for custom job validation" (plebhash,
-  2026-08-31, open, no comments). Proposes message `X`, `X.Error` triggering
+  2026-08-31). Proposes message `X`, `X.Error` triggering
   `ProvideMissingTransactions`, `X.Success` gating `DeclareMiningJob.Success`,
-  and asks whether Coinbase-only mode could use it. This draft is a concrete
-  answer to it.
+  and asks whether Coinbase-only mode could use it. Where this draft started.
 - [sv2-spec#170](https://github.com/stratum-mining/sv2-spec/issues/170)
   (closed): `DeclareMiningJob` moved from `txid` to `wtxid` so JDS cannot match
   a transaction with a different witness. Names `getblocktemplate` `proposal`
@@ -360,8 +394,8 @@ dependency.
   [#645](https://github.com/stratum-mining/sv2-apps/issues/645),
   [#795](https://github.com/stratum-mining/sv2-apps/issues/795),
   [#796](https://github.com/stratum-mining/sv2-apps/issues/796): JDS
-  hardening issues that shaped Section 4.1's rules (stale detection by
-  `prev_hash` only, payout versus fees, coinbase prefix reconstruction,
-  staging supplied transactions, duplicate `wtxid` amplification).
+  hardening issues that shaped Section 4.1's rules (stale detection, payout
+  versus fees, coinbase prefix reconstruction, staging supplied
+  transactions, duplicate `wtxid` amplification).
 - `06-Job-Declaration-Protocol.md` Section 6.1 ("RPCs (or similar)") and
   Sections 6.4.7 to 6.4.9, whose encodings this draft copies.
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index 4617608fa..e0a8e4fee 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -97,8 +97,9 @@ Do not copy them here.
   receives a multi-MB `RequestTransactionData.Success`. The 30 s close is
   the operator page above.
 - Client frame cap, per message type: a `ProposeTemplate` payload over
-  `MAX_PROPOSE_TEMPLATE_PAYLOAD` (~6.4 MB: 40 fixed bytes, a `B064K`
-  coinbase, 65535 wtxids, and a block's worth of `B016M` txs) closes the
+  `MAX_PROPOSE_TEMPLATE_PAYLOAD` (~6.5 MB: 8 fixed bytes, three `B064K`
+  fields for the coinbase prefix, suffix, and excess data, 65535 wtxids,
+  and a block's worth of `B016M` txs) closes the
   session; every other client payload closes past `MAX_CLIENT_PAYLOAD`
   (65557 bytes: `SubmitSolution`'s 20 fixed bytes plus a full `B064K`
   coinbase). codec_sv2 decrypts the header into a private buffer and reads
@@ -106,7 +107,7 @@ Do not copy them here.
   frame: the reader counts encrypted bytes per frame against the larger
   cap and closes before reading the chunk that would pass it, then applies
   the per-type cap once the frame is whole. Named RAM trade: one in-flight
-  client frame of ≤ ~6.4 MB per session, ≤ ~51 MB at `MAX_SESSIONS`,
+  client frame of ≤ ~6.5 MB per session, ≤ ~52 MB at `MAX_SESSIONS`,
   instead of the ~16 MB the 24-bit length allows.
 - Per-session budget: weight `MAX_BLOCK_WEIGHT − max(1168 +
   4·coinbase_output_max_additional_size, 2000)` WU (sv2-spec 07 §7.1);
@@ -575,8 +576,8 @@ when fees rise enough to matter, throttled. Requires Plan B.
 holds, fetches the transactions the node lacks, and submits the found block
 by `template_id`. Wire contract: [`sv2-job-validation.md`](./sv2-job-validation.md)
 (proposed TDP messages 0x77–0x7a and `SetupConnection` flag bit 0, for
-sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
-`REQUIRES_JOB_VALIDATION`.
+sv2-spec discussion #239, which supersedes #217). Requires Plan B. Ships no
+flag: a session opts in with `REQUIRES_JOB_VALIDATION`.
 
 ### D1 — Block proposal check on `ChainHub`
 
@@ -618,14 +619,15 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
   `ProposeTemplate` over its cap close it.
 - **Green:** `FrameCap { max_frame, payload: fn(u8) -> usize }`: read
   against the largest client message, apply the per-type cap once whole.
-- **RAM trade:** one in-flight client frame of ≤ ~6.4 MB per session,
-  ≤ ~51 MB at `MAX_SESSIONS`.
+- **RAM trade:** one in-flight client frame of ≤ ~6.5 MB per session,
+  ≤ ~52 MB at `MAX_SESSIONS`.
 
 ### D4 — ProposeTemplate happy path
 
 - **Contract:** on a session that negotiated the flag, a
-  `ProposeTemplate` whose `prev_hash` is the tip, whose `wtxid_list` is
-  all in the mempool, and whose placeholder coinbase pays ≤ subsidy + fees
+  `ProposeTemplate` whose `prev_hash` is the tip (field dropped in D9),
+  whose `wtxid_list` is all in the mempool, and whose placeholder coinbase
+  pays ≤ subsidy + fees
   is answered `Success{request_id, template_id, fees}`: `template_id` is
   the next id in the session's counter, `fees` the sum over the declared
   txs. The job is retained exactly like a template, so
@@ -681,7 +683,8 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
 
 - **Contract:** `Error.error_code` in this order, before any mempool
   lookup or transaction decode: `job-validation-unavailable` while
-  `in_ibd()` (the template gate), `stale-prevhash`, `duplicate-wtxid`,
+  `in_ibd()` (the template gate), `stale-prevhash` (dropped in D9),
+  `duplicate-wtxid`,
   `bad-missing-tx` (a supplied tx whose hash is not in `wtxid_list`, or a
   declared blob that does not decode), `bad-cb-decode` (this TP's code;
   the draft has none for an undecodable coinbase), then the proposal
@@ -715,10 +718,52 @@ sv2-spec#217). Requires Plan B. Ships no flag: a session opts in with
   `docs/operator/interfaces.md`, the COMPAT row, and a `changelog.d`
   fragment.
 
+### D8 — Rename to `ProposeTemplate`
+
+- **Contract:** sv2-spec discussion #239 (plebhash, 2026-10-06) supersedes
+  #217 and names the message `ProposeTemplate`; `.MissingTransactions`,
+  `.Success`, `.Error` follow. Pure rename: structs, message-type consts,
+  the frame cap, the session handler, journey names, log strings, this
+  plan, the draft, the operator doc, the COMPAT row, the changelog
+  fragment. No behaviour change.
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib`; `rg ValidateCustomJob`
+  empty.
+
+### D9 — The `DeclareMiningJob` subset; `Success` names the tip
+
+- **Contract:** `ProposeTemplate` carries what a JDS has from
+  `DeclareMiningJob` and nothing it would have to invent: `request_id`,
+  `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`,
+  `excess_data` (opaque here), plus `transaction_list`. No `prev_hash`:
+  the TP validates on its current tip and `Success` carries that tip as
+  `prev_hash` next to `template_id` and `fees`. The TP builds the
+  placeholder coinbase: `E = L − P` from the prefix (version, BIP144
+  marker and flag when present, an input count that MUST be 1, the
+  prevout, scriptSig length `L`, `P` bytes present; `2 ≤ L ≤ 100`,
+  `P ≤ L`), coinbase = prefix ‖ zeros(E) ‖ suffix. A prefix that does not
+  parse, or a result that does not decode, is `bad-cb-decode`.
+  `stale-prevhash` is gone: a declaration from before the tip moved fails
+  the proposal check on its own (`bad-cb-height` for its BIP34 push).
+- **Red:** the four journeys send prefix/suffix and `expect_job_success`
+  asserts `Success.prev_hash == tip`;
+  `propose_template_rejects_untrusted_input_in_order` swaps the stale case
+  for an old-height declaration (`bad-cb-height`) and adds a prefix with
+  more scriptSig bytes than its length declares, a two-input prefix, and a
+  truncated suffix (all `bad-cb-decode`); `job_validation_messages_round_trip`
+  carries the new fields. Red was the compile error on the new fields.
+- **Green:** `messages.rs` fields; `job::extranonce_len` (unit-tested for
+  the legacy and segwit-marker prefix and each rejection) and the
+  placeholder assembly ahead of the coinbase decode; the request
+  `prev_hash` comparison dropped; `Success.prev_hash` from the retained
+  job's header. `MAX_PROPOSE_TEMPLATE_PAYLOAD` re-priced for three
+  `B064K` fields (~6.5 MB).
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
+
 ### Test budget
 
-Units: the messages round trip, `rbitcoin-net` `check_block_proposal_*`,
-`rbitcoin-rpc` GBT proposal `bad-cb-amount`. Journeys in `rbitcoin-sv2`
+Units: the messages round trip, `job::extranonce_len`, `rbitcoin-net`
+`check_block_proposal_*`, `rbitcoin-rpc` GBT proposal `bad-cb-amount`.
+Journeys in `rbitcoin-sv2`
 `template_tests`: four, each one TP and one session on the shared regtest
 pad. No `rbitcoin-test` node journey yet (follow-up with a JDS client).
 
@@ -749,6 +794,11 @@ pad. No `rbitcoin-test` node journey yet (follow-up with a JDS client).
 - The IBD gate (`job-validation-unavailable`) and `bad-cb-decode` are
   this TP's choices within the draft's "recommended" list and should
   follow the upstream text once it settles.
+- The extranonce-tail assumption (the suffix starts at `nSequence`) now
+  lives in this TP's `extranonce_len`, not in the JDS. A JDC whose
+  extranonce is not the scriptSig tail gets `bad-cb-decode` or a coinbase
+  check failure here; the draft asks the Job Declaration Protocol to state
+  the split (§6).
 - No policy is applied (the draft forbids it); `fees` lets the pool
   price the declared coinbase.
 - The JDS role itself, and a `rbitcoin-test` journey driving a JDS

From bcca6f1c839d7e9d9e70a4b2fa31e3a7ca6b912f Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Wed, 7 Oct 2026 12:32:58 -0400
Subject: [PATCH 11/19] sv2: drop fees from ProposeTemplate.Success and retain
 jobs like templates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`ProposeTemplate.Success` is `{request_id, template_id, prev_hash}`.
Bitcoin Core's IPC cannot produce a fee total for an externally proposed
block: `checkBlock` returns only reason, debug and result, and a
`TxCollection.makeTemplate` template throws on `getTxFees`, so sv2-tp
would have to send 0. One field with two meanings across TPs is worse
than none. The node's `bad-cb-amount` check already bounds the coinbase
at subsidy + fees and the Pool reads the claimed value from the coinbase
itself. `ChainHub::check_block_proposal` keeps returning `Ok(fees)`: it
is cross-crate API from D1 and GBT proposal mode may read it.

Retention: a JDS multiplexes many JDCs over one TDP connection, so
"keep the latest validated job" is the wrong guarantee. The draft §4.3
now requires the template rule instead (stale grace after a tip change,
oldest-first eviction by a per-connection cap of at least 64), notes
that `template_id` is unique per connection, and §7.1 says the JDS
needs no fallback because JDP 6.4.9 already has JDC propagate. The Plan
D eviction risk becomes that rule (D10). Agreed with the session that
owns Plan C.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 changelog.d/sv2-job-validation.md         |  9 ++--
 crates/rbitcoin-sv2/src/job.rs            | 25 ++++++-----
 crates/rbitcoin-sv2/src/messages.rs       |  2 -
 crates/rbitcoin-sv2/src/session.rs        |  3 +-
 crates/rbitcoin-sv2/src/template_tests.rs | 27 ++++--------
 docs/sv2-job-validation.md                | 54 ++++++++++++++---------
 docs/sv2-template-provider.md             | 43 +++++++++++++-----
 7 files changed, 94 insertions(+), 69 deletions(-)

diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
index e83e85b7c..00064a8ed 100644
--- a/changelog.d/sv2-job-validation.md
+++ b/changelog.d/sv2-job-validation.md
@@ -6,10 +6,11 @@ Added
   discussion #239) with the `DeclareMiningJob` fields relayed unchanged.
   The node rebuilds the placeholder coinbase from the declared prefix and
   suffix, resolves the declared wtxids against its mempool, asks for the
-  ones it lacks, checks the job as a block on its tip, and answers the fee
-  total and that tip with a template id that `SubmitSolution` accepts like
-  one of the node's own templates. Duplicated, undeclared, or malformed
-  input is refused before anything is decoded.
+  ones it lacks, checks the job as a block on its tip, and answers that tip
+  with a template id that `SubmitSolution` accepts like one of the node's
+  own templates; the job is retained like one too (same ring, same stale
+  grace). Duplicated, undeclared, or malformed input is refused before
+  anything is decoded.
 
 Changed
 
diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index f46dc7cc0..fec311291 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -16,8 +16,8 @@ pub(crate) enum Verdict {
     /// 0-indexed positions in `wtxid_list` neither the mempool nor
     /// `transaction_list` resolves.
     Missing(Vec<u16>),
-    /// Consensus-valid on the tip: the fee total and the job to retain.
-    Valid { fees: u64, job: Job },
+    /// Consensus-valid on the tip: the job to retain.
+    Valid(Job),
     /// `ProposeTemplate.Error.error_code`: a Core reject string or one of
     /// the draft's own codes.
     Rejected(String),
@@ -119,15 +119,18 @@ fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
     // (every spend against the chain, structure, weight, sigops, coinbase
     // value; no scripts, no PoW), on the blocking pool. A JDS sends one per
     // declaration; a flood costs blocking threads, not the reactor.
-    let fees = match chain.check_block_proposal(&block) {
-        Ok(fees) => fees,
-        Err(code) => return Ok(Verdict::Rejected(code)),
-    };
-    let txs = block.txdata.split_off(1).into_iter().map(Arc::new).collect();
-    Ok(Verdict::Valid {
-        fees,
-        job: next.job(rbitcoin_store::merkle_branch(&leaves, 0), txs),
-    })
+    if let Err(code) = chain.check_block_proposal(&block) {
+        return Ok(Verdict::Rejected(code));
+    }
+    let txs = block
+        .txdata
+        .split_off(1)
+        .into_iter()
+        .map(Arc::new)
+        .collect();
+    Ok(Verdict::Valid(
+        next.job(rbitcoin_store::merkle_branch(&leaves, 0), txs),
+    ))
 }
 
 /// §4.1: `coinbase_tx_prefix` ends inside the scriptSig and
diff --git a/crates/rbitcoin-sv2/src/messages.rs b/crates/rbitcoin-sv2/src/messages.rs
index f2ddd9e09..d3c2ccd20 100644
--- a/crates/rbitcoin-sv2/src/messages.rs
+++ b/crates/rbitcoin-sv2/src/messages.rs
@@ -44,7 +44,6 @@ pub(crate) struct ProposeTemplateSuccess<'decoder> {
     pub request_id: u32,
     pub template_id: u64,
     pub prev_hash: U256<'decoder>,
-    pub fees: u64,
 }
 
 /// TP → client: the job was not validated.
@@ -109,7 +108,6 @@ mod tests {
                 request_id: 7,
                 template_id: u64::MAX,
                 prev_hash: U256::from(&h1),
-                fees: 12_345,
             },
             &mut bytes,
         );
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index 6af962132..091d49e0e 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -561,7 +561,7 @@ impl Session {
                     .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, reply)
                     .await
             }
-            Verdict::Valid { fees, job } => {
+            Verdict::Valid(job) => {
                 self.templates.last_id += 1;
                 let template_id = self.templates.last_id;
                 let prev_sent = self
@@ -574,7 +574,6 @@ impl Session {
                     request_id,
                     template_id,
                     prev_hash: U256::from(&prev_hash),
-                    fees,
                 };
                 self.conn
                     .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS, reply)
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index 13bbc3d67..ddadecbfe 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1227,15 +1227,9 @@ async fn expect_job_error(c: &mut TpClient, request_id: u32, code: &str) {
     assert_eq!(e.error_code.as_utf8_or_hex(), code);
 }
 
-/// `Success` names the tip the job was validated on, next to the id it is
-/// retained under and the declared fee sum.
-async fn expect_job_success(
-    c: &mut TpClient,
-    tc: &TestChain,
-    request_id: u32,
-    template_id: u64,
-    fees: u64,
-) {
+/// `Success` names the tip the job was validated on next to the id it is
+/// retained under, and nothing else: the fee total is not on the wire.
+async fn expect_job_success(c: &mut TpClient, tc: &TestChain, request_id: u32, template_id: u64) {
     let mut f = recv_in_time(c).await;
     assert_eq!(
         f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
@@ -1244,10 +1238,7 @@ async fn expect_job_success(
     );
     let ok: ProposeTemplateSuccess = binary_sv2::from_bytes(&mut f.payload).expect("decode");
     let tip = tc.chain.tip_header().expect("tip").block_hash();
-    assert_eq!(
-        (ok.request_id, ok.template_id, ok.fees),
-        (request_id, template_id, fees)
-    );
+    assert_eq!((ok.request_id, ok.template_id), (request_id, template_id));
     assert_eq!(ok.prev_hash.as_ref(), tip.as_byte_array(), "validated tip");
 }
 
@@ -1270,8 +1261,8 @@ async fn expect_retained(c: &mut TpClient, template_id: u64, txs: &[&Transaction
 
 /// docs/sv2-job-validation.md §4.1–4.3: a job whose txs are all in the
 /// mempool and whose coinbase pays subsidy + fees is answered `Success` with
-/// the next template id, the declared fee sum, and the tip it was validated
-/// on, and is retained like a template.
+/// the next template id and the tip it was validated on, and is retained
+/// like a template.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_prices_and_retains_the_declared_job() {
     let tc = shared_regtest(2);
@@ -1292,7 +1283,7 @@ async fn propose_template_prices_and_retains_the_declared_job() {
     Job::declare(&tc, 9, &coinbase, &[&a, &b])
         .send(&mut c)
         .await;
-    expect_job_success(&mut c, &tc, 9, last + 1, 5_000).await;
+    expect_job_success(&mut c, &tc, 9, last + 1).await;
     expect_retained(&mut c, last + 1, &[&a, &b]).await;
 
     tp.shutdown().await;
@@ -1330,7 +1321,7 @@ async fn propose_template_asks_for_and_accepts_missing_transactions() {
 
     job.supplied = vec![serialize(&b)];
     job.send(&mut c).await;
-    expect_job_success(&mut c, &tc, 4, last + 1, 5_000).await;
+    expect_job_success(&mut c, &tc, 4, last + 1).await;
     expect_retained(&mut c, last + 1, &[&a, &b]).await;
 
     tp.shutdown().await;
@@ -1447,7 +1438,7 @@ async fn submit_solution_for_a_validated_job_becomes_the_tip() {
     Job::declare(&tc, 1, &coinbase, &[&a, &b])
         .send(&mut c)
         .await;
-    expect_job_success(&mut c, &tc, 1, last + 1, 5_000).await;
+    expect_job_success(&mut c, &tc, 1, last + 1).await;
 
     let mut script_sig = bip34_height_script(height);
     script_sig.extend_from_slice(&[0x42; EXTRANONCE_LEN]);
diff --git a/docs/sv2-job-validation.md b/docs/sv2-job-validation.md
index cca8f62b9..9ba0954bb 100644
--- a/docs/sv2-job-validation.md
+++ b/docs/sv2-job-validation.md
@@ -58,7 +58,7 @@ JDC                      JDS                             TP
  |<- ProvideMissingTransactions                           |
  |-- ProvideMissingTransactions.Success ->|               |
  |                        |-- ProposeTemplate --------->|  same job + transaction_list
- |                        |<- ProposeTemplate.Success --|  template_id, prev_hash, fees
+ |                        |<- ProposeTemplate.Success --|  template_id, prev_hash
  |<- DeclareMiningJob.Success             |               |
  ...
  |-- PushSolution ------->|                               |
@@ -162,7 +162,7 @@ either `ProposeTemplate.Success` or `ProposeTemplate.Error`:
   `checkBlock` with `checkMerkleRoot=false` and `checkPow=false`.
 - The server MUST NOT reject a consensus-valid job on local policy grounds
   (standardness, minimum relay fee, mempool limits). Policy belongs to the
-  Pool, which can use `ProposeTemplate.Success.fees` for it.
+  Pool, which prices the declared coinbase from the coinbase itself.
 - The server MUST set `nBits` from its own view of the chain and MAY use its
   current time for `nTime` when it needs a header for contextual checks. The
   client does not supply them.
@@ -199,17 +199,17 @@ the job and will accept a `SubmitSolution` for it.
 | request_id  | U32       | Identifier of the original `ProposeTemplate` request                                                                                                                                  |
 | template_id | U64       | Server's identification of the validated job. Drawn from the same strictly increasing namespace as `NewTemplate.template_id`, so it can be used in `SubmitSolution` and `RequestTransactionData` |
 | prev_hash   | U256      | Hash of the server's chain tip the job was validated on, as it would appear in the block header. The client keeps it to compare against `PushSolution.prev_hash`                      |
-| fees        | U64       | Sum of the fees of the transactions in `wtxid_list`, in satoshis                                                                                                                       |
-
-The server MUST retain the validated job (its `wtxid_list`, the transactions
-it received in `transaction_list`, and the reconstructed coinbase for size
-accounting)
-until a newer `ProposeTemplate.Success` is sent on the same connection or
-the connection closes, whichever comes first. This matches the guarantee JDS
-gives JDC in Section 6.4.9: `PushSolution` is only guaranteed to be valid for
-the most recent declaration. The server SHOULD retain jobs validated against
-the previous tip for a short grace period after a tip change, as it does for
-its own templates.
+
+The server MUST retain the validated job (its transactions in block order
+and the header fields a `SubmitSolution` is assembled with) under the same
+rules as its own templates: it is retired after the stale grace that follows
+a tip change, and it MAY be evicted oldest-first by a per-connection cap on
+retained templates and jobs, which SHOULD be at least 64. A JDS multiplexes
+many JDCs over one connection, so no single job is "the latest"; a
+`SubmitSolution` for an id the server no longer retains is dropped (Section
+7.8 has no reply) and `RequestTransactionData` for it answers
+`stale-template-id` or `template-id-not-found`. See Section 7.1 for what the
+JDS does with that.
 
 ### 4.4 `ProposeTemplate.Error` (Server -> Client)
 
@@ -291,9 +291,7 @@ All four are core messages and carry `extension_type = 0x0000`.
   not by a dedicated code.
 - **Coinbase-only mode.** Out of scope. In Coinbase-only mode neither Pool nor
   JDS learns the transaction set, so a node has nothing to validate beyond the
-  coinbase, which `SetCustomMiningJob` already carries to the Pool. A
-  zero-knowledge extension could later reuse `ProposeTemplate.Success.fees`
-  as the quantity being proven.
+  coinbase, which `SetCustomMiningJob` already carries to the Pool.
 - **Node load.** Full block validation without proof of work is CPU-heavy and
   in Bitcoin Core currently serialises on `cs_main`, so validations on a node
   that also produces the Pool's templates can delay block processing
@@ -306,10 +304,19 @@ All four are core messages and carry `extension_type = 0x0000`.
   checks and the block weight limit before decoding or storing transactions,
   so that a 32-byte `wtxid` cannot be amplified into a large allocation
   (`sv2-apps#796`, `#795`).
-- **Why `fees` is in `Success`.** The Pool needs the fee revenue of a Custom
-  Job to compare the declared coinbase value against what the template is
-  worth (`sv2-apps#610`). The server computes it while checking the coinbase
-  output value, so returning it costs nothing.
+- **Why `fees` is not in `Success`.** An earlier draft returned the fee total
+  so the Pool could price the declared coinbase (`sv2-apps#610`). Bitcoin
+  Core's IPC cannot produce it for an externally proposed block: `checkBlock`
+  returns only a reason, a debug string and a result, and a template from
+  `TxCollection.makeTemplate` throws on `getTxFees`, so `sv2-tp` would have
+  to send 0. One field with two meanings across TPs is worse than none. The
+  coinbase check already bounds the payout at subsidy plus fees
+  (`bad-cb-amount`), and the Pool reads the claimed value from the coinbase.
+- **`template_id` is per connection.** `ProposeTemplate.Success.template_id`
+  MUST be unique within a connection and MUST NOT collide with a
+  `NewTemplate.template_id` sent on it. The server MAY draw it from a
+  per-connection counter (rbitcoin) or a server-global one (`sv2-tp`); a
+  client MUST NOT compare ids across connections.
 - **Why positions, not `wtxid`s, in `MissingTransactions`.** Section 6.4.7
   uses positions, so the JDS relays the list unchanged. A `wtxid` list would
   force the JDS to translate.
@@ -331,6 +338,11 @@ All four are core messages and carry `extension_type = 0x0000`.
 | `ProposeTemplate.Error`            | `DeclareMiningJob.Error` with the error code                                  |
 | `PushSolution`                       | Check `prev_hash` against the stored one, then `SubmitSolution(template_id, version, ntime, nonce, coinbase_tx)` |
 
+Solutions are keyed by `template_id`. When the server has already dropped
+the job (Section 4.3), the `SubmitSolution` is lost silently; the JDS needs no
+fallback, because Section 6.4.9 already has JDC propagate the block itself and
+the JDS submission is redundancy.
+
 No mempool mirror is needed on the JDS side. In `sv2-apps` this is a second
 `JobValidationEngine` implementation next to `BitcoinCoreIPCEngine`, and the
 Pool's "`[jds]` requires `BitcoinCoreIpc`" startup check becomes "requires
@@ -359,7 +371,7 @@ dependency.
   (`request_id`, `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`,
   `wtxid_list`, `excess_data`), with no `prev_hash`. This draft follows it
   and adds the missing-transactions reply, `transaction_list` on the repeated
-  request, and `prev_hash` and `fees` in `Success`.
+  request, and `prev_hash` in `Success`.
 - [sv2-spec#217](https://github.com/stratum-mining/sv2-spec/issues/217):
   "consider adding a new TDP message for custom job validation" (plebhash,
   2026-08-31). Proposes message `X`, `X.Error` triggering
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index e0a8e4fee..678288726 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -628,9 +628,9 @@ flag: a session opts in with `REQUIRES_JOB_VALIDATION`.
   `ProposeTemplate` whose `prev_hash` is the tip (field dropped in D9),
   whose `wtxid_list` is all in the mempool, and whose placeholder coinbase
   pays ≤ subsidy + fees
-  is answered `Success{request_id, template_id, fees}`: `template_id` is
-  the next id in the session's counter, `fees` the sum over the declared
-  txs. The job is retained exactly like a template, so
+  is answered `Success{request_id, template_id}` (D9 adds `prev_hash`; D10
+  drops the `fees` this step carried): `template_id` is the next id in the
+  session's counter. The job is retained exactly like a template, so
   `RequestTransactionData` returns the declared txs in block order and
   `SubmitSolution` finds it. Without the flag the message is ignored (the
   D3 journey already pins that).
@@ -736,7 +736,7 @@ flag: a session opts in with `REQUIRES_JOB_VALIDATION`.
   `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`,
   `excess_data` (opaque here), plus `transaction_list`. No `prev_hash`:
   the TP validates on its current tip and `Success` carries that tip as
-  `prev_hash` next to `template_id` and `fees`. The TP builds the
+  `prev_hash` next to `template_id`. The TP builds the
   placeholder coinbase: `E = L − P` from the prefix (version, BIP144
   marker and flag when present, an input count that MUST be 1, the
   prevout, scriptSig length `L`, `P` bytes present; `2 ≤ L ≤ 100`,
@@ -759,6 +759,27 @@ flag: a session opts in with `REQUIRES_JOB_VALIDATION`.
   `B064K` fields (~6.5 MB).
 - **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
 
+### D10 — Drop `fees` from `Success`; retain jobs like templates
+
+- **Contract:** `ProposeTemplate.Success` is `{request_id, template_id,
+  prev_hash}`. Bitcoin Core's IPC cannot produce a fee total for an
+  externally proposed block (`checkBlock` returns only reason, debug and
+  result; a `TxCollection.makeTemplate` template throws on `getTxFees`), so
+  `sv2-tp` would have to send 0, and one field with two meanings across TPs
+  is worse than none. `bad-cb-amount` already bounds the coinbase at
+  subsidy + fees and the Pool reads the claimed value from the coinbase. A
+  validated job is retained exactly as a template is: the same
+  `MAX_RETAINED` ring (oldest first) and the same stale grace after a tip
+  change. A JDS multiplexes many JDCs over one connection, so "the latest
+  validated job" is not a unit worth pinning; the 64-slot same-tip ring from
+  C1 is the guarantee, and the draft (§4.3) now says so.
+- **Red:** `job_validation_messages_round_trip` and `expect_job_success`
+  without `fees`; Red was `E0063` on the struct literal.
+- **Green:** the field, `Verdict::Valid { fees, .. }` and the reply plumbing
+  removed. `check_block_proposal` keeps returning `Ok(fees)`: D1 cross-crate
+  API that GBT proposal mode may read.
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
+
 ### Test budget
 
 Units: the messages round trip, `job::extranonce_len`, `rbitcoin-net`
@@ -778,11 +799,11 @@ pad. No `rbitcoin-test` node journey yet (follow-up with a JDS client).
   the flag and cost one proposal check per request. Bind to loopback or
   firewall the port (the same advice as for templates).
 - `SetupConnection.Success.flags` echoes the request flags verbatim.
-- Retention shares the `MAX_RETAINED` (3) slots with templates: on one
-  tip a JDS session that also receives constraints rebuilds (or Plan C
-  pushes) can see a validated job evicted before its solution arrives.
-  The draft asks for retention until a newer `Success` or close; a slot
-  per kind, or a larger cap for flagged sessions, is a follow-up.
+- Retention is the template rule (D10): a validated job shares the
+  session's `MAX_RETAINED` (64) ring with templates and the same stale
+  grace. Past 64 same-tip pushes and validations the oldest goes; a
+  `SubmitSolution` for it is dropped and JDC's own propagation (JDP 6.4.9)
+  covers the block.
 - A job is retained with the nBits its validation header used. On
   min-difficulty networks that can differ from the sent
   `SetNewPrevHash.n_bits` (the Plan B risk); mainnet and signet bits
@@ -799,8 +820,8 @@ pad. No `rbitcoin-test` node journey yet (follow-up with a JDS client).
   extranonce is not the scriptSig tail gets `bad-cb-decode` or a coinbase
   check failure here; the draft asks the Job Declaration Protocol to state
   the split (§6).
-- No policy is applied (the draft forbids it); `fees` lets the pool
-  price the declared coinbase.
+- No policy is applied (the draft forbids it); the Pool prices the
+  declared coinbase from the coinbase itself.
 - The JDS role itself, and a `rbitcoin-test` journey driving a JDS
   client, stay out.
 

From f8179dbec699966f1692768c7109cf57f223addd Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Wed, 7 Oct 2026 16:53:08 -0400
Subject: [PATCH 12/19] docs: note plan D's stack on plan C and the sv2-tp
 sibling PR

Plan D lands on top of sv2/plan-c-fee-push (reardencode #949, #951), which
supplies the Arc<Transaction> template bodies and the 64-slot same-tip
retention that validated jobs now rely on instead of a pin. Readers coming
from sv2-spec discussion #239 also get the pointer to the Core-IPC
implementation of the same messages (sv2-tp #137).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/sv2-template-provider.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index 678288726..56379768a 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -576,8 +576,12 @@ when fees rise enough to matter, throttled. Requires Plan B.
 holds, fetches the transactions the node lacks, and submits the found block
 by `template_id`. Wire contract: [`sv2-job-validation.md`](./sv2-job-validation.md)
 (proposed TDP messages 0x77–0x7a and `SetupConnection` flag bit 0, for
-sv2-spec discussion #239, which supersedes #217). Requires Plan B. Ships no
-flag: a session opts in with `REQUIRES_JOB_VALIDATION`.
+sv2-spec discussion #239, which supersedes #217). Requires Plan B and Plan C: the
+branch is stacked on `sv2/plan-c-fee-push` (reardencode PRs #949 then #951)
+for the shared `Arc<Transaction>` bodies and the 64-slot same-tip ring that
+retains validated jobs. The Core-IPC sibling implementation is
+stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
+`REQUIRES_JOB_VALIDATION`.
 
 ### D1 — Block proposal check on `ChainHub`
 

From 65ef2b006da02b39b7da230c5da82b8368bb990f Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Thu, 8 Oct 2026 11:45:18 -0400
Subject: [PATCH 13/19] sv2: return the fee total in ProposeTemplate.Success
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`ProposeTemplate.Success` is `{request_id, template_id, prev_hash, fees}`;
`fees` is the sum of the fees of the declared transactions as
`ChainHub::check_block_proposal` computed it. This reverses 7f202e69's
field removal.

Only the validating node can derive the total: the fee of each
transaction is its inputs minus its outputs, which needs the UTXO set,
and the node computes it anyway for `bad-cb-amount`. Without it the Pool
has only the value the coinbase claims, which that check makes a lower
bound on the real total, not the total itself. Bitcoin Core's IPC does
not expose it today (`checkBlock` returns only reason, debug and result;
a `TxCollection.makeTemplate` template throws on `getTxFees`); that gap
is raised on bitcoin/bitcoin#35671 rather than designed around.

Red was E0560/E0609 (no field `fees`) on the round trip and
`expect_job_success`. Draft §2, §4.3, §6 and §7.1, Plan D (D4, D10) and
the changelog fragment say the field is returned.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 changelog.d/sv2-job-validation.md         | 10 +++----
 crates/rbitcoin-sv2/src/job.rs            | 18 +++++++------
 crates/rbitcoin-sv2/src/messages.rs       |  4 +++
 crates/rbitcoin-sv2/src/session.rs        |  3 ++-
 crates/rbitcoin-sv2/src/template_tests.rs | 27 ++++++++++++-------
 docs/sv2-job-validation.md                | 22 ++++++++-------
 docs/sv2-template-provider.md             | 33 ++++++++++++-----------
 7 files changed, 69 insertions(+), 48 deletions(-)

diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
index 00064a8ed..bd901283e 100644
--- a/changelog.d/sv2-job-validation.md
+++ b/changelog.d/sv2-job-validation.md
@@ -6,11 +6,11 @@ Added
   discussion #239) with the `DeclareMiningJob` fields relayed unchanged.
   The node rebuilds the placeholder coinbase from the declared prefix and
   suffix, resolves the declared wtxids against its mempool, asks for the
-  ones it lacks, checks the job as a block on its tip, and answers that tip
-  with a template id that `SubmitSolution` accepts like one of the node's
-  own templates; the job is retained like one too (same ring, same stale
-  grace). Duplicated, undeclared, or malformed input is refused before
-  anything is decoded.
+  ones it lacks, checks the job as a block on its tip, and answers that tip,
+  the fee total of the declared transactions, and a template id that
+  `SubmitSolution` accepts like one of the node's own templates; the job is
+  retained like one too (same ring, same stale grace). Duplicated,
+  undeclared, or malformed input is refused before anything is decoded.
 
 Changed
 
diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index fec311291..f627fa39a 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -16,8 +16,8 @@ pub(crate) enum Verdict {
     /// 0-indexed positions in `wtxid_list` neither the mempool nor
     /// `transaction_list` resolves.
     Missing(Vec<u16>),
-    /// Consensus-valid on the tip: the job to retain.
-    Valid(Job),
+    /// Consensus-valid on the tip: the fee total and the job to retain.
+    Valid { fees: u64, job: Job },
     /// `ProposeTemplate.Error.error_code`: a Core reject string or one of
     /// the draft's own codes.
     Rejected(String),
@@ -119,18 +119,20 @@ fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
     // (every spend against the chain, structure, weight, sigops, coinbase
     // value; no scripts, no PoW), on the blocking pool. A JDS sends one per
     // declaration; a flood costs blocking threads, not the reactor.
-    if let Err(code) = chain.check_block_proposal(&block) {
-        return Ok(Verdict::Rejected(code));
-    }
+    let fees = match chain.check_block_proposal(&block) {
+        Ok(fees) => fees,
+        Err(code) => return Ok(Verdict::Rejected(code)),
+    };
     let txs = block
         .txdata
         .split_off(1)
         .into_iter()
         .map(Arc::new)
         .collect();
-    Ok(Verdict::Valid(
-        next.job(rbitcoin_store::merkle_branch(&leaves, 0), txs),
-    ))
+    Ok(Verdict::Valid {
+        fees,
+        job: next.job(rbitcoin_store::merkle_branch(&leaves, 0), txs),
+    })
 }
 
 /// §4.1: `coinbase_tx_prefix` ends inside the scriptSig and
diff --git a/crates/rbitcoin-sv2/src/messages.rs b/crates/rbitcoin-sv2/src/messages.rs
index d3c2ccd20..74d3385ce 100644
--- a/crates/rbitcoin-sv2/src/messages.rs
+++ b/crates/rbitcoin-sv2/src/messages.rs
@@ -39,11 +39,14 @@ pub(crate) struct ProposeTemplateMissingTransactions<'decoder> {
 
 /// TP → client: the job is valid on the tip `prev_hash` and retained under
 /// `template_id`, which shares the `NewTemplate.template_id` namespace.
+/// `fees` is the fee total of the declared transactions as the node's
+/// validation computed it.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
 pub(crate) struct ProposeTemplateSuccess<'decoder> {
     pub request_id: u32,
     pub template_id: u64,
     pub prev_hash: U256<'decoder>,
+    pub fees: u64,
 }
 
 /// TP → client: the job was not validated.
@@ -108,6 +111,7 @@ mod tests {
                 request_id: 7,
                 template_id: u64::MAX,
                 prev_hash: U256::from(&h1),
+                fees: 12_345,
             },
             &mut bytes,
         );
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index 091d49e0e..6af962132 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -561,7 +561,7 @@ impl Session {
                     .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, reply)
                     .await
             }
-            Verdict::Valid(job) => {
+            Verdict::Valid { fees, job } => {
                 self.templates.last_id += 1;
                 let template_id = self.templates.last_id;
                 let prev_sent = self
@@ -574,6 +574,7 @@ impl Session {
                     request_id,
                     template_id,
                     prev_hash: U256::from(&prev_hash),
+                    fees,
                 };
                 self.conn
                     .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS, reply)
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index ddadecbfe..7351869e4 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1227,9 +1227,15 @@ async fn expect_job_error(c: &mut TpClient, request_id: u32, code: &str) {
     assert_eq!(e.error_code.as_utf8_or_hex(), code);
 }
 
-/// `Success` names the tip the job was validated on next to the id it is
-/// retained under, and nothing else: the fee total is not on the wire.
-async fn expect_job_success(c: &mut TpClient, tc: &TestChain, request_id: u32, template_id: u64) {
+/// `Success` names the tip the job was validated on, next to the id it is
+/// retained under and the fee total of the declared transactions.
+async fn expect_job_success(
+    c: &mut TpClient,
+    tc: &TestChain,
+    request_id: u32,
+    template_id: u64,
+    fees: u64,
+) {
     let mut f = recv_in_time(c).await;
     assert_eq!(
         f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
@@ -1238,7 +1244,10 @@ async fn expect_job_success(c: &mut TpClient, tc: &TestChain, request_id: u32, t
     );
     let ok: ProposeTemplateSuccess = binary_sv2::from_bytes(&mut f.payload).expect("decode");
     let tip = tc.chain.tip_header().expect("tip").block_hash();
-    assert_eq!((ok.request_id, ok.template_id), (request_id, template_id));
+    assert_eq!(
+        (ok.request_id, ok.template_id, ok.fees),
+        (request_id, template_id, fees)
+    );
     assert_eq!(ok.prev_hash.as_ref(), tip.as_byte_array(), "validated tip");
 }
 
@@ -1261,8 +1270,8 @@ async fn expect_retained(c: &mut TpClient, template_id: u64, txs: &[&Transaction
 
 /// docs/sv2-job-validation.md §4.1–4.3: a job whose txs are all in the
 /// mempool and whose coinbase pays subsidy + fees is answered `Success` with
-/// the next template id and the tip it was validated on, and is retained
-/// like a template.
+/// the next template id, the declared fee sum, and the tip it was validated
+/// on, and is retained like a template.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_prices_and_retains_the_declared_job() {
     let tc = shared_regtest(2);
@@ -1283,7 +1292,7 @@ async fn propose_template_prices_and_retains_the_declared_job() {
     Job::declare(&tc, 9, &coinbase, &[&a, &b])
         .send(&mut c)
         .await;
-    expect_job_success(&mut c, &tc, 9, last + 1).await;
+    expect_job_success(&mut c, &tc, 9, last + 1, 5_000).await;
     expect_retained(&mut c, last + 1, &[&a, &b]).await;
 
     tp.shutdown().await;
@@ -1321,7 +1330,7 @@ async fn propose_template_asks_for_and_accepts_missing_transactions() {
 
     job.supplied = vec![serialize(&b)];
     job.send(&mut c).await;
-    expect_job_success(&mut c, &tc, 4, last + 1).await;
+    expect_job_success(&mut c, &tc, 4, last + 1, 5_000).await;
     expect_retained(&mut c, last + 1, &[&a, &b]).await;
 
     tp.shutdown().await;
@@ -1438,7 +1447,7 @@ async fn submit_solution_for_a_validated_job_becomes_the_tip() {
     Job::declare(&tc, 1, &coinbase, &[&a, &b])
         .send(&mut c)
         .await;
-    expect_job_success(&mut c, &tc, 1, last + 1).await;
+    expect_job_success(&mut c, &tc, 1, last + 1, 5_000).await;
 
     let mut script_sig = bip34_height_script(height);
     script_sig.extend_from_slice(&[0x42; EXTRANONCE_LEN]);
diff --git a/docs/sv2-job-validation.md b/docs/sv2-job-validation.md
index 9ba0954bb..34298026f 100644
--- a/docs/sv2-job-validation.md
+++ b/docs/sv2-job-validation.md
@@ -1,3 +1,4 @@
+| fees        | U64       | Sum of the fees of the transactions in `wtxid_list`, in satoshis, as computed by the TP's validation                                                                                   |
 # Stratum V2: Custom Job Validation over the Template Distribution Protocol
 
 Draft for [sv2-spec discussion #239](https://github.com/stratum-mining/sv2-spec/discussions/239)
@@ -58,7 +59,7 @@ JDC                      JDS                             TP
  |<- ProvideMissingTransactions                           |
  |-- ProvideMissingTransactions.Success ->|               |
  |                        |-- ProposeTemplate --------->|  same job + transaction_list
- |                        |<- ProposeTemplate.Success --|  template_id, prev_hash
+ |                        |<- ProposeTemplate.Success --|  template_id, prev_hash, fees
  |<- DeclareMiningJob.Success             |               |
  ...
  |-- PushSolution ------->|                               |
@@ -304,14 +305,15 @@ All four are core messages and carry `extension_type = 0x0000`.
   checks and the block weight limit before decoding or storing transactions,
   so that a 32-byte `wtxid` cannot be amplified into a large allocation
   (`sv2-apps#796`, `#795`).
-- **Why `fees` is not in `Success`.** An earlier draft returned the fee total
-  so the Pool could price the declared coinbase (`sv2-apps#610`). Bitcoin
-  Core's IPC cannot produce it for an externally proposed block: `checkBlock`
-  returns only a reason, a debug string and a result, and a template from
-  `TxCollection.makeTemplate` throws on `getTxFees`, so `sv2-tp` would have
-  to send 0. One field with two meanings across TPs is worse than none. The
-  coinbase check already bounds the payout at subsidy plus fees
-  (`bad-cb-amount`), and the Pool reads the claimed value from the coinbase.
+- **Why `fees` is in `Success`.** The fee total (sum of inputs minus sum of
+  outputs per transaction) needs the UTXO set, so only the validating node
+  can derive it, and it computes it anyway for `bad-cb-amount`. Without it
+  the Pool has only the value the coinbase claims, which that check makes a
+  lower bound on the real total, not the total (`sv2-apps#610`). Bitcoin
+  Core's IPC does not expose it today: `checkBlock` returns only a reason, a
+  debug string and a result, and a template from `TxCollection.makeTemplate`
+  throws on `getTxFees`. That gap is raised on bitcoin/bitcoin#35671 rather
+  than designed around.
 - **`template_id` is per connection.** `ProposeTemplate.Success.template_id`
   MUST be unique within a connection and MUST NOT collide with a
   `NewTemplate.template_id` sent on it. The server MAY draw it from a
@@ -334,7 +336,7 @@ All four are core messages and carry `extension_type = 0x0000`.
 | `DeclareMiningJob`                   | `ProposeTemplate` with `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`, `excess_data` copied unchanged, empty `transaction_list` |
 | `ProposeTemplate.MissingTransactions` | `ProvideMissingTransactions` with the position list copied                  |
 | `ProvideMissingTransactions.Success` | `ProposeTemplate` again with `transaction_list` copied                       |
-| `ProposeTemplate.Success`          | `DeclareMiningJob.Success`; store `template_id` and `prev_hash` with the declaration |
+| `ProposeTemplate.Success`          | `DeclareMiningJob.Success`; store `template_id` and `prev_hash` with the declaration; pass `fees` to the Pool, which prices the declared coinbase against it |
 | `ProposeTemplate.Error`            | `DeclareMiningJob.Error` with the error code                                  |
 | `PushSolution`                       | Check `prev_hash` against the stored one, then `SubmitSolution(template_id, version, ntime, nonce, coinbase_tx)` |
 
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index 56379768a..57a935494 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -632,9 +632,9 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   `ProposeTemplate` whose `prev_hash` is the tip (field dropped in D9),
   whose `wtxid_list` is all in the mempool, and whose placeholder coinbase
   pays ≤ subsidy + fees
-  is answered `Success{request_id, template_id}` (D9 adds `prev_hash`; D10
-  drops the `fees` this step carried): `template_id` is the next id in the
-  session's counter. The job is retained exactly like a template, so
+  is answered `Success{request_id, template_id, fees}` (D9 adds
+  `prev_hash`): `template_id` is the next id in the session's counter. The
+  job is retained exactly like a template, so
   `RequestTransactionData` returns the declared txs in block order and
   `SubmitSolution` finds it. Without the flag the message is ignored (the
   D3 journey already pins that).
@@ -763,25 +763,28 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   `B064K` fields (~6.5 MB).
 - **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
 
-### D10 — Drop `fees` from `Success`; retain jobs like templates
+### D10 — Return `fees` in `Success`; retain jobs like templates
 
 - **Contract:** `ProposeTemplate.Success` is `{request_id, template_id,
-  prev_hash}`. Bitcoin Core's IPC cannot produce a fee total for an
-  externally proposed block (`checkBlock` returns only reason, debug and
-  result; a `TxCollection.makeTemplate` template throws on `getTxFees`), so
-  `sv2-tp` would have to send 0, and one field with two meanings across TPs
-  is worse than none. `bad-cb-amount` already bounds the coinbase at
-  subsidy + fees and the Pool reads the claimed value from the coinbase. A
-  validated job is retained exactly as a template is: the same
+  prev_hash, fees}`; `fees` is the fee total of the declared transactions as
+  `ChainHub::check_block_proposal` computed it. Only the validating node can
+  derive it (sum of inputs minus sum of outputs per transaction needs the
+  UTXO set) and it computes it anyway for `bad-cb-amount`; the Pool
+  otherwise has only the coinbase's claimed value, which that check makes a
+  lower bound. Bitcoin Core's IPC does not expose it today (`checkBlock`
+  returns only reason, debug and result; a `TxCollection.makeTemplate`
+  template throws on `getTxFees`); the gap is raised on bitcoin/bitcoin#35671
+  rather than designed around. A validated job is retained exactly as a
+  template is: the same
   `MAX_RETAINED` ring (oldest first) and the same stale grace after a tip
   change. A JDS multiplexes many JDCs over one connection, so "the latest
   validated job" is not a unit worth pinning; the 64-slot same-tip ring from
   C1 is the guarantee, and the draft (§4.3) now says so.
 - **Red:** `job_validation_messages_round_trip` and `expect_job_success`
-  without `fees`; Red was `E0063` on the struct literal.
-- **Green:** the field, `Verdict::Valid { fees, .. }` and the reply plumbing
-  removed. `check_block_proposal` keeps returning `Ok(fees)`: D1 cross-crate
-  API that GBT proposal mode may read.
+  with `fees`; Red was `E0560` on the struct literal.
+- **Green:** the field, `Verdict::Valid { fees, job }` and the reply
+  plumbing. `check_block_proposal` returns `Ok(fees)`: D1 cross-crate API
+  that GBT proposal mode also reads.
 - **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
 
 ### Test budget

From e2f8182b8f66e3732f28be8371458e64216a1caa Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Thu, 8 Oct 2026 12:58:46 -0400
Subject: [PATCH 14/19] sv2: validate proposed templates off the session loop

`on_frame` awaited a ProposeTemplate's spawn_blocking inline inside the
session select!, so one validation at a time and every other frame on
that connection waited behind it, SubmitSolution for a found block
included, along with the tip push, fee poll, and retire branches. A JDS
multiplexes many JDCs over one TDP connection, so a block solution could
sit behind someone else's declaration.

The session now decodes the proposal and runs the chain-free prechecks
(duplicate-wtxid, bad-missing-tx) on arrival, answering at once on
failure, and queues the payload for a JoinSet of spawn_blocking +
BlockingRegion validations, at most MAX_INFLIGHT_VALIDATIONS (4) per
session, the rest in arrival order. A new select! arm takes each verdict
and goes through the one reply path, retaining a valid job when its
Success is sent; dropping the session aborts the set. job::validate stays
complete on its own.

Journey: 1200 supplied spends make the validation the costly frame;
a RequestTransactionData and a SubmitSolution sent behind it are
answered, and the solved tip's NewTemplate arrives, before the proposal
reply, which then takes the next id and names the tip it started on. The
request, with no disk behind it, must be answered in under a quarter of
the validation it overlapped. Red was Success as the first frame.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 changelog.d/sv2-job-validation.md         |   3 +
 crates/rbitcoin-sv2/src/job.rs            |  64 ++++++---
 crates/rbitcoin-sv2/src/session.rs        |  65 +++++++--
 crates/rbitcoin-sv2/src/template_tests.rs | 160 +++++++++++++++++++++-
 docs/sv2-job-validation.md                |   5 +-
 docs/sv2-template-provider.md             |  86 ++++++++++--
 6 files changed, 327 insertions(+), 56 deletions(-)

diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
index bd901283e..7ef64340b 100644
--- a/changelog.d/sv2-job-validation.md
+++ b/changelog.d/sv2-job-validation.md
@@ -11,6 +11,9 @@ Added
   `SubmitSolution` accepts like one of the node's own templates; the job is
   retained like one too (same ring, same stale grace). Duplicated,
   undeclared, or malformed input is refused before anything is decoded.
+  Validation runs off the session loop, up to four at once per
+  connection, so a `SubmitSolution` or a tip push never waits behind
+  another client's proposal.
 
 Changed
 
diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index f627fa39a..116a6659d 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -23,32 +23,24 @@ pub(crate) enum Verdict {
     Rejected(String),
 }
 
-/// Reads the store and the mempool: blocking region only. `None`: the
-/// payload is not a `ProposeTemplate`.
-pub(crate) fn validate(
-    chain: &ChainHub,
-    mut payload: Vec<u8>,
-) -> io::Result<Option<(u32, Verdict)>> {
-    let Ok(m) = binary_sv2::from_bytes::<ProposeTemplate>(&mut payload) else {
-        return Ok(None);
-    };
-    Ok(Some((m.request_id, check(chain, &m)?)))
+/// `None`: the payload is not a `ProposeTemplate`.
+pub(crate) fn decode(payload: &mut [u8]) -> Option<ProposeTemplate<'_>> {
+    binary_sv2::from_bytes(payload).ok()
 }
 
-/// §4.1 and §4.4, in order. The draft's own codes run before any mempool
-/// lookup or transaction decode, so a 32-byte wtxid is never amplified into
-/// a copy or an allocation the job did not declare.
-fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
-    let rejected = |code: &str| Ok(Verdict::Rejected(code.into()));
-    // Same gate as the templates: a stale tip validates nothing.
-    if chain.in_ibd() {
-        return rejected("job-validation-unavailable");
-    }
-    let next = template::next_header(chain)?;
+/// §4.1 and §4.4: the draft's own codes, before any mempool lookup or
+/// transaction decode, so a 32-byte wtxid is never amplified into a copy or
+/// an allocation the job did not declare. `Ok` is the supplied txs keyed by
+/// the wtxid of their bytes as sent; `Err` is the `Error.error_code`. No
+/// chain read, so the session runs it on arrival; [`validate`] runs it
+/// again and stays complete on its own.
+pub(crate) fn precheck<'m>(
+    m: &'m ProposeTemplate<'_>,
+) -> Result<HashMap<[u8; 32], &'m [u8]>, &'static str> {
     let mut declared = HashSet::with_capacity(m.wtxid_list.len());
     for w in m.wtxid_list.iter() {
         if !declared.insert(w.as_ref()) {
-            return rejected("duplicate-wtxid");
+            return Err("duplicate-wtxid");
         }
     }
     // The wtxid is the hash of the serialization as sent, so a supplied tx
@@ -64,8 +56,36 @@ fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
         })
         .collect();
     if supplied.keys().any(|w| !declared.contains(&w[..])) {
-        return rejected("bad-missing-tx");
+        return Err("bad-missing-tx");
+    }
+    Ok(supplied)
+}
+
+/// Reads the store and the mempool: blocking region only. `payload` was
+/// [`decode`]d once already; a second failure is a broken invariant.
+pub(crate) fn validate(chain: &ChainHub, mut payload: Vec<u8>) -> io::Result<(u32, Verdict)> {
+    let m = decode(&mut payload).ok_or_else(|| {
+        io::Error::new(
+            io::ErrorKind::InvalidData,
+            "sv2: ProposeTemplate stopped decoding",
+        )
+    })?;
+    Ok((m.request_id, check(chain, &m)?))
+}
+
+/// §4.1 and §4.4 in order: the gate, [`precheck`] again, the coinbase,
+/// the resolution, then the proposal check.
+fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
+    let rejected = |code: &str| Ok(Verdict::Rejected(code.into()));
+    // Same gate as the templates: a stale tip validates nothing.
+    if chain.in_ibd() {
+        return rejected("job-validation-unavailable");
     }
+    let next = template::next_header(chain)?;
+    let supplied = match precheck(m) {
+        Ok(supplied) => supplied,
+        Err(code) => return rejected(code),
+    };
     let Some(extranonce) = extranonce_len(m.coinbase_tx_prefix.as_ref()) else {
         return rejected("bad-cb-decode");
     };
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index 6af962132..a27eafffe 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -63,6 +63,16 @@ const CONSTRAINTS_COOLDOWN: Duration = Duration::from_secs(1);
 /// session is closed so the slot goes back to a real client.
 const MAX_SUPERSEDED_CONSTRAINTS: u32 = 8;
 
+/// CPU and RAM trade (CONTRIBUTING 9): this many `ProposeTemplate`
+/// validations run at once per session, each one full proposal check on a
+/// blocking thread holding up to a block of decoded transactions. Later
+/// proposals wait in arrival order, each holding its payload (at most
+/// `MAX_PROPOSE_TEMPLATE_PAYLOAD`), and are not refused: a JDS declares one
+/// job per JDC at every tip change, so a burst is the normal shape. The
+/// queue has no cap of its own (docs/sv2-template-provider.md, Plan D
+/// risks).
+const MAX_INFLIGHT_VALIDATIONS: usize = 4;
+
 /// Fee-delta push settings (docs/sv2-template-provider.md C1).
 #[derive(Clone, Copy)]
 pub(crate) struct FeePush {
@@ -190,6 +200,8 @@ pub(crate) async fn serve(
         held_logged: false,
         fee_check_at: None,
         seen_updates: 0,
+        validations: JoinSet::new(),
+        queued: VecDeque::new(),
     };
     s.run(&mut frames, deadline).await
 }
@@ -227,6 +239,12 @@ struct Session {
     fee_check_at: Option<Instant>,
     /// `MempoolHub::template_updates` read before the last build.
     seen_updates: u64,
+    /// `ProposeTemplate` validations in flight, at most
+    /// `MAX_INFLIGHT_VALIDATIONS`. Dropping the set aborts them with the
+    /// session.
+    validations: JoinSet<io::Result<(u32, Verdict)>>,
+    /// Prechecked proposals waiting for a validation slot, oldest first.
+    queued: VecDeque<Vec<u8>>,
 }
 
 impl Session {
@@ -253,6 +271,11 @@ impl Session {
                     Ok(_) | Err(RecvError::Lagged(_)) => self.publish().await?,
                     Err(RecvError::Closed) => return Ok(()),
                 },
+                Some(done) = self.validations.join_next(), if !self.validations.is_empty() => {
+                    let (request_id, verdict) = done.map_err(io::Error::other)??;
+                    self.reply_propose(request_id, verdict).await?;
+                    self.start_validations();
+                }
                 _ = tokio::time::sleep_until(retire_at.unwrap_or_else(Instant::now)),
                     if retire_at.is_some() =>
                 {
@@ -321,7 +344,18 @@ impl Session {
             }
             MESSAGE_TYPE_SUBMIT_SOLUTION => self.on_submit_solution(frame).await?,
             MESSAGE_TYPE_PROPOSE_TEMPLATE if self.job_validation => {
-                self.on_propose_template(frame).await?;
+                let Some(m) = job::decode(&mut frame.payload) else {
+                    rbitcoin_log::info!("sv2: undecodable ProposeTemplate");
+                    return Ok(true);
+                };
+                let request_id = m.request_id;
+                if let Err(code) = job::precheck(&m) {
+                    self.reply_propose(request_id, Verdict::Rejected(code.into()))
+                        .await?;
+                    return Ok(true);
+                }
+                self.queued.push_back(frame.payload);
+                self.start_validations();
             }
             t => rbitcoin_log::info!("sv2: ignoring message {t:#x}"),
         }
@@ -536,20 +570,25 @@ impl Session {
         Ok(())
     }
 
+    /// Fill the validation slots from the queue, oldest first. Other frames
+    /// and the loop's timers run while a validation is in flight; the reply
+    /// comes from the `join_next` arm, paired by `request_id`.
+    fn start_validations(&mut self) {
+        while self.validations.len() < MAX_INFLIGHT_VALIDATIONS {
+            let Some(payload) = self.queued.pop_front() else {
+                return;
+            };
+            let c = Arc::clone(&self.chain);
+            self.validations.spawn_blocking(move || {
+                let _g = BlockingRegion::enter();
+                job::validate(&c, payload)
+            });
+        }
+    }
+
     /// docs/sv2-job-validation.md §4: a valid job is retained under the next
     /// template id and answered `Success`; a rejected one answers `Error`.
-    async fn on_propose_template(&mut self, frame: Frame) -> io::Result<()> {
-        let c = Arc::clone(&self.chain);
-        let verdict = tokio::task::spawn_blocking(move || {
-            let _g = BlockingRegion::enter();
-            job::validate(&c, frame.payload)
-        })
-        .await
-        .map_err(io::Error::other)??;
-        let Some((request_id, verdict)) = verdict else {
-            rbitcoin_log::info!("sv2: undecodable ProposeTemplate");
-            return Ok(());
-        };
+    async fn reply_propose(&mut self, request_id: u32, verdict: Verdict) -> io::Result<()> {
         let wire = |e: binary_sv2::Error| io::Error::other(format!("sv2 ProposeTemplate: {e:?}"));
         match verdict {
             Verdict::Missing(positions) => {
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index 7351869e4..661aac5a5 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1337,13 +1337,14 @@ async fn propose_template_asks_for_and_accepts_missing_transactions() {
 }
 
 /// §4.1 and §4.4: everything in a job comes from a JDC. The checks run in
-/// order before any mempool lookup or transaction decode: a repeated wtxid,
-/// a supplied tx nobody declared (or one that does not decode), a coinbase
-/// prefix that does not parse or a coinbase that does not decode, then the
-/// proposal check's own reject string: a declaration from before the tip
-/// moved fails its BIP34 height, an overpaying coinbase its amount. While
-/// the tip is stale (IBD) every job is `job-validation-unavailable`.
-/// Nothing is retained on an error.
+/// order before any mempool lookup or transaction decode: a repeated wtxid
+/// or a supplied tx nobody declared is refused on arrival, even while the
+/// tip is stale (IBD) and every other job is `job-validation-unavailable`;
+/// then a declared blob that does not decode, a coinbase prefix that does
+/// not parse or a coinbase that does not decode, then the proposal check's
+/// own reject string: a declaration from before the tip moved fails its
+/// BIP34 height, an overpaying coinbase its amount. Nothing is retained on
+/// an error.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_rejects_untrusted_input_in_order() {
     let tc = shared_regtest(2);
@@ -1363,6 +1364,10 @@ async fn propose_template_rejects_untrusted_input_in_order() {
         .send(&mut c)
         .await;
     expect_job_error(&mut c, 1, "job-validation-unavailable").await;
+    Job::declare(&tc, 10, &coinbase, &[&a, &a])
+        .send(&mut c)
+        .await;
+    expect_job_error(&mut c, 10, "duplicate-wtxid").await;
     mock_live_tip(&tc);
     c.coinbase_output_constraints(0, 0).await.unwrap();
     let last = expect_template(&mut c, &tc, &[&a, &b], true).await;
@@ -1482,3 +1487,144 @@ async fn submit_solution_for_a_validated_job_becomes_the_tip() {
 
     tp.shutdown().await;
 }
+
+/// A proposal's validation runs off the session loop: a
+/// `RequestTransactionData` and a `SubmitSolution` sent while a heavy
+/// `ProposeTemplate` is still validating are answered, and the solution
+/// becomes the tip and pushes its `NewTemplate`, before the proposal's reply,
+/// which then takes the next template id and names the tip it was validated
+/// on. The proposal supplies 1200 spends of one confirmed fan-out, so
+/// validating it is the costly frame (over a second unoptimized; most of the
+/// test's wall) while the solved block is coinbase-only. The same proposal
+/// alone measures that wall first. The request, which has no blocking work
+/// and no disk behind it, must be answered in a small fraction of the
+/// validation it overlapped, or the order would be luck, not the contract;
+/// the solution's accept has a tip write (an fsync) behind it, so its margin
+/// is the validation wall itself.
+#[tokio::test(flavor = "multi_thread")]
+async fn propose_template_validation_does_not_delay_other_frames() {
+    let tc = shared_regtest(1);
+    let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
+    let outs = 1_200u64;
+    let each = (50_0000_0000 - 10_000) / outs;
+    let mut fanout = spend(tc.coinbases[0], 10_000, cheap.clone());
+    fanout.output = vec![
+        TxOut {
+            value: Amount::from_sat(each),
+            script_pubkey: cheap.clone(),
+        };
+        outs as usize
+    ];
+    let tip = tc.chain.tip_header().expect("tip");
+    let h = tc.chain.query.tip_height().expect("tip height").0;
+    let block = mine_regtest_paying(
+        tip.block_hash(),
+        tip.time + 1,
+        h + 1,
+        cheap.clone(),
+        vec![fanout.clone()],
+    );
+    tc.chain.accept_block(block).expect("accept fan-out");
+    let fanout_txid = fanout.compute_txid();
+    let spends: Vec<Transaction> = (0..outs as u32)
+        .map(|vout| Transaction {
+            version: Version::TWO,
+            lock_time: LockTime::ZERO,
+            input: vec![TxIn {
+                previous_output: OutPoint {
+                    txid: fanout_txid,
+                    vout,
+                },
+                script_sig: ScriptBuf::new(),
+                sequence: Sequence::ENABLE_RBF_NO_LOCKTIME,
+                witness: Witness::new(),
+            }],
+            output: vec![TxOut {
+                value: Amount::from_sat(each - 1_000),
+                script_pubkey: cheap.clone(),
+            }],
+        })
+        .collect();
+    let declared: Vec<&Transaction> = spends.iter().collect();
+
+    let FirstTemplate {
+        tp,
+        mut c,
+        template_id,
+        version,
+        mut header,
+        coinbase,
+    } = first_template(&tc, REQUIRES_JOB_VALIDATION).await;
+    let height = tc.chain.query.tip_height().unwrap().0 + 1;
+    let subsidy = block_subsidy(height, &tc.chain.params) as u64;
+    let fees = outs * 1_000;
+    let mut job = Job::declare(
+        &tc,
+        1,
+        &job_coinbase(height, subsidy + fees, &declared),
+        &declared,
+    );
+    // Supplied, not pooled: the template above stays coinbase-only.
+    job.supplied = spends.iter().map(serialize).collect();
+
+    let asked = tokio::time::Instant::now();
+    job.send(&mut c).await;
+    expect_job_success(&mut c, &tc, 1, template_id + 1, fees).await;
+    let alone = asked.elapsed();
+
+    while header.validate_pow(header.target()).is_err() {
+        header.nonce += 1;
+    }
+    job.request_id = 2;
+    let proposed = tokio::time::Instant::now();
+    job.send(&mut c).await;
+    // Past the tip check at the head of the proposal check (a few percent
+    // of the wall), so the solution cannot cut this validation short.
+    tokio::time::sleep(alone / 8).await;
+    let requested = tokio::time::Instant::now();
+    c.request_transaction_data(template_id).await.unwrap();
+    c.submit_solution(template_id, version, header.time, header.nonce, &coinbase)
+        .await
+        .unwrap();
+    let f = recv_in_time(&mut c).await;
+    let requested = requested.elapsed();
+    assert_eq!(
+        f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS,
+        "the request's reply must precede the proposal's (validation alone {alone:?})"
+    );
+    let f = recv_in_time(&mut c).await;
+    assert_eq!(
+        f.msg_type, MESSAGE_TYPE_NEW_TEMPLATE,
+        "the solved tip's template must precede the proposal reply"
+    );
+    assert_eq!(
+        tc.chain.tip_header().unwrap().block_hash(),
+        header.block_hash()
+    );
+    let pushed = check_template(&mut c, &tc, f, &[], true).await;
+    assert_eq!(pushed, template_id + 2);
+
+    let mut f = recv_in_time(&mut c).await;
+    let replied = proposed.elapsed();
+    assert_eq!(
+        f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
+        "{:?}",
+        f.payload
+    );
+    let ok: ProposeTemplateSuccess = binary_sv2::from_bytes(&mut f.payload).expect("decode");
+    assert_eq!(
+        (ok.request_id, ok.template_id, ok.fees),
+        (2, template_id + 3, fees)
+    );
+    assert_eq!(
+        ok.prev_hash.as_ref(),
+        header.prev_blockhash.as_byte_array(),
+        "validated on the tip it started on"
+    );
+    assert!(
+        requested * 4 < replied,
+        "request answered in {requested:?} against a validation of {replied:?}"
+    );
+
+    tp.shutdown().await;
+}
diff --git a/docs/sv2-job-validation.md b/docs/sv2-job-validation.md
index 34298026f..1801d72d3 100644
--- a/docs/sv2-job-validation.md
+++ b/docs/sv2-job-validation.md
@@ -299,7 +299,10 @@ All four are core messages and carry `extension_type = 0x0000`.
   (`sv2-apps#120`). A server MAY process `ProposeTemplate` requests
   sequentially and MAY bound the number queued per connection; operators
   SHOULD run a dedicated TP for job validation. A client SHOULD apply a
-  timeout before falling back.
+  timeout before falling back. A server SHOULD NOT let a validation delay
+  the other messages on the connection, `SubmitSolution` above all
+  (rbitcoin validates off the session loop, four at a time per connection,
+  the rest queued in arrival order).
 - **Untrusted input.** Everything in `ProposeTemplate` originates from a
   JDC. The server MUST enforce the `duplicate-wtxid` and `bad-missing-tx`
   checks and the block weight limit before decoding or storing transactions,
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index 57a935494..84d83a32c 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -81,9 +81,10 @@ Do not copy them here.
 - `binary_sv2` byte-buffer types and `noise_sv2`'s `secp256k1` 0.28 stay
   inside `rbitcoin-sv2`; consensus decode uses the workspace
   `rust-bitcoin`. No sv2 types in other crates' APIs.
-- Reactor rule: template builds and solution assembly run in a blocking
-  region, never on tokio workers. `MempoolHub` accessors assert
-  not-reactor.
+- Reactor rule: template builds, solution assembly, and proposal
+  validation run in a blocking region, never on tokio workers.
+  `MempoolHub` accessors assert not-reactor. A proposal validation also
+  runs off its session loop (D11): the session never waits on one.
 - Named RAM trade (CONTRIBUTING 9): each session retains its templates
   (up to 64) holding the mempool's own `Arc<Transaction>` bodies, about
   24 KB of pointers per full template while the txs are still pooled.
@@ -686,14 +687,15 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
 ### D5b — Untrusted-input rejections
 
 - **Contract:** `Error.error_code` in this order, before any mempool
-  lookup or transaction decode: `job-validation-unavailable` while
-  `in_ibd()` (the template gate), `stale-prevhash` (dropped in D9),
-  `duplicate-wtxid`,
-  `bad-missing-tx` (a supplied tx whose hash is not in `wtxid_list`, or a
-  declared blob that does not decode), `bad-cb-decode` (this TP's code;
-  the draft has none for an undecodable coinbase), then the proposal
-  check's reject string (`bad-cb-amount` for an overpaying coinbase).
-  Nothing is retained and no id is taken on an error.
+  lookup or transaction decode: `duplicate-wtxid` and `bad-missing-tx` (a
+  supplied tx whose hash is not in `wtxid_list`) on arrival, with no chain
+  read (D11 moved them ahead of the gate); then, on the blocking thread,
+  `job-validation-unavailable` while `in_ibd()` (the template gate),
+  `stale-prevhash` (dropped in D9), `bad-missing-tx` for a declared blob
+  that does not decode, `bad-cb-decode` (this TP's code; the draft has none
+  for an undecodable coinbase), then the proposal check's reject string
+  (`bad-cb-amount` for an overpaying coinbase). Nothing is retained and no
+  id is taken on an error.
 - **Red:** `propose_template_rejects_untrusted_input_in_order` — seven
   sends on one session, then `RequestTransactionData(last + 1)` answers
   `template-id-not-found`. Red was `Success` for the first send.
@@ -787,13 +789,61 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   that GBT proposal mode also reads.
 - **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
 
+### D11 — Validation off the session loop
+
+- **Contract:** a `ProposeTemplate` validation never delays the other
+  frames or loop branches of its session. `SubmitSolution`,
+  `RequestTransactionData`, tip pushes, fee checks, and retire timers run
+  while a validation is in flight; `ProposeTemplate.Success` / `.Error` is
+  sent when the validation completes, paired by `request_id`, and the job
+  is retained when that reply is sent (so it takes the template id current
+  then). Up to `MAX_INFLIGHT_VALIDATIONS` (4) validations run at once per
+  session; further proposals wait in arrival order and are not refused.
+  Session end aborts the in-flight set. Before D11 `on_frame` awaited the
+  validation inline inside the session `select!`, so a JDS multiplexing
+  many JDCs over one connection could have a found block's
+  `SubmitSolution` sit behind another JDC's validation.
+- **Red:** `propose_template_validation_does_not_delay_other_frames` —
+  1200 supplied spends of one confirmed fan-out make the validation the
+  costly frame (over a second unoptimized: `tx_output_at_fk` decodes the
+  fan-out's outputs once per input) while the solved block is
+  coinbase-only. The proposal alone measures that wall; the same proposal
+  is sent again, then past its tip check (an eighth of that wall) a
+  `RequestTransactionData` and a `SubmitSolution` for the empty template.
+  The request's reply and the `NewTemplate` for the solved tip must arrive
+  before the proposal's reply, which takes the next id and names the tip
+  it started on. The request, with no blocking work behind it, must be
+  answered in under a quarter of the validation it overlapped, or the
+  order was luck, not the contract; the solution's margin is the wall
+  itself, since its accept ends in a tip write (an fsync, 94 ms here and
+  647 ms once under the parallel suite), which a ratio guard cannot sit
+  on. Red was `Success` as the first frame, the solution 527 ms behind a
+  696 ms validation.
+- **Green:** `on_frame` decodes the proposal and runs `job::precheck`
+  (`duplicate-wtxid`, `bad-missing-tx`; no chain read) on arrival, replying
+  at once on failure; otherwise the payload joins a FIFO and
+  `start_validations` fills a `JoinSet` of `spawn_blocking` +
+  `BlockingRegion` tasks up to the bound. A new `select!` arm takes each
+  finished verdict and calls the one `reply_propose` path (retain on
+  `Valid`, then the reply). `job::validate` stays complete on its own
+  (the precheck runs again inside it).
+- **CPU and RAM trade:** four full proposal checks at once per session,
+  each on a blocking thread with up to a block of decoded txs; waiting
+  proposals hold their payloads (≤ `MAX_PROPOSE_TEMPLATE_PAYLOAD` each),
+  depth bounded by the client's burst (one job per JDC per tip change for a
+  JDS), not by this TP: see Risks.
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib`; the journey 20 times in
+  a loop.
+
 ### Test budget
 
 Units: the messages round trip, `job::extranonce_len`, `rbitcoin-net`
 `check_block_proposal_*`, `rbitcoin-rpc` GBT proposal `bad-cb-amount`.
 Journeys in `rbitcoin-sv2`
-`template_tests`: four, each one TP and one session on the shared regtest
-pad. No `rbitcoin-test` node journey yet (follow-up with a JDS client).
+`template_tests`: five, each one TP and one session on the shared regtest
+pad; the D11 journey is the one over 2 s (the margin needs a validation
+several times the accept wall). No `rbitcoin-test` node journey yet
+(follow-up with a JDS client).
 
 ### Risks / follow-ups
 
@@ -805,6 +855,16 @@ pad. No `rbitcoin-test` node journey yet (follow-up with a JDS client).
 - No operator opt-out flag: any client that can reach the port may set
   the flag and cost one proposal check per request. Bind to loopback or
   firewall the port (the same advice as for templates).
+- The waiting-proposal queue (D11) has no depth cap: a client that sends
+  well-formed, expensive proposals faster than four blocking threads
+  validate them grows it by one payload each (≤ ~6.5 MB). A refusal or a
+  flood close would cut off a JDS at a tip change, when every JDC declares
+  at once; the trust model above (who reaches the port) is the bound. A
+  byte cap with an `Error` past it is the follow-up if that model changes.
+- A job whose validation straddles a tip change is retained after the
+  push for the new tip, so it misses that tip's stale grace and stays in
+  the ring until pushed out. `Success.prev_hash` names the old tip, so the
+  JDS discards it; a solution on it is a side block, not the tip.
 - `SetupConnection.Success.flags` echoes the request flags verbatim.
 - Retention is the template rule (D10): a validated job shares the
   session's `MAX_RETAINED` (64) ring with templates and the same stale

From 213a4da1cddb1f3891a236d1449b7f0808323e8b Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Thu, 8 Oct 2026 13:35:43 -0400
Subject: [PATCH 15/19] docs: note the per-input parent decode in the proposal
 check

check_block_proposal re-decodes a parent for every input that spends it,
which is what makes the D11 journey's 1200-input proposal slow. Record the
cache follow-up and that the journey's margin currently depends on the
inefficiency.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/sv2-template-provider.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index 84d83a32c..184834f51 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -893,6 +893,15 @@ several times the accept wall). No `rbitcoin-test` node journey yet
   client, stay out.
 
 ---
+- `check_block_proposal` decodes a parent transaction once per spending
+  input (`chain_txout` → `tx_output_at_fk` → full parent decode), so a
+  fan-out parent with N children costs N decodes of the same tx: the D11
+  journey's 1200-input proposal takes ~1.4 s for that reason alone.
+  Follow-up in `rbitcoin-net`: cache decoded parents for the duration of
+  one check (RAM trade bounded by the block's distinct parents). The D11
+  journey's timing margin depends on this slowness; when the cache lands
+  the journey needs a different heavy shape (many distinct parents) or a
+  different observable.
 
 ## Test budget
 

From d569c5742535b2cc475ce2f02a2a1632323f7fd7 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Fri, 9 Oct 2026 11:32:32 -0400
Subject: [PATCH 16/19] test: order the concurrency journey on
 RequestTransactionData

The D11 journey ordered a SubmitSolution's NewTemplate before a
1200-input proposal's Success. That margin came from the per-input
parent decode in the proposal check, which #961 and #968 removed: the
validation now takes about 210 ms at 1200 inputs and the accept's tip
write races it, so the journey failed 10 of 10 runs on the merged check
(Success first, or inconclusive-not-best-prevblk when the tip moved
before the check).

Pin the contract on the frame that has no blocking work behind it: a
RequestTransactionData sent behind a 400-input proposal is answered
before that proposal's Success and in under a quarter of its wall. A
SubmitSolution sent behind a third copy is accepted and pushes the solved
tip's template; it is not ordered against that copy's reply, which is
the straddle the plan already names (Success on the starting tip, or the
proposal check's reject once the tip moved).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-sv2/src/template_tests.rs | 125 ++++++++++++----------
 docs/sv2-template-provider.md             |  38 ++++---
 2 files changed, 92 insertions(+), 71 deletions(-)

diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index 661aac5a5..abee3ce82 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1488,24 +1488,24 @@ async fn submit_solution_for_a_validated_job_becomes_the_tip() {
     tp.shutdown().await;
 }
 
-/// A proposal's validation runs off the session loop: a
-/// `RequestTransactionData` and a `SubmitSolution` sent while a heavy
-/// `ProposeTemplate` is still validating are answered, and the solution
-/// becomes the tip and pushes its `NewTemplate`, before the proposal's reply,
-/// which then takes the next template id and names the tip it was validated
-/// on. The proposal supplies 1200 spends of one confirmed fan-out, so
-/// validating it is the costly frame (over a second unoptimized; most of the
-/// test's wall) while the solved block is coinbase-only. The same proposal
-/// alone measures that wall first. The request, which has no blocking work
-/// and no disk behind it, must be answered in a small fraction of the
-/// validation it overlapped, or the order would be luck, not the contract;
-/// the solution's accept has a tip write (an fsync) behind it, so its margin
-/// is the validation wall itself.
+/// A proposal's validation runs off the session loop. The proposal supplies
+/// a few hundred spends of one confirmed fan-out, so validating it is the
+/// costly frame (tens of milliseconds) while every template stays
+/// coinbase-only; the proposal alone measures that wall first. A
+/// `RequestTransactionData` sent right behind a second copy is answered
+/// before that copy's `Success`, in a small fraction of the validation it
+/// overlapped: the request has no blocking work behind it, so a slower
+/// answer would mean the loop waited on the validation and the order was
+/// luck. A `SubmitSolution` sent behind a third copy is accepted while that
+/// copy validates and pushes the solved tip's `NewTemplate`. Its accept ends
+/// in a tip write, so it is not ordered against the copy's reply, which is
+/// the straddle the plan names: `Success` on the tip the validation started
+/// on, or the proposal check's own reject once the tip moved first.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_validation_does_not_delay_other_frames() {
     let tc = shared_regtest(1);
     let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
-    let outs = 1_200u64;
+    let outs = 400u64;
     let each = (50_0000_0000 - 10_000) / outs;
     let mut fanout = spend(tc.coinbases[0], 10_000, cheap.clone());
     fanout.output = vec![
@@ -1564,7 +1564,7 @@ async fn propose_template_validation_does_not_delay_other_frames() {
         &job_coinbase(height, subsidy + fees, &declared),
         &declared,
     );
-    // Supplied, not pooled: the template above stays coinbase-only.
+    // Supplied, not pooled: the templates stay coinbase-only.
     job.supplied = spends.iter().map(serialize).collect();
 
     let asked = tokio::time::Instant::now();
@@ -1572,59 +1572,76 @@ async fn propose_template_validation_does_not_delay_other_frames() {
     expect_job_success(&mut c, &tc, 1, template_id + 1, fees).await;
     let alone = asked.elapsed();
 
-    while header.validate_pow(header.target()).is_err() {
-        header.nonce += 1;
-    }
     job.request_id = 2;
     let proposed = tokio::time::Instant::now();
     job.send(&mut c).await;
-    // Past the tip check at the head of the proposal check (a few percent
-    // of the wall), so the solution cannot cut this validation short.
-    tokio::time::sleep(alone / 8).await;
-    let requested = tokio::time::Instant::now();
     c.request_transaction_data(template_id).await.unwrap();
-    c.submit_solution(template_id, version, header.time, header.nonce, &coinbase)
-        .await
-        .unwrap();
     let f = recv_in_time(&mut c).await;
-    let requested = requested.elapsed();
+    let requested = proposed.elapsed();
     assert_eq!(
         f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS,
         "the request's reply must precede the proposal's (validation alone {alone:?})"
     );
-    let f = recv_in_time(&mut c).await;
-    assert_eq!(
-        f.msg_type, MESSAGE_TYPE_NEW_TEMPLATE,
-        "the solved tip's template must precede the proposal reply"
-    );
-    assert_eq!(
-        tc.chain.tip_header().unwrap().block_hash(),
-        header.block_hash()
-    );
-    let pushed = check_template(&mut c, &tc, f, &[], true).await;
-    assert_eq!(pushed, template_id + 2);
-
-    let mut f = recv_in_time(&mut c).await;
+    expect_job_success(&mut c, &tc, 2, template_id + 2, fees).await;
     let replied = proposed.elapsed();
-    assert_eq!(
-        f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
-        "{:?}",
-        f.payload
-    );
-    let ok: ProposeTemplateSuccess = binary_sv2::from_bytes(&mut f.payload).expect("decode");
-    assert_eq!(
-        (ok.request_id, ok.template_id, ok.fees),
-        (2, template_id + 3, fees)
-    );
-    assert_eq!(
-        ok.prev_hash.as_ref(),
-        header.prev_blockhash.as_byte_array(),
-        "validated on the tip it started on"
-    );
     assert!(
         requested * 4 < replied,
         "request answered in {requested:?} against a validation of {replied:?}"
     );
 
+    while header.validate_pow(header.target()).is_err() {
+        header.nonce += 1;
+    }
+    job.request_id = 3;
+    job.send(&mut c).await;
+    c.submit_solution(template_id, version, header.time, header.nonce, &coinbase)
+        .await
+        .unwrap();
+    let mut pushed = None;
+    let mut verdict = None;
+    for _ in 0..2 {
+        let mut f = recv_in_time(&mut c).await;
+        match f.msg_type {
+            MESSAGE_TYPE_NEW_TEMPLATE => {
+                assert_eq!(
+                    tc.chain.tip_header().unwrap().block_hash(),
+                    header.block_hash(),
+                    "the solution became the tip before its template was pushed"
+                );
+                pushed = Some(check_template(&mut c, &tc, f, &[], true).await);
+            }
+            MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS => {
+                let ok: ProposeTemplateSuccess =
+                    binary_sv2::from_bytes(&mut f.payload).expect("decode");
+                assert_eq!((ok.request_id, ok.fees), (3, fees));
+                assert_eq!(
+                    ok.prev_hash.as_ref(),
+                    header.prev_blockhash.as_byte_array(),
+                    "validated on the tip it started on"
+                );
+                verdict = Some(Some(ok.template_id));
+            }
+            MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR => {
+                let e: ProposeTemplateError =
+                    binary_sv2::from_bytes(&mut f.payload).expect("decode");
+                assert_eq!(e.request_id, 3);
+                assert!(
+                    ["inconclusive-not-best-prevblk", "bad-cb-height"]
+                        .contains(&e.error_code.as_utf8_or_hex().as_str()),
+                    "a tip change mid-validation fails the proposal check: {}",
+                    e.error_code.as_utf8_or_hex()
+                );
+                verdict = Some(None);
+            }
+            t => panic!("unexpected frame {t:#x}"),
+        }
+    }
+    let pushed = pushed.expect("the solved tip's template");
+    let mut ids = vec![pushed];
+    ids.extend(verdict.expect("the proposal's reply"));
+    ids.sort_unstable();
+    let want: Vec<u64> = (template_id + 3..template_id + 3 + ids.len() as u64).collect();
+    assert_eq!(ids, want, "ids follow the order the loop replied in");
+
     tp.shutdown().await;
 }
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index 184834f51..bb7343084 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -804,20 +804,24 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   many JDCs over one connection could have a found block's
   `SubmitSolution` sit behind another JDC's validation.
 - **Red:** `propose_template_validation_does_not_delay_other_frames` —
-  1200 supplied spends of one confirmed fan-out make the validation the
-  costly frame (over a second unoptimized: `tx_output_at_fk` decodes the
-  fan-out's outputs once per input) while the solved block is
-  coinbase-only. The proposal alone measures that wall; the same proposal
-  is sent again, then past its tip check (an eighth of that wall) a
-  `RequestTransactionData` and a `SubmitSolution` for the empty template.
-  The request's reply and the `NewTemplate` for the solved tip must arrive
-  before the proposal's reply, which takes the next id and names the tip
-  it started on. The request, with no blocking work behind it, must be
-  answered in under a quarter of the validation it overlapped, or the
-  order was luck, not the contract; the solution's margin is the wall
-  itself, since its accept ends in a tip write (an fsync, 94 ms here and
-  647 ms once under the parallel suite), which a ratio guard cannot sit
-  on. Red was `Success` as the first frame, the solution 527 ms behind a
+  400 supplied spends of one confirmed fan-out make the validation the
+  costly frame (about 85 ms on the parent-once proposal check) while every
+  template stays coinbase-only. The proposal alone measures that wall. A
+  `RequestTransactionData` for the empty template is sent right behind a
+  second copy; its reply must arrive before that copy's `Success`, in under
+  a quarter of the validation it overlapped: the request has no blocking
+  work behind it, so a slower answer means the loop waited and the order
+  was luck. A `SubmitSolution` behind a third copy is accepted while it
+  validates and pushes the solved tip's `NewTemplate`; its accept ends in a
+  tip write (an fsync), so the journey does not order it against that
+  copy's reply, which is the straddle named under Risks: `Success` on the
+  tip the validation started on, or the proposal check's reject once the
+  tip moved first. The first shape (1200 inputs, the solution ordered
+  before the reply) owed its margin to the per-input parent decode that
+  #968 removed; on the merged check it failed 10 of 10 runs (`Success`
+  before the solved tip's template, or `inconclusive-not-best-prevblk`
+  when the tip moved first), which was Red for this shape. The original
+  Red was `Success` as the first frame, the solution 527 ms behind a
   696 ms validation.
 - **Green:** `on_frame` decodes the proposal and runs `job::precheck`
   (`duplicate-wtxid`, `bad-missing-tx`; no chain read) on arrival, replying
@@ -832,7 +836,7 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   proposals hold their payloads (≤ `MAX_PROPOSE_TEMPLATE_PAYLOAD` each),
   depth bounded by the client's burst (one job per JDC per tip change for a
   JDS), not by this TP: see Risks.
-- **Verify:** `cargo test -p rbitcoin-sv2 --lib`; the journey 20 times in
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib`; the journey 10 times in
   a loop.
 
 ### Test budget
@@ -841,8 +845,8 @@ Units: the messages round trip, `job::extranonce_len`, `rbitcoin-net`
 `check_block_proposal_*`, `rbitcoin-rpc` GBT proposal `bad-cb-amount`.
 Journeys in `rbitcoin-sv2`
 `template_tests`: five, each one TP and one session on the shared regtest
-pad; the D11 journey is the one over 2 s (the margin needs a validation
-several times the accept wall). No `rbitcoin-test` node journey yet
+pad; the D11 journey is the heaviest (a fan-out block, then three
+validations of 400 supplied spends). No `rbitcoin-test` node journey yet
 (follow-up with a JDS client).
 
 ### Risks / follow-ups

From cbb86414b66359b39b4af20d168891e91a65a5eb Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Fri, 9 Oct 2026 11:34:06 -0400
Subject: [PATCH 17/19] docs: plan D follows the merged proposal-check stack

Plan D no longer stacks on sv2/plan-c-fee-push (merged as #949 and #951)
and its D1 step is upstream: #959 moved the proposal check onto
ChainHub, #963, #967, #968, and #969 made it complete, one decode per
parent, bounded, and right about spent coins after a reorg. Name those
as the prerequisites and why: the check is the job-validation hot path.

Drop the two risks they closed (no script execution, #967; the
per-input parent decode, #968), name both ends of the tip-change
straddle the D11 journey now accepts, fix the "no scripts" CPU-trade
lines, and remove the getblocktemplate bad-cb-amount changelog entry
that #959 already carries.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 changelog.d/sv2-job-validation.md |  5 ----
 crates/rbitcoin-sv2/src/job.rs    |  2 +-
 docs/sv2-template-provider.md     | 50 ++++++++++++++-----------------
 3 files changed, 24 insertions(+), 33 deletions(-)

diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
index 7ef64340b..d36ed2e1c 100644
--- a/changelog.d/sv2-job-validation.md
+++ b/changelog.d/sv2-job-validation.md
@@ -14,8 +14,3 @@ Added
   Validation runs off the session loop, up to four at once per
   connection, so a `SubmitSolution` or a tip push never waits behind
   another client's proposal.
-
-Changed
-
-- **`getblocktemplate` proposal mode rejects an overpaying coinbase** with
-  `bad-cb-amount`, as Bitcoin Core does.
diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index 116a6659d..ea2efa564 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -137,7 +137,7 @@ fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
     let mut block = Block { header, txdata };
     // CPU trade (CONTRIBUTING 9): one full proposal check per request
     // (every spend against the chain, structure, weight, sigops, coinbase
-    // value; no scripts, no PoW), on the blocking pool. A JDS sends one per
+    // value, scripts; no PoW), on the blocking pool. A JDS sends one per
     // declaration; a flood costs blocking threads, not the reactor.
     let fees = match chain.check_block_proposal(&block) {
         Ok(fees) => fees,
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index bb7343084..a2d04865f 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -577,10 +577,16 @@ when fees rise enough to matter, throttled. Requires Plan B.
 holds, fetches the transactions the node lacks, and submits the found block
 by `template_id`. Wire contract: [`sv2-job-validation.md`](./sv2-job-validation.md)
 (proposed TDP messages 0x77–0x7a and `SetupConnection` flag bit 0, for
-sv2-spec discussion #239, which supersedes #217). Requires Plan B and Plan C: the
-branch is stacked on `sv2/plan-c-fee-push` (reardencode PRs #949 then #951)
-for the shared `Arc<Transaction>` bodies and the 64-slot same-tip ring that
-retains validated jobs. The Core-IPC sibling implementation is
+sv2-spec discussion #239, which supersedes #217). Requires Plan B and Plan C
+(merged as #949 and #951: the shared `Arc<Transaction>` bodies and the
+64-slot same-tip ring that retains validated jobs) and the proposal-check
+stack on `ChainHub`, merged as #959, #961, #963, #967, #968, and #969. That
+check is the job-validation hot path: a JDS asks once per JDC declaration,
+dozens of times a minute per pool, so before this plan could ship it had
+to become one decode per parent (#961, #968), bounded in memory (#968),
+right about spent coins after a reorg (#968, #969), and complete (immature
+coinbases and structure before spends in #963, script execution and the
+fee-overflow checks in #967). The Core-IPC sibling implementation is
 stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
 `REQUIRES_JOB_VALIDATION`.
 
@@ -592,8 +598,10 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   `time-too-old` / `time-too-new`, every spend against the block and the
   confirmed chain, then structure (merkle, weight, sigops, BIP34 height,
   witness commitment) and the coinbase priced at subsidy + fees
-  (`bad-cb-amount`, after CheckBlock as in Core's ConnectBlock). `Ok` is
-  the fee total. No PoW, no scripts, no UTXO write.
+  (`bad-cb-amount`, after CheckBlock as in Core's ConnectBlock), then the
+  scripts of every spend (#967). `Ok` is the fee total. No PoW, no UTXO
+  write. Merged as #959; #963, #967, #968, and #969 extended it (see the
+  Plan D intro).
 - **Red:** `cargo test -p rbitcoin-net --lib check_block_proposal` — tip
   child passes, other parent rejects, `bad-cb-amount` after structure,
   `Ok(fees)`; `rbitcoin-rpc` `methods_tests` pins GBT proposal mode
@@ -662,7 +670,7 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   gains a typed `send`.
 - **CPU trade:** one full proposal check per request on the blocking pool
   (every spend against the chain, structure, weight, sigops, coinbase
-  value; no scripts, no PoW). A JDS sends one per declaration; a flood
+  value, scripts; no PoW). A JDS sends one per declaration; a flood
   costs blocking threads, not the reactor, and D3 bounds its RAM.
 - **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
 
@@ -851,11 +859,6 @@ validations of 400 supplied spends). No `rbitcoin-test` node journey yet
 
 ### Risks / follow-ups
 
-- No script execution in the proposal check: mempool txs were
-  script-checked at accept; `transaction_list` txs are not. A JDC can
-  declare a job with an invalid-script tx that validates here and fails
-  at `accept_block`. Core's `TestBlockValidity` runs scripts; running
-  `confirm_scripts_phase` on the supplied txs only is the follow-up.
 - No operator opt-out flag: any client that can reach the port may set
   the flag and cost one proposal check per request. Bind to loopback or
   firewall the port (the same advice as for templates).
@@ -865,10 +868,14 @@ validations of 400 supplied spends). No `rbitcoin-test` node journey yet
   flood close would cut off a JDS at a tip change, when every JDC declares
   at once; the trust model above (who reaches the port) is the bound. A
   byte cap with an `Error` past it is the follow-up if that model changes.
-- A job whose validation straddles a tip change is retained after the
-  push for the new tip, so it misses that tip's stale grace and stays in
-  the ring until pushed out. `Success.prev_hash` names the old tip, so the
-  JDS discards it; a solution on it is a side block, not the tip.
+- A job whose validation straddles a tip change ends one of two ways.
+  Past the proposal check's tip read it is retained after the push for the
+  new tip, so it misses that tip's stale grace and stays in the ring until
+  pushed out; `Success.prev_hash` names the old tip, so the JDS discards
+  it, and a solution on it is a side block, not the tip. Before that read
+  the check rejects it (`inconclusive-not-best-prevblk`, or
+  `bad-cb-height` when the header was read after the move). The D11
+  journey accepts either.
 - `SetupConnection.Success.flags` echoes the request flags verbatim.
 - Retention is the template rule (D10): a validated job shares the
   session's `MAX_RETAINED` (64) ring with templates and the same stale
@@ -896,17 +903,6 @@ validations of 400 supplied spends). No `rbitcoin-test` node journey yet
 - The JDS role itself, and a `rbitcoin-test` journey driving a JDS
   client, stay out.
 
----
-- `check_block_proposal` decodes a parent transaction once per spending
-  input (`chain_txout` → `tx_output_at_fk` → full parent decode), so a
-  fan-out parent with N children costs N decodes of the same tx: the D11
-  journey's 1200-input proposal takes ~1.4 s for that reason alone.
-  Follow-up in `rbitcoin-net`: cache decoded parents for the duration of
-  one check (RAM trade bounded by the block's distinct parents). The D11
-  journey's timing margin depends on this slowness; when the cache lands
-  the journey needs a different heavy shape (many distinct parents) or a
-  different observable.
-
 ## Test budget
 
 Units in `rbitcoin-mempool` (budgeted selection), `rbitcoin-store`

From 6a94e3ce3a1f411bea7c5df49e047d8d3e51ebf1 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Fri, 9 Oct 2026 11:48:22 -0400
Subject: [PATCH 18/19] sv2: request missing transactions with a provide round
 trip

sv2-spec#239 settled on the JDP shape for the missing-transactions leg
(Sjors, 2026-10-08): the TP asks with a proper message and the JDS
answers with one, reusing the 6.4.7 and 6.4.8 layouts under TDP numbers,
and the TP holds the pending proposal. ProposeTemplate drops
transaction_list; ProposeTemplate.MissingTransactions becomes
ProvideMissingTransactions (0x78, TP to client) and
ProvideMissingTransactions.Success (0x7b, client to TP) carries the txs.
A JDS copies both payloads between the TP and its JDC unchanged.

The session keeps a proposal it answered ProvideMissingTransactions
under its request_id (wtxids and coinbase split, no transactions) in a
table of at most MAX_PENDING_PROPOSALS (8) for provide_timeout (30 s,
Sv2TpConfig like setup_timeout); past the bound the oldest is dropped.
A provide for an id it does not hold, already consumed, or expired is
ProposeTemplate.Error unknown-request-id; a proposal under an id still
queued, in flight, or held is duplicate-request-id; a provide short of a
requested position, with a tx the TP did not ask for, or with one that
does not decode is bad-missing-tx and ends that exchange, the first two
before any decode. These edge rules match sv2-tp #137. A validation that
still lacks a transaction (one left the mempool between rounds) asks
again for every position the mempool does not hold, the supplied ones
included, since the TP holds no transactions across the round trip. The
client frame cap moves the block-sized bound onto
ProvideMissingTransactions.Success (~4.2 MB); ProposeTemplate drops to
wtxids plus coinbase (~2.3 MB).

Red was the compile failure of the journeys against the one-message
shape (no pending table, no 0x7b handler; the old session ignored
0x7b), then a short provide answered ProvideMissingTransactions again
and a ProposeTemplate under an in-flight id validated twice. The
missing-transactions journey walks the round trip, each code, the bound,
and expiry under a 1 s provide_timeout; the D11 journey completes each
copy through its provide and refuses the in-flight duplicate.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 crates/rbitcoin-node/src/run.rs           |   1 +
 crates/rbitcoin-sv2/src/job.rs            | 157 ++++++++------
 crates/rbitcoin-sv2/src/lib.rs            |  11 +
 crates/rbitcoin-sv2/src/listener_tests.rs |  39 +++-
 crates/rbitcoin-sv2/src/messages.rs       |  37 +++-
 crates/rbitcoin-sv2/src/session.rs        | 156 +++++++++++---
 crates/rbitcoin-sv2/src/template_tests.rs | 241 ++++++++++++++++------
 crates/rbitcoin-sv2/src/transport.rs      |  40 ++--
 8 files changed, 490 insertions(+), 192 deletions(-)

diff --git a/crates/rbitcoin-node/src/run.rs b/crates/rbitcoin-node/src/run.rs
index 941dce14a..23be4b0de 100644
--- a/crates/rbitcoin-node/src/run.rs
+++ b/crates/rbitcoin-node/src/run.rs
@@ -1956,6 +1956,7 @@ async fn start_sv2_tp(config: &NodeConfig, hub: &Arc<ChainHub>) -> Option<Sv2TpH
         stale_grace: Duration::from_secs(config.sv2_tp_stale_grace_secs),
         setup_timeout: rbitcoin_sv2::SETUP_TIMEOUT,
         write_timeout: rbitcoin_sv2::WRITE_TIMEOUT,
+        provide_timeout: rbitcoin_sv2::PROVIDE_TIMEOUT,
         fee_delta: config.sv2_tp_fee_delta,
         template_interval: Duration::from_secs(config.sv2_tp_template_interval_secs),
     };
diff --git a/crates/rbitcoin-sv2/src/job.rs b/crates/rbitcoin-sv2/src/job.rs
index ea2efa564..4d999c0e2 100644
--- a/crates/rbitcoin-sv2/src/job.rs
+++ b/crates/rbitcoin-sv2/src/job.rs
@@ -4,6 +4,7 @@
 
 use crate::messages::ProposeTemplate;
 use crate::template::{self, Job};
+use binary_sv2::{Seq064K, B016M};
 use bitcoin::consensus::encode::{deserialize_partial, VarInt};
 use bitcoin::hashes::{sha256d, Hash};
 use bitcoin::{block, Block, BlockHash, Transaction, TxMerkleNode, Wtxid};
@@ -13,8 +14,9 @@ use std::io;
 use std::sync::Arc;
 
 pub(crate) enum Verdict {
-    /// 0-indexed positions in `wtxid_list` neither the mempool nor
-    /// `transaction_list` resolves.
+    /// 0-indexed positions in `wtxid_list` the mempool does not resolve,
+    /// the supplied ones included: the TP holds no transactions across the
+    /// round trip, so what it was given once it asks for again.
     Missing(Vec<u16>),
     /// Consensus-valid on the tip: the fee total and the job to retain.
     Valid { fees: u64, job: Job },
@@ -23,108 +25,129 @@ pub(crate) enum Verdict {
     Rejected(String),
 }
 
-/// `None`: the payload is not a `ProposeTemplate`.
-pub(crate) fn decode(payload: &mut [u8]) -> Option<ProposeTemplate<'_>> {
-    binary_sv2::from_bytes(payload).ok()
+/// A `ProposeTemplate` as the session keeps it: owned, so it outlives its
+/// frame while the TP waits for the transactions it asked for. `excess_data`
+/// is not kept (opaque to the TP).
+pub(crate) struct Proposal {
+    pub request_id: u32,
+    version: u32,
+    coinbase_prefix: Vec<u8>,
+    coinbase_suffix: Vec<u8>,
+    wtxids: Vec<[u8; 32]>,
 }
 
-/// §4.1 and §4.4: the draft's own codes, before any mempool lookup or
-/// transaction decode, so a 32-byte wtxid is never amplified into a copy or
-/// an allocation the job did not declare. `Ok` is the supplied txs keyed by
-/// the wtxid of their bytes as sent; `Err` is the `Error.error_code`. No
-/// chain read, so the session runs it on arrival; [`validate`] runs it
-/// again and stays complete on its own.
-pub(crate) fn precheck<'m>(
-    m: &'m ProposeTemplate<'_>,
-) -> Result<HashMap<[u8; 32], &'m [u8]>, &'static str> {
-    let mut declared = HashSet::with_capacity(m.wtxid_list.len());
-    for w in m.wtxid_list.iter() {
-        if !declared.insert(w.as_ref()) {
-            return Err("duplicate-wtxid");
-        }
-    }
-    // The wtxid is the hash of the serialization as sent, so a supplied tx
-    // is matched to its slot without decoding it.
-    let supplied: HashMap<[u8; 32], &[u8]> = m
-        .transaction_list
-        .iter()
-        .map(|raw| {
-            (
-                sha256d::Hash::hash(raw.as_ref()).to_byte_array(),
-                raw.as_ref(),
-            )
+/// Supplied transactions keyed by the wtxid of their bytes as sent.
+pub(crate) type Supplied = HashMap<[u8; 32], Vec<u8>>;
+
+impl Proposal {
+    /// `None`: the payload is not a `ProposeTemplate`.
+    pub(crate) fn decode(payload: &mut [u8]) -> Option<Self> {
+        let m: ProposeTemplate = binary_sv2::from_bytes(payload).ok()?;
+        Some(Self {
+            request_id: m.request_id,
+            version: m.version,
+            coinbase_prefix: m.coinbase_tx_prefix.as_ref().to_vec(),
+            coinbase_suffix: m.coinbase_tx_suffix.as_ref().to_vec(),
+            wtxids: m
+                .wtxid_list
+                .iter()
+                .map(|w| w.as_ref().try_into().expect("U256 is 32 bytes"))
+                .collect(),
         })
-        .collect();
-    if supplied.keys().any(|w| !declared.contains(&w[..])) {
-        return Err("bad-missing-tx");
     }
-    Ok(supplied)
-}
 
-/// Reads the store and the mempool: blocking region only. `payload` was
-/// [`decode`]d once already; a second failure is a broken invariant.
-pub(crate) fn validate(chain: &ChainHub, mut payload: Vec<u8>) -> io::Result<(u32, Verdict)> {
-    let m = decode(&mut payload).ok_or_else(|| {
-        io::Error::new(
-            io::ErrorKind::InvalidData,
-            "sv2: ProposeTemplate stopped decoding",
-        )
-    })?;
-    Ok((m.request_id, check(chain, &m)?))
+    /// §4.1: `wtxid_list` has no duplicates. No chain read, so the session
+    /// runs it on arrival; [`validate`] runs it again and stays complete on
+    /// its own.
+    pub(crate) fn precheck(&self) -> Result<(), &'static str> {
+        let mut declared = HashSet::with_capacity(self.wtxids.len());
+        if self.wtxids.iter().all(|w| declared.insert(w)) {
+            Ok(())
+        } else {
+            Err("duplicate-wtxid")
+        }
+    }
+
+    /// §4.3: every supplied transaction hashes to a wtxid at one of the
+    /// positions the TP asked for, and every asked position is covered,
+    /// before any of them is decoded or copied, so a transaction nobody
+    /// asked for costs one hash and a short provide costs none. `Err` is
+    /// the `Error.error_code`.
+    pub(crate) fn accept_supplied(
+        &self,
+        missing: &[u16],
+        transaction_list: &Seq064K<'_, B016M<'_>>,
+    ) -> Result<Supplied, &'static str> {
+        let asked: HashSet<&[u8; 32]> = missing
+            .iter()
+            .filter_map(|&pos| self.wtxids.get(usize::from(pos)))
+            .collect();
+        let mut supplied = Supplied::with_capacity(transaction_list.len());
+        for raw in transaction_list.iter() {
+            let w = sha256d::Hash::hash(raw.as_ref()).to_byte_array();
+            if !asked.contains(&w) {
+                return Err("bad-missing-tx");
+            }
+            supplied.insert(w, raw.as_ref().to_vec());
+        }
+        if supplied.len() != asked.len() {
+            return Err("bad-missing-tx");
+        }
+        Ok(supplied)
+    }
 }
 
-/// §4.1 and §4.4 in order: the gate, [`precheck`] again, the coinbase,
-/// the resolution, then the proposal check.
-fn check(chain: &ChainHub, m: &ProposeTemplate) -> io::Result<Verdict> {
+/// Reads the store and the mempool: blocking region only.
+pub(crate) fn validate(chain: &ChainHub, p: &Proposal, supplied: &Supplied) -> io::Result<Verdict> {
     let rejected = |code: &str| Ok(Verdict::Rejected(code.into()));
     // Same gate as the templates: a stale tip validates nothing.
     if chain.in_ibd() {
         return rejected("job-validation-unavailable");
     }
     let next = template::next_header(chain)?;
-    let supplied = match precheck(m) {
-        Ok(supplied) => supplied,
-        Err(code) => return rejected(code),
-    };
-    let Some(extranonce) = extranonce_len(m.coinbase_tx_prefix.as_ref()) else {
+    if let Err(code) = p.precheck() {
+        return rejected(code);
+    }
+    let Some(extranonce) = extranonce_len(&p.coinbase_prefix) else {
         return rejected("bad-cb-decode");
     };
     let zeros = vec![0u8; extranonce];
-    let raw = [
-        m.coinbase_tx_prefix.as_ref(),
-        &zeros[..],
-        m.coinbase_tx_suffix.as_ref(),
-    ]
-    .concat();
+    let raw = [&p.coinbase_prefix[..], &zeros[..], &p.coinbase_suffix[..]].concat();
     let Ok(coinbase) = bitcoin::consensus::deserialize::<Transaction>(&raw) else {
         return rejected("bad-cb-decode");
     };
-    let mut txs = Vec::with_capacity(m.wtxid_list.len());
+    let mut txs = Vec::with_capacity(p.wtxids.len());
     let mut missing = Vec::new();
-    for (pos, w) in m.wtxid_list.iter().enumerate() {
-        let w: [u8; 32] = w.as_ref().try_into().expect("U256 is 32 bytes");
-        let tx = match supplied.get(&w) {
+    let mut provided = Vec::new();
+    for (pos, w) in p.wtxids.iter().enumerate() {
+        let pos = u16::try_from(pos).expect("Seq064K holds at most 65535");
+        let tx = match supplied.get(w) {
             Some(raw) => match bitcoin::consensus::deserialize::<Transaction>(raw) {
-                Ok(tx) => Some(tx),
+                Ok(tx) => {
+                    provided.push(pos);
+                    Some(tx)
+                }
                 Err(_) => return rejected("bad-missing-tx"),
             },
             None => chain
                 .mempool()
-                .and_then(|mp| mp.get_tx_by_wtxid(&Wtxid::from_byte_array(w))),
+                .and_then(|mp| mp.get_tx_by_wtxid(&Wtxid::from_byte_array(*w))),
         };
         match tx {
             Some(tx) => txs.push(tx),
-            None => missing.push(u16::try_from(pos).expect("Seq064K holds at most 65535")),
+            None => missing.push(pos),
         }
     }
     if !missing.is_empty() {
+        missing.extend(provided);
+        missing.sort_unstable();
         return Ok(Verdict::Missing(missing));
     }
     let mut leaves = Vec::with_capacity(1 + txs.len());
     leaves.push(coinbase.compute_txid().to_byte_array());
     leaves.extend(txs.iter().map(|tx| tx.compute_txid().to_byte_array()));
     let header = block::Header {
-        version: block::Version::from_consensus(m.version as i32),
+        version: block::Version::from_consensus(p.version as i32),
         prev_blockhash: BlockHash::from_byte_array(next.prev_hash),
         merkle_root: TxMerkleNode::from_byte_array(rbitcoin_store::merkle_root_from_txids(&leaves)),
         time: next.time,
diff --git a/crates/rbitcoin-sv2/src/lib.rs b/crates/rbitcoin-sv2/src/lib.rs
index be7fe4632..84c1f810c 100644
--- a/crates/rbitcoin-sv2/src/lib.rs
+++ b/crates/rbitcoin-sv2/src/lib.rs
@@ -37,6 +37,10 @@ pub const SETUP_TIMEOUT: Duration = Duration::from_secs(10);
 /// Default [`Sv2TpConfig::write_timeout`].
 pub const WRITE_TIMEOUT: Duration = Duration::from_secs(30);
 
+/// Default [`Sv2TpConfig::provide_timeout`]: a JDS relays the request to
+/// its JDC and the answer back, so the wait is two hops over the internet.
+pub const PROVIDE_TIMEOUT: Duration = Duration::from_secs(30);
+
 /// Default [`Sv2TpConfig::fee_delta`] (stratum-mining `sv2-tp`
 /// `-sv2feedelta`).
 pub const FEE_DELTA: u64 = 1000;
@@ -76,6 +80,11 @@ pub struct Sv2TpConfig {
     /// A socket write that makes no progress this long closes the session,
     /// so a client that stops reading cannot hold a slot.
     pub write_timeout: Duration,
+    /// How long a `ProposeTemplate` the node answered
+    /// `ProvideMissingTransactions` waits for the
+    /// `ProvideMissingTransactions.Success`; a later one is
+    /// `unknown-request-id`.
+    pub provide_timeout: Duration,
     /// With the tip unchanged, a rebuild is pushed only when its fees are at
     /// least this many sats above the session's last template.
     pub fee_delta: u64,
@@ -169,6 +178,7 @@ pub async fn run_sv2_tp(config: Sv2TpConfig) -> io::Result<Sv2TpHandle> {
     let stale_grace = config.stale_grace;
     let setup_timeout = config.setup_timeout;
     let write_timeout = config.write_timeout;
+    let provide_timeout = config.provide_timeout;
     let fee_push = session::FeePush {
         delta: config.fee_delta,
         interval: config.template_interval,
@@ -226,6 +236,7 @@ pub async fn run_sv2_tp(config: Sv2TpConfig) -> io::Result<Sv2TpHandle> {
                     stale_grace,
                     setup_timeout,
                     write_timeout,
+                    provide_timeout,
                     fee_push,
                     stats,
                 )
diff --git a/crates/rbitcoin-sv2/src/listener_tests.rs b/crates/rbitcoin-sv2/src/listener_tests.rs
index f186e5159..b5c12de97 100644
--- a/crates/rbitcoin-sv2/src/listener_tests.rs
+++ b/crates/rbitcoin-sv2/src/listener_tests.rs
@@ -1,10 +1,13 @@
-use crate::messages::{MESSAGE_TYPE_PROPOSE_TEMPLATE, REQUIRES_JOB_VALIDATION};
+use crate::messages::{
+    MESSAGE_TYPE_PROPOSE_TEMPLATE, MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS,
+    REQUIRES_JOB_VALIDATION,
+};
 use crate::test_chain::shared_regtest;
 use crate::testutil::TpClient;
 use crate::transport::MAX_PROPOSE_TEMPLATE_PAYLOAD;
 use crate::{
     run_sv2_tp, Sv2TpConfig, FEE_DELTA, MAX_SESSIONS, MAX_STALE_GRACE, MAX_TEMPLATE_INTERVAL,
-    MIN_TEMPLATE_INTERVAL, SETUP_TIMEOUT, TEMPLATE_INTERVAL, WRITE_TIMEOUT,
+    MIN_TEMPLATE_INTERVAL, PROVIDE_TIMEOUT, SETUP_TIMEOUT, TEMPLATE_INTERVAL, WRITE_TIMEOUT,
 };
 use common_messages_sv2::{
     SetupConnectionError, SetupConnectionSuccess, MESSAGE_TYPE_SETUP_CONNECTION_ERROR,
@@ -67,6 +70,7 @@ async fn setup_connection_success_errors_and_session_cap() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -138,6 +142,7 @@ async fn authority_key_prints_in_key_utils_base58check() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -173,6 +178,7 @@ async fn silent_sockets_are_dropped_at_the_setup_deadline() {
         stale_grace: Duration::from_secs(10),
         setup_timeout,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -215,6 +221,7 @@ async fn session_without_constraints_is_dropped_at_the_setup_deadline() {
         stale_grace: Duration::from_secs(10),
         setup_timeout,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -272,6 +279,7 @@ async fn client_that_stops_reading_is_dropped_at_the_write_deadline() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -322,8 +330,9 @@ async fn client_that_stops_reading_is_dropped_at_the_write_deadline() {
 }
 
 /// Each client message type has its own payload cap: the largest legitimate
-/// `SubmitSolution` and a `ProposeTemplate` well past it keep the session;
-/// a frame over the cap for its type closes it.
+/// `SubmitSolution`, a `ProposeTemplate` well past it, and a
+/// `ProvideMissingTransactions.Success` past the `ProposeTemplate` cap keep
+/// the session; a frame over the cap for its type closes it.
 #[tokio::test]
 async fn oversized_client_frame_closes_the_session() {
     let tc = shared_regtest(0);
@@ -336,6 +345,7 @@ async fn oversized_client_frame_closes_the_session() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -356,7 +366,8 @@ async fn oversized_client_frame_closes_the_session() {
         .expect("open after a max-size SubmitSolution");
     assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
 
-    // No handler yet: a ProposeTemplate under its own cap is read and ignored.
+    // Without the flag a ProposeTemplate under its own cap is read and
+    // ignored.
     let big = vec![0u8; 200 << 10];
     c.send_bytes(MESSAGE_TYPE_PROPOSE_TEMPLATE, &big)
         .await
@@ -377,12 +388,17 @@ async fn oversized_client_frame_closes_the_session() {
         .expect("handshake");
     c.setup_connection(TDP, 2, 2, 0).await.unwrap();
     c.recv().await.expect("setup reply");
-    let _ = c
-        .send_bytes(
-            MESSAGE_TYPE_PROPOSE_TEMPLATE,
-            &vec![0u8; MAX_PROPOSE_TEMPLATE_PAYLOAD + 1],
-        )
-        .await;
+    let over = vec![0u8; MAX_PROPOSE_TEMPLATE_PAYLOAD + 1];
+    c.send_bytes(MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS, &over)
+        .await
+        .unwrap();
+    c.request_transaction_data(1).await.unwrap();
+    let f = c
+        .recv()
+        .await
+        .expect("open after a ProvideMissingTransactions.Success past the ProposeTemplate cap");
+    assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
+    let _ = c.send_bytes(MESSAGE_TYPE_PROPOSE_TEMPLATE, &over).await;
     c.request_transaction_data(1).await.ok();
     assert_closed(&mut c, "a ProposeTemplate over its cap").await;
     tp.shutdown().await;
@@ -417,6 +433,7 @@ async fn out_of_range_timing_refuses_to_start() {
             stale_grace,
             setup_timeout: SETUP_TIMEOUT,
             write_timeout: WRITE_TIMEOUT,
+            provide_timeout: PROVIDE_TIMEOUT,
             fee_delta: FEE_DELTA,
             template_interval,
         })
diff --git a/crates/rbitcoin-sv2/src/messages.rs b/crates/rbitcoin-sv2/src/messages.rs
index 74d3385ce..59a006ff5 100644
--- a/crates/rbitcoin-sv2/src/messages.rs
+++ b/crates/rbitcoin-sv2/src/messages.rs
@@ -1,6 +1,7 @@
 //! Job-validation extension to TDP (`docs/sv2-job-validation.md` §3–5):
-//! the `SetupConnection` flag and the four `ProposeTemplate` messages a
-//! Job Declarator Server uses to have this TP check a custom job.
+//! the `SetupConnection` flag, the `ProposeTemplate` request and its two
+//! replies, and the `ProvideMissingTransactions` pair a Job Declarator
+//! Server relays between this TP and its JDC.
 
 use binary_sv2::{Deserialize, Seq064K, Serialize, Str0255, B016M, B064K, U256};
 
@@ -9,15 +10,16 @@ use binary_sv2::{Deserialize, Seq064K, Serialize, Str0255, B016M, B064K, U256};
 pub(crate) const REQUIRES_JOB_VALIDATION: u32 = 1 << 0;
 
 pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE: u8 = 0x77;
-pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS: u8 = 0x78;
+pub(crate) const MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS: u8 = 0x78;
 pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS: u8 = 0x79;
 pub(crate) const MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR: u8 = 0x7a;
+pub(crate) const MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS: u8 = 0x7b;
 
 /// Client → TP: is this custom job a consensus-valid block on the TP tip?
 /// The `DeclareMiningJob` subset a node needs, relayed unchanged: the
-/// coinbase split around the extranonce and the declared wtxids.
-/// `transaction_list` carries the txs a prior
-/// [`ProposeTemplateMissingTransactions`] asked for, in that order.
+/// coinbase split around the extranonce and the declared wtxids. Carries no
+/// transactions; the TP asks for the ones it lacks with
+/// [`ProvideMissingTransactions`].
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
 pub(crate) struct ProposeTemplate<'decoder> {
     pub request_id: u32,
@@ -27,16 +29,24 @@ pub(crate) struct ProposeTemplate<'decoder> {
     pub wtxid_list: Seq064K<'decoder, U256<'decoder>>,
     /// Opaque to the TP (TDP 7.6 semantics belong to the Pool).
     pub excess_data: B064K<'decoder>,
-    pub transaction_list: Seq064K<'decoder, B016M<'decoder>>,
 }
 
 /// TP → client: 0-indexed positions in `wtxid_list` the TP cannot resolve.
+/// The layout of JDP 6.4.7, so a JDS copies the payload to its JDC.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
-pub(crate) struct ProposeTemplateMissingTransactions<'decoder> {
+pub(crate) struct ProvideMissingTransactions<'decoder> {
     pub request_id: u32,
     pub unknown_tx_position_list: Seq064K<'decoder, u16>,
 }
 
+/// Client → TP: the transactions a [`ProvideMissingTransactions`] asked
+/// for, in that order. The layout of JDP 6.4.8, copied from the JDC.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+pub(crate) struct ProvideMissingTransactionsSuccess<'decoder> {
+    pub request_id: u32,
+    pub transaction_list: Seq064K<'decoder, B016M<'decoder>>,
+}
+
 /// TP → client: the job is valid on the tip `prev_hash` and retained under
 /// `template_id`, which shares the `NewTemplate.template_id` namespace.
 /// `fees` is the fee total of the declared transactions as the node's
@@ -93,19 +103,26 @@ mod tests {
                 coinbase_tx_suffix: B064K::try_from(&suffix[..]).unwrap(),
                 wtxid_list: Seq064K::new(vec![U256::from(&h2), U256::from(&h3)]).unwrap(),
                 excess_data: B064K::try_from(&details[..]).unwrap(),
-                transaction_list: Seq064K::new(vec![B016M::try_from(&tx[..]).unwrap()]).unwrap(),
             },
             &mut bytes,
         );
         let mut bytes = Vec::new();
         round_trip(
-            ProposeTemplateMissingTransactions {
+            ProvideMissingTransactions {
                 request_id: 7,
                 unknown_tx_position_list: Seq064K::new(vec![0u16, 5, u16::MAX]).unwrap(),
             },
             &mut bytes,
         );
         let mut bytes = Vec::new();
+        round_trip(
+            ProvideMissingTransactionsSuccess {
+                request_id: 7,
+                transaction_list: Seq064K::new(vec![B016M::try_from(&tx[..]).unwrap()]).unwrap(),
+            },
+            &mut bytes,
+        );
+        let mut bytes = Vec::new();
         round_trip(
             ProposeTemplateSuccess {
                 request_id: 7,
diff --git a/crates/rbitcoin-sv2/src/session.rs b/crates/rbitcoin-sv2/src/session.rs
index a27eafffe..d5085f1bd 100644
--- a/crates/rbitcoin-sv2/src/session.rs
+++ b/crates/rbitcoin-sv2/src/session.rs
@@ -1,10 +1,11 @@
 //! One TDP session: Noise handshake, `SetupConnection`, then TDP messages.
 
-use crate::job::{self, Verdict};
+use crate::job::{self, Proposal, Supplied, Verdict};
 use crate::messages::{
-    ProposeTemplateError, ProposeTemplateMissingTransactions, ProposeTemplateSuccess,
-    MESSAGE_TYPE_PROPOSE_TEMPLATE, MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR,
-    MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
+    ProposeTemplateError, ProposeTemplateSuccess, ProvideMissingTransactions,
+    ProvideMissingTransactionsSuccess, MESSAGE_TYPE_PROPOSE_TEMPLATE,
+    MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
+    MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS, MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS,
     REQUIRES_JOB_VALIDATION,
 };
 use crate::template;
@@ -66,13 +67,22 @@ const MAX_SUPERSEDED_CONSTRAINTS: u32 = 8;
 /// CPU and RAM trade (CONTRIBUTING 9): this many `ProposeTemplate`
 /// validations run at once per session, each one full proposal check on a
 /// blocking thread holding up to a block of decoded transactions. Later
-/// proposals wait in arrival order, each holding its payload (at most
-/// `MAX_PROPOSE_TEMPLATE_PAYLOAD`), and are not refused: a JDS declares one
-/// job per JDC at every tip change, so a burst is the normal shape. The
-/// queue has no cap of its own (docs/sv2-template-provider.md, Plan D
-/// risks).
+/// proposals wait in arrival order, each holding its wtxids and the
+/// transactions its JDS supplied (at most
+/// `MAX_PROVIDE_MISSING_TRANSACTIONS_PAYLOAD`), and are not refused: a JDS
+/// declares one job per JDC at every tip change, so a burst is the normal
+/// shape. The queue has no cap of its own (docs/sv2-template-provider.md,
+/// Plan D risks).
 const MAX_INFLIGHT_VALIDATIONS: usize = 4;
 
+/// RAM trade (CONTRIBUTING 9): a proposal the TP answered
+/// `ProvideMissingTransactions` waits here for the `.Success`, holding its
+/// wtxids (≤ 2 MiB) and coinbase split (≤ 128 KiB) but no transactions:
+/// ≤ 8 × ~2.2 MiB per session. Past the bound the oldest is dropped, and a
+/// provide for it is `unknown-request-id`, the same recovery a JDS runs
+/// when the hold timed out.
+pub(crate) const MAX_PENDING_PROPOSALS: usize = 8;
+
 /// Fee-delta push settings (docs/sv2-template-provider.md C1).
 #[derive(Clone, Copy)]
 pub(crate) struct FeePush {
@@ -105,6 +115,20 @@ struct Retained {
     retire_at: Option<Instant>,
 }
 
+/// A proposal waiting for its `ProvideMissingTransactions.Success`.
+struct Pending {
+    proposal: Arc<Proposal>,
+    /// The positions the `ProvideMissingTransactions` named.
+    missing: Vec<u16>,
+    expires_at: Instant,
+}
+
+/// A proposal and what its JDS supplied, waiting for a validation slot.
+struct Work {
+    proposal: Arc<Proposal>,
+    supplied: Supplied,
+}
+
 impl Templates {
     fn retain(&mut self, id: u64, job: template::Job, prev_sent: (u32, Instant)) {
         if self.retained.len() == MAX_RETAINED {
@@ -156,6 +180,7 @@ pub(crate) async fn serve(
     stale_grace: Duration,
     setup_timeout: Duration,
     write_timeout: Duration,
+    provide_timeout: Duration,
     fee_push: FeePush,
     stats: Arc<Sv2TpStats>,
 ) -> io::Result<()> {
@@ -188,6 +213,7 @@ pub(crate) async fn serve(
         conn: writer,
         chain,
         stale_grace,
+        provide_timeout,
         fee_push,
         stats,
         job_validation: flags & REQUIRES_JOB_VALIDATION != 0,
@@ -202,6 +228,8 @@ pub(crate) async fn serve(
         seen_updates: 0,
         validations: JoinSet::new(),
         queued: VecDeque::new(),
+        pending: VecDeque::new(),
+        open: Vec::new(),
     };
     s.run(&mut frames, deadline).await
 }
@@ -218,6 +246,7 @@ struct Session {
     conn: NoiseWriter,
     chain: Arc<ChainHub>,
     stale_grace: Duration,
+    provide_timeout: Duration,
     fee_push: FeePush,
     stats: Arc<Sv2TpStats>,
     /// `SetupConnection` negotiated `REQUIRES_JOB_VALIDATION`.
@@ -242,9 +271,14 @@ struct Session {
     /// `ProposeTemplate` validations in flight, at most
     /// `MAX_INFLIGHT_VALIDATIONS`. Dropping the set aborts them with the
     /// session.
-    validations: JoinSet<io::Result<(u32, Verdict)>>,
+    validations: JoinSet<io::Result<(Arc<Proposal>, Verdict)>>,
     /// Prechecked proposals waiting for a validation slot, oldest first.
-    queued: VecDeque<Vec<u8>>,
+    queued: VecDeque<Work>,
+    /// Proposals waiting for their missing transactions, oldest first, at
+    /// most `MAX_PENDING_PROPOSALS`.
+    pending: VecDeque<Pending>,
+    /// Request ids accepted and not yet answered: queued or in flight.
+    open: Vec<u32>,
 }
 
 impl Session {
@@ -258,7 +292,12 @@ impl Session {
     ) -> io::Result<()> {
         let mut tips = self.chain.subscribe_tips();
         loop {
-            let retire_at = self.templates.next_retire();
+            let retire_at = self
+                .templates
+                .next_retire()
+                .into_iter()
+                .chain(self.pending.front().map(|p| p.expires_at))
+                .min();
             tokio::select! {
                 f = frames.recv() => {
                     let Some(f) = f else { return Ok(()) };
@@ -272,14 +311,21 @@ impl Session {
                     Err(RecvError::Closed) => return Ok(()),
                 },
                 Some(done) = self.validations.join_next(), if !self.validations.is_empty() => {
-                    let (request_id, verdict) = done.map_err(io::Error::other)??;
+                    let (proposal, verdict) = done.map_err(io::Error::other)??;
+                    let request_id = proposal.request_id;
+                    self.open.retain(|&id| id != request_id);
+                    if let Verdict::Missing(positions) = &verdict {
+                        self.hold(proposal, positions.clone());
+                    }
                     self.reply_propose(request_id, verdict).await?;
                     self.start_validations();
                 }
                 _ = tokio::time::sleep_until(retire_at.unwrap_or_else(Instant::now)),
                     if retire_at.is_some() =>
                 {
-                    self.templates.retire(Instant::now());
+                    let now = Instant::now();
+                    self.templates.retire(now);
+                    self.pending.retain(|p| p.expires_at > now);
                 }
                 _ = tokio::time::sleep_until(self.rebuild_at.unwrap_or_else(Instant::now)),
                     if self.rebuild_at.is_some() =>
@@ -344,19 +390,66 @@ impl Session {
             }
             MESSAGE_TYPE_SUBMIT_SOLUTION => self.on_submit_solution(frame).await?,
             MESSAGE_TYPE_PROPOSE_TEMPLATE if self.job_validation => {
-                let Some(m) = job::decode(&mut frame.payload) else {
+                let Some(p) = Proposal::decode(&mut frame.payload) else {
                     rbitcoin_log::info!("sv2: undecodable ProposeTemplate");
                     return Ok(true);
                 };
-                let request_id = m.request_id;
-                if let Err(code) = job::precheck(&m) {
-                    self.reply_propose(request_id, Verdict::Rejected(code.into()))
+                let held = self.open.contains(&p.request_id)
+                    || self
+                        .pending
+                        .iter()
+                        .any(|w| w.proposal.request_id == p.request_id);
+                let code = if held {
+                    Err("duplicate-request-id")
+                } else {
+                    p.precheck()
+                };
+                if let Err(code) = code {
+                    self.reply_propose(p.request_id, Verdict::Rejected(code.into()))
                         .await?;
                     return Ok(true);
                 }
-                self.queued.push_back(frame.payload);
+                self.open.push(p.request_id);
+                self.queued.push_back(Work {
+                    proposal: Arc::new(p),
+                    supplied: Supplied::new(),
+                });
                 self.start_validations();
             }
+            MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS if self.job_validation => {
+                let Ok(m) =
+                    binary_sv2::from_bytes::<ProvideMissingTransactionsSuccess>(&mut frame.payload)
+                else {
+                    rbitcoin_log::info!("sv2: undecodable ProvideMissingTransactions.Success");
+                    return Ok(true);
+                };
+                let at = self
+                    .pending
+                    .iter()
+                    .position(|w| w.proposal.request_id == m.request_id);
+                let Some(Pending {
+                    proposal, missing, ..
+                }) = at.and_then(|at| self.pending.remove(at))
+                else {
+                    self.reply_propose(
+                        m.request_id,
+                        Verdict::Rejected("unknown-request-id".into()),
+                    )
+                    .await?;
+                    return Ok(true);
+                };
+                match proposal.accept_supplied(&missing, &m.transaction_list) {
+                    Ok(supplied) => {
+                        self.open.push(m.request_id);
+                        self.queued.push_back(Work { proposal, supplied });
+                        self.start_validations();
+                    }
+                    Err(code) => {
+                        self.reply_propose(m.request_id, Verdict::Rejected(code.into()))
+                            .await?;
+                    }
+                }
+            }
             t => rbitcoin_log::info!("sv2: ignoring message {t:#x}"),
         }
         Ok(true)
@@ -575,29 +668,44 @@ impl Session {
     /// comes from the `join_next` arm, paired by `request_id`.
     fn start_validations(&mut self) {
         while self.validations.len() < MAX_INFLIGHT_VALIDATIONS {
-            let Some(payload) = self.queued.pop_front() else {
+            let Some(Work { proposal, supplied }) = self.queued.pop_front() else {
                 return;
             };
             let c = Arc::clone(&self.chain);
             self.validations.spawn_blocking(move || {
                 let _g = BlockingRegion::enter();
-                job::validate(&c, payload)
+                let verdict = job::validate(&c, &proposal, &supplied)?;
+                Ok((proposal, verdict))
             });
         }
     }
 
+    /// docs/sv2-job-validation.md §4.2: keep the proposal for its
+    /// `ProvideMissingTransactions.Success`, `provide_timeout` at most.
+    fn hold(&mut self, proposal: Arc<Proposal>, missing: Vec<u16>) {
+        if self.pending.len() == MAX_PENDING_PROPOSALS {
+            self.pending.pop_front();
+        }
+        self.pending.push_back(Pending {
+            proposal,
+            missing,
+            expires_at: Instant::now() + self.provide_timeout,
+        });
+    }
+
     /// docs/sv2-job-validation.md §4: a valid job is retained under the next
-    /// template id and answered `Success`; a rejected one answers `Error`.
+    /// template id and answered `Success`; a rejected one answers `Error`; one
+    /// the mempool cannot complete is asked for its missing transactions.
     async fn reply_propose(&mut self, request_id: u32, verdict: Verdict) -> io::Result<()> {
         let wire = |e: binary_sv2::Error| io::Error::other(format!("sv2 ProposeTemplate: {e:?}"));
         match verdict {
             Verdict::Missing(positions) => {
-                let reply = ProposeTemplateMissingTransactions {
+                let reply = ProvideMissingTransactions {
                     request_id,
                     unknown_tx_position_list: Seq064K::new(positions).map_err(wire)?,
                 };
                 self.conn
-                    .send(MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, reply)
+                    .send(MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS, reply)
                     .await
             }
             Verdict::Valid { fees, job } => {
diff --git a/crates/rbitcoin-sv2/src/template_tests.rs b/crates/rbitcoin-sv2/src/template_tests.rs
index abee3ce82..f6aa1fc07 100644
--- a/crates/rbitcoin-sv2/src/template_tests.rs
+++ b/crates/rbitcoin-sv2/src/template_tests.rs
@@ -1,12 +1,17 @@
 use crate::messages::{
-    ProposeTemplate, ProposeTemplateError, ProposeTemplateMissingTransactions,
-    ProposeTemplateSuccess, MESSAGE_TYPE_PROPOSE_TEMPLATE, MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR,
-    MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
+    ProposeTemplate, ProposeTemplateError, ProposeTemplateSuccess, ProvideMissingTransactions,
+    ProvideMissingTransactionsSuccess, MESSAGE_TYPE_PROPOSE_TEMPLATE,
+    MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR, MESSAGE_TYPE_PROPOSE_TEMPLATE_SUCCESS,
+    MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS, MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS,
     REQUIRES_JOB_VALIDATION,
 };
+use crate::session::MAX_PENDING_PROPOSALS;
 use crate::test_chain::{padded_chain_with, shared_regtest, TestChain};
 use crate::testutil::TpClient;
-use crate::{run_sv2_tp, Sv2TpConfig, FEE_DELTA, SETUP_TIMEOUT, TEMPLATE_INTERVAL, WRITE_TIMEOUT};
+use crate::{
+    run_sv2_tp, Sv2TpConfig, FEE_DELTA, PROVIDE_TIMEOUT, SETUP_TIMEOUT, TEMPLATE_INTERVAL,
+    WRITE_TIMEOUT,
+};
 use binary_sv2::{Seq064K, B016M, B064K, U256};
 use bitcoin::consensus::encode::serialize;
 use bitcoin::hashes::{sha256d, Hash};
@@ -193,6 +198,7 @@ async fn template_budget_fees_coinbase_and_merkle_path() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -246,6 +252,7 @@ async fn template_resent_constraints_do_not_rebuild() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -288,6 +295,7 @@ async fn template_constraint_rebuilds_are_rate_limited() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -325,6 +333,7 @@ async fn sync_gate_holds_constraints_until_a_fresh_tip() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -379,6 +388,7 @@ async fn constraints_while_ibd_keep_the_last_budget() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -444,7 +454,7 @@ async fn first_template_every(
     template_interval: Duration,
 ) -> FirstTemplate {
     mock_live_tip(tc);
-    let (tp, mut c) = connect_tp_every(tc, flags, template_interval).await;
+    let (tp, mut c) = connect_tp_with(tc, flags, template_interval, PROVIDE_TIMEOUT).await;
     c.coinbase_output_constraints(0, 0).await.unwrap();
 
     let mut f = recv_in_time(&mut c).await;
@@ -671,6 +681,7 @@ async fn constraints_flood_closes_the_session() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -723,6 +734,7 @@ async fn tip_event_rebuilds_a_template_built_on_its_prev_hash() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: TEMPLATE_INTERVAL,
     })
@@ -822,6 +834,7 @@ async fn fee_push_after_the_interval_past_the_delta() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: 1_000,
         template_interval: interval,
     })
@@ -1012,6 +1025,7 @@ async fn fee_pushes_stay_an_interval_apart_under_steady_admission() {
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout: PROVIDE_TIMEOUT,
         fee_delta: FEE_DELTA,
         template_interval: interval,
     })
@@ -1097,14 +1111,16 @@ async fn idle_session_checks_each_interval_and_does_not_rebuild() {
 
 /// A live TP on `tc` with one session past `SetupConnection(flags)`.
 async fn connect_tp(tc: &TestChain, flags: u32) -> (crate::Sv2TpHandle, TpClient) {
-    connect_tp_every(tc, flags, TEMPLATE_INTERVAL).await
+    connect_tp_with(tc, flags, TEMPLATE_INTERVAL, PROVIDE_TIMEOUT).await
 }
 
-/// [`connect_tp`] on a TP that checks fees every `template_interval`.
-async fn connect_tp_every(
+/// [`connect_tp`] on a TP that checks fees every `template_interval` and
+/// holds a proposal waiting for its missing txs for `provide_timeout`.
+async fn connect_tp_with(
     tc: &TestChain,
     flags: u32,
     template_interval: Duration,
+    provide_timeout: Duration,
 ) -> (crate::Sv2TpHandle, TpClient) {
     let tp = run_sv2_tp(Sv2TpConfig {
         listen: "127.0.0.1:0".parse().unwrap(),
@@ -1114,6 +1130,7 @@ async fn connect_tp_every(
         stale_grace: Duration::from_secs(10),
         setup_timeout: SETUP_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
+        provide_timeout,
         fee_delta: FEE_DELTA,
         template_interval,
     })
@@ -1172,7 +1189,6 @@ struct Job {
     coinbase_prefix: Vec<u8>,
     coinbase_suffix: Vec<u8>,
     wtxids: Vec<[u8; 32]>,
-    supplied: Vec<Vec<u8>>,
 }
 
 impl Job {
@@ -1195,7 +1211,6 @@ impl Job {
                 .iter()
                 .map(|tx| tx.compute_wtxid().to_byte_array())
                 .collect(),
-            supplied: Vec::new(),
         }
     }
 
@@ -1207,18 +1222,41 @@ impl Job {
             coinbase_tx_suffix: B064K::try_from(&self.coinbase_suffix[..]).unwrap(),
             wtxid_list: Seq064K::new(self.wtxids.iter().map(U256::from).collect()).unwrap(),
             excess_data: B064K::try_from(&[][..]).unwrap(),
-            transaction_list: Seq064K::new(
-                self.supplied
-                    .iter()
-                    .map(|t| B016M::try_from(&t[..]).unwrap())
-                    .collect(),
-            )
-            .unwrap(),
         };
         c.send(MESSAGE_TYPE_PROPOSE_TEMPLATE, msg).await.unwrap();
     }
 }
 
+/// The TP asks for `positions` of `request_id`'s `wtxid_list`.
+async fn expect_missing(c: &mut TpClient, request_id: u32, positions: &[u16]) {
+    let mut f = recv_in_time(c).await;
+    assert_eq!(
+        f.msg_type, MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS,
+        "{:?}",
+        f.payload
+    );
+    let m: ProvideMissingTransactions = binary_sv2::from_bytes(&mut f.payload).expect("decode");
+    assert_eq!(m.request_id, request_id);
+    assert_eq!(m.unknown_tx_position_list.into_inner(), positions);
+}
+
+/// The JDS leg of the round trip: `txs` as the JDC serialized them, under
+/// the `request_id` the TP asked with.
+async fn provide(c: &mut TpClient, request_id: u32, txs: &[Vec<u8>]) {
+    let msg = ProvideMissingTransactionsSuccess {
+        request_id,
+        transaction_list: Seq064K::new(
+            txs.iter()
+                .map(|t| B016M::try_from(&t[..]).unwrap())
+                .collect(),
+        )
+        .unwrap(),
+    };
+    c.send(MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS, msg)
+        .await
+        .unwrap();
+}
+
 async fn expect_job_error(c: &mut TpClient, request_id: u32, code: &str) {
     let mut f = recv_in_time(c).await;
     assert_eq!(f.msg_type, MESSAGE_TYPE_PROPOSE_TEMPLATE_ERROR, "{code}");
@@ -1298,49 +1336,121 @@ async fn propose_template_prices_and_retains_the_declared_job() {
     tp.shutdown().await;
 }
 
-/// §4.1–4.2: a wtxid the TP cannot resolve answers `MissingTransactions`
-/// with its 0-indexed position; the same job resent with that tx in
-/// `transaction_list` validates, and the supplied tx is retained with it.
+/// §4.1–4.2: a wtxid the TP cannot resolve answers `ProvideMissingTransactions`
+/// with its 0-indexed position and holds the proposal under its
+/// `request_id`; the JDS's `ProvideMissingTransactions.Success` for that id
+/// completes the validation with the supplied tx merged in, and the tx is
+/// retained with the job. The hold is per request: a provide for an id the
+/// TP never asked about, already consumed, or held past `provide_timeout`
+/// is `unknown-request-id`; a second proposal under an id still waiting is
+/// `duplicate-request-id`; a provide that does not cover every requested
+/// position, supplies a tx the TP did not ask for, or one that does not
+/// decode, is `bad-missing-tx` and ends that exchange. The
+/// hold is bounded: past `MAX_PENDING_PROPOSALS` waiting proposals the
+/// oldest is dropped and its provide is `unknown-request-id` too. No
+/// rejected or dropped proposal takes a template id.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_asks_for_and_accepts_missing_transactions() {
     let tc = shared_regtest(2);
     mock_live_tip(&tc);
     let cheap = ScriptBuf::from_bytes(vec![OP_TRUE]);
     let a = spend(tc.coinbases[0], 3_000, cheap.clone());
-    let b = spend(tc.coinbases[1], 2_000, cheap);
+    let b = spend(tc.coinbases[1], 2_000, cheap.clone());
+    // Decodable and unknown to the mempool, like `b`; never validated.
+    let sibling = spend(tc.coinbases[1], 2_500, cheap);
     tc.mempool.accept_tx(&a).expect("mempool accept");
-    let (tp, mut c) = connect_tp(&tc, REQUIRES_JOB_VALIDATION).await;
+    let provide_timeout = Duration::from_secs(1);
+    let (tp, mut c) = connect_tp_with(
+        &tc,
+        REQUIRES_JOB_VALIDATION,
+        TEMPLATE_INTERVAL,
+        provide_timeout,
+    )
+    .await;
     c.coinbase_output_constraints(0, 0).await.unwrap();
     let last = expect_template(&mut c, &tc, &[&a], true).await;
 
     let height = tc.chain.query.tip_height().unwrap().0 + 1;
     let subsidy = block_subsidy(height, &tc.chain.params) as u64;
     let coinbase = job_coinbase(height, subsidy + 5_000, &[&a, &b]);
-    let mut job = Job::declare(&tc, 4, &coinbase, &[&a, &b]);
-    job.send(&mut c).await;
-    let mut f = recv_in_time(&mut c).await;
-    assert_eq!(
-        f.msg_type,
-        MESSAGE_TYPE_PROPOSE_TEMPLATE_MISSING_TRANSACTIONS
-    );
-    let m: ProposeTemplateMissingTransactions =
-        binary_sv2::from_bytes(&mut f.payload).expect("decode");
-    assert_eq!(m.request_id, 4);
-    assert_eq!(m.unknown_tx_position_list.into_inner(), vec![1u16]);
+    let raw_b = serialize(&b);
+
+    provide(&mut c, 77, std::slice::from_ref(&raw_b)).await;
+    expect_job_error(&mut c, 77, "unknown-request-id").await;
 
-    job.supplied = vec![serialize(&b)];
+    let job = Job::declare(&tc, 4, &coinbase, &[&a, &b]);
+    job.send(&mut c).await;
+    expect_missing(&mut c, 4, &[1]).await;
     job.send(&mut c).await;
+    expect_job_error(&mut c, 4, "duplicate-request-id").await;
+    provide(&mut c, 4, std::slice::from_ref(&raw_b)).await;
     expect_job_success(&mut c, &tc, 4, last + 1, 5_000).await;
     expect_retained(&mut c, last + 1, &[&a, &b]).await;
+    provide(&mut c, 4, std::slice::from_ref(&raw_b)).await;
+    expect_job_error(&mut c, 4, "unknown-request-id").await;
+
+    Job::declare(&tc, 5, &coinbase, &[&a, &b])
+        .send(&mut c)
+        .await;
+    expect_missing(&mut c, 5, &[1]).await;
+    provide(&mut c, 5, &[serialize(&a)]).await;
+    expect_job_error(&mut c, 5, "bad-missing-tx").await;
+    provide(&mut c, 5, std::slice::from_ref(&raw_b)).await;
+    expect_job_error(&mut c, 5, "unknown-request-id").await;
+
+    Job::declare(&tc, 6, &coinbase, &[&a, &b, &sibling])
+        .send(&mut c)
+        .await;
+    expect_missing(&mut c, 6, &[1, 2]).await;
+    provide(&mut c, 6, std::slice::from_ref(&raw_b)).await;
+    expect_job_error(&mut c, 6, "bad-missing-tx").await;
+    provide(&mut c, 6, &[raw_b.clone(), serialize(&sibling)]).await;
+    expect_job_error(&mut c, 6, "unknown-request-id").await;
+
+    let blob = vec![0xee; 40];
+    let mut garbage = Job::declare(&tc, 8, &coinbase, &[]);
+    garbage.wtxids = vec![sha256d::Hash::hash(&blob).to_byte_array()];
+    garbage.send(&mut c).await;
+    expect_missing(&mut c, 8, &[0]).await;
+    provide(&mut c, 8, &[blob]).await;
+    expect_job_error(&mut c, 8, "bad-missing-tx").await;
+
+    for id in 10..10 + MAX_PENDING_PROPOSALS as u32 + 1 {
+        Job::declare(&tc, id, &coinbase, &[&a, &b])
+            .send(&mut c)
+            .await;
+        expect_missing(&mut c, id, &[1]).await;
+    }
+    provide(&mut c, 10, std::slice::from_ref(&raw_b)).await;
+    expect_job_error(&mut c, 10, "unknown-request-id").await;
+    provide(&mut c, 11, std::slice::from_ref(&raw_b)).await;
+    expect_job_success(&mut c, &tc, 11, last + 2, 5_000).await;
+
+    Job::declare(&tc, 7, &coinbase, &[&a, &b])
+        .send(&mut c)
+        .await;
+    expect_missing(&mut c, 7, &[1]).await;
+    tokio::time::sleep(provide_timeout + provide_timeout / 2).await;
+    provide(&mut c, 7, &[raw_b]).await;
+    expect_job_error(&mut c, 7, "unknown-request-id").await;
+
+    c.request_transaction_data(last + 3).await.unwrap();
+    let mut f = recv_in_time(&mut c).await;
+    assert_eq!(f.msg_type, MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR);
+    let e: RequestTransactionDataError = binary_sv2::from_bytes(&mut f.payload).unwrap();
+    assert_eq!(
+        e.error_code.as_utf8_or_hex(),
+        "template-id-not-found",
+        "only the two completed jobs took ids"
+    );
 
     tp.shutdown().await;
 }
 
 /// §4.1 and §4.4: everything in a job comes from a JDC. The checks run in
 /// order before any mempool lookup or transaction decode: a repeated wtxid
-/// or a supplied tx nobody declared is refused on arrival, even while the
-/// tip is stale (IBD) and every other job is `job-validation-unavailable`;
-/// then a declared blob that does not decode, a coinbase prefix that does
+/// is refused on arrival, even while the tip is stale (IBD) and every other
+/// job is `job-validation-unavailable`; then a coinbase prefix that does
 /// not parse or a coinbase that does not decode, then the proposal check's
 /// own reject string: a declaration from before the tip moved fails its
 /// BIP34 height, an overpaying coinbase its amount. Nothing is retained on
@@ -1377,18 +1487,6 @@ async fn propose_template_rejects_untrusted_input_in_order() {
         .await;
     expect_job_error(&mut c, 2, "duplicate-wtxid").await;
 
-    let mut undeclared = Job::declare(&tc, 3, &coinbase, &[&a]);
-    undeclared.supplied = vec![serialize(&b)];
-    undeclared.send(&mut c).await;
-    expect_job_error(&mut c, 3, "bad-missing-tx").await;
-
-    let blob = vec![0xee; 40];
-    let mut garbage = Job::declare(&tc, 4, &coinbase, &[]);
-    garbage.wtxids = vec![sha256d::Hash::hash(&blob).to_byte_array()];
-    garbage.supplied = vec![blob];
-    garbage.send(&mut c).await;
-    expect_job_error(&mut c, 4, "bad-missing-tx").await;
-
     // More scriptSig bytes than the length the prefix declares.
     let mut short_sig = Job::declare(&tc, 5, &coinbase, &[&a, &b]);
     short_sig.coinbase_prefix.extend_from_slice(&[0; 16]);
@@ -1488,19 +1586,23 @@ async fn submit_solution_for_a_validated_job_becomes_the_tip() {
     tp.shutdown().await;
 }
 
-/// A proposal's validation runs off the session loop. The proposal supplies
-/// a few hundred spends of one confirmed fan-out, so validating it is the
-/// costly frame (tens of milliseconds) while every template stays
-/// coinbase-only; the proposal alone measures that wall first. A
-/// `RequestTransactionData` sent right behind a second copy is answered
-/// before that copy's `Success`, in a small fraction of the validation it
-/// overlapped: the request has no blocking work behind it, so a slower
-/// answer would mean the loop waited on the validation and the order was
-/// luck. A `SubmitSolution` sent behind a third copy is accepted while that
-/// copy validates and pushes the solved tip's `NewTemplate`. Its accept ends
-/// in a tip write, so it is not ordered against the copy's reply, which is
-/// the straddle the plan names: `Success` on the tip the validation started
-/// on, or the proposal check's own reject once the tip moved first.
+/// A proposal's validation runs off the session loop. The proposal declares
+/// a few hundred spends of one confirmed fan-out that the mempool lacks, so
+/// each copy is asked for all of them and the costly frame (tens of
+/// milliseconds) is the `ProvideMissingTransactions.Success` that completes
+/// it, while every template stays coinbase-only; the first copy measures
+/// that wall. A `RequestTransactionData` sent right behind the second copy's
+/// provide is answered before that copy's `Success`, in a small fraction of
+/// the validation it overlapped: the request has no blocking work behind
+/// it, so a slower answer would mean the loop waited on the validation and
+/// the order was luck; a `ProposeTemplate` under the id in flight is refused
+/// `duplicate-request-id` on arrival the same way. A `SubmitSolution` sent
+/// behind the third copy's
+/// provide is accepted while that copy validates and pushes the solved
+/// tip's `NewTemplate`. Its accept ends in a tip write, so it is not ordered
+/// against the copy's reply, which is the straddle the plan names:
+/// `Success` on the tip the validation started on, or the proposal check's
+/// own reject once the tip moved first.
 #[tokio::test(flavor = "multi_thread")]
 async fn propose_template_validation_does_not_delay_other_frames() {
     let tc = shared_regtest(1);
@@ -1564,18 +1666,25 @@ async fn propose_template_validation_does_not_delay_other_frames() {
         &job_coinbase(height, subsidy + fees, &declared),
         &declared,
     );
-    // Supplied, not pooled: the templates stay coinbase-only.
-    job.supplied = spends.iter().map(serialize).collect();
+    // Provided, not pooled: the templates stay coinbase-only.
+    let supplied: Vec<Vec<u8>> = spends.iter().map(serialize).collect();
+    let all: Vec<u16> = (0..outs as u16).collect();
 
-    let asked = tokio::time::Instant::now();
     job.send(&mut c).await;
+    expect_missing(&mut c, 1, &all).await;
+    let asked = tokio::time::Instant::now();
+    provide(&mut c, 1, &supplied).await;
     expect_job_success(&mut c, &tc, 1, template_id + 1, fees).await;
     let alone = asked.elapsed();
 
     job.request_id = 2;
+    job.send(&mut c).await;
+    expect_missing(&mut c, 2, &all).await;
     let proposed = tokio::time::Instant::now();
+    provide(&mut c, 2, &supplied).await;
     job.send(&mut c).await;
     c.request_transaction_data(template_id).await.unwrap();
+    expect_job_error(&mut c, 2, "duplicate-request-id").await;
     let f = recv_in_time(&mut c).await;
     let requested = proposed.elapsed();
     assert_eq!(
@@ -1594,6 +1703,8 @@ async fn propose_template_validation_does_not_delay_other_frames() {
     }
     job.request_id = 3;
     job.send(&mut c).await;
+    expect_missing(&mut c, 3, &all).await;
+    provide(&mut c, 3, &supplied).await;
     c.submit_solution(template_id, version, header.time, header.nonce, &coinbase)
         .await
         .unwrap();
diff --git a/crates/rbitcoin-sv2/src/transport.rs b/crates/rbitcoin-sv2/src/transport.rs
index 62612bf5d..d041ed0f8 100644
--- a/crates/rbitcoin-sv2/src/transport.rs
+++ b/crates/rbitcoin-sv2/src/transport.rs
@@ -1,6 +1,8 @@
 //! Noise_NX transport over one TCP stream: handshake, then encrypted SV2 frames.
 
-use crate::messages::MESSAGE_TYPE_PROPOSE_TEMPLATE;
+use crate::messages::{
+    MESSAGE_TYPE_PROPOSE_TEMPLATE, MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS,
+};
 use binary_sv2::{GetSize, Serialize};
 use codec_sv2::{
     Decoded, Decrypted, Handshake, MessageFrame, NoiseDecoder, NoiseEncoder, TransportDecryptState,
@@ -20,29 +22,37 @@ pub struct Frame {
     pub payload: Vec<u8>,
 }
 
-/// Largest client→TP payload for every message but `ProposeTemplate`:
-/// `SubmitSolution`, 20 fixed bytes plus a `B064K` coinbase (2-byte length,
-/// ≤ 65535 bytes). The 24-bit frame length would otherwise let a client
-/// make the session buffer ~16 MB per frame.
+/// Largest client→TP payload for every message but the job-validation
+/// pair: `SubmitSolution`, 20 fixed bytes plus a `B064K` coinbase (2-byte
+/// length, ≤ 65535 bytes). The 24-bit frame length would otherwise let a
+/// client make the session buffer ~16 MB per frame.
 const MAX_CLIENT_PAYLOAD: usize = 20 + 2 + u16::MAX as usize;
 
+/// `SEQ0_64K` element count.
+const SEQ: usize = u16::MAX as usize;
+
 /// Largest `ProposeTemplate` payload: 8 fixed bytes, three `B064K` fields
-/// (coinbase prefix, suffix, excess data), a full `SEQ0_64K[U256]` wtxid
-/// list, and a `SEQ0_64K[B016M]` transaction list whose txs together fit a
-/// block (weight is never below serialized size) with a 3-byte length each.
+/// (coinbase prefix, suffix, excess data) and a full `SEQ0_64K[U256]` wtxid
+/// list (~2.3 MB).
+pub(crate) const MAX_PROPOSE_TEMPLATE_PAYLOAD: usize = 4 + 4 + 3 * (2 + SEQ) + (2 + SEQ * 32);
+
+/// Largest `ProvideMissingTransactions.Success` payload: 4 fixed bytes and a
+/// `SEQ0_64K[B016M]` transaction list whose txs together fit a block (weight
+/// is never below serialized size) with a 3-byte length each.
 ///
 /// RAM trade (CONTRIBUTING 9): a session buffers one in-flight client frame
-/// of at most this size (~6.5 MB), so at `MAX_SESSIONS` client frames hold
-/// ≤ ~52 MB on top of template retention (lib.rs).
-pub(crate) const MAX_PROPOSE_TEMPLATE_PAYLOAD: usize = {
-    const SEQ: usize = u16::MAX as usize;
-    4 + 4 + 3 * (2 + SEQ) + (2 + SEQ * 32) + (2 + SEQ * 3 + MAX_BLOCK_WEIGHT as usize)
-};
+/// of at most this size (~4.2 MB), so at `MAX_SESSIONS` client frames hold
+/// ≤ ~34 MB on top of template retention (lib.rs).
+pub(crate) const MAX_PROVIDE_MISSING_TRANSACTIONS_PAYLOAD: usize =
+    4 + 2 + SEQ * 3 + MAX_BLOCK_WEIGHT as usize;
 
 /// Payload cap by client message type.
 const fn client_payload_cap(msg_type: u8) -> usize {
     match msg_type {
         MESSAGE_TYPE_PROPOSE_TEMPLATE => MAX_PROPOSE_TEMPLATE_PAYLOAD,
+        MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS => {
+            MAX_PROVIDE_MISSING_TRANSACTIONS_PAYLOAD
+        }
         _ => MAX_CLIENT_PAYLOAD,
     }
 }
@@ -71,7 +81,7 @@ impl FrameCap {
     /// Client→TP: the largest client message while reading, then
     /// [`client_payload_cap`] for the type.
     const CLIENT: Self = Self {
-        max_frame: encrypted_frame_len(MAX_PROPOSE_TEMPLATE_PAYLOAD),
+        max_frame: encrypted_frame_len(MAX_PROVIDE_MISSING_TRANSACTIONS_PAYLOAD),
         payload: client_payload_cap,
     };
     /// TP→client: the 24-bit frame length only.

From 6cd50e7b54723f87810f76370e378c6adf253017 Mon Sep 17 00:00:00 2001
From: Gary Krause <gary.krause@mara.com>
Date: Fri, 9 Oct 2026 11:58:38 -0400
Subject: [PATCH 19/19] docs: job validation draft follows the request/provide
 round trip

The draft now specifies the shape sv2-spec#239 converged on: no
transaction_list on ProposeTemplate; ProvideMissingTransactions (0x78)
and ProvideMissingTransactions.Success (0x7b) reuse JDP 6.4.7 and 6.4.8
under TDP numbers (ours to propose; the thread has assigned none); the TP
holds a proposal awaiting its provide for at least N seconds and may
bound the holds per connection; unknown-request-id and
duplicate-request-id join the error table; the Success table lists
request_id, template_id, prev_hash, fees in wire order (the fees row had
drifted to the top of the file). Section 6 replaces the stateless
rationale with why the TP holds state (Sjors's request/provide point; the
TxCollection handle is that state) and opens the queue-or-refuse question
at the in-flight bound where rbitcoin and sv2-tp differ. Section 7.1 maps
the JDS relay (payload copied, message type changed) and 8 records the
2026-10-08 turn.

Plan D gains D12 for the round trip and the changelog fragment names the
provide pair.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 changelog.d/sv2-job-validation.md |   8 +-
 docs/sv2-job-validation.md        | 198 ++++++++++++++++++++----------
 docs/sv2-template-provider.md     |  72 +++++++++--
 3 files changed, 201 insertions(+), 77 deletions(-)

diff --git a/changelog.d/sv2-job-validation.md b/changelog.d/sv2-job-validation.md
index d36ed2e1c..9f9725d9d 100644
--- a/changelog.d/sv2-job-validation.md
+++ b/changelog.d/sv2-job-validation.md
@@ -2,11 +2,15 @@ Added
 
 - **SV2 TP: custom job validation for Job Declarator Servers.** A TDP
   client that sets `SetupConnection` flag bit 0 (`REQUIRES_JOB_VALIDATION`)
-  can send `ProposeTemplate` (proposed TDP messages 0x77–0x7a, sv2-spec
+  can send `ProposeTemplate` (proposed TDP messages 0x77–0x7b, sv2-spec
   discussion #239) with the `DeclareMiningJob` fields relayed unchanged.
   The node rebuilds the placeholder coinbase from the declared prefix and
   suffix, resolves the declared wtxids against its mempool, asks for the
-  ones it lacks, checks the job as a block on its tip, and answers that tip,
+  ones it lacks with `ProvideMissingTransactions` and takes them back in
+  `ProvideMissingTransactions.Success` (the Job Declaration Protocol's own
+  shapes, so a JDS relays both unchanged; the proposal is held up to 30 s,
+  at most eight per connection), checks the job as a block on its tip, and
+  answers that tip,
   the fee total of the declared transactions, and a template id that
   `SubmitSolution` accepts like one of the node's own templates; the job is
   retained like one too (same ring, same stale grace). Duplicated,
diff --git a/docs/sv2-job-validation.md b/docs/sv2-job-validation.md
index 1801d72d3..539f7fa79 100644
--- a/docs/sv2-job-validation.md
+++ b/docs/sv2-job-validation.md
@@ -1,4 +1,3 @@
-| fees        | U64       | Sum of the fees of the transactions in `wtxid_list`, in satoshis, as computed by the TP's validation                                                                                   |
 # Stratum V2: Custom Job Validation over the Template Distribution Protocol
 
 Draft for [sv2-spec discussion #239](https://github.com/stratum-mining/sv2-spec/discussions/239)
@@ -18,11 +17,13 @@ block, and later propagate the block when JDC sends `PushSolution`. The
 specification leaves how JDS talks to its Bitcoin node undefined ("RPCs (or
 similar)", Section 6.1).
 
-This document adds four TDP messages and one `SetupConnection` flag so that a
+This document adds five TDP messages and one `SetupConnection` flag so that a
 JDS can validate a declared Custom Job, and later submit its solution, through
 any Template Provider (TP) over the authenticated TDP connection it already
 uses. The request carries the subset of `DeclareMiningJob` a node needs,
-relayed unchanged. The exchange mirrors the flow the Job Declaration Protocol
+relayed unchanged; the missing-transactions leg reuses the Job Declaration
+Protocol's own `ProvideMissingTransactions` pair, relayed unchanged in both
+directions. The exchange mirrors the flow the Job Declaration Protocol
 already imposes on JDS: look transactions up by `wtxid`, ask JDC for the ones
 nobody has, validate, and submit the solution by reference.
 
@@ -45,30 +46,34 @@ nobody has, validate, and submit the solution by reference.
   without resending the block. This proposal is that flow expressed as TDP
   messages, so `sv2-tp` can serve it on top of Core IPC, and a node with a
   native TP can serve it directly.
-- Validation by `wtxid` position lets JDS relay `ProvideMissingTransactions`
-  and `ProvideMissingTransactions.Success` payloads between JDC and TP without
-  parsing them, as Sections 6.4.7 and 6.4.8 already require.
+- Validation by `wtxid` position lets JDS relay the TP's
+  `ProvideMissingTransactions` to JDC and JDC's
+  `ProvideMissingTransactions.Success` to the TP byte for byte, as Sections
+  6.4.7 and 6.4.8 already require of it; only the message type changes.
 
 ## 2. Overview
 
 ```
 JDC                      JDS                             TP
  |-- DeclareMiningJob --->|                               |
- |                        |-- ProposeTemplate --------->|  version, coinbase prefix/suffix, wtxid_list, no txs
- |                        |<- ProposeTemplate.MissingTransactions   (only if TP lacks some)
- |<- ProvideMissingTransactions                           |
+ |                        |-- ProposeTemplate --------->|  version, coinbase prefix/suffix, wtxid_list; no txs
+ |                        |<- ProvideMissingTransactions |  only if the TP lacks some; the TP holds the proposal
+ |<- ProvideMissingTransactions           |               |  same payload, JDP message type
  |-- ProvideMissingTransactions.Success ->|               |
- |                        |-- ProposeTemplate --------->|  same job + transaction_list
- |                        |<- ProposeTemplate.Success --|  template_id, prev_hash, fees
+ |                        |-- ProvideMissingTransactions.Success ->|  same payload, TDP message type
+ |                        |<- ProposeTemplate.Success --|  request_id, template_id, prev_hash, fees
  |<- DeclareMiningJob.Success             |               |
  ...
  |-- PushSolution ------->|                               |
  |                        |-- SubmitSolution(template_id)>|  existing 7.8 message
 ```
 
-- `ProposeTemplate` is stateless on the server side across the
-  missing-transactions round trip: the second request repeats the job and adds
-  the transactions. The TP MUST NOT require any state from the first request.
+- The TP holds a proposal it answered `ProvideMissingTransactions` under
+  its `request_id` until the `ProvideMissingTransactions.Success` arrives
+  or a timeout passes (Section 4.1). `request_id` pairs the whole exchange,
+  as it pairs `DeclareMiningJob` with its `ProvideMissingTransactions` in
+  Section 6.4.7. The JDS relays the two provide messages without parsing
+  them.
 - `ProposeTemplate` carries no `prev_hash`: `DeclareMiningJob` has none, so a
   JDS cannot supply one without guessing. The TP validates against its own
   current tip and names that tip in `ProposeTemplate.Success.prev_hash`, which
@@ -117,7 +122,6 @@ server's current chain tip.
 | coinbase_tx_suffix | B0_64K           | `DeclareMiningJob.coinbase_tx_suffix` unchanged: the serialized coinbase from the input's `nSequence` on. If the coinbase is a SegWit transaction, BIP141 fields (marker and flag in the prefix; witness count, witness length, witness reserved value in the suffix) MUST NOT be stripped |
 | wtxid_list         | SEQ0_64K[U256]   | `wtxid` of every transaction in the Custom Job, in block order, excluding the coinbase. Copied from `DeclareMiningJob.wtxid_list`                                                                                                                                                         |
 | excess_data        | B0_64K           | `DeclareMiningJob.excess_data` unchanged. Opaque to the server; its meaning is between JDC and Pool (Section 7.6)                                                                                                                                                                         |
-| transaction_list   | SEQ0_64K[B0_16M] | Full transactions the server reported in `ProposeTemplate.MissingTransactions`, in the order they were requested. Empty on the first request. Each transaction MUST be relayed exactly as received from JDC in `ProvideMissingTransactions.Success`, without parsing or re-encoding    |
 
 The server reconstructs a placeholder coinbase as `coinbase_tx_prefix` ||
 `E` zero bytes || `coinbase_tx_suffix`, where `E` is the scriptSig length
@@ -136,21 +140,30 @@ merkle root or proof of work, and every other coinbase check (size, weight,
 BIP34 height push, output values, witness commitment) is independent of the
 extranonce bytes.
 
-The server resolves each `wtxid` against its mempool and against
-`transaction_list`. If any transaction is still unknown, it MUST reply
-`ProposeTemplate.MissingTransactions`. Otherwise it MUST validate the job as
-a block on top of its current chain tip with the following rules, and reply
-either `ProposeTemplate.Success` or `ProposeTemplate.Error`:
+The server resolves each `wtxid` against its mempool. If any transaction is
+unknown, it MUST reply `ProvideMissingTransactions` (Section 4.2) and hold
+the proposal under its `request_id`: it MUST keep the proposal available for
+a `ProvideMissingTransactions.Success` (Section 4.3) for at least N seconds
+(RECOMMENDED 30) and MAY bound the proposals held per connection, dropping
+the oldest. A `ProvideMissingTransactions.Success` for a `request_id` the
+server does not hold, no longer holds, or has already consumed is answered
+`ProposeTemplate.Error` with `unknown-request-id`; a `ProposeTemplate` whose
+`request_id` the server has accepted and not yet answered, or still holds,
+is answered `duplicate-request-id`.
+Once every transaction is known, from the mempool or the provide, the server
+MUST validate the job as a block on top of its current chain tip with the
+following rules, and reply either `ProposeTemplate.Success` or
+`ProposeTemplate.Error`:
 
 - The server validates against its own current tip and reports that tip in
   `ProposeTemplate.Success.prev_hash`. There is no stale-tip error code: a
   job declared for a tip the server has since left fails the checks below on
   its own, normally the BIP34 height push (`bad-cb-height`) or an input the
   new tip spent; a job that still passes on the new tip is valid there.
-- `wtxid_list` MUST contain no duplicates, and every entry of
-  `transaction_list` MUST hash to a `wtxid` that the server reported missing.
-  Otherwise reply `duplicate-wtxid` or `bad-missing-tx`. These checks MUST run
-  before any transaction is decoded or copied.
+- `wtxid_list` MUST contain no duplicates (`duplicate-wtxid`), and every
+  entry of `ProvideMissingTransactions.Success.transaction_list` MUST hash to
+  a `wtxid` at a position the server asked for (`bad-missing-tx`). Both
+  checks MUST run before any transaction is decoded or copied.
 - The server MUST apply every consensus check it would apply to a received
   block except the proof-of-work check and the merkle-root check. This
   includes: transaction validity and input availability against the UTXO set
@@ -168,29 +181,50 @@ either `ProposeTemplate.Success` or `ProposeTemplate.Error`:
   current time for `nTime` when it needs a header for contextual checks. The
   client does not supply them.
 
-### 4.2 `ProposeTemplate.MissingTransactions` (Server -> Client)
+### 4.2 `ProvideMissingTransactions` (Server -> Client)
 
-The server does not know some of the transactions in `wtxid_list`. The client
-is expected to obtain them from JDC via `ProvideMissingTransactions` and send
-a new `ProposeTemplate` with `transaction_list` filled.
+The server does not know some of the transactions in `wtxid_list` and holds
+the proposal. The field layout is `ProvideMissingTransactions` of Section
+6.4.7 of the Job Declaration Protocol under a TDP message type, so the
+client copies the payload to JDC as its own `ProvideMissingTransactions`.
 
-| Field Name               | Data Type     | Description                                                                                                                                                    |
-| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| request_id               | U32           | Identifier of the original `ProposeTemplate` request                                                                                                           |
-| unknown_tx_position_list | SEQ0_64K[U16] | Positions in `wtxid_list` of the transactions the server lacks, 0-indexed, not including the coinbase. Same encoding as `ProvideMissingTransactions.unknown_tx_position_list` |
+| Field Name               | Data Type     | Description                                                                                                                      |
+| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| request_id               | U32           | Identifier of the original `ProposeTemplate` request                                                                             |
+| unknown_tx_position_list | SEQ0_64K[U16] | Positions in `wtxid_list` of the transactions the server lacks, 0-indexed, not including the coinbase. As in Section 6.4.7      |
 
 The positions are relative to `wtxid_list`, which is a copy of
-`DeclareMiningJob.wtxid_list`, so the client can copy this field into
-`ProvideMissingTransactions.unknown_tx_position_list` unchanged, and copy
-`ProvideMissingTransactions.Success.transaction_list` into
-`ProposeTemplate.transaction_list` unchanged.
-
-A server MAY reply `ProposeTemplate.MissingTransactions` to a request whose
-`transaction_list` is non-empty, for example when a transaction left its
-mempool between the two requests. A client SHOULD bound how many times it
-retries one declaration.
-
-### 4.3 `ProposeTemplate.Success` (Server -> Client)
+`DeclareMiningJob.wtxid_list`, so they are JDC's positions too.
+
+A server MAY answer a `ProvideMissingTransactions.Success` with another
+`ProvideMissingTransactions`, for example when a transaction left its
+mempool between the two. A server that holds no transactions across the
+round trip then names every position it still lacks, the ones already
+supplied included. A client SHOULD bound how many times it retries one
+declaration.
+
+### 4.3 `ProvideMissingTransactions.Success` (Client -> Server)
+
+The transactions a `ProvideMissingTransactions` asked for. The field layout
+is `ProvideMissingTransactions.Success` of Section 6.4.8, so the client
+copies JDC's payload under the TDP message type.
+
+| Field Name       | Data Type        | Description                                                                                                                                                                  |
+| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| request_id       | U32              | Identifier of the original `ProposeTemplate` request                                                                                                                         |
+| transaction_list | SEQ0_64K[B0_16M] | The transactions at the requested positions, in the order they were requested. Each MUST be relayed exactly as received from JDC, without parsing or re-encoding             |
+
+The server MUST check that every entry hashes to a requested `wtxid` and
+that every requested position is covered, before decoding any of them: a
+provide that is short, carries a transaction nobody asked for, or carries
+one that does not decode is `ProposeTemplate.Error` with `bad-missing-tx`.
+Otherwise the server completes the validation of Section 4.1 with the
+supplied transactions merged in and replies `ProposeTemplate.Success` or
+`ProposeTemplate.Error`. The proposal is no longer held either way; a second
+`ProvideMissingTransactions.Success` for the same `request_id` is
+`unknown-request-id`.
+
+### 4.4 `ProposeTemplate.Success` (Server -> Client)
 
 The job is consensus-valid on the server's current tip. The server has stored
 the job and will accept a `SubmitSolution` for it.
@@ -200,6 +234,7 @@ the job and will accept a `SubmitSolution` for it.
 | request_id  | U32       | Identifier of the original `ProposeTemplate` request                                                                                                                                  |
 | template_id | U64       | Server's identification of the validated job. Drawn from the same strictly increasing namespace as `NewTemplate.template_id`, so it can be used in `SubmitSolution` and `RequestTransactionData` |
 | prev_hash   | U256      | Hash of the server's chain tip the job was validated on, as it would appear in the block header. The client keeps it to compare against `PushSolution.prev_hash`                      |
+| fees        | U64       | Sum of the fees of the transactions in `wtxid_list`, in satoshis, as computed by the server's validation                                                                               |
 
 The server MUST retain the validated job (its transactions in block order
 and the header fields a `SubmitSolution` is assembled with) under the same
@@ -212,7 +247,7 @@ many JDCs over one connection, so no single job is "the latest"; a
 `stale-template-id` or `template-id-not-found`. See Section 7.1 for what the
 JDS does with that.
 
-### 4.4 `ProposeTemplate.Error` (Server -> Client)
+### 4.5 `ProposeTemplate.Error` (Server -> Client)
 
 The job was not validated. The client decides what to tell JDC; it SHOULD map
 consensus rejections to `DeclareMiningJob.Error` and SHOULD NOT treat the
@@ -233,11 +268,13 @@ rejection strings (`bad-txns-inputs-missingorspent`, `bad-cb-length`,
 | error_code                | Meaning                                                              |
 | ------------------------- | -------------------------------------------------------------------- |
 | duplicate-wtxid           | `wtxid_list` contains the same `wtxid` more than once                |
-| bad-missing-tx            | An entry of `transaction_list` does not hash to a requested `wtxid`  |
+| bad-missing-tx            | `ProvideMissingTransactions.Success.transaction_list` does not cover every requested position, or an entry does not hash to a requested `wtxid` or does not decode as a transaction |
+| unknown-request-id        | `ProvideMissingTransactions.Success.request_id` names no proposal the server holds: never asked about, already answered, dropped under the per-connection bound, or past the hold timeout |
+| duplicate-request-id      | `ProposeTemplate.request_id` names a proposal the server has accepted and not yet answered, or still holds for its missing transactions |
 | bad-cb-decode             | `coinbase_tx_prefix` does not parse as one input with a scriptSig length covering the bytes present, or the reconstructed coinbase does not decode |
 | job-validation-unavailable | The server cannot validate now (for example, initial block download) |
 
-### 4.5 `SubmitSolution` for validated jobs
+### 4.6 `SubmitSolution` for validated jobs
 
 When the client receives `PushSolution` from JDC it SHOULD check
 `PushSolution.prev_hash` against the `ProposeTemplate.Success.prev_hash`
@@ -263,17 +300,22 @@ Additions to Section 8, Template Distribution Protocol:
 
 | Message Type (8-bit) | channel_msg bit | Message Name                            |
 | -------------------- | --------------- | --------------------------------------- |
-| 0x77                 | 0               | ProposeTemplate                       |
-| 0x78                 | 0               | ProposeTemplate.MissingTransactions   |
-| 0x79                 | 0               | ProposeTemplate.Success               |
-| 0x7a                 | 0               | ProposeTemplate.Error                 |
-
-All four are core messages and carry `extension_type = 0x0000`.
+| 0x77                 | 0               | ProposeTemplate                         |
+| 0x78                 | 0               | ProvideMissingTransactions              |
+| 0x79                 | 0               | ProposeTemplate.Success                 |
+| 0x7a                 | 0               | ProposeTemplate.Error                   |
+| 0x7b                 | 0               | ProvideMissingTransactions.Success      |
+
+All five are core messages and carry `extension_type = 0x0000`. The two
+`ProvideMissingTransactions` numbers are this draft's proposal; discussion
+#239 has agreed on the request/provide shape but assigned no numbers yet.
+The names repeat the Job Declaration Protocol's on purpose, as
+`SetNewPrevHash` is both 0x20 and 0x72: the payloads are the same.
 
 ## 6. Design notes and open questions
 
 - **Core messages or an extension.** Issue 217 proposes a core TDP message.
-  The same four messages could instead be extension `0x0003`, negotiated with
+  The same five messages could instead be extension `0x0003`, negotiated with
   `RequestExtensions` (extension `0x0001`) and framed with
   `extension_type = 0x0003`. The `SetupConnection` flag in Section 3 gives
   negotiation without requiring extension `0x0001` in TPs, which is why the
@@ -303,6 +345,13 @@ All four are core messages and carry `extension_type = 0x0000`.
   the other messages on the connection, `SubmitSolution` above all
   (rbitcoin validates off the session loop, four at a time per connection,
   the rest queued in arrival order).
+- **At the in-flight bound: queue or refuse (open).** A server that runs a
+  bounded number of validations at once has two choices for the next
+  proposal: rbitcoin queues it in arrival order with no depth cap (four in
+  flight per connection), sv2-tp refuses it with
+  `job-validation-unavailable`. A JDS should cope with both, a refusal as
+  a retry after a backoff and a queue as a longer wait under its own
+  timeout, but the thread should settle which the text recommends.
 - **Untrusted input.** Everything in `ProposeTemplate` originates from a
   JDC. The server MUST enforce the `duplicate-wtxid` and `bad-missing-tx`
   checks and the block weight limit before decoding or storing transactions,
@@ -322,9 +371,20 @@ All four are core messages and carry `extension_type = 0x0000`.
   `NewTemplate.template_id` sent on it. The server MAY draw it from a
   per-connection counter (rbitcoin) or a server-global one (`sv2-tp`); a
   client MUST NOT compare ids across connections.
-- **Why positions, not `wtxid`s, in `MissingTransactions`.** Section 6.4.7
-  uses positions, so the JDS relays the list unchanged. A `wtxid` list would
-  force the JDS to translate.
+- **Why the TP holds state.** An earlier draft repeated the whole
+  `ProposeTemplate` with a `transaction_list`, so the TP needed nothing
+  between the two requests. Sjors (#239, 2026-10-08) asked for the missing
+  leg to be proper request and provide messages, conceptually the existing
+  ones, which is also how `TxCollection` works in Bitcoin Core: `collectTxs`
+  returns the handle whose `unknownTxPos` the TP reports and whose
+  `addMissingTxs` the provide feeds, so the handle is the held proposal. A
+  held proposal costs its `wtxid_list` and coinbase split, not transactions,
+  so a bounded table per connection is enough (rbitcoin: 8 proposals, 30 s).
+  A dropped or expired hold surfaces as `unknown-request-id` and the JDS
+  proposes again; that is the one recovery path.
+- **Why positions, not `wtxid`s, in `ProvideMissingTransactions`.** Section
+  6.4.7 uses positions, so the JDS relays the list unchanged. A `wtxid` list
+  would force the JDS to translate.
 - **Why no separate `SubmitBlock`.** The server already holds the validated
   transaction set; resending up to 4 MB at block-find time only adds latency.
   Reusing `SubmitSolution` is also what `TxCollection.makeTemplate` followed by
@@ -336,11 +396,11 @@ All four are core messages and carry `extension_type = 0x0000`.
 
 | JDP event                            | TDP action                                                                    |
 | ------------------------------------ | ----------------------------------------------------------------------------- |
-| `DeclareMiningJob`                   | `ProposeTemplate` with `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`, `excess_data` copied unchanged, empty `transaction_list` |
-| `ProposeTemplate.MissingTransactions` | `ProvideMissingTransactions` with the position list copied                  |
-| `ProvideMissingTransactions.Success` | `ProposeTemplate` again with `transaction_list` copied                       |
+| `DeclareMiningJob`                   | `ProposeTemplate` with `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`, `excess_data` copied unchanged |
+| `ProvideMissingTransactions` (from the TP) | `ProvideMissingTransactions` to JDC: the payload copied, the JDP message type |
+| `ProvideMissingTransactions.Success` (from JDC) | `ProvideMissingTransactions.Success` to the TP: the payload copied, the TDP message type |
 | `ProposeTemplate.Success`          | `DeclareMiningJob.Success`; store `template_id` and `prev_hash` with the declaration; pass `fees` to the Pool, which prices the declared coinbase against it |
-| `ProposeTemplate.Error`            | `DeclareMiningJob.Error` with the error code                                  |
+| `ProposeTemplate.Error`            | `DeclareMiningJob.Error` with the error code; on `unknown-request-id` after a slow JDC, a new `ProposeTemplate` instead |
 | `PushSolution`                       | Check `prev_hash` against the stored one, then `SubmitSolution(template_id, version, ntime, nonce, coinbase_tx)` |
 
 Solutions are keyed by `template_id`. When the server has already dropped
@@ -358,7 +418,8 @@ Pool's "`[jds]` requires `BitcoinCoreIpc`" startup check becomes "requires
 `ProposeTemplate` maps onto `getTransactionsByWitnessID` (Core v32) for the
 lookup and `checkBlock(checkMerkleRoot=false, checkPow=false)` for validation,
 or onto `TxCollection` (`collectTxs`, `unknownTxPos`, `addMissingTxs`,
-`makeTemplate`) once bitcoin/bitcoin#35671 lands. `SubmitSolution` for a
+`makeTemplate`) once bitcoin/bitcoin#35671 lands; the held proposal of
+Section 4.1 is then the `TxCollection` handle itself. `SubmitSolution` for a
 validated job maps onto `submitBlock` or `BlockTemplate.submitSolution`.
 
 ### 7.3 Template Provider in a node
@@ -374,9 +435,11 @@ dependency.
   "RFC: `ProposeTemplate`" (plebhash, 2026-10-06), supersedes #217. Names the
   message and carries the subset of `DeclareMiningJob` a node needs
   (`request_id`, `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`,
-  `wtxid_list`, `excess_data`), with no `prev_hash`. This draft follows it
-  and adds the missing-transactions reply, `transaction_list` on the repeated
-  request, and `prev_hash` in `Success`.
+  `wtxid_list`, `excess_data`), with no `prev_hash`. Sjors (2026-10-08)
+  asked for the missing leg to be proper request and provide messages
+  reusing the existing ones, mandatory `template_id`, and no second flag.
+  This draft follows both: the `ProvideMissingTransactions` pair under TDP
+  numbers, and `prev_hash` and `fees` in `Success`.
 - [sv2-spec#217](https://github.com/stratum-mining/sv2-spec/issues/217):
   "consider adding a new TDP message for custom job validation" (plebhash,
   2026-08-31). Proposes message `X`, `X.Error` triggering
@@ -399,9 +462,10 @@ dependency.
   [bitcoin/bitcoin#35671](https://github.com/bitcoin/bitcoin/pull/35671)
   (open): `TxCollection`. The combined flow written up there (collect by
   `wtxid`, report unknown positions, add missing, `makeTemplate`, submit the
-  solution by reference) is the flow Sections 2 and 4 encode. The thread also
-  records the hazard of server-side state across the missing-transactions
-  round trip, which is why `ProposeTemplate` is stateless until `Success`.
+  solution by reference) is the flow Sections 2 and 4 encode. The handle
+  `collectTxs` returns is the state a TP holds across the round trip; this
+  draft bounds that state per connection (Section 4.1) instead of avoiding
+  it.
 - [sv2-apps#299](https://github.com/stratum-mining/sv2-apps/pull/299): JDS
   refactor that removed the JSON-RPC backend and folded JDS into the Pool.
   [sv2-apps#26](https://github.com/stratum-mining/sv2-apps/issues/26) gives the
diff --git a/docs/sv2-template-provider.md b/docs/sv2-template-provider.md
index a2d04865f..3e1d168d9 100644
--- a/docs/sv2-template-provider.md
+++ b/docs/sv2-template-provider.md
@@ -576,7 +576,7 @@ when fees rise enough to matter, throttled. Requires Plan B.
 `DeclareMiningJob` against this node over the TDP connection it already
 holds, fetches the transactions the node lacks, and submits the found block
 by `template_id`. Wire contract: [`sv2-job-validation.md`](./sv2-job-validation.md)
-(proposed TDP messages 0x77–0x7a and `SetupConnection` flag bit 0, for
+(proposed TDP messages 0x77–0x7b and `SetupConnection` flag bit 0, for
 sv2-spec discussion #239, which supersedes #217). Requires Plan B and Plan C
 (merged as #949 and #951: the shared `Arc<Transaction>` bodies and the
 64-slot same-tip ring that retains validated jobs) and the proposal-check
@@ -615,7 +615,8 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
 ### D2 — Messages and the setup flag
 
 - **Contract:** `messages.rs` carries `ProposeTemplate`,
-  `.MissingTransactions`, `.Success`, `.Error` (0x77–0x7a) as binary_sv2
+  `.MissingTransactions` (the `ProvideMissingTransactions` pair since D12),
+  `.Success`, `.Error` (0x77–0x7a) as binary_sv2
   structs, and `REQUIRES_JOB_VALIDATION`. Setup accepts bit 0 and echoes
   it; any other set bit is still `unsupported-feature-flags`.
 - **Red:** `job_validation_messages_round_trip`;
@@ -680,7 +681,8 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
   resolves → `MissingTransactions{request_id, unknown_tx_position_list}`
   (0-indexed positions in `wtxid_list`); the same job resent with those
   txs in `transaction_list` validates and the supplied txs are retained
-  with it. The TP keeps no state across the round trip.
+  with it. The TP keeps no state across the round trip (reversed in D12:
+  the TP holds the proposal and the txs arrive in their own message).
 - **Red:** `propose_template_asks_for_and_accepts_missing_transactions`
   — one of two spends not in the mempool → `[1]`; resend with it
   supplied → `Success` with the full fee sum and both txs retained. Red
@@ -748,7 +750,7 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
 - **Contract:** `ProposeTemplate` carries what a JDS has from
   `DeclareMiningJob` and nothing it would have to invent: `request_id`,
   `version`, `coinbase_tx_prefix`, `coinbase_tx_suffix`, `wtxid_list`,
-  `excess_data` (opaque here), plus `transaction_list`. No `prev_hash`:
+  `excess_data` (opaque here), plus `transaction_list` (dropped in D12). No `prev_hash`:
   the TP validates on its current tip and `Success` carries that tip as
   `prev_hash` next to `template_id`. The TP builds the
   placeholder coinbase: `E = L − P` from the prefix (version, BIP144
@@ -847,6 +849,53 @@ stratum-mining/sv2-tp PR #137. Ships no flag: a session opts in with
 - **Verify:** `cargo test -p rbitcoin-sv2 --lib`; the journey 10 times in
   a loop.
 
+### D12 — Missing transactions as a request/provide pair
+
+- **Contract:** sv2-spec#239 (Sjors, 2026-10-08; agreed): the missing leg
+  is proper messages reusing JDP 6.4.7 and 6.4.8 under TDP numbers.
+  `ProposeTemplate` carries no `transaction_list`; the TP answers
+  `ProvideMissingTransactions {request_id, unknown_tx_position_list}` (0x78)
+  and the client returns `ProvideMissingTransactions.Success {request_id,
+  transaction_list}` (0x7b). A JDS copies both payloads between the TP and
+  its JDC, changing only the message type. The TP holds a proposal it asked
+  about under its `request_id`: `job::Proposal` (wtxids and the coinbase
+  split, no txs), at most `MAX_PENDING_PROPOSALS` (8) per session with the
+  oldest dropped, for `provide_timeout` (`PROVIDE_TIMEOUT` 30 s, a
+  `Sv2TpConfig` field like `setup_timeout`) checked in the retire arm. A
+  provide for an id the session does not hold, already consumed, or
+  expired is `ProposeTemplate.Error unknown-request-id`; a proposal under
+  an id still queued, in flight, or held is `duplicate-request-id`; a
+  provide that does not cover every requested position, supplies a tx the
+  TP did not ask for, or one that does not decode, is `bad-missing-tx` and
+  ends that exchange (the first two before any decode). These edge rules
+  match sv2-tp #137. A validation still short of a tx asks again for every position
+  the mempool lacks, the supplied ones included, since nothing is held
+  across the round trip but the proposal. The block-sized client frame cap
+  moves to `ProvideMissingTransactions.Success` (~4.2 MB);
+  `ProposeTemplate` is wtxids plus coinbase (~2.3 MB).
+- **Red:** `propose_template_asks_for_and_accepts_missing_transactions`
+  rewritten around the round trip: `unknown-request-id` before, after, and
+  past a 1 s `provide_timeout`; `duplicate-request-id` while held;
+  `bad-missing-tx` for a tx not asked for, a provide short of a requested
+  position (answered `ProvideMissingTransactions` again before), and a
+  blob under the declared wtxid; nine holds dropping the first; only the
+  completed jobs take ids. The D11 journey completes each copy through its
+  provide and refuses a `ProposeTemplate` under the id in flight
+  (`duplicate-request-id`; before, it was validated a second time);
+  `oversized_client_frame_closes_the_session` gains a provide past the
+  `ProposeTemplate` cap that keeps the session. Red was the compile
+  failure against the one-message shape (no table, no 0x7b handler; the
+  old session logged `ignoring message 0x7b`).
+- **Green:** `job::Proposal` (owned decode, `precheck`, `accept_supplied`
+  with the coverage count) and `job::validate(&Proposal, &Supplied)`;
+  `Session.pending` as a `VecDeque<Pending>` with `hold` and expiry folded
+  into the retire timer, `Session.open` for the ids queued or in flight;
+  `Work { proposal, supplied }` through the FIFO and the `JoinSet`; the two
+  payload caps in `transport.rs`.
+- **RAM trade:** ≤ 8 × ~2.2 MiB held per session, no transactions; one
+  in-flight client frame ≤ ~4.2 MB, ≤ ~34 MB at `MAX_SESSIONS`.
+- **Verify:** `cargo test -p rbitcoin-sv2 --lib`.
+
 ### Test budget
 
 Units: the messages round trip, `job::extranonce_len`, `rbitcoin-net`
@@ -886,10 +935,17 @@ validations of 400 supplied spends). No `rbitcoin-test` node journey yet
   min-difficulty networks that can differ from the sent
   `SetNewPrevHash.n_bits` (the Plan B risk); mainnet and signet bits
   depend only on the prev hash.
-- `transaction_list` matching hashes the bytes as sent: a legacy tx
-  relayed in segwit-marker form hashes differently from its wtxid and is
-  `bad-missing-tx`. The draft requires the bytes exactly as JDC sent
-  them, which is the serialization the wtxid was computed over.
+- `ProvideMissingTransactions.Success` matching hashes the bytes as sent:
+  a legacy tx relayed in segwit-marker form hashes differently from its
+  wtxid and is `bad-missing-tx`. The draft requires the bytes exactly as
+  JDC sent them, which is the serialization the wtxid was computed over.
+- A held proposal dropped by the bound (D12) or the timeout surfaces only
+  as `unknown-request-id` on its provide; the JDS proposes again. A JDS
+  with more than eight JDCs short of transactions at one tip change loses
+  the oldest round trips to that bound; raise `MAX_PENDING_PROPOSALS` if a
+  pool reports it (each hold is wtxids and a coinbase, not a block).
+- The message numbers 0x78 and 0x7b for the provide pair are this draft's
+  proposal; #239 has assigned none yet.
 - The IBD gate (`job-validation-unavailable`) and `bad-cb-decode` are
   this TP's choices within the draft's "recommended" list and should
   follow the upstream text once it settles.