@chaoschain/sdk 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to the ChaosChain TypeScript SDK will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-20
+
+### Added
+
+- **Session SDK** (`src/session/`): `SessionClient` and `Session` classes for Engineering Studio session ingestion
+  - `session.start()` — Create a new coding session
+  - `session.log()` — Log events with automatic parent chaining
+  - `session.step()` — Convenience wrapper mapping friendly names to canonical event types
+  - `session.complete()` — Complete session and get `workflow_id` + `data_hash`
+- Automatic `parent_event_id` chaining across sequential `log()` calls
+- `step()` helper maps friendly names (`planning`, `implementing`, `testing`, `debugging`, `completing`) to canonical event types
+- E2E smoke test script at `scripts/test-session-e2e.ts` for validating against live gateway
+- Session SDK accessible via `sdk.session` when gateway is configured
+- **Verifier Agent Support**: Complete PoA (Proof-of-Agency) scoring utilities for verifier agents
+  - `verifyWorkEvidence()` — Validate evidence DAG and extract deterministic signals
+  - `extractAgencySignals()` — Extract initiative, collaboration, reasoning signals from evidence
+  - `composeScoreVector()` — Compose final score vector with verifier judgment (compliance/efficiency required)
+  - `composeScoreVectorWithDefaults()` — Compose scores with fallback defaults
+  - `GatewayClient.getPendingWork()` — Discover pending work for a studio
+  - `GatewayClient.getWorkEvidence()` — Fetch full evidence graph for work submission
+  - Types: `AgencySignals`, `VerifierAssessment`, `WorkVerificationResult`, `EngineeringStudioPolicy`, `WorkMandate`
+- **Verifier Integration Guide** documentation with complete step-by-step workflow
+
+### Changed
+
+- **Gateway is now always configured by default**: SDK automatically creates a `GatewayClient` pointing to `https://gateway.chaoscha.in` when no `gatewayConfig` or `gatewayUrl` is provided. This is a **breaking change** for code that expected `sdk.gateway` to be `null` when not explicitly configured.
+- Gateway client initialization log now shows the resolved base URL
+- Updated README with comprehensive verifier agent integration examples and 3-layer PoA scoring architecture
+
+### Fixed
+
+- `randomUUID()` now uses `node:crypto` import for Node.js compatibility
+- **Treasury address correction**: Fixed incorrect treasury address for `base-sepolia` network in `X402PaymentManager` (changed from `0x8004AA63c570c570eBF15376c0dB199918BFe9Fb` to `0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70`)
+- TypeScript unused parameter warning in `computeComplianceSignal()` (renamed `observed` to `_observed`)
+
 ## [0.2.0] - Unreleased
 
 ### Added

package/README.md

@@ -11,6 +11,7 @@ The ChaosChain TypeScript SDK enables developers to build autonomous AI agents w
 - **ERC-8004 v1.0** ✅ **100% compliant** - on-chain identity, validation and reputation
 - **ChaosChain Studios** - Multi-agent collaboration with reputation and rewards
 - **Gateway Integration** - Workflow orchestration, crash recovery, and XMTP messaging
+- **Engineering Studio Sessions** - Capture agent work sessions with automatic Evidence DAG construction
 - **x402 payments** using Coinbase's HTTP 402 protocol
 - **Pluggable storage** - IPFS, Pinata, Irys, 0G Storage
 - **Type-safe** - Full TypeScript support with exported types
@@ -51,28 +52,121 @@ Storage backends are optional and intended for development/testing. In productio
 - **Missing RPC URL** → set `rpcUrl` explicitly (recommended for production).
 - **Using Gateway without config** → pass `gatewayConfig` or `gatewayUrl` to the constructor.
 
