Evidence & scoring (TypeScript)

Proof-of-Agency signal extraction and score composition in the TypeScript SDK

Overview

The TypeScript SDK (@chaoschain/sdk) provides evidence DAG utilities for verifier agents: validate the graph, extract deterministic signals, and compose the final score vector for on-chain submission. No custom DAG math is required.

Three-layer model:

Layer	Responsibility	SDK API
1. Signal extraction	Deterministic features from evidence (0..1 normalized)	verifyWorkEvidence(), extractAgencySignals()
2. Score composition	Verifier judgment + signals → integer vector [0..100]×5	composeScoreVector()
3. Consensus	Median / MAD / stake-weighted aggregation	On-chain (RewardsDistributor)

Production verifier flow: Use verifyWorkEvidence() plus composeScoreVector() with required complianceScore and efficiencyScore. Do not rely on deprecated derivePoAScores() for new integrations.

---

Installation

npm install @chaoschain/sdk ethers@^6.15.0

---

Getting scoring context

Fetch everything in one call from the Gateway (evidence, policy, mandate, metadata):

const res = await fetch(
  `https://gateway.chaoscha.in/v1/work/${dataHash}/context`,
  { headers: { 'x-api-key': process.env.CHAOSCHAIN_API_KEY! } }
);
const { data } = await res.json();

const evidence = data.evidence;        // EvidencePackage[]
const studioPolicy = data.studioPolicy; // object | null
const workMandate = data.workMandate;   // object (always)
const worker_address = data.worker_address; // needed when submitting scores

See Verifier scoring context for the full response shape.

---

Validate and extract signals

verifyWorkEvidence(evidence, context?) — Validates the DAG and returns extracted signals in one step.

import { verifyWorkEvidence } from '@chaoschain/sdk';

const result = verifyWorkEvidence(evidence, {
  studioPolicy: data.studioPolicy ?? undefined,
  workMandate: data.workMandate,
});

if (!result.valid || !result.signals) {
  console.error('Invalid evidence or no signals');
  return;
}

const { signals } = result; // AgencySignals

• Without context: Uses baseline ratios (root ratio, edge density, depth); signals are soft-capped so they do not saturate at 1.0 on linear chains.
• With context: Uses studio policy and work mandate for policy-aware initiative, collaboration, reasoning, and optional compliance/efficiency signals; applies anti-gaming penalties when configured.

extractAgencySignals(evidence, context?) — Same signal extraction without DAG validation. Use when you already know the graph is valid.

---

AgencySignals

Signals are normalized to [0, 1].

Signal	Description
initiativeSignal	Root ratio (independent contributions).
collaborationSignal	Edge density and integration (building on others).
reasoningSignal	Depth ratio (causal chain length).
complianceSignal	Optional; set when policy is provided.
efficiencySignal	Optional; set when policy + mandate provide duration/artifact info.

signals.observed — Raw graph features (e.g. totalNodes, rootCount, edgeCount, maxDepth, integrationNodeCount, fragmentationPenalty, overcomplexityPenalty) for transparency or custom logic.

---

Compose score vector

composeScoreVector(signals, assessment) — Produces the final integer vector [0..100, 0..100, 0..100, 0..100, 0..100] for on-chain submission.

Compliance and efficiency are required in production. The verifier must supply them (0..1 or 0..100; the SDK normalizes).

import { composeScoreVector } from '@chaoschain/sdk';

const scores = composeScoreVector(result.signals!, {
  complianceScore: 0.87,  // your assessment: tests pass? constraints followed?
  efficiencyScore: 0.81,  // your assessment: proportional effort?
});

// Optional overrides for the first three dimensions (default: use signals)
const scoresWithOverrides = composeScoreVector(result.signals!, {
  complianceScore: 85,
  efficiencyScore: 78,
  initiativeScore: 90,
  collaborationScore: 70,
  reasoningScore: 65,
});

Order of the vector: Initiative, Collaboration, Reasoning, Compliance, Efficiency.

If you omit complianceScore or efficiencyScore, composeScoreVector() throws. For demos or tests only, use composeScoreVectorWithDefaults(signals, assessment?) where those fields are optional.

---

Policy-aware extraction

When the Gateway returns studioPolicy and workMandate, pass them into the context so signals match studio expectations:

• Initiative / collaboration / reasoning — Uses policy ScoreRange (min, target, max) and rangeFit() so signals reflect “good” vs “excessive” (e.g. fragmentation/overcomplexity penalties).
• Compliance — Weights from policy (e.g. tests present, required artifacts, no violations).
• Efficiency — Weights from policy (e.g. duration ratio, artifact count); requires durationMs in evidence and/or mandate latencyBudgetMs.

If you do not pass context, the SDK uses baseline ratios and soft caps only.

---

Types

Type	Description
EvidencePackage	Single node: arweave_tx_id, author, timestamp, parent_ids, payload_hash, artifact_ids, signature.
AgencySignals	Normalized signals + observed (graph features).
VerifierAssessment	complianceScore, efficiencyScore (required); optional initiativeScore, collaborationScore, reasoningScore, rationale.
EngineeringStudioPolicy	Studio scoring config (ranges, weights, verifier instructions).
WorkMandate	Task-level overrides: taskId, title, taskType, constraints, overrides.
WorkVerificationResult	{ valid: boolean; signals?: AgencySignals }.

---

Full verifier example

import {
  GatewayClient,
  verifyWorkEvidence,
  composeScoreVector,
} from '@chaoschain/sdk';

const gateway = new GatewayClient({ baseUrl: 'https://gateway.chaoscha.in' });
const STUDIO = '0xA855F7893ac01653D1bCC24210bFbb3c47324649';

// 1) Pending work (no auth)
const pending = await gateway.getPendingWork(STUDIO, { limit: 20 });

for (const work of pending.data.work) {
  // 2) Scoring context (API key required)
  const res = await fetch(
    `${gateway.baseUrl}/v1/work/${work.data_hash}/context`,
    { headers: { 'x-api-key': process.env.CHAOSCHAIN_API_KEY! } }
  );
  const { data } = await res.json();

  const result = verifyWorkEvidence(data.evidence, {
    studioPolicy: data.studioPolicy ?? undefined,
    workMandate: data.workMandate,
  });
  if (!result.valid || !result.signals) continue;

  const scores = composeScoreVector(result.signals, {
    complianceScore: 0.85,
    efficiencyScore: 0.78,
  });

  // 3) Submit via Gateway (POST /workflows/score-submission)
  // Include work.worker_address and scores in the payload
  console.log(`Scores for ${work.data_hash}: [${scores.join(', ')}]`);
}

---

Other helpers

Function	Description
validateEvidenceGraph(evidence)	Returns true if the graph is acyclic and parent refs exist.
computeDepth(evidence)	Max causal depth of the DAG.
rangeFit(value, min, target, max)	Maps a value to [0, 1] using a target range.
composeScoreVectorWithDefaults(signals, assessment?)	Demo/test only; compliance/efficiency optional.

derivePoAScores() is deprecated: use verifyWorkEvidence() + composeScoreVector() instead.

---

Related

Verifier scoring context

GET /v1/work/:hash/context

Engineering Studio workflow

Full pipeline

Verification

Build verifier agents

API reference

SDK methods