Fedimint Files

Highlights

• Gateway recovery and mnemonic management. New first-boot setup lets you create or restore a gateway from a mnemonic. Export/import federation invite codes so you never lose track of your federations.
• Guardian discovery via Pkarr. Guardians now publish their identity and API addresses to the decentralized Pkarr DNS system, enabling peer discovery without centralized coordination.
• Gateway UI overhaul. BOLT12 send/receive, channel management with one-click opens to existing peers, balance display in sats/BTC, payment filtering, peer and notes tabs, and a modernized Material-style design across guardian and gateway UIs.
• Drastically lower memory usage. Fixed a backtrace caching issue that bloated gatewayd from ~1.6GB to under 200MB, tuned RocksDB defaults for constrained environments, and added jemalloc profiling for diagnosing memory issues.
• Comprehensive observability. Prometheus metrics for networking, iroh connections, HTLC handling, Bitcoin RPC calls, and gateway-to-LN-node latency. OpenTelemetry switched to OTLP. New connectivity indicators in the guardian UI.

Breaking Changes

Admin API / CLI

Gateway CLI output is now JSON. All gateway-cli command output is JSON-formatted. Error output uses structured JSON with error, code, and cause fields. Scripts parsing plain-text output must be updated. #8376

Gateway first-boot behavior changed. Now presents a mnemonic setup/recovery screen instead of auto-generating. Use skip_setup flag for automation. #8174

Telemetry export switched from Jaeger to OTLP. Users who configured Jaeger endpoints need to update their collector to accept OTLP. #8138

Rust API

Gateway::new_with_custom_registry replaced by GatewayBuilder. The 11-parameter constructor is replaced with a fluent builder API. #8397

IGlobalFederationApi trait extended. New methods for connection refresh/pre-warming added; implementors must provide these. #8286

ClientModuleInit trait extended. Optional Bitcoin RPC provider capability added for downstream-defined Bitcoin RPC. #8171

ILnRpc trait extended. New sync_wallet method required on all implementations. #8083

IBitcoindRpc trait refactored. The trait and related RPC interfaces in fedimint-server-core and fedimint-server-bitcoin-rpc have been refactored to support call tracking. Module server code that implements or calls these traits may need updates. #8510

Database savepoint API removed. The ISavepoint trait and savepoint-related methods on database transactions have been removed. #8207

Backup methods deprecated (migrate now). All public backup methods on Client and ClientBuilder (create_backup, backup_to_federation, validate_backup, upload_backup, download_backup_from_federation, get_backup_id) are deprecated and scheduled for removal. Please migrate away from these methods. #8224

Dummy module simplified to pure testing mock. The dummy module's server-side consensus logic has been removed and the fedimint-dummy-tests crate deleted. #8221

Gateway ecash withdrawal API simplified. SpendEcashRequest no longer accepts custom denomination parameters; the gateway now uses send_oob_notes internally. #8223

fedimint-lnurl crate replaces standalone lnurlp binary. The lnurlp binary is removed; use the fedimint-lnurl library crate instead. URL fields in the public API use String instead of Url to avoid normalization issues. LnurlResponse serde representation changed to untagged format. #8235, #8281

VerifyResponse preimage encoding changed. Now a hex-encoded string per LUD-21 spec instead of raw bytes. LNv2 functionality removed from recurringd v1 (use recurringdv2 instead). #8231

RoutingInfo struct extended. New lightning_alias field in fedimint-lnv2-common. #8374

ChannelInfo struct extended. New address field for remote peer in fedimint-gateway-common. #8417

Module file renames. event.rs renamed to events.rs in fedimint-mint-client and fedimint-mintv2-client. #8405

jemalloc now behind a Cargo feature flag. jemalloc feature (enabled by default) in fedimintd and fedimint-cli. Downstream crates using default-features = false will no longer get jemalloc automatically. #8488

Experimental MintV2/WalletV2 API (not yet relevant for most users)

MintV2 and WalletV2 modules added (experimental, disabled by default). Two new opt-in modules are included but must be explicitly enabled during federation setup. They are not yet recommended for production use. #6429, #6734

WalletV2 API changes. deposit_range endpoint renamed to output_info_slice; DepositRange type replaced with OutputInfo. The tx_chain API no longer accepts a count parameter. WalletClientConfig gains new fields (send_tx_vbytes, receive_tx_vbytes, min_feerate, WalletDescriptor). #8412, #8418, #8361, #8506

WalletV2 payment event renames. SendPaymentStatusEvent -> SendPaymentUpdateEvent, ReceivePaymentStatusEvent -> ReceivePaymentUpdateEvent. Event kind strings updated accordingly. New address field added (typed Address<NetworkUnchecked>). amount fields renamed to value. Terminology normalized: peg-out -> pegout, peg-in -> pegin, on-chain -> onchain. #8429, #8434, #8437

MintV2 error variants renamed. MintInputError::InvalidAmountTier and MintOutputError::InvalidAmountTier renamed to InvalidDenomination. #8413

MintV2 amount_unit config field added. New field in mintv2 module configuration for multi-asset support. #8466

---

What's Changed

Gateway & Lightning

