Fedimint Files

Highlights

• V2 modules are now the default.
  Freshly set up federations run the lnv2, mintv2 and walletv2 modules by default instead of the v1 module set; the v1 modules are now labeled "legacy" in the setup UI. Existing federations keep their configured module set and are unaffected. #8777, #8886
• Iroh 1.0.
  Guardian P2P and the client API migrated to Iroh 1.0, with clients running dual-stack so older federations keep working. New federations set up in production now default to the iroh networking stack. Plus many robustness fixes: idle connection reaping, request timeouts, stalled connection eviction, explicit QUIC keep-alive, and a pkarr resolver fallback. #8815, #8400, #8718, #8779
• Recovery without downtime.
  Client modules that support it (notably mintv2) stay usable while they recover, failed recoveries are reported instead of blocking forever, and recovery no longer stalls on an unresponsive guardian. #9024, #8866, #9023
• Faster Lightning payments.
  A concerted push to drive down LNv2 payment latency: transaction submission now long-polls the federation until consensus acceptance instead of retrying with backoff, decryption key shares are long-polled as well, and the payment preimage is returned to the sender as soon as it is available rather than only after the gateway's claim settles. #8950, #8764, #8762
• UniFFI bindings for the client.
  The client and the ln/mint/wallet/meta client modules can now be consumed from Kotlin, Swift and other languages via a feature-gated uniffi build, replacing the previous standalone bindings crate. #8642, #8986
• Fee transparency and full sweeps.
  New fee quote and per-operation fee APIs let clients know costs up front, and the gateway can now sweep a wallet completely on-chain, correctly accounting for module and on-chain fees. #8689, #8294, #9011, #8840
• Simpler guardian setup.
  The guardian password no longer encrypts config files and is purely an admin API/UI credential, setup codes embed the release version and Bitcoin network to catch mismatched guardians early, and the setup UI gained a guardian restore flow. #8451, #8670, #8603, #8652
• Security fixes.
  This release contains the coordinated set of security hardening fixes across the server, Lightning modules, wallet, backup and DKG that was already shipped to guardians in v0.11.2/v0.10.1 and communicated separately, plus a few follow-ups landed since. All federations should run v0.11.2 or later. #8997

Upgrading

• Supported upgrade paths: v0.11.2 → v0.12.0 and v0.10.1 → v0.12.0 are both tested in CI. #9004
• Guardians of iroh-based federations have to upgrade in sync. The Iroh 1.0 P2P upgrade is not wire-compatible with earlier releases, so upgraded and non-upgraded guardians cannot connect to each other. For a federation of n = 3f+1 guardians: up to f guardians can upgrade independently at any time, then at least f+1 guardians have to upgrade together in a coordinated window (consensus pauses briefly until the upgraded set reaches quorum), after which the remaining f can again upgrade independently. Federations using the TCP/TLS networking stack are unaffected. #8815
• Never upgrade through v0.11.0 or v0.11.1. If you are still on v0.10.x, go directly to v0.11.2 (or straight to v0.12.0) — do not step through the earlier v0.11 releases.
• StartOS packaging moved out of the repo. The in-repo s9pk builds were removed in favor of the community-maintained start-os package, so there are no .s9pk assets on this release. StartOS users should install/update via the community package. #8922
• Guardian configs are no longer encrypted at rest. Existing encrypted configs are still read transparently; newly written configs are plaintext. The guardian password remains required to access the admin API and UI. Make sure filesystem access to the config directory is appropriately restricted (it effectively already had to be, as the password was stored next to the configs). #8451
• All guardians must run the same release during setup (DKG). Setup codes now embed the release version and mismatched guardians are rejected. This only affects new federations, not upgrades of existing ones. #8670

Breaking Changes

Admin API / CLI / Operations

Guardian config encryption removed. fedimintd no longer encrypts config files with the guardian password; the password is only used for admin API/UI authentication. Legacy encrypted configs (and guardian backups) are still read. #8451

New federations default to v2 modules and iroh. With no FM_ENABLE_MODULE_* env vars set, DKG now configures lnv2/mintv2/walletv2 instead of lnv1/mintv1/walletv1, and with FM_ENABLE_IROH unset, production deployments default to the iroh stack. Both are consulted only at config generation — existing federations are unaffected. #8777, #8779

Iroh connect overrides use a new format. Connection overrides are now specified as plain <id>=<addr> pairs. #8721

Preimage retrieval requires authentication. The LNv1/LNv2 endpoints for fetching payment preimages are now gateway-authenticated. #9017

