From f06b05f79738bd36a804d5ebb01ae52b1c868be0 Mon Sep 17 00:00:00 2001
From: sommerfeld <sommerfeld@sommerfeld.dev>
Date: Wed, 24 Apr 2024 10:05:42 +0100
Subject: Add man file

---
 contrib/man/sentrum.1 | 543 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 543 insertions(+)
 create mode 100644 contrib/man/sentrum.1

(limited to 'contrib/man')

diff --git a/contrib/man/sentrum.1 b/contrib/man/sentrum.1
new file mode 100644
index 0000000..580db48
--- /dev/null
+++ b/contrib/man/sentrum.1
@@ -0,0 +1,543 @@
+.nh
+.TH sentrum
+.PP
+
+
+
+
+
+.PP
+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).
+
+.SH Installation
+.PP
+Either:
+
+.RS
+.IP \(bu 2
+Compile from source using \fBcargo install sentrum\fR (binary will be installed in
+\fB~/.cargo/bin\fR)
+.IP \(bu 2
+Download the binary from the
+releases page
+\[la]https://github.com/sommerfelddev/sentrum/releases\[ra]
+.IP \(bu 2
+If using archlinux, install it from the AUR:
+sentrum
+\[la]https://aur.archlinux.org/packages/sentrum\[ra] or sentrum-git
+\[la]https://aur.archlinux.org/packages/sentrum\-git\[ra]
+
+.RE
+
+.SH Configuration
+.SS Config file path
+.PP
+It will look for a \fBsentrum.toml\fR configuration file located in any of these
+directories (with this priority):
+
+.RS
+.IP "  1." 5
+Current working directory
+.IP "  2." 5
+\fB$XDG_CONFIG_HOME/sentrum\fR
+.IP "  3." 5
+\fB~/.config/sentrum\fR
+.IP "  4." 5
+\fB/etc/sentrum\fR (more appropriate if running as a systemd service)
+
+.RE
+
+.PP
+Alternatively, you can pass the configuration file path as an argument in the
+invocation and that will override any of the above.
+
+.PP
+\fBStart by copying the sample configuration to where you want it.\fP E.g.
+
+.EX
+cp sentrum.sample.toml sentrum.toml
+sudo cp sentrum.sample.toml /etc/sentrum/sentrum.toml
+.EE
+
+.PP
+or
+
+.EX
+sudo cp sentrum.sample.toml /etc/sentrum/sentrum.toml
+.EE
+
+.SS What to configure
+.PP
+You can use the 
+\[la]sentrum.sample.toml\[ra] file as an
+example.
+Most options have very good defaults so you don't need to change them unless you
+want to. \fBIn the examples below, commented options showcase their defaults,
+unless explicitly said otherwise.\fP
+
+.SS Required
+.RS
+.IP \(bu 2
+\fBwallets\fR: what wallets you want to monitor
+.IP \(bu 2
+\fBactions\fR: what actions you want to take once a relevant transaction is found
+
+.RE
+
+.SS Optional
+.RS
+.IP \(bu 2
+\fBelectrum\fR: by default, public electrum servers are used. You can configure it
+to connect to your own
+.IP \(bu 2
+\fBmessage\fR: 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
+
+.RE
+
+.SH Wallets
+.PP
+For each wallet you want to track, add the following configuration:
+
+.EX
+[[wallets]]
+# Identifier for naming purposes (required)
+name = "alice"
+# Wallet xpub (required)
+xpub = "xpub6CkXHzuU1NyHUFNiQZLq2bgt6QPqjZbwpJ1MDgDeo4bWZ8ZP7HZr7v9WTLCQFhxVhqiJNcw5wSKE77rkAK1SzcuHjt36ZUibBHezGzGL9h9"
+# Script kind ("legacy","nested_segwit","segwit","taproot") (optional)
+#kind = "segwit"
+.EE
+
+.PP
+It assumes a BIP84 (native segwit, \fBbc1\fR style addresses) wallet. If your wallet
+has a different script kind add the field \fBkind = "legacy"\fR (or \fBnested_segwit\fR,
+or \fBtaproot\fR).
+
+.PP
+More complex wallet types are supported by providing \fBprimary = "<desc>"\fR and
+\fBchange = "<desc>"\fR wallet descriptors instead of \fBxpub =\fR and \fBkind =\fR\&.
+
+.SH Actions
+.PP
+For each new relevant transaction, you can take multiple actions. For each
+action you desire to take, you need to add the configuration:
+
+.EX
+[[actions]]
+# Action type (required)
+type =  "<INSERT ACTION KIND>"
+<.... INSERT ACTION SPECIFIC CONFIGURATION HERE...>
+.EE
+
+.PP
+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).
+
+.SS ntfy
+.PP
+This is the best straightforward way to get push notifications on a smartphone.
+
+.RS
+.IP "  1." 5
+Install the android/iOS app following the relevant links in https://ntfy.sh
+.IP "  2." 5
+If you don't run your own ntfy self-hosted server, create an account at
+ntfy.sh
+.IP "  3." 5
+Open the app, give it the needed permissions and configure your account
+credentials
+.IP "  4." 5
+Click on the \fB+\fR button and create a "topic", preferably named \fBsentrum\fR
+since that's what will be used by default.
+
+.RE
+
+.PP
+Then you just need to add the relevant configuration:
+
+.EX
+[[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"
+.EE
+
+.SS nostr
+.PP
+Get notified by a nostr NIP04 encrypted
+DM
+\[la]https://github.com/nostr\-protocol/nips/blob/master/04.md\[ra] (leaks metadata
+but widely supported) or a
+NIP59 GiftWrap sealed sender DM
+\[la]https://github.com/nostr\-protocol/nips/blob/master/59.md\[ra]
+(more private but not supported by many clients). Add:
+
+.EX
+[[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"]
+.EE
+
+.SS email
+.PP
+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).
+
+.EX
+[[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>"
+.EE
+
+.SS telegram
+.RS
+.IP "  1." 5
+Create a new bot using @Botfather
+\[la]https://t.me/botfather\[ra] to get a token in the format \fB123456789:blablabla\fR\&.
+.IP "  2." 5
+Optionally configure the bot (name, profile pic, etc) with @Botfather
+.IP "  3." 5
+Open a chat with your bot
+.IP "  4." 5
+Add the relevant config:
+
+.RE
+
+.EX
+[[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
+.EE
+
+.SS command
+.PP
+Runs an external command where you can use transaction details as arguments.
+You can check what parameters (such as \fB{wallet}\fR or \fB{tx_net}\fR you can use in
+the message
+\[la]#message\[ra] configuration, since they are the same.
+
+.EX
+[[actions]]
+type = "command"
+cmd = "notify-send"
+args = ["[{wallet}] new tx: {tx_net} sats"]
+.EE
+
+.SS terminal_print
+.PP
+Justs prints the notification text in the terminal. You can potentially pipe it
+to something else.
+
+.EX
+[[actions]]
+type =  "terminal_print"
+.EE
+
+.SS desktop_notification
+.PP
+Displays the transaction message as a native desktop notification on the same
+computer sentrum is running.
+
+.EX
+[[actions]]
+type =  "desktop_notification"
+.EE
+
+.SH Message
+.PP
+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.
+
+.PP
+Here is the default template:
+
+.EX
+[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}"
+.EE
+
+.PP
+In the subject and body templates, you can use the following parameters:
+
+.RS
+.IP \(bu 2
+\fB{tx_net}\fR: difference between the owned outputs and owned inputs
+.IP \(bu 2
+\fB{wallet}\fR: name of the configured wallet
+.IP \(bu 2
+\fB{total_balance}\fR: total balance of the wallet
+.IP \(bu 2
+\fB{txid}\fR: txid of the transaction
+.IP \(bu 2
+\fB{txid_short}\fR: truncated txid, easier on the eyes
+.IP \(bu 2
+\fB{received}\fR: sum of owned outputs
+.IP \(bu 2
+\fB{sent}\fR: sum of owned inputs
+.IP \(bu 2
+\fB{fee}\fR: transaction fee
+.IP \(bu 2
+\fB{current_height}\fR: current blockheight
+.IP \(bu 2
+\fB{tx_height}\fR: blockheight transaction confirmation
+.IP \(bu 2
+\fB{confs}\fR: number of transaction confirmations (0 for unconfirmed)
+.IP \(bu 2
+\fB{conf_timestamp}\fR: timestamp of the first confirmation in the \fB%Y-%m-%d %H:%M:%S\fR format
+.IP \(bu 2
+\fB{tx_url}\fR: a block explorer URL to the transaction
+
+.RE
+
+.SH Electrum server
+.PP
+By default, public electrum servers will be used. I \fBstrongly suggest
+configuring your own electrum server if you want privacy (as you should)\fP\&.
+
+.PP
+The defaults are:
+
+.EX
+[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
+.EE
+
+
+.SH Usage
+.PP
+Just run \fBsentrum\fR without arguments (uses default config search paths) or
+\fBsentrum <path/to/config/file>\fR\&.
+
+.PP
+You can pass the \fB--test\fR flag to send a single test notification to all
+configured actions.
+
+.PP
+By default, only new transactions can trigger actions. If you pass
+\fB--notify-past-txs\fR, 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.
+
+.SH systemd service
+.PP
+The ideal use-case is as a long running daemon, so it makes sense to configure
+it as a systemd service.
+
+.PP
+If you installed sentrum from the AUR, you just need to edit
+\fB/etc/sentrum/sentrum.conf\fR and do \fBsudo systemclt enable --now sentrum.service\fR
+
+.PP
+If you are installing \fBsentrum\fR manually (e.g. from the releases page or \fBcargo
+install\fR), you should (either from the cloned repository or from inside the
+extracted release archive):
+
+.RS
+.IP "  1." 5
+Copy systemd files to appropriate places:
+
+.RE
+
+.EX
+sudo cp contrib/systemd/sentrum.service
+sudo cp contrib/systemd/sentrum.sysusers /etc/sysusers.d/sentrum.conf
+sudo cp contrib/systemd/sentrum.tmpfiles /etc/tmpfiles.d/sentrum.conf
+.EE
+
+.RS
+.IP "  1." 5
+Reload systemd daemon, sysusers and tmpfiles:
+
+.RE
+
+.EX
+sudo systemclt daemon-reload
+sudo systemd-sysusers
+sudo systemd-tmpfiles --create
+.EE
+
+.RS
+.IP "  1." 5
+Place the \fBsentrum.toml\fR (or \fBsentrum.sample.toml\fR) configuration file in
+\fB/etc/sentrum\fR and make sure the \fBsentrum\fR user owns it:
+
+.RE
+
+.EX
+sudo cp sentrum.toml /etc/sentrum
+sudo chown sentrum:sentrum /etc/sentrum/sentrum.toml
+.EE
+
+.RS
+.IP "  1." 5
+Enable and start the service:
+
+.RE
+
+.EX
+sudo systemclt enable --now sentrum.service
+.EE
+
+.RS
+.IP "  1." 5
+Check if everything is fine with \fBsystemctl status sentrum\fR
+.IP "  2." 5
+Check the logs with \fBjournalctl -fu sentrum\fR
+
+.RE
+
+.SH Docker
+.PP
+To run sentrum using Docker, you can either build the image yourself or use the prebuilt image.
+
+.SS Building the image
+.PP
+To build the image from source, run the following:
+
+.EX
+git clone https://github.com/sommerfelddev/sentrum.git
+cd sentrum
+docker build -t sentrum:local .
+.EE
+
+.PP
+To use the prebuilt image, simply pull from GHCR:
+
+.EX
+docker pull docker pull ghcr.io/sommerfelddev/sentrum:latest
+.EE
+
+.PP
+Note that there are two types of tags:
+
+.PP
+\fBlatest\fR: a tag from the latest commit to master
+\fBx.x.x\fR: (i.e. \fB0.1.1\fR) a tag of the corresponding sentrum version
+
+.SS Running the image
+.PP
+To run the image, simply run the following, passing in the \fBsentrum.toml\fR file you created and configured earlier:
+
+.EX
+docker run --rm -it --volume ./sentrum.toml:/sentrum.toml ghcr.io/sommerfelddev/sentrum:latest
+.EE
+
+.PP
+If using Docker compose, you can configure the service as follows:
+
+.EX
+services:
+  sentrum:
+    container_name: sentrum
+    image: ghcr.io/sommerfelddev/sentrum:latest
+    restart: unless-stopped
+    volumes:
+      - ./sentrum.toml:/sentrum.toml
+.EE
+
+.SH Future Work
+.RS
+.IP \(bu 2
+More action types:
+.RS
+.IP \(bu 2
+Matrix DM
+.IP \(bu 2
+SimpleX chat DM
+.IP \(bu 2
+IRC
+.IP \(bu 2
+XMPP
+.IP \(bu 2
+Whatsapp/Signal using linked devices (harder)
+.IP \(bu 2
+HTTP request
+
+.RE
+
+.IP \(bu 2
+More wallet types:
+.RS
+.IP \(bu 2
+Single Address (blocked by
+https://github.com/bitcoindevkit/bdk/issues/759)
+.IP \(bu 2
+Collections of wallets as a single entity
+
+.RE
+
+.IP \(bu 2
+Notifications for the first tx confirmation and after N confirmations
+.IP \(bu 2
+Filtering notifications by the transaction amounts (e.g. no action for
+transactions smaller than 1M sats)
+.IP \(bu 2
+Debian package (using \fBcargo-deb\fR)
+.IP \(bu 2
+Allow per wallet actions
+.IP \(bu 2
+Support other blockchain backends (bitcoind-rpc, explora, block filters, dojo)
+.IP \(bu 2
+Maybe create a little web UI that helps with writing the configuration
+.IP \(bu 2
+Incentivize node distributions to package sentrum
+
+.RE
-- 
cgit v1.2.3-70-g09d2