Running Bytecoin Services

Design notes

Bytecoin is split into two separate services - bytecoind and walletd. This is a direct consequence of the anonymity concept Bytecoin is built upon.

bytecoind service is responsible for P2P connections and consensus, it can assemble transactions into blocks, check transactions validity, synchronize and grow blockchain, but it cannot look inside transactions to see transfers between addresses, because this requires access to user secrets (wallet) to do so.

Here comes walletd that is designed to work with user wallet being run with a wallet file as a mandatory argument. After getting chain of blocks from bytecoind, walletd sifts through all transactions with wallet keys to see transfers from and to addresses stored in that wallet file.

Though this separation is perfect, the most common case is running bytecoind and walletd on the same computer at the same time. That's why walletd has a local copy of bytecoind built-in. If you run walletd without --bytecoind-remote-address=<ip:port> parameter, it will run in-process bytecoind while walletd itself is running. If you run walletd with --bytecoind-remote-address=<ip:port>, it will try to connect to external bytecoind running at the given remote address.

You cannot have several bytecoinds running on the same machine, because bytecoind requires exclusive access to blockchain database stored in Bytecoin data folder. (kind-of exception is running one for mainnet and one for testnet, this works because there is separate Bytecoin data folder for testnet)

In the meantime, you can have as many walletds running as you need, but the same wallet file (actually, wallet file with the same view key) cannot be open by more than one walletd. This is because walletd requires exclusive access to wallet cache database with a name derived from wallet file view key, stored in Bytecoin data folder.

Security notice: If you operate large sums of money, you should always run bytecoind in separate process, so that potential attacks exploiting security vulnerabilities in p2p network code will not get access to address space where wallet keys are stored.

Note about secrets on command line: walletd requires wallet password and HTTP basic authentication parameters to be used by JSON API. It expects them from the standard input (typed by user after launching), because secrets on a command line are security risk. So, if you wish to run walletd from script without user interaction, you should run it like this:

• On Linux and Mac OSX

  $ echo -e "<wallet_password>\n<http_user>:<http_password>" | ./walletd <other parameters>
  

• On Windows

  C:\> (echo <wallet_password> & echo <http_user>:<http_password>) | ./walletd <other parameters>
  

• On Windows, if wallet password is empty, we need special syntax to echo empty line

  C:\> (echo( & echo <http_user>:<http_password>) | ./walletd <other parameters>
  

Handy examples

Running a single walletd with built-in bytecoind and default parameters:

$ ./walletd --wallet-file=<file>

Running a single walletd with external bytecoind on the same machine (in beta you can only use 127.0.0.1 instead of localhost):

$ ./bytecoind
$ ./walletd --wallet-file=<file> --bytecoind-remote-address=127.0.0.1:8081

Running a single walletd with external bytecoind on a different machine (if not using https, you can only use IP-address):

$ ./bytecoind
$ ./walletd --wallet-file=<file> --bytecoind-remote-address=137.28.14.69:8081

Running two walletds with external bytecoind on the same machine:

$ ./bytecoind
$ ./walletd --wallet-file=<file1> --bytecoind-remote-address=127.0.0.1:8081
$ ./walletd --wallet-file=<file2> --walletd-bind-address=127.0.0.1:8071 --bytecoind-remote-address=127.0.0.1:8081

We had to specify different bind port for accessing second walletd, because port 8070 is already used by first walletd.

We can check them both in GUI wallet, selecting "Connect to remote walletd" command in Wallet menu, and typing 127.0.0.1:8070 or 127.0.0.1:8071 to connect to each of running walletds.

Running walletd with external bytecoind on a remote server via https (when using https, you can only use full DNS name):

$ ./walletd --wallet-file=<file> --bytecoind-remote-address=https://node123.amazon.com:8091

On your server, you should run bytecoind normally with Nginx HTTPS proxy (or amazon load balancer) configured with valid certificate (https://letsencrypt.org is a popular option), listening on port 8091 and redirecting requests to bytecoind that listens on port 8081.