Custodial wallet resilience: reconciliation, retry & admin recovery — backend EPIC

[grantfox-oss]

DESCRIPTION

Every account gets a custodial Stellar wallet created via WalletService.createWalletRecord() (apps/api/src/escrow/wallet.service.ts). When funding fails, the wallet is silently persisted with status: 'failed' (see AuthService.register and UsersService.ensureProfileWallet in apps/api/src/auth/auth.service.ts / apps/api/src/users/users.service.ts) — there is no retry, no reconciliation job, and no admin-facing way to recover a user stuck without a working wallet. Since the wallet is required to hold bond tokens on-chain, a failed wallet silently breaks that user's ability to participate. This epic builds the missing resilience layer.

GOAL

Wallets that failed to create/fund are automatically retried, an admin can see which accounts have a broken wallet and trigger a manual retry, and this status is visible where user data is already surfaced.

REQUIREMENTS

• A reconciliation routine (scheduled job or on-demand endpoint — pick whichever fits the current deployment, e.g. @nestjs/schedule if acceptable, or an admin-triggered endpoint if a scheduler is out of scope) that finds profiles/parties with stellar_wallet_status: 'failed' and retries WalletService.createWalletRecord().
• Bounded retry (e.g. backoff + max attempts) so a permanently-broken dependency doesn't loop forever; record the last error (stellar_wallet_error, already a column) and attempt count.
• POST /users/:id/wallet/retry (admin-only, mirroring the authorization pattern in UsersService.listUsers/setRole) to manually trigger a retry for one user.
• Surface wallet status (created / funded / failed, with last error) in the admin-facing user data — wire into the user-directory admin console if that epic has landed, otherwise expose it via GET /users for now.

ACCEPTANCE CRITERIA

• A profile/party with stellar_wallet_status: 'failed' is retried automatically (or via the admin endpoint) and transitions to funded/created once the retry succeeds — proven with a test against a mocked WalletService.
• Retries are bounded and don't hammer the network indefinitely on a permanent failure.
• POST /users/:id/wallet/retry is admin-only and audited via AuditService.emit().
• npm run build, npm run lint, npm run test pass in apps/api with NO VELAR credentials — the reconciliation logic must be testable against a mocked WalletService/SupabaseService, not real Stellar testnet calls.
• docs/BACKEND.md updated describing the reconciliation flow and the manual-retry endpoint.

NOTES

Relevant files: apps/api/src/escrow/wallet.service.ts, apps/api/src/auth/auth.service.ts, apps/api/src/users/users.service.ts, apps/api/src/users/users.controller.ts, apps/api/src/audit/audit.service.ts. Do not change the wallet creation/funding logic itself — only add retry/reconciliation around the existing createWalletRecord() (docs/AGENTS.md §3).

No VELAR credentials required: verifiable locally with a mocked WalletService/SupabaseService — no real Stellar testnet calls or VELAR credentials required for tests.

Difficulty: Advanced
Priority: Medium

PR REQUIREMENTS

• Ship this as a single pull request — do not split into stacked/sequential PRs.
• Your PR description must include Closes #<this-issue-number> (this issue's GitHub number) so merging auto-closes it.

CAMPAIGN REQUIREMENTS (FWC26)

To be eligible for the reward on this issue, the contributor must:

• Follow Velar on X: https://x.com/VelarApp
• Star the repository: https://github.com/Velar-Bonds/Velar
• Follow the Velar-Bonds organization on GitHub: https://github.com/Velar-Bonds

[Naajih09]

Hi, I'd like to work on this issue. I've gone through the description and acceptance criteria and I'm confident I can deliver it. I'll make sure every acceptance criterion is met and submit a clean, tested PR. Please assign it to me.

[Peculiarr7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[Bosun-Josh121]

Hello @josueazc,

I am an active open-source contributor and I have a strong background in backend and payments engineering on Stellar/Soroban, including reconciliation and retry systems, and I would like to tackle this issue.

This issue aligns perfectly with my skillset.

My approach: add a reconciliation pass that detects custodial wallets left in status: 'failed' from WalletService.createWalletRecord(), retry the funding idempotently with bounded backoff so a transient failure self-heals without double-funding, and expose admin recovery actions to inspect and re-drive stuck wallets. I've reviewed wallet.service.ts and the AuthService.register / UsersService.ensureProfileWallet paths, so I can make failed-wallet recovery safe and observable without changing the happy path.

I can commit to delivering a clean, tested solution within a couple of days, with tests covering the failed-wallet detection, idempotent retry, and admin recovery. I value clear communication and i'm happy to iterate on any feedback during the review process.

I have starred repo and followed as well

[Joaco2603]

Hi! I'd like to take this issue.

I'm a Software Engineer with experience in NestJS, backend architecture, resilient service integrations, testing, and Stellar/Soroban, so this issue is a strong fit for my background.

I've reviewed the requirements and understand that the goal is not to change the existing wallet creation/funding logic, but to build a recovery layer around WalletService.createWalletRecord() for accounts whose wallet provisioning failed.

My approach would be:

• First trace the current wallet lifecycle through AuthService.register, UsersService.ensureProfileWallet, and WalletService.createWalletRecord() to preserve the existing behavior.
• Add a reconciliation mechanism for records with stellar_wallet_status: 'failed'.
• Implement bounded retries with an attempt counter, last-error persistence, and backoff/eligibility rules so permanent Stellar or funding failures cannot cause an infinite retry loop.
• Add the admin-only POST /users/:id/wallet/retry endpoint following the existing authorization patterns used by user administration.
• Audit manual retry attempts/results through AuditService.emit().
• Surface wallet status and the last provisioning error through the existing admin-facing user data / GET /users.
• Keep the reconciliation logic isolated and testable by mocking WalletService and SupabaseService, with no dependency on Stellar testnet or VELAR credentials.
• Add tests covering successful recovery, permanent failure/max attempts, authorization, and the relevant status transitions.
• Document both automatic reconciliation and manual recovery in docs/BACKEND.md.

I'll keep the implementation scoped to the resilience/reconciliation layer and avoid modifying the underlying wallet creation and funding behavior.

I'm comfortable with NestJS service architecture, failure recovery, authorization, audit flows, mocked integration testing, and Stellar-based systems, and I'd be happy to take this and deliver it as the required single PR.

[grantfox-oss]

🦊 GrantFox — @Joaco2603 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 #81)
2. Your PR will be reviewed by the Velar-Bonds maintainers

Good luck! Track your progress on GrantFox.