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)