• Gateway mnemonic setup/recovery UI on first boot #8174
• Recovery checkbox when joining federation #8177
• Export/import federation invite codes for recovery #8250
• PeginFromOnchain and PegoutToOnchain APIs for automated on-chain/ecash movement #8375
• Liquidity Manager role with restricted permissions #8379
• GatewayBuilder pattern replaces multi-parameter constructor #8397
• Gateway CLI output standardized to JSON #8376
• BOLT12 send/receive support in gateway UI #8242
• Peers and Notes tabs in gateway UI #8266
• Balance display toggle (msats/sats/BTC) #8329
• Payment event filtering in payment log #8222
• Remote peer alias on channels tab #8237
• Easier channel opens to existing peers #8417
• Channels table scrolling fix #8323
• Parallelized HTLC handling for better throughput #8270
• HTLC handling time metrics #8269
• Gateway-to-LN-node and bitcoind RPC duration metrics #8251
• lightning_alias in routing_info_v2 API #8374
• Password required to reveal mnemonic #8220
• Gatewayd Start9 package #8325
• Gateway Docker Compose file #8068
• Reject funding of expired LNv1 incoming contract offers #8348
• LDK gateway sync fixes (retry on Esplora timeout) #8083
• LDK oversized channel open returns proper error #8172
• LNv2 await_final functions now properly cache operation outcomes #8415
• Payment events added to LN v1 client #8405
• Leaving unknown federation no longer panics #8396

Guardian & Federation

• Guardian metadata framework for flexible JSON-serialized guardian info #8073
• Pkarr identity and API address publishing for decentralized guardian discovery #8300
• Ability to disable pkarr publishing #8328
• federation_successor meta key for federation migration #8287
• Meta module editing UI overhaul with schema-aware editing #8289
• Setup code now embeds federation size for verification #8308
• Network connectivity indicator in setup and dashboard UI #8307
• QR code display and scanning for setup codes #8189
• Setup UI improvements: confirmation dialogs, experimental badge, max guardian limit of 19 #8331, #8346, #8372
• Modernized setup and dashboard UI with Material-style design #8428
• Password change: constant-time comparisons to prevent timing attacks #8389
• Disable modules during setup #8308
• Environment flag to disable automatic consensus version voting #8440

Client & Networking

• Downstream-defined Bitcoin RPC for clients #8171
• chain_id exposed from server to client with new CLI command #8162
• Connection refresh/pre-warming for federation API #8286
• finalize_and_submit_transaction_dbtx for atomic transaction submission #8473
• Custom root secret support in fedimint-cli for integrators #8354
• admin auth command to store credentials in client database #8205
• CLI command reorganization under module and dev subcommands #8340
• join-federation renamed to join #8321
• LNURL verify/pay methods exposed to WASM #8377
• fedimint-lnurl crate consolidating LNURL protocol utilities #8235
• Re-export common modules from server and client crates #8190
• Duplicate blind nonces fix in send_oob_notes reissuance #8256
• subscribe_ln_receive now consistently waits for notes to be claimed #8228
• Iroh transport read limit increased to fix peer catch-up #8384
• FM_IROH_RELAY env var correctly parsed as comma-separated list #8381

Observability & Operations

• Expanded Prometheus metrics for networking, API, and gateway #8212
• Prometheus metrics for iroh API connections and requests #8423
• Improved Bitcoin RPC call tracking with metrics #8510
• OpenTelemetry migrated from Jaeger to OTLP exporter #8138
• jemalloc profiling compiled in by default #8480
• jemalloc made optional Cargo feature #8488
• RocksDB defaults tuned for lower memory usage #8475
• Fix for RUST_LIB_BACKTRACE=1 reducing memory from ~1.6GB to <200MB #8202
• Improved fmt::Debug for Transaction and Note types #8319
• Better error reporting for misconfigured bitcoind connections #8243
• Improved debugging logging around tx submission #8349

Deployment & Packaging

• Gatewayd Start9 package with LDK/LND and Bitcoin Core/Esplora backends #8325
• Automated Start9 s9pk package builds in CI #8306
• macOS tarball bundling for prebuilt binaries #8345
• Gateway deployment and operation documentation #8333
• SelfCI and treefmt for development #8150
• NixOS VM test for fedimintd module #8233
• redb upgraded from v2 to v3 with automatic migration #8406

Experimental: MintV2 & WalletV2 Modules

These modules are experimental, disabled by default, and must be explicitly enabled during federation setup. They are not yet recommended for production use.

• Initial implementation of WalletV2 with single-UTXO design, probabilistic address filtering, and exponential feerate algorithm #6429
• Initial implementation of MintV2 with stateless secret derivation, tweak grinding, and per-denomination audit #6734
• Efficient mint recovery via compact server-side recovery items (~73% bandwidth reduction) #8110
• Efficient wallet recovery with slice-based recovery endpoints #8111
• WalletV2 fee rate vote clamped to 1000 sat/kvB minimum, min_feerate lowered to 250 for better low-fee UX #8359
• Expose tx vbytes and min feerate in WalletV2 client config #8361
• WalletV2 dashboard: value-in-custody chart replaces transaction table #8418
• WalletV2 deposit handling and address derivation fixes #8403
• Remove P2WSH filter from deposit detection, relying on probabilistic filter #8391
• WalletDescriptor added to WalletClientConfig for client-side address derivation #8506
• MintV2 amount_unit config field for multi-asset support #8466
• MintV2 balance update notifications on spend #8404
• Payment event system for walletv2 with address tracking #8429, #8434, #8437
• Event log assertions for mintv2, lnv2, and walletv2 tests #8430

Full Changelog: https://github.com/fedimint/fedimint/compare/v0.10.0...v0.11.0