Release v1.0.0

.claude/rules/CLAUDE.md

@@ -2,19 +2,22 @@
 
 This is the rules knowledge base. Every file here is a **self-contained rule sheet** Claude loads on demand when the touched code matches its scope. Rules override defaults; CLAUDE.md at the repo root sets the floor.
 
+The SDK is a **TypeScript-only** pnpm/turbo monorepo under [typescript/](../../typescript/CLAUDE.md). `core` and `mechanisms/evm` are **upstream forks** (keep byte-identical, additions go in overlays); `mechanisms/tron` is in-house. There is no Python in the current SDK. (The previous-generation Python + old TypeScript code lives under `legacy/` and is slated for removal — these rules do **not** cover it.)
+
 ## When Claude reads what
 
 | Scope of the change | Always read | Also read |
 |---|---|---|
 | Any file in the repo | [common/conventions.md](common/conventions.md) | — |
-| Python code under `python/x402/` | common/ | [python/conventions.md](python/conventions.md) |
 | TypeScript under `typescript/packages/` | common/ | [typescript/conventions.md](typescript/conventions.md) |
-| Scheme `exact` (ERC-3009) code or spec | common/ | [schemes/exact.md](schemes/exact.md) |
-| Scheme `exact_permit` (EIP-2612) code or spec | common/ | [schemes/exact-permit.md](schemes/exact-permit.md) |
-| Scheme `exact_gasfree` (TRON GasFree) code or spec | common/ | [schemes/exact-gasfree.md](schemes/exact-gasfree.md) + [networks/tron.md](networks/tron.md) |
-| TRON mechanisms / config | common/ | [networks/tron.md](networks/tron.md) |
-| EVM mechanisms / config | common/ | [networks/evm.md](networks/evm.md) |
-| e2e scenarios (`e2e/scenarios/`, `integration/`) | common/ | [testing/scenarios.md](testing/scenarios.md) |
+| Scheme `exact` (ERC-3009 / Permit2) | common/ | [schemes/exact.md](schemes/exact.md) |
+| Scheme `upto` (usage-based) | common/ | [schemes/upto.md](schemes/upto.md) |
+| Scheme `batch-settlement` (payment channels) | common/ | [schemes/batch-settlement.md](schemes/batch-settlement.md) |
+| Scheme `auth-capture` (EVM authorize+capture) | common/ | [schemes/auth-capture.md](schemes/auth-capture.md) |
+| Scheme `exact_gasfree` (TRON GasFree) | common/ | [schemes/exact-gasfree.md](schemes/exact-gasfree.md) + [networks/tron.md](networks/tron.md) |
+| TRON mechanisms (`mechanisms/tron`) | common/ | [networks/tron.md](networks/tron.md) |
+| EVM mechanisms (`mechanisms/evm`) | common/ | [networks/evm.md](networks/evm.md) |
+| Tests (`packages/*/test/**`) | common/ | [testing/conventions.md](testing/conventions.md) |
 
 When multiple rule files apply, read all of them before editing. Rules are layered, not exclusive.
 
@@ -25,18 +28,18 @@ When multiple rule files apply, read all of them before editing. Rules are layer
 ├── common/
 │   └── conventions.md      # repo-wide: addressing, amounts, headers, pipeline, commit style
 ├── schemes/
-│   ├── exact.md            # ERC-3009 transferWithAuthorization
-│   ├── exact-permit.md     # EIP-2612 / TIP-2612 permit + transferFrom
+│   ├── exact.md            # ERC-3009 / Permit2 (extra.assetTransferMethod)
+│   ├── upto.md             # usage-based: sign up-to-max, settle actual
+│   ├── batch-settlement.md # payment channels: deposit + off-chain vouchers + refund
+│   ├── auth-capture.md     # EVM authorize then capture
 │   └── exact-gasfree.md    # TRON GasFree custodial + TIP-712 relayer
 ├── networks/
-│   ├── evm.md              # eip155:<chainId>, contracts, signing, smoke tests
+│   ├── evm.md              # eip155:<chainId>, contracts, signing
 │   └── tron.md             # tron:<name>, TIP-712 hex-address rule, GasFree link
-├── python/
-│   └── conventions.md      # Python 3.11+, uv, pytest, pydantic v2, async-first
 ├── typescript/