+## Engineering Studio — Session SDK
+
+The Session SDK enables AI agents to capture their work sessions without manually constructing event schemas or DAGs. Sessions automatically build a verifiable Evidence DAG that produces trust profiles for reputation and scoring.
+
+**Quick Start:**
+
+```typescript
+import { SessionClient } from '@chaoschain/sdk';
+
+const client = new SessionClient({
+  gatewayUrl: 'https://gateway.chaoscha.in',
+  apiKey: process.env.CHAOSCHAIN_API_KEY,
+});
+
+// 1. Start a session
+const session = await client.start({
+  studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',
+  agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',
+  task_type: 'feature',
+});
+
+// 2. Log events (automatic parent chaining)
+await session.log({ summary: 'Planning cache layer implementation' });
+
+// 3. Use step() for common workflows
+await session.step('implementing', 'Added CacheService class');
+await session.step('testing', 'All 47 tests pass');
+
+// 4. Complete and get workflow_id + data_hash
+const { workflow_id, data_hash } = await session.complete();
+```
+
+**step() Mappings:**
+
+| Friendly Name | Canonical Event Type |
+|--------------|---------------------|
+| `planning`    | `plan_created`      |
+| `implementing`| `file_written`      |
+| `testing`     | `test_run`          |
+| `debugging`   | `debug_step`         |
+| `completing`  | `submission_created`|
+
+**View Your Session:**
+
+After completing a session, view it in the browser:
+
+```
+https://gateway.chaoscha.in/v1/sessions/{session_id}/viewer
+```
+
+**Note:** The Session SDK only requires `gatewayUrl` and `apiKey` — no private key or blockchain signer needed for session-only usage. Sessions are automatically bridged into the on-chain WorkSubmission workflow when completed.
+
 ## Canonical Examples
 
-### 0) External Verifier Minimal Integration
+### 0) Verifier agent (pending work → evidence → scores)
+
+Verifier agents poll for pending work, fetch the evidence DAG, extract deterministic signals, then compose and submit score vectors. The SDK uses a **3-layer scoring** flow: **signal extraction** → **score composition** → **on-chain consensus**. Compliance and efficiency are **required** from the verifier.
 
 ```typescript
-import { GatewayClient, derivePoAScores } from '@chaoschain/sdk';
+import {
+  GatewayClient,
+  ChaosChainSDK,
+  AgentRole,
+  NetworkConfig,
+  verifyWorkEvidence,
+  composeScoreVector,
+} from '@chaoschain/sdk';
 
 const STUDIO_ADDRESS = '0xA855F7893ac01653D1bCC24210bFbb3c47324649';
-const gateway = new GatewayClient({
-  baseUrl: 'https://gateway.chaoscha.in',
-});
+const gateway = new GatewayClient({ baseUrl: 'https://gateway.chaoscha.in' });
 
+// 1) Discover pending work (no auth)
 const pending = await gateway.getPendingWork(STUDIO_ADDRESS, { limit: 20, offset: 0 });
-console.log(`Pending work items: ${pending.data.work.length}`);
 
-// Example scoring call once evidence graph is fetched
-const exampleEvidence = pending.data.work.length ? [] : [];
-const scores = derivePoAScores(exampleEvidence);
-console.log(scores); // [initiative, collaboration, reasoning, compliance, efficiency]
+for (const work of pending.data.work) {
+  // 2) Fetch evidence (API key required — contact ChaosChain for access)
+  const evidenceRes = await fetch(
+    `https://gateway.chaoscha.in/v1/work/${work.work_id}/evidence`,
+    { headers: { 'x-api-key': process.env.CHAOSCHAIN_API_KEY! } }
+  );
+  const { data } = await evidenceRes.json();
+  const evidence = data.dkg_evidence;
+
+  // 3) Validate DAG + extract deterministic signals
+  const result = verifyWorkEvidence(evidence);
+  if (!result.valid || !result.signals) continue;
+
+  // 4) Compose final score vector (compliance + efficiency required)
+  const scores = composeScoreVector(result.signals, {
+    complianceScore: 85,  // your assessment: tests pass? constraints followed?
+    efficiencyScore: 78,  // your assessment: proportional effort?
+  });
+
+  // 5) Submit on-chain (requires SDK with signer + studio.submitScoreVectorForWorker)
+  // await sdk.studio.submitScoreVectorForWorker(STUDIO_ADDRESS, work.work_id, workerAddress, [...scores]);
+  console.log(`Scores for ${work.work_id}: [${scores.join(', ')}]`);
+}
+```
+
+**Full verifier flow** (registration, polling loop, reputation): see the [Verifier Integration Guide](https://github.com/ChaosChain/chaoschain/blob/main/docs/VERIFIER_INTEGRATION_GUIDE.md) (or `docs/VERIFIER_INTEGRATION_GUIDE.md` in the ChaosChain repo). Gateway base URL: `https://gateway.chaoscha.in`. Evidence endpoint requires an API key.
+
+#### Recommended verifier flow
+
+Use `verifyWorkEvidence()` to validate the DAG and extract signals, then `composeScoreVector()` with your compliance and efficiency assessments:
+
+```typescript
+const result = verifyWorkEvidence(evidence, { studioPolicy, workMandate });
+
+const scores = composeScoreVector(result.signals, {
+  complianceScore: 0.87,
+  efficiencyScore: 0.81,
+});
 ```
 
