402-trinity-gaming 0.1.0

package/INTEGRATION.md

@@ -0,0 +1,188 @@
+# ⚡ 402-Trinity-Gaming — Integration Brief
+
+**A white-label microtransaction engine for game storefronts. The player holds their own wallet.**
+
+Players buy cosmetics, battle passes and timer skips without ever leaving your game. No
+overlay, no browser tab, no checkout screen wearing someone else's brand. Your button, your
+art, your unlock animation.
+
+---
+
+## 🛠️ Step 1 — Studio setup (done once)
+
+**Install** into your existing game backend:
+
+```bash
+npm install 402-trinity-gaming
+```
+
+**Configure** your catalog and your treasury:
+
+```js
+const store = createStorefront({
+  payTo: '0xYourStudioTreasury',
+  network: 'base',
+  facilitator: 'https://...',
+  nonceStore,
+  catalog: {
+    vanguard_skin_01: '1500000',   // $1.50
+    season_pass_04:   '9990000',   // $9.99
+  },
+  surcharge: { proceedsKey },
+});
+```
+
+**Hook up your UI.** Your artists design the store exactly how they want. When a player taps
+*Purchase*, your button calls your server, and two events come back — one when the purchase is
+accepted, one when the money has moved:
+
+```js
+store.on('settled',  e => grantItem(e.playerId, e.itemId));
+store.on('declined', e => showRefusal(e.playerId, e.code));
+```
+
+That is the whole integration surface. Nothing renders, nothing takes over input, and nothing
+writes to your console — the build fails if it does.
+
+> Prices live in your server's catalog, never in the client call. A client that names its own
+> price is a client that sets its own price.
+
+---
+
+## 🕹️ Step 2 — Player wallet (done once per player)
+
+When a player creates an account, your client generates a wallet on their device.
+
+```js
+const { privateKey, address } = createPlayerWallet();
+```
+
+You store the address. **They** keep the key — you never hold it, and you cannot spend from
+their wallet. The player is the real buyer, paying you directly.
+
+> **If you use tabs** (see below), note that a partly-spent tab *is* a balance you hold: the
+> player's cash is yours, and what they have left is credit in your game. That is closed-loop
+> — spendable only on your items, never withdrawable — so it is the same shape as any in-game
+> currency, not a deposit account. Worth raising with your counsel all the same.
+
+> **Yours to build today:** the encryption, unlock and backup flow. We hand you the key; where
+> it sleeps is your product decision. There is no password reset — give players a recovery
+> phrase or an encrypted backup at setup.
+
+---
+
+## 💳 Step 3 — Funding the wallet
+
+It is an ordinary Base address, so there are two doors and you can open either.
+
+**Players who hold crypto** send USDC straight to it from any exchange or wallet.
+
+**Everyone else** goes through a card on-ramp you drop into your launcher or account page.
+They pay with a card, USDC lands in their wallet.
+
+---
+
+## ⚔️ Step 4 — The checkout loop
+
+A player taps *Buy* on a $5.00 weapon skin, mid-lobby.
+
+**On their machine**, the client signs one authorization — about **3 milliseconds**,
+comfortably inside a frame, touching no network. Only the signature leaves the device.
+
+**On your server**, that signature is verified and settled through your facilitator.
+
+**Back in the game**, `accepted` fires the moment the signature checks out, and `settled` when
+the transfer confirms on Base a few seconds later.
+
+**Design this bit deliberately.** Settlement is a real transfer on a real chain — seconds, not
+milliseconds. Want the skin to appear the instant they tap? Grant on `accepted` and reconcile
+on `settled`. Rather never take something back? Wait for `settled`. One line either way.
+
+**The player is debited exactly $5.00.** The price on the label is the price they pay.
+
+---
+
+## 🔁 Tabs — for games that charge constantly
+
+Survival, MMO and sandbox economies bill in fractions of a cent: a timer skip, a stack of ore,
+a repair. Settling each one on-chain costs more in gas than the action costs the player.
+
+So the player **loads a tab** — one signature, one transfer — and every action after that is a
+deduction from that credit. No signature, no chain, no gas, nothing to wait for.
+
+```js
+const tabs = createBatchManager({
+  ...sameConfigAsAbove,
+  tabs: { session: '2000000' },   // $2.00 of credit
+  ledger,                         // durable - see below
+});
+
+await tabs.open({ tabId: 'session', playerId, playerAddress, authorization, signature });
+
+// then, on any gameplay path:
+await tabs.spend({ playerId, actionId: 'skip:furnace:8412', amount: '20000' });
+```
+
+**Why it is worth doing:** a hundred separate $0.02 payments cost roughly $0.13 in gas. One
+$2.00 tab costs about $0.0013. Same money to you.
+
+**`actionId` makes spending idempotent.** A client that retries after a dropped connection is
+charged once; the second call reports `duplicate: true` so you still grant the item.
+
+**Your ledger must be durable.** In memory, every player's remaining credit dies with the
+process — they paid for something your server no longer remembers. Use the file store for a
+single instance, or your own database adapter for more than one:
+
+```js
+import { createFileLedgerStore } from '402-trinity-gaming/budget-file';
+const ledger = createFileLedgerStore('./tabs.json');
+```
+
+**If you run more than one game server**, implement `ledger.update()` and hold a row lock
+across the read and the write. Without it, two servers can read the same balance and both
+approve a spend it could only cover once.
+
+**A tab is a balance you hold.** The player's cash is yours the moment the tab opens; what
+they have left is credit in your game.
+
+**Giving it back:**
+
+```js
+await tabs.refund({ playerId });                    // everything unspent
+await tabs.refund({ playerId, amount: '500000' });  // or part of it
+```
+
+Your treasury signs, the facilitator submits, the USDC lands back in the player's wallet — you
+need no gas. The credit is deducted before the transfer is attempted, so it cannot be spent
+while the refund is in flight, and it is **put back if the transfer fails**. Requires
+`surcharge.proceedsKey`, since that is the key for the wallet holding the money.
+
+The 0.1% taken when the tab opened is not reversed — it was charged on a sale that happened.
+
+---
+
+## 🧾 When something is refused
+
+Every refusal comes back with a code you can switch on — item not for sale, bad signature,
+authorization already spent, or settlement failed on the server's side.
+
+Each also carries **`retryable`**, and it is the field that stops you charging a player twice.
+When settlement fails on our side the payment was valid, so the *same* authorization must go
+out again — minting a fresh one risks paying twice if the first lands late. When a signature
+is rejected or already spent, it will never work. We make that call so your code doesn't have
+to.
+
+---
+
+## 📦 What you get today
+
+**Available now:** the TypeScript backend library and client signer. Base mainnet, USDC.
+
+**Coming:** native Unity (C#) and Unreal (C++) packages — the signer is a single function and
+porting it is next. Key encryption and the card on-ramp are yours for now.
+
+---
+
+Business Source License 1.1. Source-available; converts to MIT on 2029-08-25.
+
+Merchant proceeds are settled net of a 0.1% network fee.

package/LICENSE

@@ -0,0 +1,110 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             x402 trinity
+
+Licensed Work:        x402-trinity
+                      The Licensed Work is (c) 2026 x402 trinity
+
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you do not offer the Licensed Work to third parties as
+                      a hosted or managed service that provides users with
+                      access to any substantial set of its features or
+                      functionality.
+
+Change Date:          2029-08-25
+
+Change License:       MIT
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses
+   without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+THIS SOFTWARE MOVES MONEY. Additional notice:
+
+This software constructs and signs cryptographic payment authorizations. You
+are solely responsible for the funds in any wallet you configure it with, for
+the spending limits you set, and for the behaviour of any autonomous agent you
+connect to it. Set `maxAmountPerRequest` and `totalBudget`, use a dedicated
+wallet, and read the security notes in the README before using it with real
+assets.

package/README.md

@@ -0,0 +1,105 @@
+# 402-trinity-gaming
+
+**A payment backend for game storefronts that your players never see.**
+
+No UI. No overlay. No browser handoff. No console output. Your button, your art, your unlock
+animation — this handles the money and gets out of the way.
+
+```bash
+npm install 402-trinity-gaming
+```
+
+## How it fits
+
+```
+Your storefront UI  ──▶  your backend  ──▶  chain
+   (Unreal/Unity)         (this package)
+        ▲                       │
+        └────── events ─────────┘
+```
+
+The player's client signs one authorization with their own key. Your server does everything
+else. **You never hold the player's key**, and for direct purchases you hold no balance
+either. (Tabs are the exception - see `INTEGRATION.md`.)
+
+## Use
+
+```js
+import { createStorefront } from '402-trinity-gaming/storefront';
+
+const store = createStorefront({
+  payTo: '0xYourStudioWallet',
+  network: 'base',
+  facilitator: 'https://your-facilitator.example',   // REQUIRED - no default
+  nonceStore,                                        // REQUIRED - must survive restarts
+  catalog: {
+    vanguard_skin_01: '1500000',   // atomic units: 1.50 USDC (6 decimals)
+    season_pass_04:  '9990000',    // 9.99
+  },
+  surcharge: { proceedsKey },      // the key for payTo
+});
+
+store.on('settled',  e => grantItem(e.playerId, e.itemId));
+store.on('declined', e => showRefusal(e.playerId, e.code));
+```
+
+Serve the quote, take the signature, redeem it:
+
+```js
+// 1. the client asks what it must sign
+const quote = store.quote('vanguard_skin_01');
+
+// 2. the client signs it and posts back { authorization, signature }
+const result = await store.purchase({
+  itemId: 'vanguard_skin_01',
+  playerId: 'player-8823',
+  playerAddress: '0xPlayerWallet',
+  authorization,
+  signature,
+});
+```
+
+## Events
+
+| event | when | what to do |
+|---|---|---|
+| `accepted` | the request is well formed, the item is real, settlement is underway | grant optimistically if you want the item to appear instantly |
+| `settled` | the money has moved, with an on-chain transaction hash | grant, or reconcile an optimistic grant |
+| `declined` | it was refused | read `code`, not `message` |
+
+Decline codes are `unknown_item`, `already_used`, `rejected`, `settlement_failed` and
+`malformed`. Each carries `retryable` — **true** means the same authorization may be presented
+again unchanged, **false** means mint a fresh one. Re-sending when `retryable` is false risks
+paying twice.
+
+## Prices are strings
+
+Atomic units of the asset, as a decimal string. USDC has 6 decimals, so `1.50` is
+`'1500000'`. A float cannot represent money exactly, and this value goes inside a signature.
+
+## Nothing is printed
+
+This library never writes to `stdout` or `stderr` — that is enforced by its build, not by
+convention. Diagnostics reach you through `onDiagnostic`, and the fee disclosure is exported
+as `NOTICE` for you to place wherever disclosure belongs in your product.
+
+## Scope
+
+**Base mainnet + USDC.** Other EVM chains work by passing `customChains`. Check any entry
+against the deployed contract first: call `DOMAIN_SEPARATOR()` and confirm it matches what
+this library computes. A wrong `name` or `version` produces a signature that looks valid and
+the contract rejects.
+
+## Before you use it with real money
+
+This software signs payment authorizations. You are responsible for the funds in any wallet
+you configure it with and for the limits you set. `nonceStore` must be durable — an in-memory
+replay guard forgets every settled payment on restart, which means selling the same item twice
+for free.
+
+## License
+
+Business Source License 1.1. Source-available; converts to MIT on 2029-08-25. See
+[LICENSE](LICENSE).
+
+Network fee: 0.1% of merchant proceeds and 1 cent every 100 sales.

package/dist/batch-manager.d.ts

@@ -0,0 +1,201 @@
+/**
+ * OFF-CHAIN MICRO-ACTION LEDGER.
+ *
+ * Survival, MMO and sandbox economies charge constantly and in fractions of a cent - a timer
+ * skip, a stack of ore, a repair. Settling each one on-chain costs more in gas than the
+ * action costs the player, so nothing here touches the chain per action.
+ *
+ * Instead the player opens a TAB: one signed authorization, settled once, credited to a local
+ * ledger. Every action after that is a synchronous deduction - no signature, no network, no
+ * frame cost. When the tab runs low the player tops up with another single signature.
+ *
+ *     const tab = await tabs.open({ playerId, playerAddress, authorization, signature });
+ *     tabs.spend({ playerId, actionId: 'skip:furnace:8412', amount: '20000' });  // instant
+ *
+ * WHY A TAB AND NOT A HUNDRED CACHED SIGNATURES. An EIP-3009 authorization is redeemed by its
+ * own contract call with its own nonce; a hundred of them cannot be summed into one transfer.
+ * Caching signatures and flushing them together still costs a hundred settlements - about
+ * 6.4% of a $2.00 batch at real Base gas, against 0.06% for a single one. The saving comes
+ * from one signature covering the batch, not from when the signatures are sent.
+ *
+ * WHY PREPAID AND NOT POSTPAID. Charging at the END of a hundred actions means granting
+ * ninety-nine of them on credit. A player who closes the game keeps them, and a farm of bots
+ * does it deliberately. Money in hand first removes the question.
+ */
+import { type StorefrontConfig, type PurchaseDeclined } from './storefront.js';
+import type { Authorization } from './x402.js';
+export interface TabConfig extends Omit<StorefrontConfig, 'catalog'> {
+    /**
+     * Tab sizes a player may open, in atomic units. Named like a catalog because that is what
+     * they are - a $2.00 tab is a $2.00 purchase that happens to be spent gradually.
+     */
+    tabs: Record<string, string>;
+    /**
+     * Durable ledger. WITHOUT ONE, EVERY PLAYER'S REMAINING BALANCE IS LOST ON RESTART - they
+     * paid for credit the process no longer remembers. In memory is for local development only.
+     */
+    ledger?: LedgerStore;
+    /** Warn when a tab drops below this fraction of its opening size. Default 0.15. */
+    lowWaterMark?: number;
+}
+export interface LedgerStore {
+    get: (playerId: string) => Promise<TabState | null>;
+    set: (playerId: string, s: TabState) => Promise<void>;
+    /** Read-modify-write under a lock. Without it two game servers double-spend one tab. */
+    update?: (playerId: string, fn: (cur: TabState | null) => TabState) => Promise<TabState>;
+}
+export interface TabState {
+    playerAddress: string;
+    /** Atomic units still available. */
+    remaining: string;
+    /** What the tab was opened for, for reporting. */
+    opened: string;
+    /**
+     * Action ids already charged, with when. Kept BY AGE rather than by count: a retry happens
+     * within seconds, so a day is generous - and a cap by count means a long-lived tab silently
+     * forgets an old id and charges for it a second time.
+     */
+    spent: Array<{
+        id: string;
+        at: number;
+    }>;
+    updatedAt: string;
+}
+export type SpendResult = {
+    ok: true;
+    remaining: string;
+    charged: string;
+    duplicate: boolean;
+} | {
+    ok: false;
+    code: 'no_tab' | 'insufficient' | 'invalid_amount';
+    remaining: string;
+    message: string;
+};
+export type RefundResult = {
+    ok: true;
+    refunded: string;
+    remaining: string;
+    transaction: string;
+} | {
+    ok: false;
+    code: 'no_tab' | 'nothing_to_refund' | 'too_much' | 'no_key' | 'failed';
+    remaining: string;
+    message: string;
+};
+interface Events {
+    opened: {
+        playerId: string;
+        playerAddress: string;
+        amount: string;
+        transaction: string;
+    };
+    refunded: {
+        playerId: string;
+        playerAddress: string;
+        amount: string;
+        transaction: string;
+    };
+    spent: {
+        playerId: string;
+        actionId: string;
+        amount: string;
+        remaining: string;
+    };
+    low: {
+        playerId: string;
+        remaining: string;
+        opened: string;
+    };
+    exhausted: {
+        playerId: string;
+    };
+}
+export declare function createBatchManager(cfg: TabConfig): {
+    /** Tab sizes on offer. */
+    readonly sizes: string[];
+    /** What the client signs to open tab `tabId`. */
+    quote(tabId: string): {
+        scheme: string;
+        network: string;
+        amount: string;
+        asset: string;
+        payTo: string;
+        maxTimeoutSeconds: number;
+        extra: {
+            name: string;
+            version: string;
+        };
+        itemId: string;
+    } | null;
+    on<K extends keyof Events>(n: K, h: (e: Events[K]) => void): () => void;
+    /**
+     * Open or top up a tab. This is the ONLY on-chain step - one settlement covering every
+     * action the player takes until the balance runs out.
+     *
+     * Credit is added only after the transfer settles. A declined payment adds nothing.
+     */
+    open(req: {
+        tabId: string;
+        playerId: string;
+        playerAddress: string;
+        authorization: Authorization;
+        signature: string;
+    }): Promise<{
+        ok: true;
+        remaining: string;
+        transaction: string;
+    } | {
+        ok: false;
+        declined: PurchaseDeclined;
+    }>;
+    /**
+     * Charge one micro-action. Synchronous in spirit - no signature, no chain, no network -
+     * so it is safe on a gameplay path.
+     *
+     * `actionId` makes it idempotent. A client that retries after a dropped response charges
+     * once, and the second call reports `duplicate: true` so you can grant without re-billing.
+     */
+    spend(req: {
+        playerId: string;
+        actionId: string;
+        amount: string;
+    }): Promise<SpendResult>;
+    /**
+     * Return unspent credit to the player's wallet.
+     *
+     * The studio signs an authorization to the player and the facilitator submits it, so the
+     * studio needs no gas - the same shape as every other transfer here, just pointing the
+     * other way. Requires `surcharge.proceedsKey`, because that is the key for the wallet
+     * holding the money.
+     *
+     * ORDER MATTERS. The credit is deducted BEFORE the transfer is attempted, so it cannot be
+     * spent while the refund is in flight, and restored if the transfer fails. The opposite
+     * order lets a player spend the same money twice - once in-game and once on-chain.
+     *
+     * The 0.1% taken when the tab opened is NOT reversed. It was charged on a sale that did
+     * happen, and clawing it back out of the vault is not something this can do.
+     */
+    refund(req: {
+        playerId: string;
+        amount?: string;
+    }): Promise<RefundResult>;
+    /** What the player has left. Read-only. */
+    balance(playerId: string): Promise<{
+        remaining: string;
+        opened: string;
+    } | null>;
+    /** The network fee taken from proceeds when a tab is opened. */
+    fee: {
+        readonly enabled: boolean;
+        stats: () => Promise<{
+            enabled: boolean;
+            salesSinceLastSweep: string;
+            accrued: string;
+            collected: string;
+            held: string;
+            lost: string;
+        }>;
+    };
+};
+export {};