Skip to content

Latest commit

 

History

History
452 lines (347 loc) · 14.7 KB

README.md

File metadata and controls

452 lines (347 loc) · 14.7 KB
Raw

sentrum

Crates.io Total Downloads AUR Version GitHub Actions Workflow Status GitHub Release

Daemon that monitors the Bitcoin blockchain for transactions involving your wallets and sends you notifications in many different channels (ntfy push notifications, email, telegram, nostr, arbitrary command, etc).

Example screenshot of many noifications for a single transaction:

Installation

Either:

  • Download the binary from the releases page
  • Install cargo, compile from source using cargo install sentrum (binary will be installed in ~/.cargo/bin)
  • If using archlinux, install it from the AUR: sentrum, sentrum-bin or sentrum-git

Configuration

Config file path

It will look for a sentrum.toml configuration file located in any of these directories (with this priority):

  1. Current working directory
  2. $XDG_CONFIG_HOME/sentrum
  3. ~/.config/sentrum
  4. /etc/sentrum (more appropriate if running as a systemd service)

Alternatively, you can pass the configuration file path as an argument in the invocation and that will override any of the above.

Start by copying the sample configuration to where you want it. E.g.

cp sentrum.sample.toml sentrum.toml

or

sudo cp sentrum.sample.toml /etc/sentrum/sentrum.toml

What to configure

You can use the sentrum.sample.toml file as an example. Most options have very good defaults so you don't need to change them unless you want to. In the examples below, commented options showcase their defaults, unless explicitly said otherwise.

Required

  • wallets: what wallets you want to monitor
  • actions: what actions you want to take once a relevant transaction is found

Optional

  • electrum: by default, public electrum servers are used. You can configure it to connect to your own
  • message: this allows you to configure the subject and body templates of the notification message and choose the relevant data from the transaction that you want to include

Wallets

For each wallet you want to track, add the following configuration:

[[wallets]]
# Identifier for naming purposes (required)
name = "alice"
# Wallet xpub (required)
xpub = "xpub6CkXHzuU1NyHUFNiQZLq2bgt6QPqjZbwpJ1MDgDeo4bWZ8ZP7HZr7v9WTLCQFhxVhqiJNcw5wSKE77rkAK1SzcuHjt36ZUibBHezGzGL9h9"
# Script kind ("legacy","nested_segwit","segwit","taproot") (optional)
#kind = "segwit"

It assumes a BIP84 (native segwit, bc1 style addresses) wallet. If your wallet has a different script kind add the field kind = "legacy" (or nested_segwit, or taproot).

Multisig and friends

More complex wallet types are supported by providing descriptor = "<desc>" and change_descriptor = "<desc>" wallet descriptors instead of xpub = and kind = . You don't need to provide change_descriptor, it's optional, and many times the main descriptor already includes it. Example:

[[wallets]]
name = "charlie"
descriptor = "wsh(sortedmulti(2,[bbc5fee8/48h/1h/0h/2h]tpubDEuo3nCajorgHFrA5unQB3dSR3Mh7EPfedyU36GC2wVLwB32PsDuiPcsw5RobqNRfQyjas3cxeEraxs6HYJvQPcNX5neut2jRvZijyxLiqT/<0;1>/*,[3f007faa/48h/1h/0h/2h]tpubDEgyzFTDNEUcy674okNRZFuV1Q3P3RNdhd5FwncHBZ9DpZNHR3FGm5c4n8co1Efg3Xv6cUCPuPraJ85j8CV2QXqhLdXn38uyNoSX3rVMpbC/<0;1>/*,[c478c82d/48h/1h/0h/2h]tpubDFKmAnxyJKb7LLQ2UDU4ytFZ1Lx5R7C9op23Ew7zxDwCHDMUhqWfmgMi7d6YNSfKnsW3wp9QEU4TuNJxcPCcAi4ddCYsVL9ken6tWGPD9jz/<0;1>/*))#3l992dql"

You can retrieve the wallet descriptor for practically any wallet using Sparrow Wallet by opening the wallet, going to Settings >> Script Policy >> Descriptor Edit. A window will pop-up where you can copy the wallet descriptor string and paste it as the descriptor = value of the sentrum.toml.

Not all scripts are supported. sentrum depends on bdk which only supports these scripts.

Actions

For each new relevant transaction, you can take multiple actions. For each action you desire to take, you need to add the configuration:

[[actions]]
# Action type (required)
type =  "<INSERT ACTION KIND>"
<.... INSERT ACTION SPECIFIC CONFIGURATION HERE...>

Below we explain the configuration for each action kind. You can have multiple actions of the same kind (e.g. you want to send multiple emails from different accounts for some reason).

ntfy