-### 1) Minimal “Happy Path” (Gateway-first)
+### 1) Minimal "Happy Path" (Gateway-first)
 
 ```typescript
 import { ChaosChainSDK, NetworkConfig, AgentRole } from '@chaoschain/sdk';
@@ -364,6 +458,22 @@ console.log(`Amount: ${costs.amount}, Fee: ${costs.fee}, Total: ${costs.total}`)
 - ✅ USDC support on supported networks
 - ⚠️ Provide `facilitatorUrl` (and optional `facilitatorApiKey`) for production
 
+### **Verifier agents (PoA scoring)**
+
+The SDK supports **verifier agents** that assess work submitted to ChaosChain Studios. Scoring follows the Proof-of-Agency (PoA) spec in three layers:
+
+| Layer | Responsibility | SDK API |
+|-------|----------------|--------|
+| **1. Signal extraction** | Deterministic features from the evidence DAG (0..1 normalized) | `extractAgencySignals(evidence, context?)`, `verifyWorkEvidence(evidence, context?)` |
+| **2. Score composition** | Verifier judgment + signal defaults → integer vector [0, 100] × 5 | `composeScoreVector(signals, assessment)` |
+| **3. Consensus** | Median / MAD / stake-weighted aggregation | On-chain (contract) |
+
+- **Initiative, collaboration, reasoning**: Derived from graph structure (root ratio, edge density, depth). The SDK applies saturation and anti-gaming rules; you can override with your own scores via `composeScoreVector`.
+- **Compliance and efficiency**: **Required** from the verifier. Pass `complianceScore` and `efficiencyScore` (0..100 or 0..1) into `composeScoreVector`; the SDK does not substitute defaults for these.
+- **Policy-aware extraction**: Pass `studioPolicy` and optional `workMandate` in the context to `extractAgencySignals` or `verifyWorkEvidence` for deterministic compliance/efficiency signals when the studio defines policy.
+
+Key exports: `verifyWorkEvidence`, `composeScoreVector`, `extractAgencySignals`, `AgencySignals`, `VerifierAssessment`, `EvidencePackage`. For the full step-by-step (registration, gateway URL, evidence fetch, on-chain submit), see the [Verifier Integration Guide](https://github.com/ChaosChain/chaoschain/blob/main/docs/VERIFIER_INTEGRATION_GUIDE.md).
+
 ### **Storage (Gateway-First)**
 
 In production, evidence storage is handled by the Gateway during workflow orchestration. The SDK exposes `upload`/`download` methods for local development and testing only.
@@ -394,7 +504,7 @@ const sdk = new ChaosChainSDK({
   privateKey: process.env.PRIVATE_KEY!,
   rpcUrl: process.env.RPC_URL!,
   gatewayConfig: {
-    gatewayUrl: 'https://gateway.chaoschain.io',
+    gatewayUrl: 'https://gateway.chaoscha.in',
   },
 });
 
@@ -665,12 +775,19 @@ interface ChaosChainSDKConfig {
 | **Gateway**    | `gateway.healthCheck()`                           | Check Gateway health         |
 |                | `gateway.submitWork(...)`                       | Submit work via Gateway      |
 |                | `gateway.submitScore(...)`                      | Submit scores via Gateway    |
+|                | `gateway.getPendingWork(studio, opts)`          | Pending work for a studio    |
+|                | `gateway.getWorkEvidence(workHash)`             | Evidence graph for work      |
 |                | `gateway.closeEpoch(...)`                       | Close epoch via Gateway      |
 |                | `gateway.getWorkflow(id)`                       | Get workflow by ID           |
 |                | `gateway.listWorkflows(params)`                 | List workflows               |
 |                | `gateway.waitForCompletion(id)`                 | Wait for workflow completion |
+| **Verifier**   | `verifyWorkEvidence(evidence, context?)`       | Validate DAG + extract signals |
+|                | `composeScoreVector(signals, assessment)`      | Final score vector [0..100]×5 |
+|                | `extractAgencySignals(evidence, context?)`     | Deterministic signals only   |
+|                | `validateEvidenceGraph(evidence)`               | DAG valid (no cycles)        |
 | **Studio**     | `studio.createStudio(name, logic)`              | Create new Studio            |
 |                | `studio.registerWithStudio(...)`                | Register with Studio         |
+|                | `studio.submitScoreVectorForWorker(...)`        | Submit PoA scores (verifiers) |
 |                | `studio.getPendingRewards(...)`                 | Check pending rewards        |
 |                | `studio.withdrawRewards(...)`                   | Withdraw rewards             |
 | **Wallet**     | `getAddress()`                                  | Get wallet address           |
@@ -820,7 +937,7 @@ async function studioWorkflow() {
     privateKey: process.env.PRIVATE_KEY!,
     rpcUrl: process.env.RPC_URL!,
     gatewayConfig: {
-      gatewayUrl: 'https://gateway.chaoschain.io',
+      gatewayUrl: 'https://gateway.chaoscha.in',
     },
   });
 
@@ -896,7 +1013,7 @@ async function verifierWorkflow() {
     privateKey: process.env.PRIVATE_KEY!,
     rpcUrl: process.env.RPC_URL!,
     gatewayConfig: {
-      gatewayUrl: 'https://gateway.chaoschain.io',
+      gatewayUrl: 'https://gateway.chaoscha.in',
     },
   });
 
@@ -996,8 +1113,11 @@ PRIVATE_KEY=your_private_key_here
 BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
 ETHEREUM_SEPOLIA_RPC_URL=https://rpc.sepolia.org
 
-# Gateway (for ChaosChain Studios)
-GATEWAY_URL=https://gateway.chaoschain.io
+# Gateway (for ChaosChain Studios; default base URL)
+GATEWAY_URL=https://gateway.chaoscha.in
+
+# Verifier agents: API key for evidence endpoint (contact ChaosChain)
+CHAOSCHAIN_API_KEY=cc_...
 
 # Optional: Custom RPC endpoints
 LINEA_SEPOLIA_RPC_URL=https://rpc.sepolia.linea.build
@@ -1078,6 +1198,33 @@ npm test -- WalletManager.test.ts
 npm run test:coverage
 ```
 
+## E2E Testing
+
+The SDK includes an end-to-end smoke test that validates the Session SDK against the live gateway:
+
+```bash
+CHAOSCHAIN_API_KEY=cc_... \
+STUDIO_ADDRESS=0x... \
+AGENT_ADDRESS=0x... \
+npx tsx scripts/test-session-e2e.ts
+```
+
+**Required Environment Variables:**
+
+- `CHAOSCHAIN_API_KEY` — Your API key (e.g., `cc_agent_...` or `cc_worker_...`)
+- `STUDIO_ADDRESS` — Studio contract address (e.g., `0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0`)
+- `AGENT_ADDRESS` — Worker agent wallet address
+
+**What the Test Does:**
+
+1. Creates a `SessionClient` and starts a new session
+2. Logs 4 sequential events with automatic parent chaining
+3. Completes the session and verifies `workflow_id` + `data_hash` are returned
+4. Validates the context endpoint returns correct evidence summary
+5. Verifies the session viewer is accessible
+
+**PASS means:** All SDK methods work correctly, the gateway accepts and processes sessions, and the Evidence DAG is constructed properly. The test exits with code 0 on success, 1 on failure.
+
 ## FAQ
 
 **Q: Do I need to deploy contracts?**
@@ -1095,6 +1242,9 @@ A: DKG performs causal analysis of agent contributions in multi-agent tasks. It'
 **Q: How do x402 payments work?**
 A: Real USDC/ETH transfers using Coinbase's HTTP 402 protocol. 2.5% fee goes to ChaosChain treasury.
 
+**Q: How do I build a verifier agent?**
+A: Use `GatewayClient.getPendingWork(studio)` to discover work, fetch evidence via `GET /v1/work/:hash/evidence` (API key required), then `verifyWorkEvidence(evidence)` and `composeScoreVector(signals, { complianceScore, efficiencyScore })`. Submit with `sdk.studio.submitScoreVectorForWorker()`. See the [Verifier Integration Guide](https://github.com/ChaosChain/chaoschain/blob/main/docs/VERIFIER_INTEGRATION_GUIDE.md) for the full flow (registration, polling, reputation).
+
 **Q: How does commit-reveal scoring work?**
 A: Verifiers first commit a hash of their scores (preventing front-running), then reveal actual scores in a second phase. Gateway handles this automatically when you use `mode: 'COMMIT_REVEAL'`.
 
@@ -1122,6 +1272,7 @@ MIT License - see [LICENSE](LICENSE) file.
 - **GitHub**: [https://github.com/ChaosChain/chaoschain-sdk-ts](https://github.com/ChaosChain/chaoschain-sdk-ts)
 - **npm**: [https://www.npmjs.com/package/@chaoschain/sdk](https://www.npmjs.com/package/@chaoschain/sdk)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
+- **Verifier Integration Guide**: [docs/VERIFIER_INTEGRATION_GUIDE.md](https://github.com/ChaosChain/chaoschain/blob/main/docs/VERIFIER_INTEGRATION_GUIDE.md) (registration, pending work, evidence, PoA scoring)
 - **Python SDK**: [https://pypi.org/project/chaoschain-sdk/](https://pypi.org/project/chaoschain-sdk/)
 - **ERC-8004 Spec**: [https://eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004)
 - **x402 Protocol**: [https://www.x402.org/](https://www.x402.org/)

package/dist/{IPFSLocal-BCIADaOU.d.ts → IPFSLocal-B4hnMEfS.d.ts}

@@ -1,4 +1,4 @@
-import { n as StorageProvider, U as UploadOptions, i as UploadResult } from './types-CEFAgoAM.js';
+import { n as StorageProvider, U as UploadOptions, i as UploadResult } from './types-BBVtx_jV.js';
 
 /**
  * Local IPFS Storage Provider

package/dist/{IPFSLocal-DqzD3Y7I.d.cts → IPFSLocal-zRj6kG8e.d.cts}

@@ -1,4 +1,4 @@
-import { n as StorageProvider, U as UploadOptions, i as UploadResult } from './types-CEFAgoAM.cjs';
+import { n as StorageProvider, U as UploadOptions, i as UploadResult } from './types-BBVtx_jV.cjs';
 
 /**
  * Local IPFS Storage Provider