Wallet creation
Compiles declarative spending conditions (single sig, sortedmulti, taproot multisig with NUMS internal key, primary + time-locked recovery) into Bitcoin descriptors.
walletrs
walletrs is a standalone Bitcoin wallet service written in Rust. It speaks both gRPC and HTTP/JSON against the same handler set, supports multisig and miniscript policies, taproot leaf-hash spends, and the full PSBT lifecycle. It is built on BDK and rust-miniscript, with a vendored fork of Liana for primary + time-locked recovery descriptor compilation.
It is the wallet engine behind Sigvault, but it is also a self-contained OSS service that any operator can deploy on its own, BSD-3-Clause licensed.
What it does
Section titled “What it does”Key management
Imports customer xpubs and generates system-managed keys with envelope-encrypted private material under a 32-byte KEK.
PSBT lifecycle
Funds, signs, finalizes, and broadcasts PSBTs. Resolves taproot leaf hashes back to BDK policy paths so clients can pick the spending route.
Pluggable storage
Local filesystem or S3-compatible object storage (Cloudflare R2, MinIO, AWS S3) with envelope-encrypted writes for sensitive blobs.
Two surfaces, one handler set
Section titled “Two surfaces, one handler set”walletrs exposes the same RPCs over two wire formats:
- gRPC on the configured
WALLETRS_PORT(default50051). Use this for server-to-server traffic when you have tonic / grpcio / grpc-go in your stack. - HTTP/JSON on
WALLETRS_HTTP_PORT(default8080). Routes are derived at build time from(google.api.http)annotations onproto/walletrpc.protoand exposed atPOST /wallet/<snake_case_method>. Use this from browsers, curl, scripts, or any polyglot client without protoc tooling.
Bearer-token auth is shared between both surfaces. The Ping RPC bypasses on both.
What it does not do
Section titled “What it does not do”- Multi-tenancy. One walletrs instance serves one logical owner. Deploy multiple instances if you need tenant isolation.
- TLS termination. Run it behind a reverse proxy (Caddy, Traefik, nginx) when exposing it across a network boundary.
- Hardware-wallet integration. The signer flow assumes managed keys live in walletrs’ encrypted store. HWW signing happens client-side; walletrs accepts pre-signed PSBTs.
Where to start
Section titled “Where to start”Quickstart
Bring up walletrs with the bundled Docker Compose stack (regtest bitcoind + electrs + walletrs) in one command.
Architecture
How the gRPC + HTTP gateway, storage layer, signer, and wallet pipeline fit together.
Configuration
Every knob is an environment variable. The full list, with defaults and when each is required.
API: HTTP / JSON
The full RPC ↔ HTTP path table, request/response shapes, JSON encoding rules, and curl examples.
Status
Section titled “Status”Pre-1.0. The wire contract (proto/walletrpc.proto) is stable in spirit but may still gain fields. Track the CHANGELOG before integrating.