aboutsummaryrefslogtreecommitdiffstatshomepage

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).

Installation

Either:

  • Compile from source using cargo install sentrum (binary will be installed in ~/.cargo/bin)
  • Download the binary from the releases page
  • If using archlinux, install it from the AUR: sentrum 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
sudo cp sentrum.sample.toml /etc/sentrum/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).

More complex wallet types are supported by providing primary = "<desc>" and change = "<desc>" wallet descriptors instead of xpub = and kind =.

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. If you don't run your own ntfy self-hosted server, create an account at ntfy.sh
  3. Open the app, give it the needed permissions and configure your account credentials
  4. Click on the + button and create a "topic", preferably named sentrum since that's what will be used by default.

Then you just need to add the relevant configuration:

[[actions]]
type =  "ntfy"
# Credentials (required if you use a public server like the default one)
credentials.username = "<YOUR USERNAME HERE>"
credentials.password = "<YOUR PASSWORD HERE>"
# ntfy server (optional)
#url = "https://ntfy.sh"
# notification channel name (optional)
#topic = "sentrum"
# Proxy used to connect (optional, defaults to None)
#proxy = "socks5://127.0.0.1:9050"
# Priority ("max", "high", "default", "low", "min") (optional)
#priority = "default"

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 <youremailhere@host.tld>"
# Configure recipient (optional, defaults to the same as the "from" sender)
#to = "sentrum <youremailhere@host.tld>"

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 are installing sentrum manually (e.g. from the releases page), you should:

  1. Create a new sentrum user:
sudo useradd -d /var/lib/sentrum -m sentrum
  1. Place the sentrum.toml configuration file in /etc/sentrum:
sudo mkdir -p /etc/sentrum
sudo cp sentrum.toml /etc/sentrum
sudo chown -R sentrum:sentrum /etc/sentrum

  1. Copy the contrib/sentrum.service into the /etc/systemd/system

  2. Reload systemd so that the service file can be found:

sudo systemclt daemon-reload
  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:
    • Single Address (blocked by https://github.com/bitcoindevkit/bdk/issues/759)
    • Collections of wallets as a single entity
  • 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
generated by cgit v1.2.3-70-g09d2 (git 2.47.0) at 2024-12-12 09:50:14 +0000