Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

wallet init bricks into degraded mode on Unknown Keyset after mint rotation — no self-heal despite reachable mint (rc1, real hardware)

Open
  • Is something wrong?
#818 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
22/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
go
Domain
backend, payments

Research direction

Start from the wallet init log lines quoted in the issue ("error getting keyset from mint: Unknown Keyset" and the degraded-mode warning) and find where the keyset lookup happens during TollWallet.New. Reproduce by seeding a wallet DB with retired keyset IDs against a mock mint that answers /v1/keys with new IDs. Done means init refreshes keysets from the mint and registers without discarding the wallet DB, and retired-keyset proofs stay spendable; read AGENTS.md first for the counter rules, since the issue says they constrain the fix.

Written by the indexing model from the issue text.

Description

needs:owner-decision

Summary

On real hardware (GL.iNet MT3000, OpenWrt 25.12.5) with an existing wallet DB (created under v0.6.0-alpha4), the rc1 daemon deterministically fails wallet initialization with error getting keyset from mint: Unknown Keyset whenever the mint has rotated its keysets since the wallet last synced — and it never self-heals, despite logging "wallet will initialize when a mint becomes reachable" while the mint IS reachable. The router stays in degraded mode (payments refused, no-reachable-mints on :2121) until an operator manually intervenes.

Evidence (2026-10-09, desk run)

  1. Upgraded alpha4→rc1 (binary swap; config + wallet.db preserved). Mint reachable, DNS fine.
  2. Startup, then service restart — identical failure both times (deterministic, not a race):
TollWallet.New: Loading wallet with config: {WalletPath:/etc/tollgate CurrentMintURL:https://testnut.cashu.space/}
WARNING: Wallet initialization failed (failed to create wallet: error getting keyset from mint: Unknown Keyset) — starting in degraded mode
Degraded mode: offline wallet load failed (first boot or no cached data): failed to create wallet: error getting keyset from mint: Unknown Keyset
WARN Merchant started in degraded mode — wallet will initialize when a mint becomes reachable
  1. No retry ever fires: 45+ minutes later the state was unchanged, and the promise's condition was already true (mint answered /v1/keys fine the whole time).
  2. Root cause shape: the wallet DB caches a dozen retired keyset IDs (strings wallet.db: 00003ac3…, 00020989…, …); testnut.cashu.space rotates its ENTIRE keyset set frequently — the sat keyset observed changed from 0184237e… to 017bc604… within ~1 hour during this run. The init path asks the mint for a keyset by a cached/known ID, the mint answers Unknown Keyset, and init treats that as fatal instead of falling back to fetching the mint's current keysets.
  3. Workaround verified on-device (recovery for anyone hitting this): move the stale wallet aside and restart — fresh init registers all mints and the merchant reaches ready:
/etc/init.d/tollgate-wrt stop
mv /etc/tollgate/wallet.db /etc/tollgate/wallet.db.stale-keysets
/etc/init.d/tollgate-wrt start
# → TollWallet: registered mint … ×8, === Merchant ready ===

(Safe here only because balance was 0 — see the fund-safety note.)

Impact

Any router whose mint rotates keysets between syncs (testnut does it aggressively; production mints rotate on schedule) bricks into degraded mode at the next restart. For an unattended payment gateway this is a stop-ship-class availability bug in the upgrade/restart path: no payments until manual recovery, and the recovery that works today discards the wallet (unacceptable at nonzero balance).

Fund-safety note

The workaround above discards proofs still held in the moved-aside DB. The proper fix must NOT require wallet disposal: on Unknown Keyset at init, refresh keysets from the mint (/v1/keys) and re-register before giving up — the AGENTS.md counter-discipline rules (monotonic counters, no fresh-record overwrites, #480-class alias/refresh handling) apply to whatever path performs that refresh. Retired-keyset PROOFS must remain spendable through whatever swap path the mint still honors; keyset rotation must not orphan them.

Reproducer

Any wallet.db cached against keysets a mint has since retired (testnut.cashu.space guarantees rotation within hours): restart the daemon, observe the degraded loop above, confirm /v1/keys answers fine from the same router.

Dominant language
Go
Stars
12
Forks
14
Avg merge
1d 5h
Merged PRs (30d)
239

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenTollGate/tollgate-module-basic-go

All issues in OpenTollGate/tollgate-module-basic-go

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.