Block Delivery Network
block-dn is a simple web server that connects to your
existing Bitcoin full node to serve data from the time chain to fetch
over HTTP(S).
The goal is to serve the following data to Light Clients (e.g. mobile
wallets):
- Block headers
- Blocks
- Compact Filter headers
- Compact Filters
- Raw Transactions
- Block Transaction Inclusion Proofs (TxOutProofs)
- Silent Payments Block Tweak Data
There are two ways to use block-dn:
Connect to your own node
Install and run block-dn on your own device and configure
that HTTP endpoint in your compatible wallet. Your own node's chain
information is then used to sync the wallet state.
Use the Cloud Flare CDN cached instance
If you have a way to find out the current most recent block hash from
your peers or your own node, the rest of the chain data (e.g. block
headers, blocks, compact filters) can be downloaded from an untrusted
source. Such an untrusted source can be found at
block-dn.org. Both these
sites run an instance of block-dn and are behind Cloud
Flare's caching proxy service, effectively caching the data in
geographically distributed sites around the world for maximum access
speed and very low latency.
Available REST endpoints
| Endpoint | Description | Example |
|---|---|---|
/status |
Returns a JSON file with the latest block height and hash. | block-dn.org/status |
/block/<block_hash> |
Returns a single block, identified by its block hash. | block-dn.org/block/000000000000000000030ee5.... |
/headers/<start_block> |
Returns a binary file containing 100'000 block headers, serialized as 80 bytes per header (8 MB per file). | block-dn.org/headers/0 |
/headers/import/<end_block> |
Returns a binary file containing end_block
block headers, for import directly into a Neutrino database.
The file starts with the 10 byte metadata header (4 bytes
Bitcoin network identifier, 1 byte import format version,
1 byte header type, 4 byte start header height), followed by
the headers serialized as 80 bytes per header.end_block is non-inclusive (heights
0..end_block-1 are returned), so the maximum
useful value is the server's current tip height plus one.
When the requested range is fully covered by sealed files
on disk, end_block must additionally be
divisible by 100'000; otherwise the response is served
partly from memory and any value ≤ tip+1 is accepted.
|
block-dn.org/headers/import/200000 |
/headers/import/latest |
Convenience shortcut for clients that want every header
the server currently has without first looking up the tip
height. Behaves exactly like
/headers/import/<tip+1> — same binary
format, same 10 byte metadata prefix — but the end height
is resolved by the server. The response is always
short-cached (memory tier) because the tip is mutable.
|
block-dn.org/headers/import/latest |
/filter-headers/<start_block> |
Returns a binary file containing 100'000 compact filter headers, serialized as 32 bytes per filter header hash (3.2 MB per file). | block-dn.org/filter-headers/100000 |
/filter-headers/import/<end_block> |
Returns a binary file containing end_block
compact filter headers, for import directly into a Neutrino
database. The file starts with the 10 byte metadata header
(4 bytes Bitcoin network identifier, 1 byte import format
version, 1 byte header type, 4 byte start header height),
followed by the filter header hashes serialized as 32 bytes
per header hash.The same end_block rules as
/headers/import apply: non-inclusive, capped
at tip+1, and required to be divisible by 100'000 only
when the requested range is fully covered by sealed files
on disk.
|
block-dn.org/filter-headers/import/200000 |
/filter-headers/import/latest |
Convenience shortcut for clients that want every filter
header the server currently has without first looking up
the tip height. Behaves exactly like
/filter-headers/import/<tip+1> — same
binary format, same 10 byte metadata prefix — but the end
height is resolved by the server. The response is always
short-cached (memory tier) because the tip is mutable.
|
block-dn.org/filter-headers/import/latest |
/filters/<start_block> |
Returns a binary file containing 2'000 compact filters,
serialized as variable length byte arrays:
Each filter starting with a VarInt specifying
the length of a filter, followed by that many bytes for the
actual filter (up to 58 MiB per file as per block 817'995).
|
block-dn.org/filters/802000 |
/sp/tweak-data/<start_block> |
Returns a JSON file containing Silent Payment tweak data
entries for transactions of 2'000 blocks, using the
following format:
{
"start_height": <start_block>,
"num_blocks": 2000,
"blocks": [
{
"<tx_index 1>": "02a1633f5b1c4e8...",
"<tx_index x>": "03cdefa84923dc8..."
},
{
...
}
]
}
|
block-dn.org/sp/tweak-data/802000 |
/block/<hash> |
Returns the block with the given hash in its raw binary format or an error if the block cannot be found. | block-dn.org/block/00000000000000000001976b2202ff92bee756134a875e8fa73703f4047ac9fa |
/block/<hash>/spenttxouts?[format=json|hex|bin] |
Returns the previous outputs of all transactions that were
spent in the block with the given hash. The default response
format is JSON but the format can be changed to binary or
hex by adding a query parameter (e.g.
?format=bin or ?format=hex).
|
block-dn.org/block/00000000000000000001976b2202ff92bee756134a875e8fa73703f4047ac9fa/spenttxouts?format=json |
/tx/out-proof/<txid> |
Returns a binary merkle proof for the given transaction that proves it was included in the block. Returns an error if the transaction cannot be found or is not included in a block yet. | block-dn.org/tx/out-proof/8f900c6414c5c27231080f46168105e9fec20f9fb2f11b25ee0312d89bc022c0 |
/tx/raw/<txid> |
Returns a binary response with the encoded transaction or an error if the transaction cannot be found. | block-dn.org/tx/raw/8f900c6414c5c27231080f46168105e9fec20f9fb2f11b25ee0312d89bc022c0 |
/utxo/<hash>-<vout>/?[mempool=true][&format=json|hex|bin] |
Returns the previous outputs of all transactions that were
spent in the block with the given hash. The default response
format is JSON but the format can be changed to binary or
hex by adding a query parameter (e.g.
?format=bin or ?format=hex).
|
block-dn.org/utxo/0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098-0/?mempool=true&format=json |
/fees/estimate/<blocks> |
Returns a JSON response with an estimated fee rate for the given number of blocks until confirmation. The fee rate is given as sat/kvByte, sat/kWU and sat/vByte. | block-dn.org/fees/estimate/6 |
Test instances
There are instances of all Bitcoin test networks available for testing as well:
-
Testnet3:
testnet3.block-dn.org/status -
Testnet4:
testnet4.block-dn.org/status -
Signet:
signet.block-dn.org/status
Source code on GitHub
Check out the source code and installation instructions for this project at github.com/guggero/block-dn.