such-gitea
9536dd099c
Premium could invoice through exactly one processor, so an operator running BTCPay for BTC, LTC and Grin could not also take Monero or Wownero: BTCPay has no Wownero support, and this operator runs Monero through its own checkout rather than the BTCPay plugin. xmrcheckout and wowcheckout implement the same two Greenfield invoice routes, accept the same `token` auth and report the same statuses, so the existing adapter serves them unchanged. What was missing was more than one of them. Each is now an optional rail with its own URL, store and key (PAYMENT_XMRCHECKOUT_* and PAYMENT_WOWCHECKOUT_*), all three values or none, and a half-configured rail refuses to start and names itself rather than advertising a coin that cannot be paid. The invoice row already recorded which provider minted it; activation now polls that one, never whichever is primary today. An invoice whose rail was switched off is refused and left unconsumed, so turning the rail back on lets the user redeem what they paid. A client that names a rail the instance does not offer is refused rather than handed an invoice in a different coin; a client that names none gets the primary, which is how every client before this behaved. Registration is untouched and keeps the primary. /capabilities lists the rails and their assets, primary first, from config alone, so it never depends on a processor being reachable. PAYMENT_ASSETS labels the primary. Checkout rails also get an exact confirmationsRequired, which BTCPay Server is not sent since it only has speedPolicy buckets.
smirk-backend-core
Open, self-hostable backend for the Smirk non-custodial multi-chain wallet. Rust + Axum + PostgreSQL.
It gives a wallet chain access (balances, history, UTXOs, spend inputs, fee estimation, broadcast), Nostr-native identity, a fiat price feed, an async Grin slatepack relay, and a public social-tips subsystem, all without ever holding a spend key or seed. Run your own; the wallet is backend-agnostic.
Status: v0.3.0 — feature-complete and security-reviewed, but young. The schema/API may still evolve. Run your own chain backends where you can, review the code, and treat early deployments accordingly.
Non-custodial by construction
The server stores public addresses, public keys, and (for Monero/Wownero) incoming view keys only — never a spend key, never a seed. View credentials are forwarded per request to the chain backends that scan with them and are not persisted here. The wallet signs and broadcasts locally; the backend reads chains and relays bytes.
Chains
| Chain | Source | Notes |
|---|---|---|
| Bitcoin, Litecoin | Electrum / Fulcrum | reads, fee estimation, broadcast |
| Monero, Wownero | light-wallet-server (LWS) | stateless view-key forwarding |
| Grin | grin-lws (default) / grin-wallet (view-only) + node | rewind_hash scan, broadcast, slatepack relay; scans proxy to grin-lws when configured, falling back to the authoritative grin-wallet scan |
Each chain is independently feature-flagged; a chain whose source isn't configured
is reported enabled: false by /capabilities rather than failing at call time.
API
The HTTP contract is generated from the handlers and committed to
openapi.json — the single source of truth for the API and the
wallet's generated client. A CI gate fails the build on any drift.
Public surface (/api/v1):
- Identity & auth — NIP-98 (Nostr) sign-in + link, wallet-signature auth,
audience-separated JWT sessions, NIP-05 directory (
/.well-known/nostr.json). - Chain access — per-chain balance / history / UTXOs / spend inputs / fee / broadcast.
- Grin relay — non-custodial store-and-forward mailbox for interactive Grin transfers (feature-flagged).
- Social tips (
/tips/social/*, feature-flagged): the public send-a-tip surface across BTC/LTC/XMR/WOW and Grin. Roughly ten endpoints cover the lifecycle: create (two-phase draft), attach-funding, public metadata for a share-URL holder, sent, received, claimable, cancel, claim, confirm-sweep, and clawback. ATipStatusstate machine (draft → pending_confirmation → pending → claiming → claimed, pluscancelled/clawed_back/funding_mismatch) governs the row. The backend never holds the spend key: for BTC/LTC/XMR/WOW the tip key rides the share URL; Grin tips use a voucher/commitment model verified against the node'sget_outputs/get_kernel. Three background workers keep it honest, and every one leaves a row untouched on any upstream error (never a status flip): a funding verifier (confirmation-count + on-chain amount check before a tip becomes claimable), a sweep reconciler (settlesclaiming → claimedonly after the claim sweep confirms on-chain to the per-asset depth, with reorg revert), and lifecycle/draft GC janitors for abandoned rows. - Capabilities (
/capabilities) — what this instance enables, so the wallet adapts per-instance. - Prices (
/prices) — cached fiat feed, per-feed operator control. - Self-service erasure (
/account/erasure,/account/export) — action-bound, two-phase delete-my-data + export. - Health (
/health) and an optional, default-off public landing (/).
Operator surface
Operator/admin functions live on a separate loopback listener (front it with Tor or an SSH tunnel) — confidentiality by socket, never merged into the public router or OpenAPI.
- Operator Console: an embedded single-page app served at
/adminon the loopback admin plane. Sign in with your admin key, then review status, manage admin keys and invite codes, and edit the runtime config overlay (env plus a validated DB layer). Guide: docs/operations/CONSOLE.md. - Sign-in-with-Smirk admin auth — a NIP-98 signed action over a single-use nonce (AUTHN) + a MAC-protected key allowlist (AUTHZ), composed so a route can't run without both.
- First-run bootstrap — an explicit, MAC-protected latch (no trust-on-first- use); a live deployment adopts as already-bootstrapped; tampering fails closed.
smirk-adminCLI — break-glass key management,create-admin-wallet(zeroized),doctor. Talks to Postgres directly, bypassing the network plane.- Tamper-evident audit — privileged actions are written to a hash-chained audit trail, fail-closed (the state change rolls back if the audit write fails).
Running it
Requires Rust (stable) and PostgreSQL.
cp .env.example .env # then edit: DATABASE_URL + the required secrets
createdb smirk_backend_core # or point DATABASE_URL at an existing database
cargo run --release # migrations run automatically on startup
The server fails closed: it refuses to start on a missing/weak secret or an
inconsistent feature configuration rather than booting with a control silently
defeated. Generate secrets with openssl rand -hex 32. See
.env.example for the full, documented configuration surface.
First admin (headless bootstrap) — run one of these; both latch, so the other is refused afterward by design:
smirk-admin setup --pubkey <x-only-hex> # seed YOUR pubkey (active immediately)
smirk-admin create-admin-wallet --out key.hex # generate a key (pending) + latch, no setup needed
<x-only-hex> is the admin's Sign-in-with-Smirk (Nostr) public key; the admin
then authenticates with the matching key over NIP-98. Full deployment guide:
docs/operations/OPERATOR_SETUP.md.
Security posture
- Fail-closed configuration — the only place that reads the environment; validates secrets (length + placeholder checks) and feature consistency at boot.
- Identity at rest is peppered —
pubkey_hash/seed_fingerprintare stored as HMACs, so the database is not a seed-existence oracle or a cross-instance linker. - Strict JWTs — HS256 pinned, zero leeway, audience-separated; admin tokens are cryptographically distinct from user tokens.
- Bounded, hardened upstream I/O — TLS with hostname verification, streaming size caps, and per-request timeouts on every external call.
- Adversarially reviewed — every security-critical subsystem was built clean (never ported) and put through a multi-agent adversarial review before landing.
Report vulnerabilities privately — see SECURITY.md. Please do not open public issues for security reports.
Testing
cargo test # unit + doc tests (no database needed)
TEST_DATABASE_URL=postgres://… cargo test --tests # + L1 integration against Postgres
Integration tests self-skip when TEST_DATABASE_URL is unset. They use only
deterministic, non-sensitive test secrets and ephemeral identities — never a
funded or otherwise sensitive wallet seed.
License
MIT © Such Software LLC — run it, embed it, modify it. Built for interop.