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