bitcoin-manual.rst (15428B)
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 2.1, 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 blockhain Taler adapter. 23 24 This manual targets system administrators who want to install and 25 operate a Bictoin GNU Taler Depolymerizer 26 27 In this manual, we explain how to setup a depolymerizer. 28 29 .. contents:: Table of Contents 30 :local: 31 32 Installation of the Bitcoin Depolymerizer 33 ========================================= 34 35 Installing on Debian 36 -------------------- 37 38 .. include:: frags/installing-debian.rst 39 40 To install the depolymerizer, you can now simply run: 41 42 .. code-block:: shell-session 43 44 # apt install bitcoin-depolymerizer 45 46 Installing on Ubuntu 47 -------------------- 48 49 .. include:: frags/installing-ubuntu.rst 50 51 To install the depolymerizer, you can now simply run: 52 53 .. code-block:: shell-session 54 55 # apt install bitcoin-depolymerizer 56 57 Building from source 58 -------------------- 59 60 Bitcoin Depolymerizer belongs to the Depolymerization project, and can be downloaded via Git: 61 62 .. code-block:: console 63 64 $ git clone git://git.taler.net/depolymerization 65 $ cd depolymerization 66 67 You will need the latest version of the rust stable toolchain and a C toolchain: 68 69 .. code-block:: console 70 71 $ sudo apt install rustup build-essential 72 $ rustup toolchain install stable 73 74 Then from top-level run: 75 76 .. code-block:: console 77 78 $ ./bootstrap 79 80 Install deb package 81 ~~~~~~~~~~~~~~~~~~~ 82 83 To install the depolymerizer as a Debian/Ubuntu package with an automated secure setup and systemd services: 84 85 .. code-block:: console 86 87 $ sudo apt install debhelper 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 localy 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 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 If the database is run on a different host, please follow the instructions 240 from the PostgreSQL manual for configuring remote access. 241 242 Assuming the configuration is correct, the following 243 command initializes (or upgrades) the database schema using: 244 You can then use a script to automate a secure database setup: 245 246 .. code-block:: console 247 248 $ sudo depolymerizer-bitcoin-dbconfig 249 250 Worker setup 251 ~~~~~~~~~~~~ 252 253 You will need a bitcoin wallet to sync, you can either create: 254 255 .. code-block:: console 256 257 $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf createwallet $WALLET false false $PASSWORD 258 259 Or use an existing one: 260 261 .. code-block:: console 262 263 $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf loadwallet $WALLET 264 265 You also need to choose an address from you wallet to use as it's unique Taler identifier. You can generate a new address using: 266 267 .. code-block:: console 268 269 $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -rpcwallet=$WALLET getnewaddress 270 271 Update the configuration files: 272 273 .. code-block:: ini 274 :caption: /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf 275 276 [depolymerizer-bitcoin] 277 CURRENCY = BTC 278 WALLET = $ADDRESS 279 NAME = John Smith S.A. 280 281 .. code-block:: ini 282 :caption: /etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-worker.conf 283 284 [depolymerizer-bitcoin-worker] 285 WALLET_NAME = $WALLET 286 287 .. code-block:: ini 288 :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-worker.secret.conf 289 290 [depolymerizer-bitcoin-worker] 291 PASSWORD = $PASSWORD 292 293 And finaly run the setup process: 294 295 .. code-block:: console 296 297 $ sudo -u depolymerizer-bitcoin-worker depolymerizer-bitcoin setup 298 299 Server setup 300 ~~~~~~~~~~~~ 301 302 Update the configuration files: 303 304 .. code-block:: ini 305 :caption: /etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-httpd.conf 306 307 [depolymerizer-bitcoin-httpd-wire-gateway-api] 308 ENABLED = YES 309 310 .. code-block:: ini 311 :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-httpd.secret.conf 312 313 [depolymerizer-bitcoin-httpd-wire-gateway-api] 314 AUTH_METHOD = bearer 315 TOKEN = $SECRET_TOKEN 316 317 Check the server is correctly configured: 318 319 .. code-block:: console 320 321 $ sudo -u depolymerizer-bitcoin-httpd depolymerizer-bitcoin serve --check 322 323 Simple setup 324 ------------ 325 326 Database setup 327 ~~~~~~~~~~~~~~ 328 329 The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default 330 is: 331 332 .. code-block:: ini 333 :caption: $CONFIG_FILE 334 335 [depolymerizer-bitcoindb-postgres] 336 config = postgres:///depolymerizer-bitcoin 337 338 You must make sure that this database exists and is accessible to the user 339 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. 340 341 Assuming that the configuration file exists at ``$CONFIG_FILE``, the following 342 command initializes (or upgrades) the database schema: 343 344 .. code-block:: console 345 346 $ depolymerizer-bitcoin -c "$CONFIG_FILE" dbinit 347 348 You will need a bitcoin wallet to sync, you can either create: 349 350 .. code-block:: console 351 352 $ bitcoin-cli createwallet $WALLET false false $PASSWORD 353 354 Or use an existing one: 355 356 .. code-block:: console 357 358 $ bitcoin-cli loadwallet $WALLET 359 360 You also need to choose an address from you wallet to use as it's unique Taler identifier. You can generate a new address using: 361 362 .. code-block:: console 363 364 $ bitcoin-cli -rpcwallet=$WALLET getnewaddress 365 366 Update the configuration files: 367 368 .. code-block:: ini 369 :caption: $CONFIG_FILE 370 371 [depolymerizer-bitcoin] 372 CURRENCY = BTC 373 WALLET = $ADDRESS 374 NAME = John Smith S.A. 375 376 [depolymerizer-bitcoin-worker] 377 WALLET_NAME = $WALLET 378 PASSWORD = $PASSWORD 379 380 And finaly run the setup process: 381 382 .. code-block:: console 383 384 $ depolymerizer-bitcoin -c "$CONFIG_FILE" setup 385 386 Server setup 387 ~~~~~~~~~~~~ 388 389 Update the configuration files: 390 391 .. code-block:: ini 392 :caption: $CONF_FILE 393 394 [depolymerizer-bitcoin-httpd-wire-gateway-api] 395 ENABLED = YES 396 AUTH_METHOD = bearer 397 TOKEN = $SECRET_TOKEN 398 399 Check the server is correctly configured: 400 401 .. code-block:: console 402 403 $ depolymerizer-bitcoin -c "$CONF_FILE" serve --check 404 405 Configuring bitcoind 406 ==================== 407 408 Here are some bitcoind configuration you might want to change: 409 410 .. code-block:: ini 411 :caption: bitcoin.conf 412 413 # bitcoin transactions fees can exceed taler wire fees, putting 414 your wire in bankruptcy. You must specify an acceptable transaction fee cap. 415 maxtxfee=? 416 417 Configuring Bitcoin Depolymerizer 418 ================================= 419 420 Here are some bitcoind configuration you might want to change: 421 422 .. code-block:: ini 423 424 [depolymerizer-bitcoin] 425 # Number of blocks to consider a transactions durable 426 # The default is the recommended value 427 # Lowering it make the confirmation process faster (more user friendly) 428 # But it make the depolymerizer more sensible to adversarial reorg 429 CONFIRMATION = 6 430 431 # Amount to keep when bouncing malformed credit 432 # Default is 0 as the mining fee is always paid by the creditor 433 BOUNCE_FEE = 0.00001 434 435 Process lifetime 436 ---------------- 437 438 You may want to restart depolymerization processes regularly to improve 439 stability (ex. fix memory fragmentation). It is possible to configure a lifetime 440 that triggers a graceful shutdown every time a specific amount of work has been 441 done. 442 443 .. code-block:: ini 444 445 [depolymerizer-bitcoin-worker] 446 # Number of worker's loops before worker shutdown (0 means never) 447 LIFETIME = 0 448 449 [depolymerizer-bitcoin-httpd] 450 # Number of requests to serve before server shutdown (0 means never) 451 LIFETIME = 0 452 453 Stuck transaction 454 ----------------- 455 456 When we send a transaction with a fee too small, it may not be confirmed in a 457 timely fashion. To unstuck those transactions, it is possible to replace them 458 with other transactions with more fees. Depolymerizer can be configured to do 459 this automatically: 460 461 .. code-block:: ini 462 463 [depolymerizer-bitcoin-worker] 464 # Delay in seconds before bumping an unconfirmed transaction fee (0 means never) 465 BUMP_DELAY = 0 466 467 Deployment 468 ========== 469 470 This chapter describes how to deploy the depolymerizer once the basic installation 471 and configuration are completed. 472 473 Serving 474 ------- 475 476 The depolymerizer can serve HTTP over both TCP and UNIX domain socket. 477 478 The following options are to be configured in the section ``[depolymerizer-bitcoin-httpd]``: 479 480 - ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve 481 HTTP over a UNIX domain socket. 482 483 - ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``. 484 485 - ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is 486 ``unix``. 487 488 - ``UNIXPATH_MODE``: Number giving the mode with the access permission mask 489 for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such 490 a way that your depolymerizer has permissions to access the UNIX domain 491 socket. The default (660) assumes that the reverse proxy is a member of 492 the group under which the depolymerizer HTTP server is running. 493 494 Reverse Proxy Setup 495 ------------------- 496 497 By default, the ``depolymerizer-bitcoin-httpd`` service listens for HTTP connections 498 on a UNIX domain socket. To make the service publicly available, a reverse 499 proxy such as nginx should be used. We strongly recommend to configure nginx 500 to use TLS. 501 502 The ``depolymerizer-bitcoin-bank`` package ships with a sample configuration that can be 503 enabled in nginx: 504 505 .. code-block:: shell-session 506 507 # vim /etc/nginx/sites-available/depolymerizer-bitcoin 508 < ... customize configuration ... > 509 # ln -s /etc/nginx/sites-available/depolymerizer-bitcoin /etc/nginx/sites-enabled/depolymerizer-bitcoin 510 # systemctl reload nginx 511 512 With this last step, we are finally ready to launch the 513 main depolymerizer process. 514 515 Launching the depolymerizer 516 --------------------------- 517 518 .. code-block:: console 519 520 $ sudo systemctl start depolymerizer-bitcoin.target