Skip to content

RevFramework – Sample Scene: 05_Currency_Escrow

Goal

Teach the hard-hold escrow lifecycle:

TryHold debits now → token returned → Commit keeps the debit or Release refunds it → optional TTL expiry resolves stale holds.

What This Scene Demonstrates

This scene shows escrow as a capability on the composed currency service stack.

The flow is:

Owner → ICurrencyService → ICurrencyEscrow → TryHold → token → Commit / Release / ExpireStale

  • Escrow must be present on the resolved service stack
  • TryHold debits the wallet immediately
  • A successful hold returns a token
  • Commit resolves the token and keeps the debit
  • Release resolves the token and refunds the held amount
  • A positive TTL can be processed later by ExpireStale or an expiry pump
  • The local holds list only shows tokens created by this panel

Escrow is real service behaviour.

The service result is truth.

What To Look For

Use the CurrencyEscrowPanel to follow the hold lifecycle from creation to resolution.

  • Setup tab

  • Owner is the wallet receiving holds

  • Service shows the resolved ICurrencyService stack
  • Escrow shows whether ICurrencyEscrow is present
  • Pump shows whether a CurrencyEscrowExpiryPump is attached

  • Reason / SourceId are passed into escrow operations

  • Currency

  • Selects which CurrencyDefinition can be held

  • Resolves the selected CurrencyId

  • Shows the live owner balance before and after holds

  • Hold Inputs

  • Amount controls how much currency is reserved

  • TTL controls how long the hold can live before expiry processing
  • TTL of 0 means no automatic expiry

  • Try Hold calls TryHold and debits immediately when successful

  • Holds tab

  • Shows tokens created by this panel

  • Shows token, currency, amount, and age/TTL
  • Commit keeps the debit

  • Release refunds the held amount

  • Pump tab

  • Can add or remove a local CurrencyEscrowExpiryPump

  • Can adjust pump interval
  • Manual ExpireStale triggers expiry processing immediately

Sample Scope

This scene covers:

  • Detecting ICurrencyEscrow on the active service stack
  • Creating hard holds with TryHold
  • Resolving holds with Commit and Release
  • TTL-based expiry concepts
  • Manual expiry through ExpireStale
  • Optional expiry pumping through CurrencyEscrowExpiryPump
  • Verifying changes through live wallet balance and returned results

This scene does NOT cover:

  • Full checkout system design
  • Crafting reservation flows in depth
  • Persisting escrow tokens across scene loads
  • Network-safe token ownership
  • Production cleanup policies
  • Multiplayer replication or networking

Those are project-level integration concerns.

Authority Note

This scene may include a permissive sample authority setup so it runs without additional configuration.

Networking Reminder

RevFramework does not include networking.

For multiplayer projects, escrow requests, commits, releases, and expiry decisions must be validated and executed through your own authority and networking layer.

How To Use

  1. Enter Play Mode.
  2. Toggle the CurrencyEscrowPanel with F8.

  3. In Setup:

  4. Confirm Owner is assigned

  5. Confirm ICurrencyService is resolved
  6. Confirm Escrow is present
  7. Use another panel or gameplay to give the owner enough currency for a hold.
  8. Select a currency.
  9. Enter a hold amount.
  10. Optionally enter a TTL in seconds.
  11. Press Try Hold.
  12. Confirm the live balance drops immediately.

  13. Open Holds:

    • Press Commit to keep the debit
    • Press Release to refund the held amount

    • Open Pump:

    • Add a pump if needed

    • Adjust the interval if needed
    • Press ExpireStale manually to process stale holds immediately

Failure Behaviour

Failures are shown through dependency messages, hold results, token results, or expiry results.

Common causes:

  • Play Mode required

  • Escrow holds and TTL expiry run against live wallet state

  • Fix: enter Play Mode

  • Service missing

  • No ICurrencyService was resolved

  • Fix: add SceneCurrencyService, add CurrencyServiceBootstrap, or publish a composed service

  • Escrow not composed

  • The resolved service stack does not expose ICurrencyEscrow

  • Fix: compose escrow support using the appropriate currency factory/bootstrap setup

  • Owner missing

  • No wallet owner is selected

  • Fix: assign an owner or tag the player GameObject as Player

  • No currencies bound

  • No CurrencyDefinition assets are available for holds

  • Fix: assign currencies in the Inspector or provide a CurrencySet

  • Invalid CurrencyId

  • The selected CurrencyDefinition has an invalid Id

  • Fix: correct the CurrencyDefinition asset

  • Invalid hold amount

  • Hold amount must be greater than zero

  • Fix: enter a positive amount

  • Hold failed

  • The service rejected the hard hold

  • Fix: check owner balance, escrow composition, caps/policy, authority, and selected currency

  • Commit or Release failed

  • The token could not be resolved

  • Fix: the token may already be committed, released, expired, or unknown to the escrow service

  • Expired token still appears locally

  • The local holds list only tracks tokens created by this panel

  • Fix: trust the escrow result; the local list is not a full escrow database view

Behind The Scenes

The panel uses real Currency escrow APIs:

  • CurrencyResolve.ServiceFrom

  • resolves the active ICurrencyService

  • CurrencyFactories.TryGetEscrow

  • detects ICurrencyEscrow on the composed service stack

  • ICurrencyEscrow

  • TryHold

  • Commit
  • Release

  • ExpireStale

  • CurrencyEscrowExpiryPump

  • periodically calls expiry processing on the escrow service

  • ICurrencyService

  • provides the live wallet state used to verify escrow effects

The panel does not inspect escrow internals.

The local holds list is only a teaching list of tokens created here.

The escrow service decides whether each token operation succeeds.

Key Takeaway

Escrow is a hard hold.

TryHold reserves currency by debiting it immediately.

Commit keeps the debit, Release refunds it, and expiry processing resolves stale holds.