@playmos/sdk 0.1.6 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # @playmos/sdk
 
+**🧪 Beta — Playmos SDK.** Runs on Base Sepolia **testnet**. The value-movement primitives (escrow / marketplace / transfer) are proven on-chain but **not yet production-hardened**, and nothing is on mainnet. Build and integrate freely against the sandbox; don't route real user funds yet.
+
 Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-game prize-pool entries (10%, 60/30/10), and agent economies. USD in, USDC on-chain — no crypto UX for your players.
 
 ## Install
@@ -8,6 +10,15 @@ Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-
 npm i @playmos/sdk
 ```
 
+Requires **Node 18 / 20 / 22 LTS** for the monorepo toolchains (Hardhat/service). See repo `docs/TOOLCHAIN.md` (issue #5).
+
+## Browser vs server entry
+
+- **Games (browser / Vite / Phaser):** `import { Playmos } from "@playmos/sdk"` — this entry is browser-safe and does **not** import Node `crypto` (issue #9).
+- **Your backend (webhook receivers):** `import { verifyWebhook } from "@playmos/sdk/server"` — HMAC verification uses Node crypto and must stay off the client bundle.
+
+The sandbox API also sends CORS headers so browser `pay()` / `enterRound()` work without a same-origin proxy (issue #10).
+
 ## Quickstart — the no-wallet sandbox
 
 The public sandbox key `pk_test_playmos_sandbox` runs against a real Playmos test service on Base Sepolia. **You don't need a wallet:** on a `pk_test` key with no `wallet` configured, the SDK routes to a server-settle path where Playmos signs and submits the on-chain transaction for you. You still get a real, confirmed `txHash` — just signed by the service. No wallet, no gas, no crypto.
@@ -45,6 +56,118 @@ const entry = await playmos.enterRound({
 // entry.status === "confirmed"; entry.split is the on-chain 60/30/10 breakdown
 ```
 
