fix: make wallet creation and pending debits idempotent (EN-1204)

[flemzord]

Problem (Medium — M1, M7-wallet)

• M1 — a pending debit generated uuid.NewString() for the hold per request and baked it into the Numscript and metadata. A retry with the same Idempotency-Key therefore produced a different ledger request body, so the ledger (which hashes the body to enforce idempotency) rejected the retry instead of returning the original result.
• M7 (wallet) — POST /wallets ignored the Idempotency-Key and minted a fresh wallet UUID on every call, so a retry created a duplicate wallet.

Fix

• Derive the wallet ID and the pending-debit hold ID from the Idempotency-Key (UUIDv5 over a fixed namespace) when one is provided; keep random IDs when it is absent.
• Forward the Idempotency-Key to the ledger when creating a wallet.

Tests

• TestWalletsCreateIdempotency: two POST /wallets with the same key forward the key to the ledger and resolve to the same wallet ID.
• TestWalletsDebitPendingIdempotency: two pending debits with the same key yield the same hold ID.

Note

The balance-creation idempotency (M7-balance) is handled together with the CreateBalance concurrency fix (M5) in a sibling PR, since both touch the same function.

From the in-depth repository review.

[coderabbitai]

Warning

Review limit reached

@flemzord, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 19 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9d6d3508-c4a3-48ab-aadf-edfd43c94823

📥 Commits

Reviewing files that changed from the base of the PR and between 85e1d3f and ccf7dca.

📒 Files selected for processing (4)

• pkg/api/handler_wallets_create.go
• pkg/api/handler_wallets_create_test.go
• pkg/api/handler_wallets_debit_test.go
• pkg/manager.go

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/idempotency-create

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[flemzord]

Revue inline: l’idempotence est améliorée, mais deux cas restent fragiles dans les tests et dans les sources expirables.

[flemzord]

Ça stabilise le hold ID, mais pas forcément toute la requête ledger. Plus bas, les sources sont recalculées puis filtrées avec time.Now(); pour un pending debit avec balances:["*"] ou une balance nommée qui expire entre deux essais, le retry avec la même Idempotency-Key peut produire un script/body différent et être rejeté par le ledger. Il faut rendre la résolution des sources déterministe pour une clé/requête donnée, ou au minimum couvrir ce cas par un test d’expiration.

[flemzord]

You're right — the deterministic hold ID stabilises the ID but not the whole body. I documented this explicitly at the call site and strengthened TestWalletsDebitPendingIdempotency to assert a byte-identical PostTransaction across retries for the stable case (explicit, non-expiring source set). The wildcard (balances:["*"]) and expiry-crossing cases remain non-deterministic because sources are resolved against live ledger state with time.Now(); fully fixing those needs deterministic source resolution (e.g. persisting the resolved request per key), which I called out in the comment as separate follow-up rather than solve in this PR.

[NumaryBot]

🛑 Changes requested — multi-model review

The PR stabilizes wallet and hold IDs by deriving them deterministically from the Idempotency-Key via UUIDv5, and forwards the key to the ledger for wallet creation. However, pending-debit idempotency is only partially achieved: the hold ID is now stable, but the ledger request body is still rebuilt from live balance state on every retry. A retry crossing an expiry boundary or involving wildcard source resolution will produce a different Numscript body and be rejected by the ledger as a conflict rather than replayed. The new test TestWalletsDebitPendingIdempotencyWithExpiringBalance explicitly demonstrates this non-idempotent path. Until the full transaction body is also made deterministic for a given key, the feature's correctness guarantee is incomplete for a significant class of valid retries. Additionally, both wallet IDs and hold IDs are derived from the same namespace without any type discriminator, which creates a latent collision risk if the same key is ever used across both operation types.

🟠 [major] Pending debit retries can still yield a different ledger body, breaking idempotency

pkg/manager.go:200 — reported by claude, gpt

Only the hold ID is made deterministic; the full ledger request body is still reconstructed from live balance state (source balances fetched and filtered against time.Now()) on every call. Because the ledger enforces idempotency by hashing the entire body, a retry under the same Idempotency-Key that crosses a balance-expiry boundary or encounters a different wildcard source resolution will be rejected as a conflict instead of replaying the original result. The added TestWalletsDebitPendingIdempotencyWithExpiringBalance test acknowledges and demonstrates this failure path, meaning the PR does not fully satisfy its stated goal for pending debits in these cases.

Suggestion: Make the entire pending-debit ledger body deterministic for a given idempotency key. For example, persist or cache the resolved transaction body (or at minimum the resolved source set) keyed by the idempotency key before submitting to the ledger, and reuse it on retry. As a short-term alternative, explicitly reject idempotent pending-debit retries that depend on expiring or wildcard source resolution with a clear error until deterministic body construction is implemented.

🟡 [minor] Wallet ID and hold ID derived from the same namespace without a type discriminator

pkg/manager.go:27 — reported by claude

deterministicID(ik) is used with the same namespace for both the wallet ID in CreateWallet and the hold ID in Debit. If a client reuses the same Idempotency-Key value across a create-wallet and a pending-debit call, both operations derive the same UUID. While the IDs live in different account namespaces within the chart, this separation is implicit rather than enforced. The derivation is fragile and the intent is not self-documenting.

Suggestion: Prefix the key with a resource-type discriminator before hashing, e.g. uuid.NewSHA1(idempotencyNamespace, []byte("wallet:"+ik)) for wallet creation and []byte("hold:"+ik) for hold IDs. This makes each derived ID namespace-safe and self-documenting.

🟡 [minor] Documented idempotency limitation for expiring/wildcard balances needs follow-up tracking

pkg/manager.go:152 — reported by claude

The NOTE comment and the TestWalletsDebitPendingIdempotencyWithExpiringBalance test honestly scope out the expiring-balance case, but this means clients using expiring or named balances silently experience non-idempotent behavior on legitimate retries. Without a tracked follow-up, this gap may remain unresolved in production.

Suggestion: Ensure the limitation is surfaced clearly in user-facing API documentation and that a follow-up issue (e.g. for deterministic source resolution) is filed and linked from the NOTE comment, so the production gap is not forgotten.

⚪ [nit] testEnv captured by closure before assignment is a fragile pattern

pkg/api/handler_wallets_debit_test.go:466 — reported by claude

WithGetAccount references testEnv.LedgerName() and testEnv.Chart() inside a closure, while testEnv is assigned in the same statement. This works because the callback only executes during ServeHTTP (after assignment), but the assign-and-capture pattern is subtle and could confuse future maintainers.

Suggestion: Optionally extract ledgerName and chart into local variables after the newTestEnv call and reference those inside the closure, making the data-flow explicit and eliminating the concern.

---

_{Reviewed in parallel by claude (anthropic/claude-opus-4-8) and gpt (openai/gpt-5.5), then consolidated. This comment is updated on each push.}