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

Priority: P0 — research-first: the swap crash window can silently destroy received value; the correct fix shape (pre-persisted swap intents) must be designed, not improvised.

Open
  • Is something wrong?
#497 5 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
backend, databases

Research direction

Start with wallet/wallet.go and wallet/storage/bolt.go, then read the CDK saga references named in the issue and inspect TollGate startup. First produce the requested research document: map crash windows for swap, mint, and melt, and compare pre-persisted intents with accept-and-bound reconciliation. Done means the document records a decision and supporting evidence; implementation and crash-injection tests are subsequent work.

Written by the indexing model from the issue text.

Description

Priority: P0 — research-first: the swap crash window can silently destroy received value; the correct fix shape (pre-persisted swap intents) must be designed, not improvised.

Problem

In gonuts Receive, the swap secrets (secrets, rs) exist only in memory (swapRequestPayload). The mint consumes the input proofs the moment the swap request lands; if the process dies (or panics, or the disk fills) after PostSwap succeeds but before SaveProofs, the newly issued outputs are unrecoverable: the wallet cannot unblind signatures without rs, and the mint has burned the inputs. The customer's token is gone with no local trace of the outputs.

The same window exists in MintTokens (mint signatures → SaveProofs) and in Melt (change proofs → save).

Why it matters

This is the fund-safety gap that CDK's wallet saga exists to close (saga record with counter range + blinded messages persisted before the network call; recovery replays or restores). gonuts has no equivalent. Probability is low per-request but non-zero over fleet lifetime (OOM, power loss, flash-full — flash-full is realistic on 8 MB routers), and the blast radius is total for the affected swap. We must either close it or consciously accept and bound it — but not leave it undocumented.

Current behavior (source refs, gonuts v0.11.2)

  • wallet/wallet.go:822-840 — createSwapRequest builds outputs, secrets, rs in memory.
  • wallet/wallet.go:723-732 — swap POST then SaveProofs(newProofs); nothing durable before the POST except the counter increment (which only prevents reuse, it does not enable recovery).
  • CDK reference model: crates/cdk/src/wallet/swap/saga/{mod,resume}.rs — add_saga (with counter_start/end, blinded messages) before post_swap; resume_swap_saga replays via NUT-19-cached responses or /restore-style checks.

Desired invariant

At any crash point, either (a) the operation's inputs were not consumed, or (b) enough durable state exists to reconstruct the outputs (secrets + rs + expected signatures) and complete the operation at next boot. No crash window may destroy issued-but-unstored value.

Proposed scope (research deliverable first, then implementation PRs)

  1. Research doc (docs/ in gonuts or TollGate): enumerate every in-flight monetary operation in gonuts and its crash windows (swap/mint/melt × before-POST/after-POST-before-save); for each, what durable pre-state would enable recovery; evaluate two designs:
    a. Pre-persist swap intents: bbolt bucket pending_ops storing {opId, mint, keysetId, counter range, outputs, secrets, rs, inputs Ys} written in the same tx as the counter increment; removed after SaveProofs; boot-time resume: re-POST (NUT-19 replay-safe? verify mints' behavior on identical swap re-POST — cdk-mintd caches; Nutshell?) or verify inputs' spend state + mint restore API availability.
    b. Accept-and-bound: document the window, add wallet balance-vs-mint reconciliation tooling to detect the loss after the fact (weaker; only acceptable if (a) proves infeasible).
  2. Decide per-operation; implement (a) where feasible (swap first — it is the customer-facing path).
  3. TollGate side: boot triggers resume before serving payments.

Areas / files

gonuts wallet/wallet.go, wallet/storage/bolt.go; TollGate startup.

Acceptance criteria (for the implementation phase)

  • Test kills the process (SIGKILL) between POST-swap and SaveProofs with a mint that recorded the swap; on restart the wallet completes the swap and the proofs appear (balance preserved).
  • Research doc merged with the decision and evidence.

Required tests

  • Crash-injection harness at the exact boundary (proxy that forwards to mint, then kills the process before response handling).

Failure-injection tests

  • Kill pre-POST (after intent write) → resume completes or compensates (inputs unspent → re-derive fresh range).
  • Kill post-POST → resume recovers outputs.
  • Mint lost the swap (never received) → resume re-POSTs identical request (assert mint idempotency behavior; document per-mint divergence).

Compatibility

Storage addition only; old DBs unaffected.

Dependencies

After G03's storage canonicalization lands (same file, avoid conflicts).

Out of scope

  • Full saga machinery beyond recovery of in-flight ops (business-level saga is TollGate-side, separate issue).
Dominant language
Go
Stars
12
Forks
14
Avg merge
1d 6h
Merged PRs (30d)
211

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.