Add nonce leak recovery for failed or timed-out submissions

[N-thnI]

Description

Release reserved sequences that were never actually consumed on-chain.

Problem Statement

A reserved sequence whose transaction fails to submit — network error, timeout, rejection — is currently never returned to the pool. vero-core-engine#181 describes exactly this: TxAggregator.execute() leaks reserved nonces on failure, permanently desyncing the account sequence cache and forcing a manual refresh.

Proposed Changes

• Add release(account, sequence) to return an unused reservation
• Provide a withReservation(account, fn) helper that reserves, runs fn, and releases automatically if fn throws
• Document that release is only valid for a sequence that never reached the network

Technical Implementation Scaffolding

• Target Repository: vero-sdk
• Target Path: src/nonce/index.ts
• Branch Naming: feat/issue--nonce-leak-recovery
• Authority Context: Security-sensitive — transaction sequencing

Acceptance Criteria

• A throwing withReservation callback leaves the sequence available for reuse
• A successful callback does not release the sequence
• Test covers both paths
• npm test, npm run typecheck, npm run lint, and npm run build all pass

Definition of Done

• Reviewed by lead maintainer
• Pull request merged via verified status check

[Archive-000]

please can i work on this

[grantfox-oss]

🦊 GrantFox — @Archive-000 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #4)
2. Your PR will be reviewed by the Vero-protocol maintainers

Good luck! Track your progress on GrantFox.

[bukeeastrey]

Hi maintainer, I've gone through this issue and confident I can do this. kindly assign it to me.

[N-thnI]

Dependency note (added by maintainer): this issue builds on #1 (NonceManager core) and #2 (per-account lock primitive), which are assigned separately and not yet merged. src/nonce/ does not exist on main yet.

Please wait for #1 and #2 to land, then build on top of them. Implementing the manager yourself inside this PR will collide with the other work in this cluster — that has already happened three times here, and it's our fault for filing these together without flagging the dependency. Sorry for the confusion.

[N-thnI]

Update — unblocked. PR #6 has merged, so src/nonce/index.ts and src/nonce/lock.ts now exist on main. This issue is standalone again: rebase onto main and add only the piece described here, rather than reimplementing the manager.

Disregard the earlier dependency note.