bitcoin-manual.rst (15672B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2025 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Antoine d'Aligny 17 18 19 Bitcoin Depolymerizer Setup Manual 20 ################################## 21 22 depolymerizer-bitcoin is a bitcoin blockchain Taler adapter. 23 24 This manual targets system administrators who want to install and 25 operate a Bitcoin GNU Taler Depolymerizer 26 27 In this manual, we explain how to setup a depolymerizer. 28 29 Installation of the Bitcoin Depolymerizer 30 ========================================= 31 32 Installing on Debian 33 -------------------- 34 35 .. include:: ../frags/installing-debian.rst 36 37 To install the depolymerizer, you can now simply run: 38 39 .. code-block:: shell-session 40 41 # apt install depolymerizer-bitcoin 42 43 Installing on Ubuntu 44 -------------------- 45 46 .. include:: ../frags/installing-ubuntu.rst 47 48 To install the depolymerizer, you can now simply run: 49 50 .. code-block:: shell-session 51 52 # apt install depolymerizer-bitcoin 53 54 Building from source 55 -------------------- 56 57 Bitcoin Depolymerizer belongs to the Depolymerization project, and can be downloaded via Git: 58 59 .. code-block:: console 60 61 $ git clone git://git.taler.net/depolymerization 62 $ cd depolymerization 63 64 Building Debian/Ubuntu packages requires the distribution packages ``cargo`` 65 and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git: 66 67 .. code-block:: console 68 69 $ sudo apt install cargo rustc build-essential python3 git debhelper 70 71 If your distribution provides an older ``rustc``, install newer distribution 72 packages before continuing. A toolchain installed only through ``rustup`` does 73 not satisfy the Debian package build dependencies. 74 75 Then from top-level run: 76 77 .. code-block:: console 78 79 $ ./bootstrap 80 81 Install deb package 82 ~~~~~~~~~~~~~~~~~~~ 83 84 To install the depolymerizer as a Debian/Ubuntu package with an automated secure setup and systemd services: 85 86 .. code-block:: console 87 88 $ make deb 89 $ sudo dpkg -i ../depolymerizer-bitcoin*.deb 90 91 If the previous steps succeeded, the ``depolymerizer-bitcoin`` command should be found in the $PATH. 92 93 Install binaries 94 ~~~~~~~~~~~~~~~~ 95 96 To install the depolymerizer binaries and default configuration locally run: 97 98 .. code-block:: console 99 100 $ ./configure --prefix=$PREFIX 101 $ make install 102 103 If the previous steps succeeded, the ``depolymerizer-bitcoin`` command should be found in the $PATH. 104 105 Services, users, groups and file system hierarchy 106 ------------------------------------------------- 107 108 The *depolymerizer-bitcoin* package will create several system users 109 to compartmentalize different parts of the system: 110 111 * ``depolymerizer-bitcoin-httpd``: runs the HTTP daemon with the API logic. 112 * ``depolymerizer-bitcoin-worker``: runs the worker daemon with the bitcoind node. 113 * ``depolymerizer-bitcoin-node``: runs the bitcoind node daemon interacting. 114 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 115 116 The depolymerizer setup uses the following system groups: 117 118 * ``depolymerizer-bitcoin-db``: group for all users with direct database access, specifically depolymerizer-bitcoin-httpd and depolymerizer-bitcoin-worker. 119 * ``depolymerizer-bitcoin-cookie``: group for all users with access to the bicoind cookie file, specifically depolymerizer-bitcoin-worke and depolymerizer-bitcoin-node. 120 121 The package will deploy systemd service files in 122 ``/usr/lib/systemd/system/`` for the various components: 123 124 * ``depolymerizer-bitcoin-httpd.service``: adapter REST API. 125 * ``depolymerizer-bitcoin-httpd.socket``: systemd socket activation for the HTTP daemon. 126 * ``depolymerizer-bitcoin-worker.service``: worker daemon with the bitcoind node. 127 * ``depolymerizer-bitcoin-node.service``: bitcoin node. 128 * ``depolymerizer-bitcoin.target``: main target for the depolymerizer to be operational. 129 130 The deployment creates the following key locations in the system: 131 132 * ``/etc/depolymerizer-bitcoin/``: configuration files. 133 * ``/run/depolymerizer-bitcoin/``: contains the UNIX domain sockets for inter-process communication (IPC). 134 * ``/var/lib/bitcoind``: serves as the $HOME for depolymerizer-bitcoin-node and contains the bitcoind node data and cookie files. 135 136 Installation of the Bitcoin node 137 ================================ 138 139 You need to install bitcoind & bitcoin-cli yourself, you can install them from the `Bitcoin Core website <https://bitcoincore.org/en/download/>`_. 140 141 .. code-block:: console 142 143 $ curl -L https://bitcoincore.org/bin/bitcoin-core-29.0/bitcoin-29.0-x86_64-linux-gnu.tar.gz | tar xz 144 $ sudo cp bitcoin-29.0/bin/bitcoin* /usr/bin 145 $ rm -r bitcoin-29.0 146 147 Starting a local Bitcoin node 148 ============================= 149 150 Using package script 151 -------------------- 152 153 Start the node service: 154 155 .. code-block:: console 156 157 $ sudo systemctl start depolymerizer-bitcoin-node 158 159 Then check if the node is running: 160 161 .. code-block:: console 162 163 $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf getblockchaininfo 164 165 Simple setup 166 ------------ 167 168 You need to edit bitcoind default configuration: 169 170 .. code-block:: ini 171 :caption: $HOME/.bitcoin/bitcoin.conf 172 173 txindex=1 # Enable full transaction indexes 174 rpcservertimeout=0 # Disable RPC timeout 175 176 Start the node daemon: 177 178 .. code-block:: console 179 180 $ bitcoind 181 182 In another terminal check if the node is running: 183 184 .. code-block:: console 185 186 $ bitcoin-cli getblockchaininfo 187 188 Configuration Fundamentals 189 ========================== 190 191 This chapter provides fundamental details about the adapter configuration. 192 193 The configuration for all adapter components uses a single configuration file 194 as entry point: ``/etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf``. 195 196 System defaults are automatically loaded from files in 197 ``/usr/share/depolymerizer-bitcoin/config.d``. 198 These default files should never be modified. 199 200 The default configuration ``depolymerizer-bitcoin.conf`` configuration file 201 also includes all configuration files in ``/etc/depolymerizer-bitcoin/conf.d``. 202 The settings from files in 203 ``conf.d`` are only relevant to particular components of an adapter, while 204 ``depolymerizer-bitcoin.conf`` contains settings that affect all adapter components. 205 206 207 The directory ``/etc/depolymerizer-bitcoin/secrets`` contains configuration file snippets with 208 values that should only be readable to certain users. They are included with the ``@inline-secret@`` 209 directive and should end with ``.secret.conf``. 210 211 To view the entire configuration annotated with the source of each configuration option, you 212 can use the ``depolymerizer-bitcoin config`` helper: 213 214 215 .. code-block:: shell-session 216 217 # depolymerizer-bitcoin -c /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf config dump --diagnostics 218 219 .. include:: ../frags/configuration-format.rst 220 221 Bitcoin Depolymerizer Setup 222 =========================== 223 224 Using package script 225 -------------------- 226 227 Database setup 228 ~~~~~~~~~~~~~~ 229 230 The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default 231 is: 232 233 .. code-block:: ini 234 :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-db.secret.conf 235 236 [depolymerizer-bitcoindb-postgres] 237 config = postgres:///depolymerizer-bitcoin 238 239 For a local PostgreSQL installation, the following helper creates the database 240 and roles, initializes (or upgrades) the schema, and grants service access: 241 242 .. code-block:: console 243 244 $ sudo depolymerizer-bitcoin-dbconfig 245 246 Worker setup 247 ~~~~~~~~~~~~ 248 249 You will need a bitcoin wallet to sync, you can either create: 250 251 .. code-block:: console 252 253 $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf createwallet $WALLET false false $PASSWORD 254 255 Or use an existing one: 256 257 .. code-block:: console 258 259 $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf loadwallet $WALLET 260 261 You also need to choose an address from your wallet to use as its unique Taler identifier. You can generate a new address using: 262 263 .. code-block:: console 264 265 $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -rpcwallet=$WALLET getnewaddress 266 267 Update the configuration files: 268 269 .. code-block:: ini 270 :caption: /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf 271 272 [depolymerizer-bitcoin] 273 CURRENCY = BTC 274 WALLET = $ADDRESS 275 NAME = John Smith S.A. 276 277 .. code-block:: ini 278 :caption: /etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-worker.conf 279 280 [depolymerizer-bitcoin-worker] 281 WALLET_NAME = $WALLET 282 283 .. code-block:: ini 284 :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-worker.secret.conf 285 286 [depolymerizer-bitcoin-worker] 287 PASSWORD = $PASSWORD 288 289 And finally run the setup process: 290 291 .. code-block:: console 292 293 $ sudo -u depolymerizer-bitcoin-worker depolymerizer-bitcoin -c /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf setup 294 295 Server setup 296 ~~~~~~~~~~~~ 297 298 Update the configuration files: 299 300 .. code-block:: ini 301 :caption: /etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-httpd.conf 302 303 [depolymerizer-bitcoin-httpd-wire-gateway-api] 304 ENABLED = YES 305 306 .. code-block:: ini 307 :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-httpd.secret.conf 308 309 [depolymerizer-bitcoin-httpd-wire-gateway-api] 310 AUTH_METHOD = bearer 311 TOKEN = $SECRET_TOKEN 312 313 Check the server is correctly configured: 314 315 .. code-block:: console 316 317 $ sudo -u depolymerizer-bitcoin-httpd depolymerizer-bitcoin -c /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf serve --check 318 319 Simple setup 320 ------------ 321 322 Database setup 323 ~~~~~~~~~~~~~~ 324 325 The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default 326 is: 327 328 .. code-block:: ini 329 :caption: $CONFIG_FILE 330 331 [depolymerizer-bitcoindb-postgres] 332 config = postgres:///depolymerizer-bitcoin 333 334 You must make sure that this database exists and is accessible to the user 335 running the depolymerizer before continuing. If the database is run on a different host, please follow the instructions from the PostgreSQL manual for configuring remote access. 336 337 Assuming that the configuration file exists at ``$CONFIG_FILE``, the following 338 command initializes (or upgrades) the database schema: 339 340 .. code-block:: console 341 342 $ depolymerizer-bitcoin -c "$CONFIG_FILE" dbinit 343 344 You will need a bitcoin wallet to sync, you can either create: 345 346 .. code-block:: console 347 348 $ bitcoin-cli createwallet $WALLET false false $PASSWORD 349 350 Or use an existing one: 351 352 .. code-block:: console 353 354 $ bitcoin-cli loadwallet $WALLET 355 356 You also need to choose an address from your wallet to use as its unique Taler identifier. You can generate a new address using: 357 358 .. code-block:: console 359 360 $ bitcoin-cli -rpcwallet=$WALLET getnewaddress 361 362 Update the configuration files: 363 364 .. code-block:: ini 365 :caption: $CONFIG_FILE 366 367 [depolymerizer-bitcoin] 368 CURRENCY = BTC 369 WALLET = $ADDRESS 370 NAME = John Smith S.A. 371 372 [depolymerizer-bitcoin-worker] 373 WALLET_NAME = $WALLET 374 PASSWORD = $PASSWORD 375 376 And finally run the setup process: 377 378 .. code-block:: console 379 380 $ depolymerizer-bitcoin -c "$CONFIG_FILE" setup 381 382 Server setup 383 ~~~~~~~~~~~~ 384 385 Update the configuration files: 386 387 .. code-block:: ini 388 :caption: $CONFIG_FILE 389 390 [depolymerizer-bitcoin-httpd-wire-gateway-api] 391 ENABLED = YES 392 AUTH_METHOD = bearer 393 TOKEN = $SECRET_TOKEN 394 395 Check the server is correctly configured: 396 397 .. code-block:: console 398 399 $ depolymerizer-bitcoin -c "$CONFIG_FILE" serve --check 400 401 Configuring bitcoind 402 ==================== 403 404 Here are some bitcoind configuration you might want to change: 405 406 .. code-block:: ini 407 :caption: bitcoin.conf 408 409 # bitcoin transactions fees can exceed taler wire fees, putting 410 your wire in bankruptcy. You must specify an acceptable transaction fee cap. 411 maxtxfee=? 412 413 Configuring Bitcoin Depolymerizer 414 ================================= 415 416 Here are some bitcoind configuration you might want to change: 417 418 .. code-block:: ini 419 420 [depolymerizer-bitcoin-worker] 421 # Number of blocks to consider a transactions durable 422 # The default is the recommended value 423 # Lowering it make the confirmation process faster (more user friendly) 424 # But it make the depolymerizer more sensible to adversarial reorg 425 CONFIRMATION = 6 426 427 # Amount to keep when bouncing malformed credit 428 # Default is 0 as the mining fee is always paid by the creditor 429 BOUNCE_FEE = BTC:0.00001 430 431 Process lifetime 432 ---------------- 433 434 You may want to restart depolymerization processes regularly to improve 435 stability (ex. fix memory fragmentation). It is possible to configure a lifetime 436 that triggers a graceful shutdown every time a specific amount of work has been 437 done. 438 439 .. code-block:: ini 440 441 [depolymerizer-bitcoin-worker] 442 # Number of worker's loops before worker shutdown (0 means never) 443 LIFETIME = 0 444 445 [depolymerizer-bitcoin-httpd] 446 # Number of requests to serve before server shutdown (0 means never) 447 LIFETIME = 0 448 449 Stuck transaction 450 ----------------- 451 452 When we send a transaction with a fee too small, it may not be confirmed in a 453 timely fashion. To unstuck those transactions, it is possible to replace them 454 with other transactions with more fees. Depolymerizer can be configured to do 455 this automatically: 456 457 .. code-block:: ini 458 459 [depolymerizer-bitcoin-worker] 460 # Delay in seconds before bumping an unconfirmed transaction fee (0 means never) 461 BUMP_DELAY = 0 462 463 Deployment 464 ========== 465 466 This chapter describes how to deploy the depolymerizer once the basic installation 467 and configuration are completed. 468 469 Serving 470 ------- 471 472 The depolymerizer can serve HTTP over both TCP and UNIX domain socket. 473 474 The following options are to be configured in the section ``[depolymerizer-bitcoin-httpd]``: 475 476 - ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve 477 HTTP over a UNIX domain socket. 478 479 - ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``. 480 481 - ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is 482 ``unix``. 483 484 - ``UNIXPATH_MODE``: Number giving the mode with the access permission mask 485 for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such 486 a way that your depolymerizer has permissions to access the UNIX domain 487 socket. The default (660) assumes that the reverse proxy is a member of 488 the group under which the depolymerizer HTTP server is running. 489 490 Reverse Proxy Setup 491 ------------------- 492 493 By default, the ``depolymerizer-bitcoin-httpd`` service listens for HTTP connections 494 on a UNIX domain socket. To make the service publicly available, a reverse 495 proxy such as nginx should be used. We strongly recommend to configure nginx 496 to use TLS. 497 498 The ``depolymerizer-bitcoin`` package ships with a sample configuration that can be 499 enabled in nginx: 500 501 .. code-block:: shell-session 502 503 # vim /etc/nginx/sites-available/depolymerizer-bitcoin 504 < ... customize configuration ... > 505 # ln -s /etc/nginx/sites-available/depolymerizer-bitcoin /etc/nginx/sites-enabled/depolymerizer-bitcoin 506 # systemctl reload nginx 507 508 With this last step, we are finally ready to launch the 509 main depolymerizer process. 510 511 Launching the depolymerizer 512 --------------------------- 513 514 .. code-block:: console 515 516 $ sudo systemctl enable --now depolymerizer-bitcoin.target