BIP drafts: SwiftSync Specification #2152

   0 | @@ -0,0 +1,86 @@
   1 | +```
   2 | +  BIP: ?
   3 | +  Layer: Applications
   4 | +  Title: SwiftSync initial block download
   5 | +  Authors: Robert Netzke <bips@2140.dev>, Ruben Somsen <bips@2140.dev>
   6 | +  Status: Draft
   7 | +  Type: Specification
   8 | +  Assigned: ?
   9 | +  License: BSD-3-Clause

murchandamus commented at 12:36 PM on May 6, 2026:

Could you please add links to the relevant discussions on the mailing list and Delving on this document and the others?

  License: BSD-3-Clause
  Discussion: https://groups.google.com/g/bitcoindev/c/FpSWUxItXQs/m/pnfjP6rFCgAJ

   7 | +  Type: Specification
   8 | +  Assigned: ?
   9 | +  License: BSD-3-Clause
  10 | +  Requires: BIP ?, BIP ?
  11 | +```
  12 | +# Abstract

murchandamus commented at 12:37 PM on May 6, 2026:

IIRC, Markdown only allows a single first-level header per document, so you probably want to bump all of the headers up one level.

## Abstract

  11 | +```
  12 | +
  13 | +# Abstract
  14 | +
  15 | +Inputs of a Bitcoin block are referenced by the outpoint data structure. This poses a limitation during initial block download (IBD), such that a client must process blocks sequentially to validate the chain history. The SwiftSync protocol allows blocks to be evaluated in arbitrary order, however additional data is required that must be served over the peer-to-peer network. Namely, the creation height, coinbase flag, input script, and amount for each spent coin must be accessible to fully validate a block in a state-less manner. This data cannot be trusted by a peer under usual conditions, however SwiftSync allows a client performing IBD to validate the correctness of this data.
  16 | +# Motivation

danielabrozzoni commented at 12:50 PM on May 6, 2026:

The motivation is a bit repetitive with what's in the abstract, and there are a lot of technical details. I would reshape this a little in order to give a stronger motivation ("IBD is slow because it must be done sequentially, SwiftSync speeds this up by removing this limitation")

jurraca commented at 12:57 PM on May 8, 2026:

The Abstract and Motivation repeat similar ideas. imo the Abstract part should focus more on what this proposal provides, instead of the reasoning and context that led to it. Could also merge them into one section if you want.

  10 | +  License: BSD-3-Clause
  11 | +```
  12 | +
  13 | +# Abstract
  14 | +
  15 | +Inputs of a Bitcoin block are referenced by the outpoint data structure. This poses a limitation during initial block download (IBD), such that a client must process blocks sequentially to validate the chain history. The SwiftSync protocol allows blocks to be evaluated in arbitrary order, however additional data is required that must be served over the peer-to-peer network. Namely, the creation height, coinbase flag, input script, and amount for each spent coin must be accessible to fully validate a block in a state-less manner. This data cannot be trusted by a peer under usual conditions, however SwiftSync allows a client performing IBD to validate the correctness of this data.

danielabrozzoni commented at 12:56 PM on May 6, 2026:

While reading the spec we notice that the bip is about sharing undo data, but that was not clear from the abstract.

I would add a sentence along the lines of "This document describes how to share [this additional data] over the peer to peer network"

jurraca commented at 2:25 PM on May 7, 2026:

however additional data is required that must be served over the peer-to-peer network

I would combine this and the next sentence so it's clear what the data is required for at the end of this sentence, e.g. "... in order to validate the blocks, namely the creation height, coinbase flag...".

This data cannot be trusted by a peer under usual conditions

"under usual conditions" doesn't provide much value here, imo it's either trusted or validated, in this case it can't be trusted when served by a peer.

  33 | +
  34 | +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
  35 | +## Data structures
  36 | +#### Height Code
  37 | +
  38 | +The height and coinbase flag are encoded as a 32 bit integer. To encode the height and flag, binary left shift the height one bit, treat the boolean as a bit, insert it into the newly opened bit position. To decode the height, binary right shift the code. To decode the coinbase flag, mask the first bit position of the header code and interpret the bit as a boolean.

danielabrozzoni commented at 1:00 PM on May 6, 2026:

"To encode the height and flag, binary left shift the height one bit, treat the boolean as a bit, insert it into the newly opened bit position."

I would be slightly more explicit and say "the coinbase flag" instead of "the boolean"

  89 | +| :---------- | :-------------------------------- | -------------------------------------------------------------- |
  90 | +| `blockhash` | 32 byte vector                    | Block hash these coins are spent from                          |
  91 | +| `len`       | `CompactSize(Len(vector<Coins>))` | The length of the coins vector                                 |
  92 | +| `coins`     | `vector<Coin>`                    | Coins that were spent, after filtering on the request `cutoff` |
  93 | +
  94 | +A client supporting the `bspent` MUST include coins created _before_ the `cutoff` field in `getbspent` requests. A client receiving a `bspent` message with un-requested or missing coins MUST disconnect from the serving peer. A client supporting `bspent` MUST adhere to the format of `Coin` specified in the `verion` of the request.

danielabrozzoni commented at 1:16 PM on May 6, 2026:

