Skip to content

Commit 440e585

Browse files
romanzromanz
committed
Update documentation for the upcoming release
1 parent 9175b0f commit 440e585

6 files changed

Lines changed: 60 additions & 117 deletions

File tree

‎doc/config.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,10 @@ If you use automated systems, refer to their documentation first!
55

66
### Bitcoind configuration
77

8-
Pruning must be turned **off** for `electrs` to work.
8+
REST API must be **enabled** for block indexing and transaction lookup.
9+
Pruning must be **disabled** for `electrs` to work.
910
`txindex` is allowed but unnecessary for `electrs`.
1011
However, you might still need it if you run other services (e.g.`eclair`).
11-
The option `maxconnections` (if used) should be set to 12 or more for bitcoind to accept inbound p2p connections.
12-
Note that setting `maxuploadtarget` may cause p2p-based sync to fail - so consider using `-whitelist=download@127.0.0.1` to disable the limit for local p2p connections.
1312

1413
The highly recommended way of authenticating `electrs` is using cookie file.
1514
It's the most [secure](https://github.com/Kixunil/security_writings/blob/master/cookie_files.md) and robust method.
@@ -21,7 +20,7 @@ You can skip it if you're running both daemons under the same user and with the
2120
Example command for running `bitcoind` (assuming same user, default dirs):
2221

2322
```bash
24-
$ bitcoind -server=1 -txindex=0 -prune=0
23+
$ bitcoind -server=1 -rest=1 -txindex=0 -prune=0
2524
```
2625
### Electrs configuration
2726

‎doc/install.md‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,14 @@
11
## Quickstart
22

3-
<details>
4-
<summary>Building from source on an Ubuntu 25.04 / Debian 13:</summary>
3+
Building from source on an Ubuntu 25.04 / Debian 13:
54

65
```bash
76
$ sudo apt update
87
$ sudo apt install -y build-essential libclang-dev git cargo
9-
$ git clone https://github.com/romanz/electrs
10-
$ cd electrs
11-
$ cargo build --locked --release
12-
$ ./target/release/electrs --version # should print the latest version
8+
$ git clone https://github.com/romanz/electrs && cd electrs
9+
$ cargo run --locked --release -- --version # build and print the latest version
1310
```
1411

