6 releases
0.4.0 | Oct 9, 2024 |
---|---|
0.3.7 | Sep 21, 2024 |
0.3.6 | May 14, 2024 |
0.3.3 | Apr 20, 2024 |
#11 in #e-cash
258 downloads per month
125KB
2.5K
SLoC
fedimint-clientd: A Fedimint Client for Server Side Applications
fedimint-clientd runs a fedimint client with Ecash, Lightning, and Onchain modules to let a server side application hold and use Bitcoin with Fedimint. It exposes a REST API & provides wrappers in typescript, python, golang, and elixir. It uses the multimint
crate to manage clients connected to multiple Federations from a single fedimint-clientd
instance.
This project is intended to be an easy-to-use starting point for those interested in adding Fedimint client support to their applications. Fedimint-clientd only exposes Fedimint's default modules, and any more complex Fedimint integration will require custom implementation using Fedimint's rust crates.
Getting Started
You can install the cli app with cargo install fedimint-clientd
or by cloning the repo and running cargo build --release
in the root directory.
fedimint-clientd
runs from the command line and takes a few arguments, which are also available as environment variables. Fedimint uses rocksDB, an embedded key-value store, to store its state. The --fm_db_path
argument is required and should be an absolute path to a directory where the database will be stored.
CLI USAGE:
fedimint-clientd \
--db-path=/absolute/path/to/dir/to/store/database \
--password="some-secure-password-that-becomes-the-bearer-token" \
--addr="127.0.0.1:8080"
--mode="rest"
--invite-code="fed1-fedimint-invite-code"
ENV USAGE:
FEDIMINT_CLIENTD_DB_PATH=/absolute/path/to/dir/to/store/database
FEDIMINT_CLIENTD_PASSWORD="some-secure-password-that-becomes-the-bearer-token"
FEDIMINT_CLIENTD_ADDR="127.0.0.1:8080"
FEDIMINT_CLIENTD_MODE="rest"
FEDIMINT_CLIENTD_INVITE_CODE="fed1-fedimint-invite-code"
Fedimint Clientd Endpoints
fedimint-clientd
supports the following endpoints (and has naive websocket support at /fedimint/v2/ws
, see code for details until I improve the interface. PRs welcome!). All the endpoints are authed with a Bearer token from the password (from CLI or env). You can hit the endpoints as such with curl, or use the python/typescript/golang wrappers:
curl http://localhost:3333/fedimint/v2/admin/info -H 'Authorization: Bearer some-secure-password-that-becomes-the-bearer-token'
Admin related commands:
/fedimint/v2/admin/info
: Display wallet info (holdings, tiers)./fedimint/v2/admin/backup
: Upload the (encrypted) snapshot of mint notes to federation./fedimint/v2/admin/discover-version
: Discover the common api version to use to communicate with the federation./fedimint/v2/admin/restore
: Restore the previously created backup of mint notes (withbackup
command)./fedimint/v2/admin/list-operations
: List operations./fedimint/v2/admin/module
: Call a module subcommand./fedimint/v2/admin/config
: Returns the client config.
Mint related commands:
/fedimint/v2/mint/reissue
: Reissue notes received from a third party to avoid double spends./fedimint/v2/mint/spend
: Prepare notes to send to a third party as a payment./fedimint/v2/mint/validate
: Verifies the signatures of e-cash notes, but not if they have been spent already./fedimint/v2/mint/split
: Splits a string containing multiple e-cash notes (e.g. from thespend
command) into ones that contain exactly one./fedimint/v2/mint/combine
: Combines two or more serialized e-cash notes strings.
Lightning network related commands:
/fedimint/v2/ln/invoice
: Create a lightning invoice to receive payment via gateway./fedimint/v2/ln/await-invoice
: Wait for incoming invoice to be paid./fedimint/v2/ln/pay
: Pay a lightning invoice or lnurl via a gateway./fedimint/v2/ln/await-pay
: Wait for a lightning payment to complete./fedimint/v2/ln/list-gateways
: List registered gateways./fedimint/v2/ln/switch-gateway
: Switch active gateway.
Onchain related commands:
/fedimint/v2/onchain/deposit-address
: Generate a new deposit address, funds sent to it can later be claimed./fedimint/v2/onchain/await-deposit
: Wait for deposit on previously generated address./fedimint/v2/onchain/withdraw
: Withdraw funds from the federation.
Extra endpoints:
/health
: health check endpoint./metrics
: exports API metrics using opentelemetry with prometheus exporter (num requests, latency, high-level metrics only)
Dependencies
~101MB
~2M SLoC