This is the best straightforward way to get push notifications on a smartphone.

  1. Install the android/iOS app following the relevant links in https://ntfy.sh
  2. Open the app, give it the needed permissions

Then you just need to add the relevant configuration:

[[actions]]
type =  "ntfy"
#
# EVERYTHING BELOW IS OPTIONAL
#
# Credentials (optional, relevant for self-hosted instances or paid reserved topics)
# You can also use an access token by setting the username to an empty string ""
#credentials.username = "<YOUR USERNAME HERE>"
#credentials.password = "<YOUR PASSWORD HERE>"
# ntfy server (optional)
#url = "https://ntfy.sh"
# notification channel name (optional, defaults to random string for security)
#topic = "<RANDOM TOPIC NAME>"
# Proxy used to connect (optional, defaults to None)
#proxy = "socks5://127.0.0.1:9050"
# Priority ("max", "high", "default", "low", "min") (optional)
#priority = "default"

If you don't set a topic = , sentrum will auto-generate one for you randomly (since topic names are kind of like a password for the public default ntfy.sh server). When you later run sentrum, it will print out the topic name it's using.

Open the ntfy app, click on the + button, create a "topic" and set the same equal to the one should be the sentrum logs.

nostr

Get notified by a nostr NIP04 encrypted DM (leaks metadata but widely supported) or a NIP59 GiftWrap sealed sender DM (more private but not supported by many clients). Add:

[[actions]]
type = "nostr"
# Which npub to send the DM (required)
recipient = "<YOUR npub, hex pubkey, nprofile or nip05>"
# If NIP59 giftwrap DMs should be used instead of NIP04 (optional)
#sealed_dm = false
# Which relays to use to send DMs
#relays = ["wss://nostr.bitcoiner.social", "wss://nostr.oxtr.dev", "wss://nostr.orangepill.dev", "wss://relay.damus.io"]

email

You need to add the configuration below and essentially configure an authenticated connection to your email provider's SMTP server. I cannot help you out with every provider's weird rules (maybe you need to allow 3rd party apps for gmail, who knows).

[[actions]]
type =  "email"
# SMTP server (required)
server = "<insert smtp server url (e.g. smtp.gmail.com)"
# SMTP connection type ("tls", "starttls" or "plain") (optional)
#connection = "tls"
# SMTP port (optional, defaults to 587 for TLS, 465 for STARTTLS and 25 for plain connections
#port = 1025
# SMTP credentials (required in most cases)
credentials.authentication_identity = "<insert login email>"
credentials.secret = "<insert password>"
# Accept self signed certificates (needed if you are using protonmail-bridge) (optional)
#self_signed_cert = false
# Configure sender (required)
from = "sentrum <[email protected]>"
# Configure recipient (optional, defaults to the same as the "from" sender)
#to = "sentrum <[email protected]>"

telegram

  1. Create a new bot using @Botfather to get a token in the format 123456789:blablabla.
  2. Optionally configure the bot (name, profile pic, etc) with @Botfather
  3. Open a chat with your bot
  4. Add the relevant config:
[[actions]]
type =  "telegram"
# Auth token of the bot created with @Botfather (required)
bot_token = "<insert bot token>"
# 10-digit user id of the DM recipient, go to your profile to get it (required)
user_id = 1234567890

command