In-repo StartOS (s9pk) builds removed. Use the community start-os package instead. #8922

Rust API

Blanket SystemTime consensus codecs removed. Structs that #[derive(Encodable, Decodable)] a SystemTime field no longer compile; modules with such fields in persisted or consensus-encoded types must write manual impls using the new encode_legacy_system_time/decode_legacy_system_time_from_finite_reader helpers, which keep the wire format byte-identical (no DB migration or consensus change). New code should encode times explicitly instead. #8931

ClientContext::outcome_or_updates takes an is_terminal predicate. The operation log entry is now passed by reference and callers must supply a predicate identifying terminal states; only terminal updates are cached as an operation's durable outcome, and previously mis-cached non-terminal outcomes are transparently rebuilt from the update stream. Client modules need to define terminal states for their operation state enums and update call sites. #8826

api_endpoint! split into public_api_endpoint! and admin_api_endpoint!. Every endpoint now declares its access policy explicitly; admin handlers can no longer silently omit guardian authentication, and manual check_auth calls move into the macro. ApiEndpointContext::request_auth() was removed. Module authors must migrate their endpoint declarations. #8905

SafeUrl::join replaced by SafeUrl::join_path. The new method normalizes slashes and always appends instead of RFC 3986 join semantics that silently drop base path segments. #8554

fedimint-client-uniffi crate removed. Replaced by the feature-gated uniffi support built into the client crates (--features uniffi). #8494, #8642

Arithmetic overflow is now an error. Amount addition overflow is rejected instead of wrapping/panicking, and LNv2 PaymentFee addition overflow is explicit. #8686, #8948

notes_json output now includes the note nonce. Consumers parsing this output may need updating. #8290

Module API versions are now derived automatically. Each server module's advertised API version is derived from its registered endpoints by default; ServerModuleInit::supported_api_versions() was removed. Modules that need to advertise a version without a corresponding endpoint can override ServerModule::supported_api_versions (returning MultiApiVersion). #8778

Dependency pins downstream workspaces will inherit. Fedimint v0.12 pins iroh 1.0.x and moves to arti-client 0.38; downstream lockfiles holding older versions of these trees may need a targeted cargo update of the conflicting crates (a full cargo update is not required).

---

What's Changed

Gateway & Lightning

• On-chain sweep of the full gateway balance, accounting for module and on-chain fees #9011
• Max affordable send amount computation, with fast startup #8840, #8853
• Edit channel fees from the gateway UI, and set feerate and routing fees when opening a channel #8620, #8617
• Connect-peer action in the gateway UI; manually connected peers are persisted across restarts #8795, #8829
• Total inbound/outbound liquidity shown in the gateway UI #8445
• List all hold invoices #8843
• Federation-scoped capability health reporting #9020
• Custom LND routing timeout and time preference #8804, #8621
• LND route hints built from the remote peer's fee policy #8928
• Cancel unmatched federation HTLCs instead of forwarding them; serialize same-circuit LNv1 HTLC handling; make HTLC interception idempotent on replay #8625, #8716, #8655
• Outgoing contracts are bound to the invoice being paid; outgoing claims deduplicated in the gateway's global database #8957, #8808
• Stricter fee limit verification on payment paths #8989, #8921, #8925
• Gateway disconnects a federation when its LNv1/LNv2 tasks exit unexpectedly #8653
• Fixed a deadlock on gateway shutdown, a panic on amountless invoices, and gateway UI auth issues #8990, #8984, #8863
• LNv2 preimage returned to the sender without waiting for the gateway's claim to settle (faster payments) #8762
• LNv2: only a single payment attempt per invoice; send status and preimage exposed to integrators; invoice amount and fee reported in payment events #8806, #8879, #8649, #8741
• LNv2 decryption key share endpoint long-polled; LNURL receive no longer holds a database transaction across the long-poll #8764, #8816
• LNv1: manual reclaim of stuck receives; pay idempotency checked before invoice expiry #8713, #8818
• LNURL: invoice amount verified against the requested amount #8982
• recurringd: selects available, vetted gateways sorted by fees, caches the selection, and repairs consecutive orphaned invoices #8654, #8675, #8727
• Removed LDK bolt11 payment polling; LDK logs redirected into the gateway log #8788, #8783
• Gateway verify endpoint handled correctly over Iroh; liquidity manager route prefix handling fixed #9010, #8865
• Corrected Lagrange multiplier in threshold decryption with a single share #8838

Client & SDK

