`stealth-vault` time-locked stealth payments contract

[truthixify]

Labels: Stellar Wave, stellar, feature, drips, help-wanted
Tier: L (1–2 weeks)
Type: feature

Context

Today every Wraith payment is unlocked the moment it lands at the stealth address — the recipient can spend it as soon as they scan and derive the private key. There's no concept of "send now, recipient can claim after N ledgers" or "send with a refund window."

These primitives are useful for: escrow, time-released payroll, payment links with a "claim by" deadline (after which funds return to sender), and conditional invoicing. Several Drips program partners have asked for them.

This is not in scope of stealth-sender — we want a separate Soroban contract that doesn't expand the audit surface of the existing simple sender.

Scope

Build a new crate contracts/stellar/stealth-vault/:

1. deposit(sender, recipient_meta_address, amount, asset, unlock_ledger, refund_after, ephemeral_pub_key):
   • Transfers amount of asset from sender into the contract.
   • Records the deposit with unlock_ledger (recipient can withdraw at or after) and refund_after (sender can claw back at or after — must be > unlock_ledger + some grace).
   • Emits an announcement so the recipient can find it during a normal scan.
2. claim(deposit_id, signature):
   • Recipient proves ownership of the stealth address (signature over deposit_id || claim_nonce).
   • Requires current ledger ≥ unlock_ledger.
   • Transfers funds to a destination of recipient's choice.
3. refund(deposit_id):
   • Only the original sender may call.
   • Requires current ledger ≥ refund_after AND the deposit is unclaimed.
   • Returns funds to sender.
4. Each deposit gets a deterministic deposit_id so recipients can index efficiently.

Open design questions

• Should unlock_ledger == current be allowed (= immediate-claim with refund window)? Argue.
• Refund window grace — pick a minimum (e.g., 100 ledgers ≈ 8 min) so a malicious sender can't set refund_after == unlock_ledger and race the recipient.
• Should the deposit emit a modified announcement schema that includes unlock_ledger? Or is the standard announcement plus a separate read-by-ID call sufficient? (Affects SDK scan logic — flag SDK follow-up issue.)

Acceptance criteria

• New crate with full unit and property tests.
• Adversarial tests: sender tries to claim before refund window, recipient tries to claim before unlock, double-claim attempts.
• Deploy script integration (issue #07).
• SDK follow-up issue filed for buildVaultDeposit / buildVaultClaim.
• Demo follow-up issue filed for the UI surface.

Why this matters

Time-locked stealth is the smallest possible step from "private payment" to "private escrow." Once it exists, a wide range of products (invoicing with deadlines, vesting, conditional disbursements) become buildable on Wraith without leaving the privacy envelope.

[Ladydee1]

@Ladydee1 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi maintainer, I’d like to work on this issue.

The scope is clear: build a separate stealth-vault Soroban contract for time-locked stealth deposits, claims, and refunds without increasing the audit surface of the existing sender.

I have experience with smart contract logic, TypeScript/Rust workflows, tests, and edge-case handling. I’ll focus on the new crate, deterministic deposit IDs, ledger-based claim/refund rules, adversarial tests, and the required follow-up issues for SDK and demo integration. thank you

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ladydee1 to this issue.

[hashmart138-creator]

@hashmart138-creator has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi team, I’d like to be assigned to this issue. I can implement the stealth-vault contract within contracts/stellar/stealth-vault/. I will build out the deposit, claim, and refund entry points, enforcing a strict minimum grace window of 100 ledgers for refund_after to prevent sender racing. I'll implement signature verification to validate ownership of the derived stealth address without exposing state, and supply a thorough adversarial test suite covering double-claims and premature unlock boundaries.

ETA: 3–4 hours

ℹ️ Repo Maintainers: To accept this application, review their application or assign @hashmart138-creator to this issue.

[drips-wave]

Congratulations, @Ladydee1! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @Ladydee1: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