electrum-personal-server

Maximally lightweight electrum server for a single user
git clone https://git.parazyd.org/electrum-personal-server
Log | Files | Refs | README

README.md (15056B)


      1 # Electrum Personal Server
      2 
      3 Electrum Personal Server aims to make using Electrum bitcoin wallet more secure
      4 and more private. It makes it easy to connect your Electrum wallet to your own
      5 full node.
      6 
      7 [Full node](https://en.bitcoin.it/wiki/Full_node) wallets are important in
      8 bitcoin because they are a big part of what makes the system trustless. No
      9 longer do people have to trust a financial institution like a bank or Paypal,
     10 they can run software on their own computers. If bitcoin is digital gold, then
     11 a full node wallet is your own personal goldsmith who checks for you that
     12 received payments are genuine.
     13 
     14 Full node wallets are also important for privacy. Using Electrum under default
     15 configuration requires it to send (hashes of) all your bitcoin addresses to some
     16 server. That server can then easily spy on your transactions. Full node
     17 wallets like Electrum Personal Server would download the entire blockchain and
     18 scan it for the user's own addresses, and therefore don't reveal to anyone else
     19 which bitcoin addresses they are interested in.
     20 
     21 ## Contents
     22 
     23 - [Features](#features)
     24 - [Detailed how-to guide](#how-to)
     25 - [Quick start for Debian/Ubuntu](#quick-start-on-a-debianubuntu-machine-with-a-running-bitcoin-full-node)
     26 - [Links to other setup guides](#links-to-other-setup-guides)
     27 - [How to expose the server to the internet](#exposure-to-the-internet)
     28 - [How is this different from other Electrum servers ?](#how-is-this-different-from-other-electrum-servers-)
     29 - [Articles, Discussion and Talks](#articles-discussion-and-talks)
     30 - [Contributing](#contributing)
     31 
     32 ### Features
     33 
     34 - Fully-featured Electrum server for a single user. Combine full node security
     35   and privacy with all of Electrum's feature-richness: (Hardware wallet
     36   integration, [Multisignature wallets](http://docs.electrum.org/en/latest/multisig.html),
     37   [Offline signing](http://docs.electrum.org/en/latest/coldstorage.html),
     38   [Seed recovery phrases](https://en.bitcoin.it/wiki/Seed_phrase), Coin control,
     39   Fee-bumping)
     40 - Maximally lightweight. Very low CPU, RAM and disk space requirements. Only a
     41   full node required.
     42 - Compatible with all Bitcoin Core resource-saving features:
     43   - [Pruning](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.12.0.md#wallet-pruning)
     44   - [Blocksonly](https://bitcointalk.org/index.php?topic=1377345.0)
     45   - Disabled txindex
     46 - Scriptable transaction broadcasting. When the user click "Send" the server
     47   can be configured to run a system call with the new transaction:
     48   - Broadcast transactions through Tor, for [resisting traffic analysis](https://en.bitcoin.it/wiki/Privacy#Tor_and_tor_broadcasting).
     49   - By writing a shell script (eg. `send-tx-over-sms.sh`) the server can
     50     broadcast transactions via SMS, radio or any other creative way.
     51 
     52 ## How To
     53 
     54 - If you dont already have them, download and install Bitcoin Core version 0.17
     55   or higher. Make sure you
     56   [verify the digital signatures](https://bitcoin.stackexchange.com/questions/50185/how-to-verify-bitcoin-core-release-signing-keys)
     57   of any binaries before running them, or compile from source. The Bitcoin node
     58   must have wallet functionality enabled, and must have the RPC server switched on (`server=1`
     59   in bitcoin.conf). Create a wallet dedicated to Electrum Personal Server by adding
     60   `wallet=electrumpersonalserver` to the bitcoin.conf file.
     61 
     62 - If you dont already have it, download and install
     63   [Electrum bitcoin wallet](https://electrum.org/), and set up your Electrum
     64   wallet (for example by linking your hardware wallet). To avoid damaging
     65   privacy by connecting to public Electrum servers, disconnect from the
     66   internet first or run Electrum with the command line argument
     67   `--server localhost:50002:s`. To avoid accidentally connecting to public
     68   electrum servers, also use the command line argument `--offline`.
     69 
     70 - Download the [latest release](https://github.com/chris-belcher/electrum-personal-server/releases)
     71   of Electrum Personal Server. If using Windows OS take the packaged binary
     72   release build `electrumpersonalserver-windows-release-XXX.zip`.
     73 
     74 - Extract and enter the directory, and copy the file `config.ini_sample` to
     75   `config.ini`. Edit the file `config.ini` to configure everything about the
     76   server. Add your wallet master public keys or watch-only addresses to the
     77   `[master-public-keys]` and `[watch-only-addresses]` sections. Master public
     78   keys for an Electrum wallet (which start with xpub/ypub/zpub/etc) can be found
     79   in the Electrum client menu `Wallet` -> `Information`. You can add multiple
     80   master public keys or watch-only addresses by adding separate lines for the
     81   different keys/addresses:
     82 
     83       wallet1 = xpub661MyMwAqRbcF...
     84       wallet2 = xpub7712KLsfsg46G...
     85 
     86 - If you created a wallet dedicated to Electrum Personal Server in Bitcoin Core,
     87   you have to modify the line `wallet_filename` in the `[bitcoin-rpc]` section
     88   with the name of the wallet, for example `wallet_filename = electrumpersonalserver`.
     89 
     90 - If using the windows packaged binary release, drag the file `config.ini` onto
     91   the file `electrum-personal-server.exe` to run the server, or on the command
     92   line run `electrum-personal-server config.ini`.
     93 
     94 - If installing from the source release, install Electrum Personal Server in
     95   your home directory with `pip3 install --user .`. On Linux the script
     96   `electrum-personal-server` will be installed in `~/.local/bin`. Please note,
     97   if for some reason, you want to make a system-wide install, simply run
     98   `pip3 install .` as root (e.g. if you have `sudo` setup, you could use:
     99   `sudo pip3 install .`). Run `electrum-personal-server /path/to/config.ini`
    100   to start Electrum Personal Server.
    101 
    102 - The first time the server is run it will import all configured addresses as
    103   watch-only into the Bitcoin node, and then exit.
    104   If the wallets contain historical transactions you can use the rescan script
    105   (`electrum-personal-server --rescan /path/to/config.ini`) to make them appear.
    106   If using the windows packaged binary release build then drag the file
    107   `config.ini` onto the file `electrum-personal-server-rescan.bat`.
    108 
    109 - Run the server again which will start Electrum Personal Server. Wait until
    110   the message `Listening for Electrum Wallet ...` appears and then tell
    111   Electrum to connect to the server in `Tools` -> `Server`. By default the
    112   server details are `localhost` if running on the same machine. Make sure the
    113   port number matches what is written in `config.ini` (port 50002 by default).
    114 
    115 Pro Tip: run Electrum wallet with the command line arguments `--oneserver --server localhost:50002:s`.
    116 This stops Electrum connecting to other servers to obtain block
    117 headers; and locks Electrum to connect only to your server, disabling the GUI
    118 button to stop accidental connections. This helps avoid a user accidentally
    119 ruining their privacy by connecting to public Electrum servers. Another way
    120 to do this is to open Electrum's config file and edit the lines to
    121 `oneserver=true`.
    122 
    123 Pro Tip2: run tor on the same machine as Electrum Personal Server. Then by
    124 default transactions will be broadcast through tor. If running tor, also set
    125 `walletbroadcast=0` in your `bitcoin.conf`. This prevents the node from
    126 rebroadcasting transactions without tor.
    127 
    128 ### Quick start on a Debian/Ubuntu machine with a running Bitcoin full node
    129 
    130 1. Download the [latest release](https://github.com/chris-belcher/electrum-personal-server/releases)
    131    of Electrum Personal Server. (Not the Windows version, the "Source code" zip or
    132    tar.gz.)
    133 1. Extract the compressed file
    134 1. Enter the directory
    135 1. `cp config.ini_sample config.ini`
    136 1. Edit the config.ini file:
    137    1. Add bitcoind back-end RPC auth information
    138    1. Add wallet master public keys for your wallets
    139 1. Install the server to your home directory with `pip3 install --user .`
    140 1. Make sure `~/.local/bin` is in your \$PATH (`echo $PATH`). If not, add it:
    141    `echo 'PATH=$HOME/.local/bin:$PATH' >> ~/.profile`, logout, and log in again
    142 1. Run the server: `electrum-personal-server config.ini`
    143 1. Rescan if needed: `electrum-personal-server --rescan config.ini`
    144 1. Restart the server if needed
    145 1. Start your Electrum wallet: `electrum --oneserver --server localhost:50002:s`.
    146 
    147 ### Links to other setup guides
    148 
    149 - [How to setup Electrum Personal Server on a Raspberry Pi](https://github.com/Stadicus/RaspiBolt/blob/master/raspibolt_64_electrum.md)
    150 - [Electrum Personal Server on Windows 10](https://driftwoodpalace.github.io/Hodl-Guide/hodl-guide_63_eps-win.html)
    151 - [Running Electrum Personal Server on Mac OS](https://driftwoodpalace.github.io/Hodl-Guide/hodl-guide_64_eps-mac.html)
    152 - [How to set up your own Bitcoin node, Electrum wallet and Server](https://curiosityoverflow.xyz/posts/bitcoin-electrum-wallet/)
    153 - [How to set up Wireguard to connect to EPS](https://curiosityoverflow.xyz/posts/wireguard-eps/)
    154 - [Linux setup video tutorial on youtube](https://www.youtube.com/watch?v=1JMP4NZCC5g)
    155 - [BTCPay Server integration with Electrum Personal Server](https://docs.btcpayserver.org/ElectrumPersonalServer/)
    156 - [Using Electrum Personal Server with a Bitseed node](https://github.com/john-light/bitcoin/blob/master/eps.md)
    157 - [Spanish language video tutorial / InstalaciĆ³n del servidor Electrum Personal Server](https://www.youtube.com/watch?v=F3idwecYvcU)
    158 - [Japanese language setup guide](https://freefromjp.wordpress.com/2019/07/13/electrum-personal-server-%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB/)
    159 - [Connect to Electrum Personal Server via Wireguard ](https://curiosityoverflow.xyz/posts/wireguard-eps/#connecting-to-electrum-personal-server)
    160 
    161 #### Exposure to the Internet
    162 
    163 Right now, Electrum Personal Server is easiest to use when it, your full node
    164 and your Electrum wallet are all on the same computer.
    165 
    166 Other people should not be connecting to your server. They won't be
    167 able to synchronize their wallet, and they could potentially learn all your
    168 wallet transactions. By default the server will accept connections only from
    169 `localhost`, though this can be changed in the configuration file.
    170 
    171 The whitelisting feature can be used accept only certain IP addresses ranges
    172 connecting to the server. The Electrum protocol uses SSL for encryption. If
    173 your wallet connects over the public internet you should generate your own
    174 SSL certificate instead of using the default one, otherwise your connection
    175 can be decrypted. See the configuration file for instruction on how to do
    176 this.
    177 
    178 Another option is to use a SSH tunnel to reach Electrum Personal Server. SSH
    179 connections are encrypted and authenticated. This can be done on the command
    180 line with: `ssh username@host -L 50002:localhost:50002` or with [Putty](https://www.putty.org/)
    181 for Windows. Then connect Electrum to localhost, and SSH will forward that
    182 connection to the server.
    183 
    184 ##### Number of connections
    185 
    186 Right now Electrum Personal Server can only accept one connection at a time.
    187 
    188 ##### Lightning Network
    189 
    190 Right now Electrum Personal Server does not support Lightning Network which
    191 Electrum wallet 4.0 and above implements.
    192 
    193 #### How is this different from other Electrum servers ?
    194 
    195 They are different approaches with different tradeoffs. Electrum Personal
    196 Server is compatible with pruning, blocksonly and txindex=0, uses less CPU and
    197 RAM, is suitable for being used intermittently rather than needing to be
    198 always-on, and doesn't require an index of every bitcoin address ever used. The
    199 tradeoff is when recovering an old wallet, you must import your wallet first
    200 and you may need to rescan, so it loses the "instant on" feature of Electrum
    201 wallet. Other Electrum server implementations will be able to sync your wallet
    202 immediately even if you have historical transactions, and they can serve
    203 multiple Electrum connections at once.
    204 
    205 Traditional Electrum servers inherently are not very scalable and use many
    206 resources which push people towards using centralized solutions. This is what
    207 we'd like to avoid with Electrum Personal Server.
    208 
    209 Definitely check out other implementations:
    210 - [ElectrumX](https://github.com/spesmilo/electrumx) - Full Electrum server maintained by the Electrum project
    211 - [Electrs](https://github.com/romanz/electrs) - Full Electrum server coded in rust
    212 - [Bitcoin Wallet Tracker](https://github.com/bwt-dev/bwt) - Wallet indexer coded in rust
    213 - [Obelisk](https://github.com/parazyd/obelisk) - Minimal Electrum server using zeromq and libbitcoin as backend
    214 
    215 #### Further ideas for work
    216 
    217 - Allowing connections from more than one Electrum instance at a time. See issue
    218   [#50](https://github.com/chris-belcher/electrum-personal-server/issues/50). First
    219   the server code should be separated from the networking code.
    220 - Fix mempool lock/CPU bottleneck issue. See issue [#96](https://github.com/chris-belcher/electrum-personal-server/issues/96).
    221 - Research and develop an easier way of rescanning the wallet when blockchain
    222   pruning is enabled. See issue [#85](https://github.com/chris-belcher/electrum-personal-server/issues/85).
    223 - Developing some way for Electrum servers to authenticate clients, so that
    224   Electrum Personal Server can accept connections from the entire internet but
    225   without a fear of privacy loss.
    226 - Dynamic adding of wallet master public keys. Perhaps by polling for changes
    227   in the config file.
    228 
    229 ## Contact
    230 
    231 I can be contacted on freenode IRC on the `#bitcoin` and `#electrum` channels,
    232 by email or on [twitter](https://twitter.com/chris_belcher_/).
    233 
    234 My PGP key fingerprint is: `0A8B 038F 5E10 CC27 89BF CFFF EF73 4EA6 77F3 1129`.
    235 
    236 ## Articles, Discussion and Talks
    237 
    238 - [BitcoinMagazine.com article](https://bitcoinmagazine.com/articles/electrum-personal-server-will-give-users-full-node-security-they-need/)
    239 - [Electrum Personal Server talk at London Bitcoin Developer Meetup](https://www.youtube.com/watch?v=uKMXYdfm-is)
    240 - Electrum Personal Server used as a building block for systems which use
    241   bitcoin without internet access. See [here](https://twitter.com/notgrubles/status/1091011511961731073)
    242   and [here](https://medium.com/hackernoon/completely-offline-bitcoin-transactions-4e58324637bd)
    243   for information and setup guide.
    244 - [Mailing list email](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-February/015707.html)
    245 - [Bitcointalk thread](https://bitcointalk.org/index.php?topic=2664747.msg27179198)
    246 - [Nasdaq article](https://www.nasdaq.com/article/the-electrum-personal-server-will-give-users-the-full-node-security-they-need-cm920443)
    247 - [Bitcoinnews.ru article (russian)](https://bitcoinnews.ru/novosti/electrum-personal-server-uluchshennaya-versiya-/)
    248 - [bits.media article (russian)](https://bits.media/razrabotchiki-electrum-opublikovali-alfa-versiyu-electrum-personal-server/)
    249 
    250 ## Contributing
    251 
    252 Donate to help improve Electrum Personal Server: `bc1qwt8kh83dpdj4yuquvsf28rhcft2rjh6jvy6678` or `15wAE63DG8RH6xp7nTucgYn1Jb4acR1EvM`. Signed donation addresses can be found [here](/docs/signed-donation-addresses.txt).
    253 
    254 This is open source project which happily accepts coding contributions from
    255 anyone. See [developer-notes.md](docs/developer-notes.md).