Skip to content

V1_1_SUMMARY.md

Latest commit

 

History

History
171 lines (119 loc) · 5.7 KB

V1_1_SUMMARY.md

File metadata and controls

171 lines (119 loc) · 5.7 KB

ClawPay MCP v1.1.0 — Build Summary

Built: 2026-02-21
Status: ✅ Complete — 107/107 tests passing, TypeScript clean, build clean
NOT published to npm — awaiting Bill's review

What Was Built

x402 V2 Session Payment Support

x402 V2 (released December 11, 2025) introduced "wallet-based access & reusable sessions": agents pay once to establish a session, then skip on-chain payment for all subsequent calls within that session. v1.1.0 is the first complete, non-custodial MCP implementation of this pattern.

Architecture

New Files

File Purpose
src/session/types.ts TypeScript interfaces: SessionRecord, SessionTokenPayload, CreateSessionOptions, etc.
src/session/manager.ts In-process session store: create, lookup, list, end sessions; token encoding/decoding
src/tools/session.ts Four new MCP tools: x402_session_start, x402_session_fetch, x402_session_status, x402_session_end
tests/session.test.ts 48 new tests covering all session tool behaviour
CHANGELOG.md Full changelog (v1.0.0 + v1.1.0)

Modified Files

File Change
src/index.ts Register 4 new session tools; bump version to 1.1.0
src/tools/x402.ts Add skip_session_check parameter; auto-detect active sessions before paying
package.json Version 1.0.0 → 1.1.0
.env.example Add SESSION_TTL_SECONDS environment variable documentation

New Tools (4)

1. x402_session_start

Pay once to establish an x402 V2 session. The tool:

  • Makes a single x402 payment to the endpoint
  • Creates a cryptographically signed session token (ECDSA via viem signMessage)
  • Stores the session in-process with configurable TTL
  • Returns a session_id UUID for use in subsequent calls

2. x402_session_fetch

Make HTTP requests within an active session — no payment made. The tool:

  • Looks up the session by ID (validates scope, expiry)
  • Injects X-Session-Token, X-Session-Wallet, PAYMENT-SESSION headers
  • Uses plain fetch() (not the x402 client) — the session token bypasses the payment wall
  • Tracks call count per session
  • Handles 402 responses gracefully (server may not support x402 V2 sessions yet)

3. x402_session_status

List all active sessions or inspect a specific session:

  • Active sessions: ID, endpoint, scope, TTL progress bar, call count
  • Specific session: full detail including payment TX hash, token info (protocol version, truncated signature)

4. x402_session_end

Explicitly close a session before it expires naturally.

Updated Behaviour: x402_pay Auto-Session Detection

x402_pay now checks for active sessions before making payments:

  1. If an active session covers the requested URL → inject session headers, skip payment
  2. If the server still returns 402 → fall through to standard x402 payment flow
  3. New skip_session_check: boolean parameter forces fresh payment regardless

This means agents using x402_pay in existing flows automatically benefit from sessions established with x402_session_start — zero workflow change required.

Session Token Design

X-Session-Token:  <base64url(canonical JSON payload)>.<hex ECDSA signature>
X-Session-Wallet: <agent wallet address>
PAYMENT-SESSION:  <session UUID>
```text

**Canonical payload** (keys sorted alphabetically, signed via ECDSA):

```json
{
  "createdAt": 1708538400,
  "endpoint": "https://api.example.com/v1",
  "expiresAt": 1708542000,
  "paymentAmount": "1000000",
  "paymentTxHash": "0x...",
  "scope": "prefix",
  "sessionId": "uuid-v4",
  "version": "clawpay/1.1",
  "walletAddress": "0x..."
}
```text

This format is compatible with x402 V2's SIGN-IN-WITH-X (SIWx) / CAIP-122 identity pattern.
Servers can independently verify ownership of `walletAddress` by calling `ecrecover` on the
signature without any external service.

---

## Non-Custodial Guarantees

All non-custodial principles from v1.0.0 are preserved and extended:

- Session tokens are signed **locally** by the agent's private key via `viem.signMessage`
- No third party holds or validates keys at any point
- Session tokens are self-contained cryptographic claims
- The session manager lives in-process — no external databases, no custody infrastructure
- Even if a session token is intercepted, it only grants access to the specific endpoint for the session TTL

---

## Test Results

```text
Tests:  107 passed (107)
  ✓ tests/deploy.test.ts      (10 tests)   — existing, unchanged
  ✓ tests/payments.test.ts    (32 tests)   — existing, unchanged
  ✓ tests/x402.test.ts        (17 tests)   — existing, unchanged
  ✓ tests/session.test.ts     (48 tests)   — new
```text

TypeScript: 0 errors  
Build: clean

---

## New Environment Variable

```bash
SESSION_TTL_SECONDS=3600  # Default: 3600 (1 hour). Min: 60. Max: 2592000 (30 days).
```text

---

## Competitive Positioning

- **Latinum.ai** is building the same thing but is not yet live
- We have ~30 day window before space gets crowded
- ClawPay v1.1.0 is the **first** non-custodial x402 V2 session implementation in MCP
- Key differentiators: non-custodial token signing, auto-session detection in `x402_pay`,
  scope-based session matching (prefix/exact), in-process storage (no dependencies)

---

## Recommended Next Steps (for Bill's review)

1. Review all new code (5 new files, 3 modified files)
2. Test manually with an x402-enabled endpoint that supports V2 sessions
3. Update npm publish workflow to tag v1.1.0
4. Consider adding session persistence to disk (e.g. encrypted JSON in `.clawpay_sessions`) for cross-restart survival — this would be v1.1.1
5. Update README.md to document the new session tools
6. Discord announcement: `#clawpay` channel