docs: soften ERC-4337 on-chain-caps claims to beta/designed (live proof pending) — no settled on-chain guarantee until the Base Sepolia loop is published (#81)

Co-authored-by: Klow <deploy@klow.ai>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.plans/v1.21-live-loop-runbook.md

@@ -0,0 +1,36 @@
+# v1.21 Live Verification Loop — turnkey runbook
+
+Goal: prove the headline claim on a real chain so we can ship the v1.21 release + the viral post WITHOUT misleading language. The claim: **set local policy to `unrestricted`, and the chain still refuses an over-cap transfer.**
+
+## Network: Base Sepolia (NOT Ethereum Sepolia)
+
+Fund the account on **Base Sepolia** (chainId 84532), not Ethereum Sepolia. The Smart Sessions module contracts are deployed on Base Sepolia (already verified live via eth_getCode). Wrong network = nothing resolves.
+
+- **Token to fund:** Base Sepolia ETH (it's still "ETH", just on the Base testnet).
+- **How much:** ~0.02–0.05 Base Sepolia ETH is plenty. Account deployment + a session grant + a couple of agent userOps cost a few cents of testnet gas. Round up so faucet rate-limits don't stall you.
+- **Faucets:** Coinbase Base Sepolia faucet (faucet.quicknode.com/base/sepolia or the Coinbase Developer Platform faucet); Alchemy Base Sepolia faucet. Most drip 0.05–0.1/day.
+- **Bundler:** a free Pimlico key → `https://api.pimlico.io/v2/base-sepolia/rpc?apikey=<KEY>` (Pimlico supports v0.7 on Base Sepolia). Alchemy's bundler works too.
+
+## What "the Sepolia account" is
+
+An ERC-7579 **smart account** (Biconomy Nexus 1.x) that YOU own — the grantor. The agent's wallet (the plugin's local keystore EOA) becomes its scoped session key. You need a throwaway EOA to own/deploy the Nexus account; never give me a private key.
+
+## Your part (one-time, ~10 min)
+
+1. Register Base Sepolia as a custom chain (dashboard "Custom chains" tab, or the env): chainId 84532, RPC `https://sepolia.base.org`, explorer `https://sepolia.basescan.org`, native ETH.
+2. Create + fund a Nexus 1.x account on Base Sepolia (Biconomy SDK quickstart, or the Rhinestone/Biconomy demo app). Fund it with the ~0.03 ETH above. Deploy a test ERC-20 (or use an existing Base Sepolia test token) and send the account, say, 100 of it.
+3. Tell me: the **smart-account address**, the **test-token address**, and the **Pimlico bundler URL**. (No keys.)
+4. When I hand you the grant payload + userOpHash, sign it with your throwaway OWNER key (in your own wallet) and give me back the signature — I submit it via `chaingpt_aa_submit_userop`.
+
+## My part (then, ~5 min, no keys of yours)
+
+1. `chaingpt_agent_wallet_init` (if not already) → the session key.
+2. `chaingpt_aa_session_build_grant` chain=base-sepolia account=<yours> tokenCaps=[{token, cap:"100"}] validUntil=<+24h> → you sign → `chaingpt_aa_submit_userop`.
+3. `chaingpt_aa_session_status` → permission ENABLED, cap 100.
+4. `chaingpt_agent_wallet_4337_sign_and_send` transfer 40 → succeeds. Again 40 → succeeds. Third 40 → **chain refuses** (cumulative 120 > 100). The agent signs with ITS OWN keystore key, never yours.
+5. **The headline:** set local `policy.json` to `unrestricted: true` (+ `erc4337.enabled: true`), retry the over-cap transfer → bundler/EntryPoint STILL refuses at validation. Screenshot that.
+6. Freeze the live permissionId as the golden vector in `smart_sessions.test.ts`.
+
+## Then (me, automatic)
+
+Tag + release v1.21.0 with the now-true on-chain claim; the screenshot anchors the launch thread. No claim ships before step 5 passes.

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Changelog
 
 ## [1.21.0] - 2026-06-11
-### Added — ERC-4337 session keys: caps enforced BY THE CHAIN
-The trust-story endgame. The user's ERC-7579 smart account grants the agent's existing EOA a scoped on-chain session via the audited Smart Sessions module (ChainLight/Ackee/Cantina-reviewed, vendor-neutral across Nexus/Kernel/Safe7579): cumulative per-token spend caps, mandatory expiry, optional usage caps — validated by the EntryPoint on every operation. Even a fully compromised host (policy file rewritten, `unrestricted: true`) cannot exceed what the chain granted. Zero new dependencies: deterministic module addresses + viem encoders only.
+### Added — ERC-4337 session keys: caps designed to be enforced on-chain (beta)
+The trust-story endgame. The user's ERC-7579 smart account grants the agent's existing EOA a scoped on-chain session via the audited Smart Sessions module (ChainLight/Ackee/Cantina-reviewed, vendor-neutral across Nexus/Kernel/Safe7579): cumulative per-token spend caps, mandatory expiry, optional usage caps — validated by the EntryPoint on every operation. The intent: even a fully compromised host (policy file rewritten, `unrestricted: true`) should not be able to exceed what the chain granted. **This on-chain layer is BETA: the module addresses are verified deployed on Base Sepolia, and the full grant → over-cap-refusal loop will be published before we claim it unconditionally. Until then, rely on the local policy gate (tested) as your primary fence.** Zero new dependencies: deterministic module addresses + viem encoders only.
 
 - **5 new MCP tools (135 → 140):**
   - `chaingpt_aa_session_build_grant` / `_build_revoke` — UNSIGNED grant/revoke payloads; the account OWNER signs externally (never the agent key); unbounded grants are refused by construction. Revoke = chain-level kill.
@@ -12,8 +12,9 @@ The trust-story endgame. The user's ERC-7579 smart account grants the agent's ex
 - **`erc4337` policy sub-policy** — fail-closed, type-strict, OFF even in the balanced default (this surface acts on a third-party account): smart-account allowlist + https-only bundler-host allowlist.
 - v1 account support: Biconomy Nexus 1.x (Kernel v3 / Safe7579 follow — the module layer is already shared). PreToolUse guard asks on both new signing/submitting tools.
 
-### Pending before tagging
-- The live Base Sepolia loop (TESTING.md recipe): grant → agent spends inside cap → chain refuses the over-cap op even with local policy set to unrestricted. The on-chain-refusal proof is the release claim; the tag waits for it.
+### Verification status (be precise on what's proven)
+- **Proven + tested:** the local policy gate — per-tx caps, rolling-24h velocity caps, allowlists, kill switch, custody-free unsigned-tx flow — across 428 vitest cases incl. adversarial refusals.
+- **Beta / pending live proof:** the ON-CHAIN session-cap layer. Smart Sessions module addresses verified deployed on Base Sepolia via eth_getCode; the encoders/readers are unit-tested; the end-to-end grant → over-cap-refusal loop (TESTING.md recipe) is not yet published. We will not market "the chain refuses it even on a hacked host" as a settled fact until that loop is recorded.
 
 ### Tests
 - Suite 399 → 428 (+19 lib/gate from PR A, +10 tool surface/custody-invariant/offline-refusal incl. zero-network assertions on every pre-RPC gate).

README.md

@@ -803,6 +803,7 @@ There are several Web3 + AI agent toolkits in flight. They aim at the same outco
 | **Prediction markets** | Polymarket native | No | No | No | No |
 | **Perps** | Hyperliquid (signed) + Drift (read) | Add‑on | No | No | No |
 | **Spending limits under autonomy** | Per‑tx cap + rolling‑24h spend/tx‑count caps enforced in code the LLM can't modify | No | Smart‑wallet policies (CDP) | Per‑tx MetaMask approval | N/A |
+| **On‑chain caps (ERC‑4337 session keys)** | Yes — designed so the chain enforces per‑token caps at validation _(beta: addresses verified on Base Sepolia; full live proof pending)_ | No | No | No | No |
 | **Scheduled execution safety** | Crash‑safe execution journal (re‑runs can't double‑buy) | No | No | No | No |
 | **Shipped agents** | 3 (researcher / auditor / trader) with tuned guardrails | No | No | No | No |
 | **Test harness** | 6 layers + daily live smoke + self‑healing CI (drift auto‑PRs) | Per‑plugin | Examples only | Snap testing | None |

skills/agent-wallet/SKILL.md

@@ -148,13 +148,13 @@ Hard facts to relay accurately:
 
 ## On-chain caps — ERC-4337 session keys (v1.21+)
 
-The endgame: the user's ERC-7579 smart account grants the agent's EOA a SCOPED on-chain session (Smart Sessions module). The caps live in audited contracts and are enforced by the EntryPoint — they survive what nothing local can:
+The endgame: the user's ERC-7579 smart account grants the agent's EOA a SCOPED on-chain session (Smart Sessions module). The caps live in audited contracts and are validated by the EntryPoint. **Status: BETA — the module addresses are verified deployed on Base Sepolia and the encoders are unit-tested, but the end-to-end live proof is not yet published. Treat the on-chain column below as the DESIGNED guarantee, not yet an independently-demonstrated one; the local gate is your tested fence today.**
 
-| Threat | Local policy gate | On-chain session caps |
+| Threat | Local policy gate (tested) | On-chain session caps (designed, beta) |
 |---|---|---|
-| Prompt injection | ✅ blocks | ✅ blocks |
-| Policy file tampered/rewritten | ❌ falls | ✅ blocks |
-| Full host compromise (keystore stolen) | ❌ falls | ✅ blocks (bounded by remaining allowance + expiry) |
+| Prompt injection | ✅ blocks | ✅ designed to block |
+| Policy file tampered/rewritten | ❌ falls | ✅ designed to block |
+| Full host compromise (keystore stolen) | ❌ falls | ✅ designed to block, bounded by remaining allowance + expiry (live proof pending) |
 
 ```text
 chaingpt_aa_session_build_grant chain=base account=<user SCW> tokenCaps=[{token: USDC, cap: "100000000"}] validUntil=<unix>