Skip to content

Abstractions / Escrow

Purpose

The Escrow folder defines the public escrow contracts and result types for the Currency system.

These types describe how hold-based currency flows are represented and interacted with. They do not define how holds are stored or internally managed (including expiry handling and cleanup behaviour).

Usage Guidance

Escrow abstractions are intended to:

  • Define the public escrow lifecycle contract
  • Provide machine-readable result codes for hold operations
  • Expose read-only inspection for UI, debugging, and tooling
  • Keep escrow consumers independent from concrete implementations

What Lives Here

ICurrencyEscrow

  • Optional escrow capability for hold-based flows

  • Supports:

  • TryHold

  • Commit
  • Release
  • ExpireStale

ICurrencyEscrowReadOnly

  • Optional non-mutating inspection surface

  • Supports:

  • active token checks

  • time-to-expiry queries
  • owner token enumeration
  • hold info lookup

EscrowOpCode

  • Machine-readable outcomes for escrow operations
  • Includes hold/commit/release failures and token lifecycle states

EscrowOpResult

  • Result type for escrow operations

  • Includes:

  • operation code

  • optional message
  • token for successful holds

EscrowHoldInfo

  • Lightweight immutable snapshot of an active hold
  • Intended for display/debug without exposing internals

Important Notes

  • Escrow is an optional capability
  • These abstractions do not guarantee that a service supports escrow
  • They define how hold-based flows behave when escrow is composed
  • Token lifecycle states are escrow-specific and do not map directly to currency operation results
  • Cleanup and expiry behaviour are implementation-defined

Usage Guidance

Mental model

  • Abstractions define the contract
  • Implementations decide storage, retention, and expiry behaviour
  • Consumers should depend only on available capabilities

If escrow is not present, a service may not implement:

  • ICurrencyEscrow
  • ICurrencyEscrowReadOnly

Internal Use Only

This folder defines contracts only.

Do not:

  • Add storage or lifecycle management logic
  • Assume token persistence or retention guarantees
  • Depend on implementation details from other layers

Safe to Remove

This folder should not be removed if any escrow-based workflows are used.

Other systems may depend on these contracts when escrow capability is composed.

  • Abstractions / Primitives — shared result and value primitives
  • PublicAPI / Transactions — CurrencyHoldTxn uses escrow when available
  • PublicAPI / Helpers — factories can compose escrow-enabled stacks
  • Internal — escrow implementation details (not part of the public contract)