+### Move USDC between wallets — `transfer()`
+
+The base value-movement primitive: move USDC from one wallet to another with a configurable per-call fee. The **game logic is the authority** — you already decided the move is valid — so this is a direct, unconditional push (reach for `escrow`/`marketplace` when a trust boundary needs fair exchange). Settled through the on-chain `PlaymosTransfer` contract; the split is verifiable on BaseScan.
+
+```ts
+// NPC→NPC with a 5% fee (Playmos Town P2P). Requires sk_test_ + agents.createWallet first.
+// Full agent/Town walkthrough: see "Agent economies — the Playmos Town golden path" below.
+// Confirm: status === "settled" && txHash, or await playmos.transfers.wait(id) if settling.
+const t = await playmos.transfer({
+  // `from` is OPTIONAL in the sandbox — omit it and the service uses its server-held signer wallet
+  // (Phase 1a's only payer), so you don't need to know that address to run this example.
+  to:     "0x…blacksmith",
+  amount: "0.80",         // USD; USDC settles on-chain. Stay UNDER the $1.00 sandbox cap (see below).
+  feeBps: 500,            // 5% — 0–10000
+  feeSink: "0x…treasury", // required when feeBps > 0
+  memo:   "ore",          // optional, echoed on the receipt
+});
+t.status;          // "settled" — real, on Base Sepolia
+t.txHash;          // 0x… open on sepolia.basescan.org
+t.net;             // "0.76"  (payee)
+t.fee;             // "0.04"  (feeSink)
+t.idempotentReplay; // false on the first settle
+```
+
+**`feeBps: 0` is an untaxed reward/faucet transfer** (no fee taken; `feeSink` not needed) — e.g. a monster-bounty payout from a world wallet to a fighter. Set `feeBps: 10000` for a 100% first-party sale (all of it to `feeSink`).
+
+| Field | Required | Notes |
+|---|---|---|
+| `from` | no | Payer wallet — a `0x` address. **Omit in the sandbox** and the service defaults it to its server-held signer wallet (Phase 1a's only payer). If supplied, it must be that wallet. |
+| `to` | yes | Payee wallet — a `0x` address. |
+| `amount` | yes | USD decimal string ("0.80"); > 0, ≤ 2 dp. **Sandbox cap: ≤ $1.00 per transfer** (see limits below). |
+| `feeBps` | no (default `0`) | Per-call fee in bps, **0–10000**. `0` = untaxed reward/faucet. |
+| `feeSink` | when `feeBps > 0` | Fee destination `0x` address. |
+| `memo` | no | Optional note, echoed on the receipt. |
+| `idempotencyKey` | no | Pass the same key on a retry to guarantee **at most one** on-chain transfer (see below). |
+
+**Sandbox limits (enforced before any signing).** The public sandbox signs from a shared funded testnet wallet, so the transfer path is guarded: **$1.00 max per transfer** (a larger `amount` is a `400`), **5 requests/minute** per IP and per key (`429`), and a **$20/day budget** across all sandbox transfers (`429`). These are testnet abuse controls — not product limits.
+
+**Retries are safe (idempotent, no double-spend).** Every transfer is anchored on a requirement id derived from `idempotencyKey`. The service durably reserves the transfer *before* broadcasting, so a retry with the same key — or two concurrent calls with the same key — **broadcast at most one transaction**; the loser returns the original result with `idempotentReplay: true`. Preview the split with no network via `previewTransferSplit(amount, feeBps)`. Reusing an id with **different** terms (payTo/amount/fee/sink/from) is rejected, not silently replayed.
+
+**REST (no SDK).** The SDK's `transfer()` is a thin wrapper over `POST /v1/transfers`:
+
+```bash
+curl -X POST https://<sandbox-host>/v1/transfers \
+  -H "Authorization: Bearer pk_test_playmos_sandbox" \
+  -H "Content-Type: application/json" \
+  -d '{ "to": "0x…blacksmith", "amount": "0.80", "feeBps": 500, "feeSink": "0x…treasury", "memo": "ore", "idempotencyKey": "ore-trade-1" }'
+```
+
+Fields match the table above (`from` optional → defaults to the signer; `feeBps`/`feeSink` as documented). Poll `GET /v1/transfers/:id` to reconcile a transfer's status against the chain (it recovers a transfer left mid-flight by a crash).
+
+> Sandbox only (Phase 1a): `transfer` settles server-held NPC/agent wallets on Base Sepolia. The player-signed (EIP-3009) non-custodial path is Phase 1b.
+
+### Agent economies — the Playmos Town golden path
+
+The NPCs in your game can hold and move USDC. This is the loop the [Playmos Town example](https://github.com/playmos-labs/playmos-sdk/blob/main/docs/examples/playmos-town-sdk.mjs) runs end to end: give each NPC a wallet, fund it, then move value with a per-call fee — P2P (5%), a monster bounty (0%), a shop sale (100%).
+
+**Agents need a SECRET test key — `sk_test_`, not `pk_test_`.** Assigning NPC wallets and transferring *from* an NPC are privileged, server-side actions, so they require an `sk_test_` key kept on **your backend** — not the public `pk_test_playmos_sandbox`. `pk_test_` runs the no-wallet `pay()` / `enterRound()` demos above; `sk_test_` unlocks `agents.*` and NPC-funded `transfer`.
+
+```ts
+import { Playmos } from "@playmos/sdk";
+
+// Server-side only — an sk_test_ secret key, never shipped to the browser.
+const playmos = new Playmos({ apiKey: process.env.PLAYMOS_SK_TEST });
+const feeSink = process.env.PLAYMOS_FEE_SINK; // 0x treasury / shop wallet
+
+// 1) Assign a wallet to an NPC your game already owns (idempotent — safe to re-call).
+const miner = await playmos.agents.createWallet({ agentId: "npc_pico_miner" });
+miner.address; // 0x… — the NPC's USDC wallet on Base Sepolia
+
+// 2) Fund it from your treasury (sandbox faucet, per-NPC lifetime cap).
+const funded = await playmos.agents.fund({ agentId: "npc_pico_miner", amount: "0.20" });
+funded.funding.status; // "settled" | "settling"
+
+// 3a) P2P trade — 5% fee to the treasury (feeBps: 500). NPC `from` ⇒ gasless (NPC signs, Playmos relays + pays gas).
+const p2p = await playmos.transfer({
+  from:    "npc_pico_miner",
+  to:      "npc_bruna_blacksmith",
+  amount:  "0.10",
+  feeBps:  500,       // 5% P2P
+  feeSink,            // required when feeBps > 0
+});
+
+// Confirm with the new ergonomics (#54): wait for a terminal state — no hand-rolled poll loop.
+const settled = await playmos.transfers.wait(p2p.id);
+settled.status; // "settled" — txHash on sepolia.basescan.org
+
+// 3b) Monster-bounty payout — 0% untaxed reward from the treasury signer (omit `from`, no feeSink).
+await playmos.transfer({ to: "npc_wynn_ranger", amount: "0.05", feeBps: 0 });
+
+// 3c) First-party shop sale — 100% to the shop (feeBps: 10000).
+await playmos.transfer({ from: "npc_kane_knight", to: feeSink, amount: "0.05", feeBps: 10_000, feeSink });
+```
+
+**Prefer one call? Confirm inline.** Pass `{ confirm: true }` and `transfer` blocks until the transfer is terminal before it resolves — identical to calling `transfers.wait(id)` yourself (#54):
+
+```ts
+const t = await playmos.transfer(
+  { from: "npc_pico_miner", to: "npc_bruna_blacksmith", amount: "0.10", feeBps: 500, feeSink },
+  { confirm: true },
+);
+t.status; // "settled" (or "failed") — already terminal, no follow-up call
+```
+
+The sandbox throttles (5 req/min per key), so back-to-back legs can `429`. **Retries are automatic** — the SDK backs off and retries a `429` up to twice by default, and every write carries an idempotency key so a retry never double-broadcasts (tune with `new Playmos({ apiKey, retry: { maxRetries } })`, or `retry: false` to opt out).
+
+The full 5-NPC walkthrough — create → fund → P2P / shop / bounty, each confirmed on-chain — is [`docs/examples/playmos-town-sdk.mjs`](https://github.com/playmos-labs/playmos-sdk/blob/main/docs/examples/playmos-town-sdk.mjs):
+
+```bash
+PLAYMOS_SK_TEST=sk_test_… PLAYMOS_FEE_SINK=0x… node docs/examples/playmos-town-sdk.mjs
+```
+
 ### Verify before you grant
 
 Grant items on a verified confirmation — never on the client `pay()` return alone.
@@ -81,6 +204,29 @@ const playmos = new Playmos({
 
 Promote by swapping the key — the same code that passed in the sandbox works live.
 
+## Value movement — escrow, marketplace, transfer (0.2.0, testnet)
+
+`0.2.0` adds non-custodial USDC value-movement primitives on top of the settlement core:
+
+- **`playmos.transfer(...)`** — a direct USDC transfer.
+- **`playmos.escrow.hold / release / refund / get`** — hold funds against a deal, then pay the payee (fee skimmed at release) or refund the payer (100%). Every term is frozen on-chain at hold.
+- **`playmos.marketplace.list / buy / confirm / refund / cancel / get`** — a listing packaged as an escrow deal (`buy` = hold, `confirm` = release, timeout/dispute = refund), including `buy({ deliver: true })` to hold+release in one call.
+
+**Status quo (2026-07): testnet-sandbox only.** These paths are proven on Base Sepolia (independently reconciled on-chain) but are **not** marketed as production-hardened, and are not on mainnet. For money preflights, **point the service at a dedicated RPC** (Alchemy/QuickNode) — do not rely on a load-balanced public endpoint for read-your-write consistency.
+
+### Resolve status-code contract
+
+The escrow/marketplace resolve endpoints (release/refund/confirm) return a deterministic contract — handle it explicitly:
+
+| Code | Meaning | Client action |
+|------|---------|---------------|
+| **404** | Unknown escrow / listing | Terminal — the id does not exist |
+| **409** | Not resolvable (already released/refunded, or genuinely never held) | Terminal — do not retry |
+| **503** | Transient (RPC read-lag, or a crash-orphaned hold being reconciled) | **Retry** with backoff |
+| **400** | Malformed input | Terminal — fix the request |
+
+**On a `503`, retry the release/confirm** — it means the on-chain state just hasn't propagated yet, not that anything failed.
+
 ## Docs
 
 Full documentation — skill games, webhooks, gas, payouts, agent economies, and the REST API — at [playmos.io](https://playmos.io).