-│   └── conventions.md      # Node 20+, pnpm, ESM, viem, BigInt, named exports
+│   └── conventions.md      # pnpm/turbo, ESM, viem/tronweb, fork+overlay, signer factories
 └── testing/
-    └── scenarios.md        # e2e/scenarios/ JSON scenario authoring + ports + tiers
+    └── conventions.md      # vitest unit + integration layout, self-skip, mocking
 ```
 
 ## Authoring a new rule
@@ -45,35 +48,31 @@ Add a rule **only when the knowledge is non-obvious and would otherwise be relea
 
 Structure every rule file:
 
-1. **Header** — one line: what scope this covers + pointer to the canonical spec under `specs/`.
+1. **Header** — one line: what scope this covers + pointer to the authoritative source (the package source, or [typescript/CLAUDE.md](../../typescript/CLAUDE.md)).
 2. **When to use** — the decision the rule answers.
 3. **Key invariants** — the short list that must hold.
-4. **Common gotchas** — cite commits or `docs/solutions.md` entries. Every bullet should map to a real incident.
+4. **Common gotchas** — cite commits. Every bullet should map to a real incident.
 5. **Testing** — where the tests live and what template to reuse.
 
 ### New scheme
 
-1. New spec at `specs/<scheme>.md`.
-2. New rule at `.claude/rules/schemes/<scheme>.md` — link back to the spec.
-3. Register the scheme in the mechanism and the `config.md` registry.
-4. Scenario skeleton: `/x402:create-scenario` (see [../commands/x402/create-scenario.md](../commands/x402/create-scenario.md)).
+1. New scheme classes per role under `mechanisms/<chain>/src/<scheme>/{client,facilitator,server}` — `<Scheme><Chain>Scheme`, same class name across roles, role = import subpath (see [typescript/CLAUDE.md](../../typescript/CLAUDE.md)).
+2. New rule at `.claude/rules/schemes/<scheme>.md`.
+3. Register the scheme on the client/facilitator with `new + register` (thin pass-through register helpers are not added).
 
 ### New network
 
-1. Add to `specs/config.md` registry.
-2. New rule at `.claude/rules/networks/<name>.md` — chain ids, signing rules, RPC defaults, contract table.
-3. If it introduces a new signing flavor (e.g. TIP-712 analogue), document the conversion helpers.
+1. New rule at `.claude/rules/networks/<name>.md` — chain ids, signing rules, RPC defaults, contract table.
+2. If it introduces a new signing flavor (e.g. a TIP-712 analogue), document the conversion helpers.
 
 ## Relation to other surfaces
 
-- **specs/** — authoritative protocol definitions. Rules cite specs; specs do not cite rules.
-- **docs/solutions.md** — incident log. Rules point here when a gotcha came from a real bug; new solutions are added via `/x402:compound`.
-- **.claude/agents/** — specialized reviewers (`code-reviewer`, `security-reviewer`, `scheme-author`) that load the rules relevant to their domain. Payment-path / signing changes route through `security-reviewer`.
-- **.claude/commands/x402/** — slash-command wizards that scaffold code + scenarios conforming to these rules.
+- **[typescript/CLAUDE.md](../../typescript/CLAUDE.md)** — the SDK's own build/test/layout guide and the fork/overlay + signer-factory + scheme-API rules. Rules here cite it; it is the authoritative source for structure.
+- **.claude/agents/** — specialized reviewers (`code-reviewer`, `security-reviewer`) that load the rules relevant to their domain. Payment-path / signing changes route through `security-reviewer`.
+- **.claude/commands/x402/** — slash-command wizards that scaffold code conforming to these rules.
 
 ## Don'ts
 
-- **No code examples longer than 10 lines** in a rule. If it needs more, it belongs in `specs/` or an example.
-- **No duplicating specs.** Rules are *behavioral guidance*; specs are *definitions*. Link, don't copy.
+- **No code examples longer than 10 lines** in a rule.
 - **No rule without a scope.** If you can't say which file touches trigger it, it belongs in `CLAUDE.md` instead.
 - **No rules that rot.** Anything citing a specific line number or commit that isn't a historical anchor will drift — prefer filenames and invariants.

.claude/rules/common/conventions.md

@@ -1,17 +1,17 @@
 # x402 Conventions
 
-Repository-wide conventions that apply to every component, every language, every scheme. Break these silently and you will produce bugs that take days to diagnose.
+Repository-wide conventions that apply to every component, every scheme. Break these silently and you will produce bugs that take days to diagnose.
 
 ## Addressing
 
 - **Lowercase everything**: addresses, selectors, event topics.
-- **TRON + EIP/TIP-712**: convert TRON Base58 addresses (`T...`) to **0x-prefixed EVM hex** before passing to any EIP-712 / TIP-712 signer. This applies to `verifyingContract`, `token`, `serviceProvider`, `user`, `receiver`, and any other `address`-typed field, **both in the domain and in the message**. See [docs/solutions.md entry #1](../../../docs/solutions.md).
-- **Network identifiers**: CAIP-2 `eip155:<chainId>` for EVM, `tron:<name>` for TRON. Detection rule: `tron:` prefix → TRON, `eip155:` prefix → EVM. See [specs/config.md](../../../specs/config.md).
+- **TRON + EIP/TIP-712**: convert TRON Base58 addresses (`T...`) to **0x-prefixed EVM hex** before passing to any EIP-712 / TIP-712 signer. This applies to `verifyingContract`, `token`, `serviceProvider`, `user`, `receiver`, and any other `address`-typed field, **both in the domain and in the message**. Use `tronAddressToEvm` / `normalizeAddressForSigning` from `mechanisms/tron/src/utils.ts` — do not reimplement. See [docs/solutions.md entry #1](../../../docs/solutions.md).
+- **Network identifiers**: CAIP-2 `eip155:<chainId>` for EVM, `tron:<name>` for TRON. Detection rule: `tron:` prefix → TRON, `eip155:` prefix → EVM.
 
 ## Amounts & fees
 
 - **Fees in millionths** (e.g. `3000` = 0.3%).
-- **Token amounts in smallest unit** (wei / sun). Never use floating point. Use `BigInt` in TS, `int` in Python.
+- **Token amounts in smallest unit** (wei / sun). Never use floating point. Use `BigInt` in TS; serialize with `.toString()`, never through `Number`.
 
 ## Payment identifiers
 
@@ -20,7 +20,7 @@ Repository-wide conventions that apply to every component, every language, every
 ## HTTP wire format
 
 - **Header encoding**: `Base64(UTF-8(JSON.stringify(object)))`.
-- **Headers** (see [specs/protocol.md](../../../specs/protocol.md)):
+- **Headers**:
   - `PAYMENT-REQUIRED` — server → client (402 response)
   - `PAYMENT-SIGNATURE` — client → server (retry request)
   - `PAYMENT-RESPONSE` — server → client (success response, with settlement info)
@@ -37,11 +37,11 @@ Repository-wide conventions that apply to every component, every language, every
 ## Mechanism registration
 
 - **Exact match** (e.g. `"tron:nile"`) outranks **wildcard** (e.g. `"tron:*"`). Register more specific first, or accept that exact-match mechanisms win the lookup regardless of insertion order.
-- Each mechanism is associated with a scheme (`exact`, `exact_permit`, `exact_gasfree`, ...). Do not conflate schemes across mechanisms; register each scheme-network pair explicitly.
+- Each scheme class is registered per `(network, scheme)` with `new + register` (no thin wrapper). Do not conflate schemes across mechanisms; register each scheme-network pair explicitly. See [typescript/CLAUDE.md](../../../typescript/CLAUDE.md) "Scheme API surface".
 
 ## Policy pipeline
 
-Client payment selection is a five-step pipeline (see [specs/roles.md](../../../specs/roles.md)):
+Client payment selection is a five-step pipeline:
 
 ```
 [1] Filter by scheme  →  [2] Filter by network  →  [3] Filter by max amount
@@ -56,4 +56,4 @@ Format: `<type>(<scope>): <description>`.
 
 Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`.
 
-Scopes (choose the narrowest one that fits): `python`, `typescript`, `tron`, `evm`, `gasfree`, `facilitator`, `client`, `server`, `specs`, `docs`, `ci`, `design`.
+Scopes (choose the narrowest one that fits): `typescript`, `tron`, `evm`, `gasfree`, `facilitator`, `client`, `server`, `core`, `http`, `mcp`, `docs`, `ci`, `design`.