taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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