Skip to content

💰 Crafting — Currency Abstractions

📦 Folder Overview

This folder defines the currency integration seam for the Crafting system.

Currency support is optional. If no currency adapter is provided, the Crafting service skips currency checks and treats recipes as having no enforced currency cost.

🧩 What Lives Here

  • ICraftingCurrencyAdapter — primary currency integration contract
  • ICraftingCurrencyHoldAdapter — optional escrow/hold extension
  • CraftCurrencyHoldToken — value representing a currency hold

🎯 Purpose

These abstractions provide a way to:

  • integrate Crafting with external currency systems
  • perform balance checks and debits during crafting
  • optionally support escrow-style, two-phase currency flows

They allow Crafting to remain currency-agnostic while supporting different backend implementations.

🧠 Usage Guidance

ICraftingCurrencyAdapter

Used by the Crafting service to:

  • query balances
  • attempt to debit currency
  • credit currency amounts

Normal failure should be reported via return values rather than exceptions.

Credit does not return a success value. Implementations should avoid throwing for expected failure modes.

ICraftingCurrencyHoldAdapter (optional)

An optional extension used by escrow-style crafting.

Supports a two-phase model:

  1. Hold (reserve currency)
  2. Capture (commit the hold)

Correctness guarantees (such as atomicity or idempotency) depend on the adapter implementation. The Crafting service relies on these guarantees but does not enforce them.

CraftCurrencyHoldToken

A lightweight value representing a held currency reservation.

⚠️ Important Notes

  • Currency integration depends on the adapter provided by the project
  • Missing adapters result in currency checks being skipped
  • Escrow paths require a hold-capable adapter to function
  • Crafting Core (currency usage in preflight and execution)
  • Integrations (currency adapter implementations)