@routedock/routedock 0.1.1 → 0.1.2

package/README.md

@@ -1,35 +1,33 @@
-# @routedock/sdk
+# @routedock/routedock
 
 Unified payment execution layer for autonomous agents on Stellar. One SDK for x402, MPP charge, and MPP session — mode selected automatically from the provider's `routedock.json` manifest.
 
 ## Install
 
 ```bash
-npm install @routedock/sdk
-# or
-pnpm add @routedock/sdk
+npm install @routedock/routedock
 ```
 
 ## Agent Usage
 
 ```ts
-import { RouteDockClient } from '@routedock/sdk/client'
+import { RouteDockClient } from '@routedock/routedock/client'
 import { Keypair } from '@stellar/stellar-sdk'
 
 const client = new RouteDockClient({
   wallet: Keypair.fromSecret(process.env.AGENT_SECRET),
   network: 'testnet',
-  spendCap: { daily: '1.00', asset: 'USDC' }, // optional local guard
+  spendCap: { daily: '1.00', asset: 'USDC' },
 })
 
 // Single call — SDK reads manifest, picks mode automatically
-const result = await client.pay('https://provider.railway.app/price')
+const result = await client.pay('https://provider.example.com/price')
 // result.data   — response body
 // result.txHash — settlement hash (or null for session vouchers)
 // result.mode   — 'x402' | 'mpp-charge' | 'mpp-session'
 
 // Sustained streaming access
-const session = await client.openSession('https://provider.railway.app/stream/orderbook')
+const session = await client.openSession('https://provider.example.com/stream/orderbook')
 for await (const update of session.stream()) {
   console.log(update)
   if (done) break
@@ -41,47 +39,88 @@ await session.close() // triggers on-chain settlement
 
 ```ts
 import express from 'express'
-import { routedock, SupabaseSessionStore } from '@routedock/sdk/provider'
-import { createClient } from '@supabase/supabase-js'
+import { routedock } from '@routedock/routedock/provider'
 
 const app = express()
 
-// Price endpoint — x402 + MPP charge
 app.use('/price', routedock({
   modes: ['x402', 'mpp-charge'],
   pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
   asset: 'USDC',
+  assetContract: process.env.USDC_ASSET_CONTRACT,
   payee: process.env.STELLAR_PAYEE_ADDRESS,
-  network: process.env.STELLAR_NETWORK as 'testnet' | 'mainnet',
-  facilitatorApiKey: process.env.OPENZEPPELIN_API_KEY,
+  network: 'testnet',
+  payeeSecretKey: process.env.STELLAR_PAYEE_SECRET,
+  manifest,
+  onSettled: async (txHash, amount, mode) => {
+    console.log(`settled: ${mode} ${amount} USDC — ${txHash}`)
+  },
 }))
+```
+
+## Session Lifecycle Hooks
+
+For `mpp-session` mode, the middleware exposes three hooks that fire at each stage of the payment channel lifecycle:
 
-// Stream endpoint — MPP session only
-const store = new SupabaseSessionStore(createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_KEY))
-app.use('/stream/orderbook', routedock({
+```ts
+app.use('/stream', routedock({
   modes: ['mpp-session'],
-  pricing: { 'mpp-session': { rate: '0.0001', channelContract: process.env.CHANNEL_CONTRACT_ID } },
+  pricing: { 'mpp-session': { rate: '0.0001', channelContract: CHANNEL_CONTRACT } },
   asset: 'USDC',
-  payee: process.env.STELLAR_PAYEE_ADDRESS,
-  network: process.env.STELLAR_NETWORK as 'testnet' | 'mainnet',
-  store,
+  assetContract: USDC_ASSET_CONTRACT,
+  payee: PAYEE_ADDRESS,
+  network: 'testnet',
+  payeeSecretKey: PAYEE_SECRET,
+  manifest,
+  commitmentPublicKey: COMMITMENT_PUBLIC_KEY,
+
+  // Fires once when the first voucher is verified for a new session
+  onSessionOpen: async (channelId) => {
+    await db.from('sessions').insert({
+      channel_id: channelId,
+      status: 'open',
+      voucher_count: 0,
+    })
+  },
+
+  // Fires after each verified ed25519 commitment (off-chain, no tx fee)
+  onVoucher: async (voucherIndex, cumulativeAmount) => {
+    await db.from('sessions').update({
+      voucher_count: voucherIndex,
+      cumulative_amount: parseFloat(cumulativeAmount),
+    }).eq('channel_id', channelId)
+  },
+
+  // Fires after the on-chain channel close settles the cumulative amount
+  onSettled: async (txHash, totalPaid, mode) => {
+    await db.from('sessions').update({
+      status: 'closed',
+      settlement_tx_hash: txHash,
+    }).eq('channel_id', channelId)
+  },
 }))
 ```
 
+| Hook | When it fires | On-chain? |
+|---|---|---|
+| `onSessionOpen(channelId)` | First verified voucher in a new session | No |
+| `onVoucher(index, cumulativeAmount)` | Each verified ed25519 commitment | No |
+| `onSettled(txHash, amount, mode)` | Channel close transaction confirmed | Yes |
+
 ## Mode Selection Logic
 
 The `ModeRouter` uses this decision tree (deterministic, no randomness):
 
 1. If `{ sustained: true }` passed AND manifest supports `mpp-session` → session
 2. Else if manifest supports `mpp-charge` AND network is Stellar → MPP charge (lower fees)
-3. Else if manifest supports `x402` → x402 with OZ facilitator
+3. Else if manifest supports `x402` → x402 with facilitator
 4. Else throw `RouteDockNoSupportedModeError`
 
 Override with `{ forceMode: 'x402' }` to bypass auto-selection.
 
 ## Security
 
-The `one-way-channel` Soroban contract wrapped by `MppSessionClient` is **unaudited** (`stellar-experimental/one-way-channel`). Safe defaults are enforced: 17280 ledger refund window, durable `SupabaseSessionStore` with monotonic invariant. Production use should await a formal audit.
+The `one-way-channel` Soroban contract wrapped by `MppSessionClient` is **unaudited** (`stellar-experimental/one-way-channel`). Safe defaults are enforced: 17280 ledger refund window, monotonic cumulative enforcement at application, database, and contract layers. Production mainnet use should await a formal audit.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routedock/routedock",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Unified payment execution layer for autonomous agents on Stellar",
   "license": "MIT",
   "repository": {