typo: verion -> version

  25 | +This section defines how to request and serve block spent coins over the peer-to-peer protocol, as well as signaling support of this feature to peers.
  26 | +## Definitions
  27 | +
  28 | +- `[]byte`: arbitrary byte vector
  29 | +- `<N bytes>`: size `N` byte vector
  30 | +- `vector<Foo>`: arbitrary sized vector of `Foo`

danielabrozzoni commented at 9:12 AM on May 7, 2026:

nit: I was a bit confused at first, I would reshape this a little to make it clearer:

• []byte: arbitrary sequence of bytes with no fixed length
• <N bytes>: byte vector of size N, where N is specified inline (e.g. <32 bytes>)
• vector<Foo>: vector of arbitrary length of elements of type Foo

  27 | +
  28 | +- `[]byte`: arbitrary byte vector
  29 | +- `<N bytes>`: size `N` byte vector
  30 | +- `vector<Foo>`: arbitrary sized vector of `Foo`
  31 | +- `CompactSize`: encoding of unsigned integers defined in peer-to-peer messages
  32 | +- `CompressAmount`: defined in the Function Appendix section

danielabrozzoni commented at 9:15 AM on May 7, 2026:

nit: I would be a bit more explicit here:

• CompressAmount: compression function for integer amounts, as defined in the Function Appendix section

  51 | +| `0x05` | `P2SH`   | `<20 bytes>`                          | `OP_HASH160 20 <20 bytes> OP_EQUAL`                          |
  52 | +| `0x06` | `P2WSH`  | `<32 bytes>`                          | `OP_0 32 <32 bytes>`                                         |
  53 | +| `0x07` | `P2WPKH` | `<20 bytes>`                          | `OP_0 20 <20 bytes>`                                         |
  54 | +| `0x08` | `P2TR`   | `<32 byte X-only public key>`         | `OP_1 32 <32 bytes>`                                         |
  55 | +
  56 | +Scripts are serialized in this format by concatenating the `Prefix` and `Format` fields.

danielabrozzoni commented at 9:18 AM on May 7, 2026:

I would move this above the table, I kept wondering how to encode until I read this :)

  60 | +#### Coin
  61 | +
  62 | +| Field                    | Type                          | Serialization | Description                                                                                                       |
  63 | +| :----------------------- | :---------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
  64 | +| Input index              | 32 bit unsigned integer       | Little endian | The index in the block inputs for which this coin corresponds. The coinbase inputs are _excluded_ from this index |
  65 | +| Height and coinbase flag | Height code                   | Little endian |                                                                                                                   |

danielabrozzoni commented at 9:20 AM on May 7, 2026:

I think this should have "Defined above" in "Serialization"

  16 | +# Motivation
  17 | +
  18 | +A current limitation of IBD is that it must be done sequentially. This is a result of the height, coinbase flag, input script, and amount of the block inputs being omitted from the data committed to by proof of work in the current block, and, thus, this data cannot be trusted if received over the wire naively. Using the SwiftSync protocol, a client is able to verify the correctness of this data, even if served by a potentially untrusted party. This is a property of the SwiftSync hash aggregate, which commits to the height, coinbase flag, script, and amount when creating and deleting coins.
  19 | +# Specification
  20 | +
  21 | +In Bitcoin Core, to roll-back the chain state in the event of a block reorganization, the height, coinbase flag, script and amount metadata for each input of a block are stored in a data structure known colloquially as "undo data". This terminology stems from its use to "undo" the effect of a block by repopulating the UTXO set with the coins that were spent by the reorganized block. To remain general in language, this data will be referred as "spent coins."

danielabrozzoni commented at 2:21 PM on May 7, 2026:

nit: it took me a while to figure out that the coinbase flag is needed in order to check that a transaction is not spending an immature coinbase... It would be nice to have this specified somewhere to avoid confusion, but I'm not sure if it really fits here, so, as you wish

  18 | +A current limitation of IBD is that it must be done sequentially. This is a result of the height, coinbase flag, input script, and amount of the block inputs being omitted from the data committed to by proof of work in the current block, and, thus, this data cannot be trusted if received over the wire naively. Using the SwiftSync protocol, a client is able to verify the correctness of this data, even if served by a potentially untrusted party. This is a property of the SwiftSync hash aggregate, which commits to the height, coinbase flag, script, and amount when creating and deleting coins.
  19 | +# Specification
  20 | +
  21 | +In Bitcoin Core, to roll-back the chain state in the event of a block reorganization, the height, coinbase flag, script and amount metadata for each input of a block are stored in a data structure known colloquially as "undo data". This terminology stems from its use to "undo" the effect of a block by repopulating the UTXO set with the coins that were spent by the reorganized block. To remain general in language, this data will be referred as "spent coins."
  22 | +
  23 | +Bitcoin Core full archival nodes store spent coins for all blocks. This is useful in the context of SwiftSync, as no additional index must be created or maintained to serve this data to peers. There are, however, some discrepancies between how this data is serialized on disk in Bitcoin core and how this proposal seeks to serialize this data over the peer-to-peer protocol, which are detailed in the rationale section.

jurraca commented at 12:59 PM on May 8, 2026:

Bitcoin core / Core