Skip to content

feat: implement idempotent Stellar wallet provisioning - #121

Merged
3m1n3nc3 merged 1 commit into
learnault:mainfrom
ceshez:agent/stellar-wallet-provisioning
Aug 19, 2026
Merged

feat: implement idempotent Stellar wallet provisioning#121
3m1n3nc3 merged 1 commit into
learnault:mainfrom
ceshez:agent/stellar-wallet-provisioning

Conversation

@ceshez

@ceshez ceshez commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Closes #90

What changed

  • Added transactional wallet reservation, opaque managed-key references, and a durable wallet provisioning job with a database migration.
  • Gated reservation on a verified user and the latest granted custodial_wallet consent record.
  • Added a Stellar keypair adapter and a KMS boundary that redacts signing material from string/JSON serialization.
  • Added an AES-GCM in-memory KMS adapter for development/tests; it stores only ciphertext and supports deterministic lookup by wallet id.
  • Added lease-based outbox handling, exponential retries, dead-lettering, and sanitized lifecycle audits.
  • Preserved the existing users.walletAddress compatibility field using only the public Stellar key.

Recovery and idempotency

  • A unique wallet and job are reserved before key generation.
  • Concurrent requests reuse the same reservation; concurrent workers use a conditional lease so only one generates.
  • The wallet id is the KMS idempotency key. A lost response after a successful KMS write is repaired by lookup.
  • A database failure after KMS storage retries with the already protected key instead of generating another one.
  • Expired process leases become claimable again after a worker crash.

Secret handling

  • Prisma and the migration define no seed/private/secret-key column.
  • The database receives only the public key plus provider/version/opaque KMS reference.
  • Failure persistence and audits contain stable failure codes, never provider exception text or signing material.
  • Ordinary wallet DTOs exclude all KMS references.

Verification evidence

  • pnpm exec prisma validate
  • pnpm run lint
  • pnpm run build
  • pnpm run test:ci — 42 test files passed; 536 tests passed and 3 existing integration tests were skipped because the local PostgreSQL test credentials were unavailable.
  • 12 focused wallet tests cover 50 concurrent reservations, 25 concurrent workers, KMS failure before/after storage, DB finalization failure, abandoned process lease recovery, and automated schema/DTO secret scanning.

The minimal wallet/KMS/job persistence needed by this feature is included because #89 and #63 are still open and the earlier #89 implementation in #111 was reverted. This PR does not claim to close those broader foundation issues.

@ceshez
ceshez marked this pull request as ready for review August 19, 2026 03:24
@3m1n3nc3
3m1n3nc3 merged commit 7016415 into learnault:main Aug 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Implement Idempotent Stellar Wallet Provisioning

2 participants