• Modules that support it stay usable while recovering; failed recoveries are reported instead of blocking the client forever #9024, #8866
• Feature-gated UniFFI bindings for the client and client modules, with simplified export names and fixed callback runtimes #8642, #8986, #8871
• Fee quote API, get_operation_fees, and a mint send quote so costs are known before committing #8689, #8294, #8751
• mintv2 and walletv2 clients compile under WASM; a WASM panic hook preserves panic messages #8761, #9052
• Client event log exposed over the global RPC (paginated) for transaction-history recovery after restore #8609
• Meta consensus value exposed via WASM client RPC; connection type included in connection_status_stream #8532, #8520
• Transaction submissions that never resolve are reported #8835
• No-timeout out-of-band spend mode #8740
• Federation prefix on client-side logs; operation log cache fix for historical inserts #8557, #8707
• New dev tooling: dev check-nonce / dev check-blind-nonce, API version refresh command, and note/transaction/operation visualization commands #8891, #8288, #8355

Mint & Wallet

• Fixed mint input refund issues and made repair-wallet transactions atomic #8426, #8613
• Duplicate blind nonces during mint recovery no longer panic #8533, #8537
• mintv2: duplicate e-cash receives return an error, e-cash includes the invite code, and send returns an operation ID #8923, #8667, #8722
• Wallet: peg-out change recorded as an already-claimed peg-in; peg-in monitor improvements; bounded reuse of unused deposit addresses #8938, #8580, #8563
• walletv2: await-receive, receive fee on the CLI, custom metadata on sends, and receive address/outpoint exposed in events #8628, #8746, #8676, #8646
• walletv2 client: skips receive claims that cannot cover their fees; claims outputs before extending the address index; terminal states persisted to the operation log #8807, #8855, #8648, #8647

Server & Consensus

• Transaction submission long-polls until consensus acceptance, removing client resubmission backoff from tail latency #8950
• Consensus items are reprocessed on stale-snapshot commits #8874
• The process exits if a consensus session times out (pairs with automatic restarts); FM_P2P_MAX_CONNECTION_AGE_SECS recycles old P2P connections as a lighter-weight remedy #8693, #8875
• No panic on peer-supplied Aleph node indices; unit creation delay jitter restricted to test environments #8893, #8958
• All API endpoints explicitly classified as public or admin #8905
• Module API versions derived automatically from registered endpoints #8778
• API secrets are no longer silently ignored on the Iroh API; meta module uses check_auth #8949, #8900
• Consensus versions logged on startup #8463

Guardian UI & Setup

• Guardian password simplified: config encryption removed, password is a pure admin credential; StartOS auto-generates it #8451
• Guardian restore flow in the setup UI #8652
• Setup codes embed the release version and Bitcoin network; mismatches are rejected #8670, #8603
• v1 modules labeled "legacy" in the setup UI #8886
• fedimintd version and git hash shown in the dashboard footer #8641
• Correct invite code shown after API URL replacement; setup form preserved on error #8618, #8604
• Federation IP privacy query for checking what a federation exposes #8669

Networking (Iroh)

• Guardian P2P upgraded to Iroh 1.0; client API migration path runs Iroh 1.0 alongside 0.35 (dual-stack) #8815, #8400, #8718
• Iroh enabled by default for new production federations; default relays configured when none are set; n0 pkarr resolver fallback #8779, #8643, #8695
• Requests are time-bounded and stalled connections evicted; idle Iroh API connections reaped; explicit QUIC idle timeout and keep-alive #8571, #8726, #8422
• FM_IROH_RELAYS_ENABLE honored, numeric FM_ENABLE_IROH values accepted, bind failures return errors instead of panicking, DHT discovery is logged #8523, #8786, #8518, #8524
• Connectivity reporting for iroh-next connections; pooled gateway HTTP connections reused instead of reconnecting per request #8987, #8932

Observability & Operations

• Iroh and JSON-RPC API metric labels bounded; Iroh API response codes tracked #9033, #9032, #8720
• Module environment variables surfaced in fedimintd --help #8474
• RocksDB uses the TolerateCorruptedTailRecords WAL recovery mode, preventing data loss from a torn final write #8614
• StartOS exposes the session timeout watchdog; NixOS module allows custom nginx vhost settings #8875, #8857
• Smaller release binaries #8504

Documentation

• Security vulnerability disclosure policy #8978
• Cryptographic scheme write-ups for threshold blind signatures (tbs), threshold point encryption (tpe), and DKG #8708

Plus the usual stream of dependency updates, CI improvements, and test hardening.

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