Runs an external command where you can use transaction details as arguments. You can check what parameters (such as {wallet} or {tx_net} you can use in the message configuration, since they are the same.

[[actions]]
type = "command"
cmd = "notify-send"
args = ["[{wallet}] new tx: {tx_net} sats"]

terminal_print

Justs prints the notification text in the terminal. You can potentially pipe it to something else.

[[actions]]
type =  "terminal_print"

desktop_notification

Displays the transaction message as a native desktop notification on the same computer sentrum is running.

[[actions]]
type =  "desktop_notification"

Message

You can configure the message template and it applies to almost every action type. This configuration is entirely optional since the default templates will be used if omitted.

Here is the default template:

[message]
subject = "[{wallet}] new transaction"
body = "net: {tx_net} sats, balance: {total_balance} sats, txid: {txid_short}"
# Can be "plain", "markdown" or "html"
format = "plain"
# Configure blockexplorer urls. This is used to create the {tx_url} parameter
block_explorers.mainnet = "https://mempool.space/tx/{txid}"
block_explorers.testnet = "https://mempool.space/testnet/tx/{txid}"
block_explorers.signet = "https://mempool.space/signet/tx/{txid}"

In the subject and body templates, you can use the following parameters:

  • {tx_net}: difference between the owned outputs and owned inputs
  • {wallet}: name of the configured wallet
  • {total_balance}: total balance of the wallet
  • {txid}: txid of the transaction
  • {txid_short}: truncated txid, easier on the eyes
  • {received}: sum of owned outputs
  • {sent}: sum of owned inputs
  • {fee}: transaction fee
  • {current_height}: current blockheight
  • {tx_height}: blockheight transaction confirmation
  • {confs}: number of transaction confirmations (0 for unconfirmed)
  • {conf_timestamp}: timestamp of the first confirmation in the %Y-%m-%d %H:%M:%S format
  • {tx_url}: a block explorer URL to the transaction

Electrum server

By default, public electrum servers will be used. I strongly suggest configuring your own electrum server if you want privacy (as you should).

The defaults are:

[electrum]
# Defaults:
# - mainnet: ssl://fulcrum.sethforprivacy.com:50002
# - testnet: ssl://electrum.blockstream.info:60002
# - signet: ssl://mempool.space:60602
# Use "tcp://" if you are connecting without SSL (e.g. "tcp://localhost:50001"
# or "tcp://fwafiuesngirdghrdhgiurdhgirdgirdhgrd.onion:50001"
url = "ssl://fulcrum.sethforprivacy.com:50002"
# blockchain network ("bitcoin", "testnet", "signet", "regtest")
network = "bitcoin"
# Optional socks5 proxy (defaults to None)
#socks5 = 127.0.0.1:9050
# If using ssl with a trusted certificate, set this to true
certificate_validation = false

Usage

Just run sentrum without arguments (uses default config search paths) or sentrum <path/to/config/file>.

You can pass the --test flag to send a single test notification to all configured actions.

By default, only new transactions can trigger actions. If you pass --notify-past-txs, it will send notifications of past transactions in the initial wallet sync. If you have a long transaction history, this will spam your notification channels for every transaction.

systemd service

The ideal use-case is as a long running daemon, so it makes sense to configure it as a systemd service.

If you installed sentrum from the AUR, you just need to edit /etc/sentrum/sentrum.conf and do sudo systemclt enable --now sentrum.service

If you are installing sentrum manually (e.g. from the releases page or cargo install), you should (either from the cloned repository or from inside the extracted release archive):

  1. Copy systemd files to appropriate places:
sudo cp contrib/systemd/sentrum.service /etc/systemd/system
sudo cp contrib/systemd/sentrum.sysusers /etc/sysusers.d/sentrum.conf
sudo cp contrib/systemd/sentrum.tmpfiles /etc/tmpfiles.d/sentrum.conf
  1. Reload systemd daemon, sysusers and tmpfiles:
sudo systemclt daemon-reload
sudo systemd-sysusers
sudo systemd-tmpfiles --create
  1. Place the sentrum.toml (or sentrum.sample.toml) configuration file in /etc/sentrum and make sure the sentrum user owns it:
sudo cp sentrum.toml /etc/sentrum
sudo chown sentrum:sentrum /etc/sentrum/sentrum.toml
  1. Enable and start the service:
sudo systemclt enable --now sentrum.service

  1. Check if everything is fine with systemctl status sentrum

  2. Check the logs with journalctl -fu sentrum

Docker

To run sentrum using Docker, you can either build the image yourself or use the prebuilt image.

Building the image

To build the image from source, run the following:

git clone https://github.com/sommerfelddev/sentrum.git
cd sentrum
docker build -t sentrum:local .

To use the prebuilt image, simply pull from GHCR:

docker pull docker pull ghcr.io/sommerfelddev/sentrum:latest

Note that there are two types of tags:

latest: a tag from the latest commit to master x.x.x: (i.e. 0.1.1) a tag of the corresponding sentrum version

Running the image

To run the image, simply run the following, passing in the sentrum.toml file you created and configured earlier:

docker run --rm -it --volume ./sentrum.toml:/sentrum.toml ghcr.io/sommerfelddev/sentrum:latest

If using Docker compose, you can configure the service as follows:

services:
  sentrum:
    container_name: sentrum
    image: ghcr.io/sommerfelddev/sentrum:latest
    restart: unless-stopped
    volumes:
      - ./sentrum.toml:/sentrum.toml

Future Work

  • More action types:
    • Matrix DM
    • SimpleX chat DM
    • IRC
    • XMPP
    • Whatsapp/Signal using linked devices (harder)
    • HTTP request
  • More wallet types:
  • Notifications for the first tx confirmation and after N confirmations
  • Filtering notifications by the transaction amounts (e.g. no action for transactions smaller than 1M sats)
  • Debian package (using cargo-deb)
  • Allow per wallet actions
  • Support other blockchain backends (bitcoind-rpc, explora, block filters, dojo)
  • Maybe create a little web UI that helps with writing the configuration
  • Incentivize node distributions to package sentrum