@pwngh/economy-lab
    Preparing search index...

    Interface InstanceEconomy

    One epoch's lane over one netting session. purchase grants now and defers the money; settle nets the epoch to the ledger and applies the backstops — grants whose movement the settle replay refused are revoked (the report's revoked list), immature holds release, and prefund escrows refund their remainder to spendable. Every entry point rides one internal writer queue, so concurrent calls from an HTTP edge serialize instead of forking the session chain. Construct through openInstanceEconomy, or InstanceEconomies.laneFor.

    interface InstanceEconomy {
        flush(): Promise<void>;
        pending(userId: string): Promise<Amount>;
        purchase(input: InstancePurchase): Promise<PurchaseOutcome>;
        settle(): Promise<InstanceSettleReport>;
        spentOf(userId: string): Amount;
        stats(): { accepted: number; rejected: number };
    }
    Index
    • Forces the journal batch out (a durability point between settles).

      Returns Promise<void>

    • This tier's pending-out total for the user, for display as balance - pending.

      Parameters

      • userId: string

      Returns Promise<Amount>

    • One in-world purchase, grant-now-settle-later: the entitlement grant is durable before the movement is offered to the session, so ownership reads true everywhere immediately while the money waits for epoch-end settle (the worst crash leaves one owned-but-unpaid item, reconcilable by its sale:<orderId> source — never lost money). Idempotent per orderId: a repeat replays the recorded outcome. Malformed input throws; the expected refusals come back rejected — INSUFFICIENT_FUNDS against matured balance minus everything pending (or a failed prefund), RISK_DENIED over perUserCapMinor — and a rejection leaves no grant behind.

      Parameters

      Returns Promise<PurchaseOutcome>

    • The buyer's accepted spend this epoch — the total perUserCapMinor screens against.

      Parameters

      • userId: string

      Returns Amount

    • This epoch's accepted and rejected purchase counts; the manager's sweep reads accepted against its rotation bound.

      Returns { accepted: number; rejected: number }