15-
</details>
16-
17-
[![asciicast](https://asciinema.org/a/XKznxilP4O7lCZiVZ9vZNd5vx.svg)](https://asciinema.org/a/XKznxilP4O7lCZiVZ9vZNd5vx?speed=3)
18-
1912
## Manual installation from source
2013

2114
**See below for automated/binary installation options.**

‎doc/schema.md‎

Lines changed: 1 addition & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1 @@
1-
# Index Schema
2-
3-
The index is stored at a single RocksDB database using the following column families.
4-
Most of the data is stored in key-only DB rows (i.e. having empty values).
5-
6-
## Transaction outputs' index (`funding`)
7-
8-
Allows efficiently finding all funding transactions for a specific address:
9-
10-
| Script Hash Prefix | Confirmed Block Height |
11-
| -------------------- | ---------------------- |
12-
| `SHA256(script)[:8]` | `height as u32` |
13-
14-
## Transaction inputs' index (`spending`)
15-
16-
Allows efficiently finding spending transaction of a specific output:
17-
18-
| Previous Outpoint Prefix | Confirmed Block Height |
19-
| ------------------------ | ---------------------- |
20-
| `txid[:8] as u64 + vout` | `height as u32` |
21-
22-
23-
## Transaction ID index (`txid`)
24-
25-
In order to save storage space, we map the 8-byte transaction ID prefix to its confirmed block height:
26-
27-
| Txid Prefix | Confirmed height |
28-
| ----------- | ---------------- |
29-
| `txid[:8]` | `height as u32` |
30-
31-
Note that this mapping allows us to use `getrawtransaction` RPC to retrieve actual transaction data from without `-txindex` enabled
32-
(by explicitly specifying the [blockhash](https://github.com/bitcoin/bitcoin/commit/497d0e014cc79d46531d570e74e4aeae72db602d)).
33-
34-
## Headers (`headers`)
35-
36-
For faster loading, we store all block headers in RocksDB:
37-
38-
| Serialized header |
39-
| ----------------------- |
40-
| `header as BlockHeader` |
41-
42-
In addition, we also store the chain tip:
43-
44-
| Key | | Value |
45-
| --- | - | ------------------------ |
46-
| `T` | | `blockhash as BlockHash` |
47-
48-
## Configuration (`config`)
49-
50-
| Key | | Value |
51-
| --- | - | --------------------------- |
52-
| `C` | | `serialized config as JSON` |
53-
1+
See https://github.com/romanz/bindex-rs for more details.

‎doc/upgrading.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,20 @@
1+
### Important changes from versions older than 0.12.0
2+
3+
In 0.12.0 we have changed the RocksDB index format to optimize electrs performance.
4+
5+
We also use new bitcoind REST API endpoints (instead of P2P protocol)
6+
7+
* [#32540 (index: fetch spent transaction outputs by blockhash)](https://github.com/bitcoin/bitcoin/pull/32540) → released in 30.0
8+
* [#33657 (rest: allow reading partial block data from storage)](https://github.com/bitcoin/bitcoin/pull/33657) → released in 31.0
9+
10+
Upgrading checklist:
11+
12+
* Make sure you upgrade at a time when you don't need to use electrs for a while.
13+
Because of reindex electrs will be unable to serve your requests for a few hours.
14+
(The exact time depends on your hardware.)
15+
* Make sure you have at least 120 GB of free space (for reindexing mainnet chain).
16+
17+
118
### Important changes from versions older than 0.9.3
219

320
* If you use `verbose` (or `-v` argument), switch to `log_filters` (or `RUST_LOG` environment variable).

‎doc/usage.md‎

Lines changed: 35 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,56 @@
11
## Quickstart
22

3-
<details>
4-
<summary>Assuming Bitcoin Core 0.21+ is installed on the same machine (with the standard configuration at `~/.bitcoin/bitcoin.conf`):</summary>
3+
Assuming Bitcoin Core 31+ is installed on the same machine (with the standard configuration at `~/.bitcoin/bitcoin.conf`):
54

65
```bash
7-
$ bitcoind -server=1 -prune=0 &
6+
$ bitcoind -server=1 -rest=1 -prune=0 &
87
$ # ... wait until the chain is synced (e.g. using `bitcoin-cli getblockchaininfo`)
9-
$ electrs --log-filters=INFO --db-dir ./db --daemon-dir ~/.bitcoin --network bitcoin
8+
$ RUST_LOG=INFO electrs --network bitcoin --db-dir ./db --daemon-dir ~/.bitcoin
109
```
1110

12-
</details>
13-
14-
[![asciicast](https://asciinema.org/a/zRNZp5HsBDi5rAlGWU7470Pzl.svg)](https://asciinema.org/a/zRNZp5HsBDi5rAlGWU7470Pzl?speed=3)
15-
1611
## Usage
1712

18-
First index sync should take ~6.5 hours for ~504GB @ August 2023 (on a dual core Intel CPU @ 3.3 GHz, 8 GB RAM, 1TB WD Blue HDD):
13+
First index sync should take ~2 hours for ~800GB `.bitcoin/blocks/` @ July 2026 (on a 6-core CPU, 32 GB RAM, 2TB NVMe):
1914
```bash
20-
$ du -ch ~/.bitcoin/blocks/blk*.dat | tail -n1
21-
336G total
22-
23-
$ ./target/release/electrs --network bitcoin --db-dir ./db --daemon-dir /home/user/.bitcoin
24-
Starting electrs 0.10.0 on x86_64 linux with Config { network: Bitcoin, db_path: "./db/bitcoin", daemon_dir: "/home/user/.bitcoin", daemon_auth: CookieFile("/home/user/.bitcoin/.cookie"), daemon_rpc_addr: 127.0.0.1:8332, electrum_rpc_addr: 127.0.0.1:50001, monitoring_addr: 127.0.0.1:4224, wait_duration: 10s, jsonrpc_timeout: 15s, index_lookup_limit: None, reindex_last_blocks: 0, auto_reindex: true, ignore_mempool: false, sync_once: false, skip_block_download_wait: false, disable_electrum_rpc: false, server_banner: "Welcome to electrs 0.10.0 (Electrum Rust Server)!", magic: f9beb4d9, args: [] }
25-
[2023-08-16T19:17:11.193Z INFO electrs::metrics::metrics_impl] serving Prometheus metrics on 127.0.0.1:4224
26-
[2023-08-16T19:17:11.193Z INFO electrs::server] serving Electrum RPC on 127.0.0.1:50001
27-
[2023-08-16T19:17:12.355Z INFO electrs::db] "./db/bitcoin": 0 SST files, 0 GB, 0 Grows
28-
[2023-08-16T19:17:12.446Z INFO electrs::index] indexing 2000 blocks: [1..2000]
29-
[2023-08-16T19:17:12.866Z INFO electrs::chain] chain updated: tip=00000000dfd5d65c9d8561b4b8f60a63018fe3933ecb131fb37f905f87da951a, height=2000
30-
[2023-08-16T19:17:12.879Z INFO electrs::index] indexing 2000 blocks: [2001..4000]
31-
[2023-08-16T19:17:13.227Z INFO electrs::chain] chain updated: tip=00000000922e2aa9e84a474350a3555f49f06061fd49df50a9352f156692a842, height=4000
32-
[2023-08-16T19:17:13.238Z INFO electrs::index] indexing 2000 blocks: [4001..6000]
33-
[2023-08-16T19:17:13.587Z INFO electrs::chain] chain updated: tip=00000000dbbb79792303bdd1c6c4d7ab9c21bba0667213c2eca955e11230c5a5, height=6000
34-
[2023-08-16T19:17:13.598Z INFO electrs::index] indexing 2000 blocks: [6001..8000]
35-
[2023-08-16T19:17:13.950Z INFO electrs::chain] chain updated: tip=0000000094fbacdffec05aea9847000522a258c269ae37a74a818afb96fc27d9, height=8000
36-
[2023-08-16T19:17:13.961Z INFO electrs::index] indexing 2000 blocks: [8001..10000]
37-
<...>
38-
[2023-08-17T00:13:16.443Z INFO electrs::index] indexing 2000 blocks: [798001..800000]
39-
[2023-08-17T00:14:58.310Z INFO electrs::chain] chain updated: tip=00000000000000000002a7c4c1e48d76c5a37902165a270156b7a8d72728a054, height=800000
40-
[2023-08-17T00:14:58.325Z INFO electrs::index] indexing 2000 blocks: [800001..802000]
41-
[2023-08-17T00:16:36.425Z INFO electrs::chain] chain updated: tip=0000000000000000000311b41f1d611f977b024b947568c1dd760704360f148a, height=802000
42-
[2023-08-17T00:16:36.437Z INFO electrs::index] indexing 1534 blocks: [802001..803534]
43-
[2023-08-17T00:17:51.338Z INFO electrs::chain] chain updated: tip=00000000000000000003c0cd1b62ed8bb502e24bcbfeee16e81d6ea33d026263, height=803534
44-
[2023-08-17T00:18:00.592Z INFO electrs::db] starting config compaction
45-
[2023-08-17T00:18:00.778Z INFO electrs::db] starting headers compaction
46-
[2023-08-17T00:18:00.870Z INFO electrs::db] starting txid compaction
47-
[2023-08-17T00:33:34.370Z INFO electrs::db] starting funding compaction
48-
[2023-08-17T01:03:56.784Z INFO electrs::db] starting spending compaction
49-
[2023-08-17T01:35:05.983Z INFO electrs::db] finished full compaction
50-
[2023-08-17T01:36:23.300Z INFO electrs::index] indexing 5 blocks: [803535..803539]
51-
[2023-08-17T01:36:23.646Z INFO electrs::chain] chain updated: tip=000000000000000000006a3aaddd4b643607b33e000f1200d35005c330ecfa88, height=803539
52-
[2023-08-17T01:41:26.009Z INFO electrs::index] indexing 1 blocks: [803540..803540]
53-
[2023-08-17T01:41:26.143Z INFO electrs::chain] chain updated: tip=00000000000000000003266d31db92629b64241eef7ce708244f6d6283b080b4, height=803540
54-
[2023-08-17T01:42:42.999Z INFO electrs::index] indexing 1 blocks: [803541..803541]
55-
[2023-08-17T01:42:43.153Z INFO electrs::chain] chain updated: tip=00000000000000000000884a77c8b8ad2fb0c25510a3251bf5ef57f0db275146, height=803541
15+
$ du -ch ~/.bitcoin/blocks/*.dat | tail -n1
16+
802G total
17+
18+
$ RUST_LOG=INFO electrs --network bitcoin --db-dir ./db --daemon-dir ~/.bitcoin
19+
Starting electrs 0.12.0 on x86_64 linux with Config { network: Bitcoin, db_dir: "./db", ... }
20+
[2026-07-18T16:37:24.024Z INFO electrs::metrics::metrics_impl] serving Prometheus metrics on 127.0.0.1:4224
21+
[2026-07-18T16:37:24.025Z INFO electrs::server] serving Electrum RPC on 127.0.0.1:50001
22+
[2026-07-18T16:37:24.025Z INFO bindex::chain] index: Config { db_path: "./db/bitcoin", url: "http://127.0.0.1:8332" }
23+
[2026-07-18T16:37:24.054Z INFO bindex::db] CF config: 0 files, 0.000000 MBs
24+
[2026-07-18T16:37:24.054Z INFO bindex::db] CF headers: 0 files, 0.000000 MBs
25+
[2026-07-18T16:37:24.054Z INFO bindex::db] CF txpos: 0 files, 0.000000 MBs
26+
[2026-07-18T16:37:24.054Z INFO bindex::db] CF txid: 0 files, 0.000000 MBs
27+
[2026-07-18T16:37:24.054Z INFO bindex::db] CF script_hash: 0 files, 0.000000 MBs
28+
[2026-07-18T16:37:24.054Z INFO bindex::db] CF spending: 0 files, 0.000000 MBs
29+
[2026-07-18T16:37:24.054Z INFO bindex::db] CF funding: 0 files, 0.000000 MBs
30+
[2026-07-18T16:37:24.129Z INFO bindex::chain] block=00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09 height=1000: indexed 1001 blocks, 0.226[MB], dt = 0.047[s]: 0.047 [ms/block], 0.000 [MB/block], 4.837 [MB/s]
31+
[2026-07-18T16:37:24.196Z INFO bindex::chain] block=00000000dfd5d65c9d8561b4b8f60a63018fe3933ecb131fb37f905f87da951a height=2000: indexed 1000 blocks, 0.234[MB], dt = 0.043[s]: 0.043 [ms/block], 0.000 [MB/block], 5.376 [MB/s]
32+
[2026-07-18T16:37:24.263Z INFO bindex::chain] block=000000004a81b9aa469b11649996ecb0a452c16d1181e72f9f980850a1c5ecce height=3000: indexed 1000 blocks, 0.230[MB], dt = 0.043[s]: 0.043 [ms/block], 0.000 [MB/block], 5.298 [MB/s]
33+
[2026-07-18T16:37:24.331Z INFO bindex::chain] block=00000000922e2aa9e84a474350a3555f49f06061fd49df50a9352f156692a842 height=4000: indexed 1000 blocks, 0.234[MB], dt = 0.044[s]: 0.044 [ms/block], 0.000 [MB/block], 5.366 [MB/s]
34+
[2026-07-18T16:37:24.398Z INFO bindex::chain] block=000000004d78d2a8a93a1d20a24d721268690bebd2b51f7e80657d57e226eef9 height=5000: indexed 1000 blocks, 0.229[MB], dt = 0.043[s]: 0.043 [ms/block], 0.000 [MB/block], 5.349 [MB/s]
35+
...
36+
[2026-07-18T18:02:21.114Z INFO bindex::chain] block=0000000000000000000055222909c19ed96cd371013861337214a3c39a63d828 height=955000: indexed 1000 blocks, 1842.985[MB], dt = 9.457[s]: 9.457 [ms/block], 1.843 [MB/block], 194.886 [MB/s]
37+
[2026-07-18T18:02:33.592Z INFO bindex::chain] block=000000000000000000012d9ea47c8b3282ae1a7792d54b8b4bcc0536c1883191 height=956000: indexed 1000 blocks, 1846.173[MB], dt = 9.522[s]: 9.522 [ms/block], 1.846 [MB/block], 193.879 [MB/s]
38+
[2026-07-18T18:02:45.872Z INFO bindex::chain] block=00000000000000000000e898fc9d01b0729d8830f2068248debbff575a3b0990 height=957000: indexed 1000 blocks, 1855.303[MB], dt = 9.295[s]: 9.295 [ms/block], 1.855 [MB/block], 199.600 [MB/s]
39+
[2026-07-18T18:02:58.221Z INFO bindex::chain] block=000000000000000000022c6a6d538a4372b0eeadb4ea9eb2edd4e32ec780084b height=958000: indexed 1000 blocks, 1844.747[MB], dt = 9.376[s]: 9.376 [ms/block], 1.845 [MB/block], 196.759 [MB/s]
40+
[2026-07-18T18:03:05.539Z INFO bindex::chain] block=000000000000000000020934afa0945d959250e9a4598d39c53fa280639b096a height=958594: indexed 594 blocks, 1115.055[MB], dt = 5.357[s]: 9.018 [ms/block], 1.877 [MB/block], 208.155 [MB/s]
41+
[2026-07-18T18:03:05.666Z INFO bindex::db] started auto compactions
5642
```
5743
You can specify options via command-line parameters, environment variables or using config files.
5844
See the documentation above.
5945
60-
Note that the final DB size should be ~10% of the `blk*.dat` files, but it may increase to ~20% at the end of the initial sync (just before the [full compaction is invoked](https://github.com/facebook/rocksdb/wiki/Manual-Compaction)).
46+
Note that the final DB size should be ~7% of the `blocks/*.dat` files, but it may increase to ~14% at the end of the initial sync (just before the [full compaction is invoked](https://github.com/facebook/rocksdb/wiki/Manual-Compaction)).
6147
6248
It should take roughly 18 hours to sync and compact the index on an ODROID-HC1 with 8 CPU cores @ 2GHz, 2GB RAM, and an SSD using the command above.
6349
6450
The index database is stored here:
6551
```bash
66-
$ du db/
67-
42G db/mainnet/
52+
$ du -h db/bitcoin/
53+
56G db/bitcoin/
6854
```
6955
7056
See [extra configuration suggestions](config.md#extra-configuration-suggestions) that you might want to consider.
@@ -98,7 +84,7 @@ You can invoke any supported RPC using `netcat`, for example:
9884
9985
```
10086
$ echo '{"jsonrpc": "2.0", "method": "server.version", "params": ["", "1.4"], "id": 0}' | netcat 127.0.0.1 50001
101-
{"id":0,"jsonrpc":"2.0","result":["electrs 0.9.0","1.4"]}
87+
{"id":0,"jsonrpc":"2.0","result":["electrs 0.12.0","1.4"]}
10288
```
10389
10490
For more complex tasks, you may need to convert addresses to

‎server.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ cargo build --all --features "metrics_process" --release
88
NETWORK=$1
99
shift
1010

11-
DB=${DB-./_db}
11+
DB=${DB-./db}
1212
export RUST_LOG=${RUST_LOG-INFO}
1313
target/release/electrs --network $NETWORK --db-dir $DB --daemon-dir $HOME/.bitcoin $*
1414

0 commit comments

Comments
 (0)