Skip to content

Escrow Vault Payment Manager #549

Description

@Kingsman-99

Description

Some invoice payment flows require holding funds in escrow (locked until delivery confirmation) before releasing them to recipients. The SDK has no escrow primitive — callers use claimable balances ad-hoc without lifecycle management. An escrow vault manager should wrap the create-hold-release pattern using claimable balances with time-lock predicates, coordinating with invoice status to trigger release automatically.

Technical Context

Add src/escrowVaultManager.ts. Builds on src/claimableBalanceFallback.ts and src/predicateBuilder.ts. Adds EscrowVault, EscrowStatus, and EscrowReleaseCondition to src/types.ts. Integrates with src/poller.ts to monitor delivery confirmation events. Release is triggered by src/client.ts confirmDelivery() method. Emits escrowFunded, escrowReleased, and escrowExpired via src/events.ts.

Acceptance Criteria

  • EscrowVaultManager.create(invoiceId, amount, asset, holdUntil): Promise<EscrowVault> creates a claimable balance with an absolute-time predicate and returns the vault record
  • EscrowVaultManager.release(vaultId, recipientId): Promise<TransactionResult> claims the balance on behalf of the recipient after the hold period
  • EscrowVaultManager.getStatus(vaultId): Promise<EscrowStatus> returns the current state: holding | released | expired
  • Emits escrowExpired when the hold predicate window closes without release and the SDK detects the balance is claimable by anyone
  • Integration test creates an escrow, waits for predicate window (using testnet fast ledger), and asserts escrowReleased event fires after release() call
  • All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions