@chaoschain/sdk 0.2.3 → 0.2.4

package/README.md

@@ -53,25 +53,53 @@ Storage backends are optional and intended for development/testing. In productio
 
 ## 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.
+
 ### 1) Minimal “Happy Path” (Gateway-first)
 
 ```typescript
@@ -364,6 +392,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 +438,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 +709,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 +871,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 +947,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 +1047,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
@@ -1095,6 +1149,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 +1179,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-BqyHRp_l.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-DZze-Z8B.js';
 
 /**
  * Local IPFS Storage Provider

package/dist/{IPFSLocal-DqzD3Y7I.d.cts → IPFSLocal-azjjaiGR.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-DZze-Z8B.cjs';
 
 /**
  * Local IPFS Storage Provider

package/dist/index.cjs

@@ -12037,10 +12037,10 @@ var X402PaymentManager = class {
    */
   getTreasuryAddress(network) {
     const treasuries = {
-      "base-sepolia": "0x8004AA63c570c570eBF15376c0dB199918BFe9Fb",
-      "ethereum-sepolia": "0x8004a6090Cd10A7288092483047B097295Fb8847",
-      "optimism-sepolia": "0x8004a6090Cd10A7288092483047B097295Fb8847",
-      "linea-sepolia": "0x8004aa7C931bCE1233973a0C6A667f73F66282e7"
+      "base-sepolia": "0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70",
+      "ethereum-sepolia": "0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70",
+      "optimism-sepolia": "0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70",
+      "linea-sepolia": "0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70"
     };
     return treasuries[network] || treasuries["base-sepolia"];
   }
@@ -15396,7 +15396,6 @@ var StudioClient = class {
 
 // src/ChaosChainSDK.ts
 var ChaosChainSDK = class _ChaosChainSDK {
-  static warnedGatewayMissing = false;
   static warnedStudioClientProduction = false;
   // Core components
   walletManager;
@@ -15574,25 +15573,16 @@ var ChaosChainSDK = class _ChaosChainSDK {
         this.computeProvider
       );
     }
-    if (config.gatewayConfig || config.gatewayUrl) {
-      const gatewayConfig = config.gatewayConfig || { gatewayUrl: config.gatewayUrl };
-      this.gateway = new GatewayClient(gatewayConfig);
-      console.log(
-        `\u{1F310} Gateway client initialized: ${gatewayConfig.baseUrl || gatewayConfig.gatewayUrl || "https://gateway.chaoscha.in"}`
-      );
-    }
+    const gatewayConfig = config.gatewayConfig ?? (config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {});
+    this.gateway = new GatewayClient(gatewayConfig);
+    const gatewayBaseUrl = gatewayConfig.baseUrl ?? gatewayConfig.gatewayUrl ?? "https://gateway.chaoscha.in";
+    console.log(`\u{1F310} Gateway client initialized: ${gatewayBaseUrl}`);
     this.studio = new StudioClient({
       provider: this.provider,
       signer: this.walletManager.getWallet(),
       network: typeof config.network === "string" ? config.network : config.network
     });
     const isLocalNetwork = String(config.network) === "local" /* LOCAL */ || String(config.network) === "local";
-    if (!this.gateway && !isLocalNetwork && !_ChaosChainSDK.warnedGatewayMissing) {
-      console.warn(
-        "\u26A0\uFE0F Gateway is not configured. For production workflows, use gatewayConfig to enable Gateway orchestration."
-      );
-      _ChaosChainSDK.warnedGatewayMissing = true;
-    }
     if (process.env.NODE_ENV === "production" && !isLocalNetwork && !_ChaosChainSDK.warnedStudioClientProduction) {
       console.warn(
         "\u26A0\uFE0F StudioClient is intended for low-level or testing use. In production, prefer Gateway workflows."
@@ -16017,7 +16007,7 @@ var ChaosChainSDK = class _ChaosChainSDK {
    * Get SDK version
    */
   getVersion() {
-    return "0.2.3";
+    return "0.2.4";
   }
   /**
    * Get SDK capabilities summary
@@ -16472,24 +16462,51 @@ function resolveScoring(policy, mandate) {
 }
 function computeObserved(evidence) {
   const totalNodes = evidence.length;
+  const byId = /* @__PURE__ */ new Map();
   const childrenOf = /* @__PURE__ */ new Map();
   for (const e of evidence) {
+    byId.set(e.arweave_tx_id, e);
     childrenOf.set(e.arweave_tx_id, []);
   }
   let edgeCount = 0;
   let rootCount = 0;
-  let integrationNodeCount = 0;
   let artifactCount = 0;
   for (const e of evidence) {
     edgeCount += e.parent_ids.length;
     if (e.parent_ids.length === 0) rootCount++;
-    if (e.parent_ids.length > 1) integrationNodeCount++;
     if (e.artifact_ids.length > 0) artifactCount++;
     for (const pid of e.parent_ids) {
       const c = childrenOf.get(pid);
       if (c) c.push(e.arweave_tx_id);
     }
   }
+  const rootOrigins = /* @__PURE__ */ new Map();
+  function getRootOrigins(id) {
+    if (rootOrigins.has(id)) return rootOrigins.get(id);
+    const node = byId.get(id);
+    if (!node || node.parent_ids.length === 0) {
+      const s = /* @__PURE__ */ new Set([id]);
+      rootOrigins.set(id, s);
+      return s;
+    }
+    const origins = /* @__PURE__ */ new Set();
+    for (const pid of node.parent_ids) {
+      for (const r of getRootOrigins(pid)) origins.add(r);
+    }
+    rootOrigins.set(id, origins);
+    return origins;
+  }
+  for (const e of evidence) getRootOrigins(e.arweave_tx_id);
+  let integrationNodeCount = 0;
+  for (const e of evidence) {
+    if (e.parent_ids.length < 2) continue;
+    const parentRootSets = e.parent_ids.filter((pid) => byId.has(pid)).map((pid) => rootOrigins.get(pid));
+    const uniqueRoots = /* @__PURE__ */ new Set();
+    for (const s of parentRootSets) {
+      for (const r of s) uniqueRoots.add(r);
+    }
+    if (uniqueRoots.size >= 2) integrationNodeCount++;
+  }
   let terminalCount = 0;
   for (const [, children] of childrenOf) {
     if (children.length === 0) terminalCount++;
@@ -16622,12 +16639,13 @@ function extractAgencySignals(evidence, context) {
     durationMs: observed.durationMs
   };
   if (!scoring) {
-    initiativeSignal = Math.max(0, Math.min(1, rootRatio));
-    collaborationSignal = Math.max(0, Math.min(1, edgeDensity));
-    reasoningSignal = Math.max(0, Math.min(1, depthRatio));
+    const SOFT_CAP = 0.9;
+    initiativeSignal = Math.max(0, Math.min(SOFT_CAP, rootRatio));
+    collaborationSignal = Math.max(0, Math.min(SOFT_CAP, edgeDensity));
+    reasoningSignal = Math.max(0, Math.min(SOFT_CAP, depthRatio));
   } else {
     const ir = scoring.initiative.rootRatio;
-    initiativeSignal = rangeFit(rootRatio, ir.min, ir.target, ir.max);
+    const initiativeBase = rangeFit(rootRatio, ir.min, ir.target, ir.max);
     const cw = scoring.collaboration.weights;
     const ed = scoring.collaboration.edgeDensity;
     const intR = scoring.collaboration.integrationRatio;
@@ -16639,7 +16657,13 @@ function extractAgencySignals(evidence, context) {
     }
     collaborationSignal = Math.max(0, Math.min(1, collaborationSignal));
     const dr = scoring.reasoning.depthRatio;
-    reasoningSignal = rangeFit(depthRatio, dr.min, dr.target, dr.max);
+    const reasoningBase = rangeFit(depthRatio, dr.min, dr.target, dr.max);
+    const fragmentationPenalty = rootRatio > ir.max ? (rootRatio - ir.max) * 0.5 : 0;
+    const overcomplexityPenalty = depthRatio > dr.max ? (depthRatio - dr.max) * 0.5 : 0;
+    initiativeSignal = Math.max(0, Math.min(1, initiativeBase - fragmentationPenalty));
+    reasoningSignal = Math.max(0, Math.min(1, reasoningBase - overcomplexityPenalty));
+    observedBlock.fragmentationPenalty = fragmentationPenalty;
+    observedBlock.overcomplexityPenalty = overcomplexityPenalty;
     const compResult = computeComplianceSignal(evidence, observed, scoring, context?.workMandate);
     complianceSignal = compResult.signal;
     observedBlock.testsPresent = compResult.testsPresent;
@@ -16688,17 +16712,32 @@ function normalizeInput(value) {
   return Math.max(0, Math.min(1, v));
 }
 var CLAMP_100 = (v) => Math.max(0, Math.min(100, Math.round(v)));
+function resolveDimension(override, signal) {
+  if (override !== void 0) return normalizeInput(override);
+  return signal ?? 0;
+}
 function composeScoreVector(signals, assessment) {
-  const resolve = (override, signal) => {
-    if (override !== void 0) return normalizeInput(override);
-    return signal ?? 0;
-  };
+  if (assessment.complianceScore === void 0 || assessment.complianceScore === null) {
+    throw new Error("complianceScore is required for production scoring");
+  }
+  if (assessment.efficiencyScore === void 0 || assessment.efficiencyScore === null) {
+    throw new Error("efficiencyScore is required for production scoring");
+  }
+  return [
+    CLAMP_100(resolveDimension(assessment.initiativeScore, signals.initiativeSignal) * 100),
+    CLAMP_100(resolveDimension(assessment.collaborationScore, signals.collaborationSignal) * 100),
+    CLAMP_100(resolveDimension(assessment.reasoningScore, signals.reasoningSignal) * 100),
+    CLAMP_100(normalizeInput(assessment.complianceScore) * 100),
+    CLAMP_100(normalizeInput(assessment.efficiencyScore) * 100)
+  ];
+}
+function composeScoreVectorWithDefaults(signals, assessment) {
   return [
-    CLAMP_100(resolve(assessment?.initiativeScore, signals.initiativeSignal) * 100),
-    CLAMP_100(resolve(assessment?.collaborationScore, signals.collaborationSignal) * 100),
-    CLAMP_100(resolve(assessment?.reasoningScore, signals.reasoningSignal) * 100),
-    CLAMP_100(resolve(assessment?.complianceScore, signals.complianceSignal) * 100),
-    CLAMP_100(resolve(assessment?.efficiencyScore, signals.efficiencySignal) * 100)
+    CLAMP_100(resolveDimension(assessment?.initiativeScore, signals.initiativeSignal) * 100),
+    CLAMP_100(resolveDimension(assessment?.collaborationScore, signals.collaborationSignal) * 100),
+    CLAMP_100(resolveDimension(assessment?.reasoningScore, signals.reasoningSignal) * 100),
+    CLAMP_100(resolveDimension(assessment?.complianceScore, signals.complianceSignal) * 100),
+    CLAMP_100(resolveDimension(assessment?.efficiencyScore, signals.efficiencySignal) * 100)
   ];
 }
 function derivePoAScores(evidence, options) {
@@ -16712,7 +16751,7 @@ function derivePoAScores(evidence, options) {
     ];
   }
   const signals = extractAgencySignals(evidence);
-  return composeScoreVector(signals, {
+  return composeScoreVectorWithDefaults(signals, {
     complianceScore: options?.compliance,
     efficiencyScore: options?.efficiency
   });
@@ -16764,7 +16803,7 @@ function verifyWorkEvidence(evidence, context) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.2.3";
+var SDK_VERSION = "0.2.4";
 var ERC8004_VERSION = "1.0";
 var X402_VERSION = "1.0";
 var src_default = ChaosChainSDK;
@@ -16839,6 +16878,7 @@ exports.X402Server = X402Server;
 exports.X402_VERSION = X402_VERSION;
 exports.ZeroGStorage = ZeroGStorage;
 exports.composeScoreVector = composeScoreVector;
+exports.composeScoreVectorWithDefaults = composeScoreVectorWithDefaults;
 exports.computeDepth = computeDepth;
 exports.default = src_default;
 exports.derivePoAScores = derivePoAScores;