@chaoschain/sdk 0.2.2 → 0.2.3

package/dist/types-CEFAgoAM.d.ts

@@ -0,0 +1,756 @@
+import { ethers } from 'ethers';
+
+/**
+ * Evidence DAG utilities for ChaosChain PoA scoring.
+ *
+ * These helpers operate on evidence graphs produced by the gateway's DKG engine.
+ * Verifier agents use them to derive Proof-of-Agency scores from evidence structure.
+ *
+ * Architecture (3 layers per VA scoring spec):
+ *
+ *   Layer 1 — extractAgencySignals(evidence, context?)
+ *             Deterministic signal extraction. 0..1 normalized.
+ *             Same evidence + same policy = same signals.
+ *
+ *   Layer 2 — composeScoreVector(signals, assessment?)
+ *             Verifier agent produces final score vector.
+ *             Accepts 0..1 or 0..100 inputs, normalizes internally.
+ *             Output: integer tuple [0..100] × 5 for on-chain submission.
+ *
+ *   Layer 3 — Contract aggregation (outside SDK)
+ *             Median / MAD / stake-weighted consensus over verifier vectors.
+ */
+interface EvidencePackage {
+    arweave_tx_id: string;
+    author: string;
+    timestamp: number;
+    parent_ids: string[];
+    payload_hash: string;
+    artifact_ids: string[];
+    signature: string;
+}
+/** @deprecated Use WorkVerificationResult instead */
+interface WorkEvidenceVerificationResult {
+    valid: boolean;
+    scores: number[];
+}
+interface WorkVerificationResult {
+    valid: boolean;
+    signals?: AgencySignals;
+}
+/**
+ * Verifier assessment — optional overrides for each dimension.
+ * Values can be in 0..1 (normalized) or 0..100 (integer); the SDK
+ * auto-detects and normalizes internally.
+ */
+type VerifierAssessment = {
+    initiativeScore?: number;
+    collaborationScore?: number;
+    reasoningScore?: number;
+    complianceScore?: number;
+    efficiencyScore?: number;
+};
+/**
+ * Deterministic agency signals extracted from an evidence DAG.
+ *
+ * Signals are normalized to [0, 1]. The `observed` block carries raw graph
+ * features so verifier agents can apply their own judgment on top.
+ */
+type AgencySignals = {
+    initiativeSignal: number;
+    collaborationSignal: number;
+    reasoningSignal: number;
+    complianceSignal?: number;
+    efficiencySignal?: number;
+    observed: {
+        totalNodes: number;
+        rootCount: number;
+        edgeCount: number;
+        maxDepth: number;
+        artifactCount: number;
+        terminalCount: number;
+        integrationNodeCount: number;
+        uniqueAuthors?: number;
+        testsPresent?: boolean;
+        policyViolations?: string[];
+        requiredArtifactsPresent?: string[];
+        missingArtifacts?: string[];
+        durationMs?: number;
+    };
+};
+type ScoreRange = {
+    min: number;
+    target: number;
+    max: number;
+};
+type EngineeringStudioPolicy = {
+    version: string;
+    studioName: string;
+    scoring: {
+        initiative: {
+            rootRatio: ScoreRange;
+        };
+        collaboration: {
+            edgeDensity: ScoreRange;
+            integrationRatio: ScoreRange;
+            weights: {
+                edgeDensity: number;
+                integrationRatio: number;
+            };
+        };
+        reasoning: {
+            depthRatio: ScoreRange;
+        };
+        compliance: {
+            requiredChecks: string[];
+            forbiddenPatterns: string[];
+            requiredArtifacts: string[];
+            weights: {
+                testsPresent: number;
+                requiredArtifactsPresent: number;
+                noPolicyViolations: number;
+            };
+        };
+        efficiency: {
+            durationRatio?: ScoreRange;
+            artifactCountRatio?: ScoreRange;
+            weights: {
+                durationRatio?: number;
+                artifactCountRatio?: number;
+            };
+        };
+    };
+    verifierInstructions: {
+        initiative: string;
+        collaboration: string;
+        reasoning: string;
+        compliance: string;
+        efficiency: string;
+    };
+};
+type WorkMandate = {
+    taskId: string;
+    title: string;
+    objective: string;
+    taskType: 'bugfix' | 'feature' | 'refactor' | 'review' | 'research';
+    constraints?: {
+        mustPassTests?: boolean;
+        requiredArtifacts?: string[];
+        forbiddenPatterns?: string[];
+        latencyBudgetMs?: number;
+        targetFiles?: string[];
+    };
+    overrides?: Partial<EngineeringStudioPolicy['scoring']>;
+    verifierPrompt?: string;
+};
+/**
+ * Optional context passed to extractAgencySignals for policy-conditioned scoring.
+ */
+type SignalExtractionContext = {
+    studioPolicy?: EngineeringStudioPolicy;
+    workMandate?: WorkMandate;
+};
+/**
+ * Maps a value to [0, 1] based on a (min, target, max) range.
+ *
+ * - value <= min or value >= max → 0
+ * - value === target → 1
+ * - value between min and target → linear interpolation 0..1
+ * - value between target and max → linear interpolation 1..0
+ *
+ * Result is clamped to [0, 1].
+ */
+declare function rangeFit(value: number, min: number, target: number, max: number): number;
+/**
+ * Deterministic agency signal extraction from an evidence DAG.
+ *
+ * Without context: produces raw structural ratio signals (Phase 1 baseline).
+ * With studioPolicy/workMandate: produces policy-conditioned signals via
+ * rangeFit, including deterministic compliance and efficiency (Phase 2).
+ *
+ * Same evidence + same context always produces the same signals.
+ */
+declare function extractAgencySignals(evidence: EvidencePackage[], context?: SignalExtractionContext): AgencySignals;
+/**
+ * Returns the maximum causal depth of the evidence DAG.
+ * A single-node graph has depth 1. A linear chain of N nodes has depth N.
+ */
+declare function computeDepth(evidence: EvidencePackage[]): number;
+/**
+ * Composes a final on-chain score vector from deterministic signals and
+ * optional verifier assessment.
+ *
+ * For each dimension:
+ *   - If the verifier provides an override → use it (normalized)
+ *   - Otherwise → use the deterministic signal
+ *   - If the signal is also undefined → 0
+ *
+ * Input values can be in 0..1 or 0..100; the SDK auto-detects.
+ * Output is always integer tuple [0..100] × 5 ready for contract submission.
+ */
+declare function composeScoreVector(signals: AgencySignals, assessment?: VerifierAssessment): [number, number, number, number, number];
+/**
+ * Convenience wrapper: extract signals + compose score vector in one call.
+ *
+ * Returns [Initiative, Collaboration, Reasoning, Compliance, Efficiency]
+ * as integers 0..100 for on-chain submission.
+ *
+ * Compliance and efficiency come from signals when available, or from the
+ * verifier-provided `options`. No hardcoded placeholders.
+ */
+declare function derivePoAScores(evidence: EvidencePackage[], options?: {
+    compliance?: number;
+    efficiency?: number;
+}): [number, number, number, number, number];
+/**
+ * Validates that the evidence forms a valid DAG:
+ * - No cycles
+ * - All parent_ids reference existing nodes
+ */
+declare function validateEvidenceGraph(evidence: EvidencePackage[]): boolean;
+/**
+ * High-level verifier helper:
+ * 1) validates evidence graph integrity
+ * 2) extracts deterministic agency signals (optionally policy-conditioned)
+ *
+ * Returns { valid, signals } — the verifier then uses composeScoreVector()
+ * to produce the final on-chain score vector.
+ */
+declare function verifyWorkEvidence(evidence: EvidencePackage[], context?: SignalExtractionContext): WorkVerificationResult;
+
+/**
+ * ChaosChain SDK Type Definitions
+ * TypeScript types and interfaces for building verifiable AI agents
+ */
+
+/**
+ * Supported blockchain networks with pre-deployed ERC-8004 contracts
+ */
+declare enum NetworkConfig {
+    ETHEREUM_MAINNET = "ethereum-mainnet",
+    ETHEREUM_SEPOLIA = "ethereum-sepolia",
+    BASE_MAINNET = "base-mainnet",
+    BASE_SEPOLIA = "base-sepolia",
+    POLYGON_MAINNET = "polygon-mainnet",
+    POLYGON_AMOY = "polygon-amoy",
+    ARBITRUM_MAINNET = "arbitrum-mainnet",
+    ARBITRUM_TESTNET = "arbitrum-testnet",
+    CELO_MAINNET = "celo-mainnet",
+    CELO_TESTNET = "celo-testnet",
+    GNOSIS_MAINNET = "gnosis-mainnet",
+    SCROLL_MAINNET = "scroll-mainnet",
+    SCROLL_TESTNET = "scroll-testnet",
+    TAIKO_MAINNET = "taiko-mainnet",
+    MONAD_MAINNET = "monad-mainnet",
+    MONAD_TESTNET = "monad-testnet",
+    OPTIMISM_SEPOLIA = "optimism-sepolia",
+    LINEA_SEPOLIA = "linea-sepolia",
+    HEDERA_TESTNET = "hedera-testnet",
+    MODE_TESTNET = "mode-testnet",
+    ZEROG_TESTNET = "0g-testnet",
+    BSC_MAINNET = "bsc-mainnet",
+    BSC_TESTNET = "bsc-testnet",
+    LOCAL = "local"
+}
+/**
+ * W3C-compliant payment methods supported by the SDK.
+ */
+declare enum PaymentMethod {
+    BASIC_CARD = "basic-card",
+    GOOGLE_PAY = "https://google.com/pay",
+    APPLE_PAY = "https://apple.com/apple-pay",
+    PAYPAL = "https://paypal.com",
+    A2A_X402 = "https://a2a.org/x402",
+    DIRECT_TRANSFER = "direct-transfer"
+}
+/**
+ * Agent role in the ChaosChain network
+ */
+declare enum AgentRole {
+    WORKER = "worker",
+    VERIFIER = "verifier",
+    CLIENT = "client",
+    ORCHESTRATOR = "orchestrator"
+}
+/**
+ * ERC-8004 contract addresses for a network
+ */
+interface ContractAddresses {
+    identity: string;
+    reputation: string;
+    validation: string;
+    identityRegistry?: string;
+    reputationRegistry?: string;
+    validationRegistry?: string;
+    identity_registry?: string;
+    reputation_registry?: string;
+    validation_registry?: string;
+    rewardsDistributor?: string | null;
+    chaosCore?: string | null;
+    rewards_distributor?: string | null;
+    chaos_core?: string | null;
+    network?: NetworkConfig | null;
+}
+/**
+ * Network configuration with RPC and contract addresses
+ */
+interface NetworkInfo {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    contracts: ContractAddresses;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+}
+/**
+ * Agent metadata structure (ERC-8004 compliant)
+ */
+interface AgentMetadata {
+    name: string;
+    domain: string;
+    role: AgentRole | string;
+    capabilities?: string[];
+    version?: string;
+    description?: string;
+    image?: string;
+    contact?: string;
+    supportedTrust?: string[];
+}
+/**
+ * Agent registration result
+ */
+interface AgentRegistration {
+    agentId: bigint;
+    txHash: string;
+    owner: string;
+}
+/**
+ * Feedback submission parameters
+ */
+interface FeedbackParams {
+    agentId: bigint;
+    rating: number;
+    feedbackUri: string;
+    feedbackData?: FeedbackData;
+}
+/**
+ * Feedback metadata payload (ERC-8004 Jan/Feb 2026)
+ */
+interface FeedbackData extends Record<string, unknown> {
+    tag1?: string;
+    tag2?: string;
+    endpoint?: string;
+    value?: number | bigint;
+    valueDecimals?: number;
+    content?: string;
+    feedbackHash?: string;
+    /**
+     * @deprecated ERC-8004 Jan 2026 removed feedbackAuth
+     */
+    feedbackAuth?: string;
+}
+/**
+ * Feedback record
+ */
+interface FeedbackRecord {
+    feedbackId: bigint;
+    fromAgent: bigint;
+    toAgent: bigint;
+    rating: number;
+    value?: number;
+    valueDecimals?: number;
+    tag1?: string;
+    tag2?: string;
+    endpoint?: string;
+    feedbackIndex?: bigint;
+    feedbackUri: string;
+    timestamp: number;
+    revoked: boolean;
+}
+/**
+ * Validation request parameters
+ */
+interface ValidationRequestParams {
+    validatorAgentId: bigint;
+    requestUri: string;
+    requestHash: string;
+}
+/**
+ * Validation request record
+ */
+interface ValidationRequest {
+    requestId: bigint;
+    requester: bigint;
+    validator: bigint;
+    requestUri: string;
+    requestHash: string;
+    status: ValidationStatus;
+    responseUri?: string;
+    timestamp: number;
+}
+/**
+ * Validation status enum
+ */
+declare enum ValidationStatus {
+    PENDING = 0,
+    APPROVED = 1,
+    REJECTED = 2
+}
+/**
+ * x402 payment parameters
+ */
+interface X402PaymentParams {
+    toAgent: string;
+    amount: string;
+    currency?: string;
+    serviceType?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * x402 payment result
+ */
+interface X402Payment {
+    from: string;
+    to: string;
+    amount: string;
+    currency: string;
+    txHash: string;
+    timestamp: number;
+    feeAmount?: string;
+    feeTxHash?: string;
+}
+/**
+ * Storage upload options
+ */
+interface UploadOptions {
+    mime?: string;
+    metadata?: Record<string, unknown>;
+    pin?: boolean;
+}
+/**
+ * Storage upload result
+ */
+interface UploadResult {
+    cid: string;
+    uri: string;
+    size?: number;
+    timestamp: number;
+}
+/**
+ * Storage provider interface
+ */
+interface StorageProvider {
+    upload(data: Buffer | string | object, options?: UploadOptions): Promise<UploadResult>;
+    download(cid: string): Promise<Buffer>;
+    pin(cid: string): Promise<void>;
+    unpin(cid: string): Promise<void>;
+}
+/**
+ * Compute provider interface
+ */
+interface ComputeProvider {
+    inference(model: string, input: unknown): Promise<unknown>;
+    getModels(): Promise<string[]>;
+}
+/**
+ * Verification method
+ */
+declare enum VerificationMethod {
+    TEE_ML = "tee-ml",// Trusted Execution Environment
+    ZK_ML = "zk-ml",// Zero-Knowledge Machine Learning
+    OP_ML = "op-ml",// Optimistic Machine Learning
+    NONE = "none"
+}
+/**
+ * TEE attestation data
+ */
+interface TEEAttestation {
+    jobId: string;
+    provider: string;
+    executionHash: string;
+    verificationMethod: VerificationMethod;
+    model?: string;
+    attestationData: unknown;
+    proof?: string;
+    metadata?: unknown;
+    timestamp: string;
+}
+/**
+ * Integrity proof structure
+ */
+interface IntegrityProof {
+    proofId: string;
+    functionName: string;
+    codeHash: string;
+    executionHash: string;
+    timestamp: Date;
+    agentName: string;
+    verificationStatus: string;
+    ipfsCid?: string;
+    teeAttestation?: TEEAttestation;
+    teeProvider?: string;
+    teeJobId?: string;
+    teeExecutionHash?: string;
+}
+/**
+ * Main SDK configuration
+ */
+interface ChaosChainSDKConfig {
+    agentName: string;
+    agentDomain: string;
+    agentRole: AgentRole | string;
+    network: NetworkConfig | string;
+    privateKey?: string;
+    mnemonic?: string;
+    rpcUrl?: string;
+    enableAP2?: boolean;
+    enableProcessIntegrity?: boolean;
+    enablePayments?: boolean;
+    enableStorage?: boolean;
+    storageProvider?: StorageProvider;
+    computeProvider?: ComputeProvider;
+    walletFile?: string;
+    facilitatorUrl?: string;
+    facilitatorApiKey?: string;
+    facilitatorMode?: 'managed' | 'decentralized';
+    agentId?: string;
+    gatewayUrl?: string;
+    gatewayConfig?: GatewayClientConfig;
+}
+/**
+ * Wallet configuration
+ */
+interface WalletConfig {
+    privateKey?: string;
+    mnemonic?: string;
+    walletFile?: string;
+}
+/**
+ * Transaction result
+ */
+interface TransactionResult {
+    hash: string;
+    receipt?: ethers.TransactionReceipt;
+    confirmations?: number;
+}
+/**
+ * Workflow types supported by Gateway.
+ */
+declare enum WorkflowType {
+    WORK_SUBMISSION = "WorkSubmission",
+    SCORE_SUBMISSION = "ScoreSubmission",
+    CLOSE_EPOCH = "CloseEpoch"
+}
+/**
+ * Workflow states.
+ */
+declare enum WorkflowState {
+    CREATED = "CREATED",
+    RUNNING = "RUNNING",
+    STALLED = "STALLED",
+    COMPLETED = "COMPLETED",
+    FAILED = "FAILED"
+}
+/**
+ * Score submission modes supported by Gateway.
+ * - DIRECT: Simple direct scoring via submitScoreVectorForWorker (default, MVP)
+ * - COMMIT_REVEAL: Commit-reveal pattern (prevents last-mover bias)
+ */
+declare enum ScoreSubmissionMode {
+    DIRECT = "direct",
+    COMMIT_REVEAL = "commit_reveal"
+}
+/**
+ * Progress data for a workflow.
+ * Populated as the workflow progresses through steps.
+ */
+interface WorkflowProgress {
+    /** Arweave transaction ID for evidence archival */
+    arweaveTxId?: string;
+    /** Whether Arweave transaction is confirmed */
+    arweaveConfirmed?: boolean;
+    /** On-chain transaction hash */
+    onchainTxHash?: string;
+    /** Whether on-chain transaction is confirmed */
+    onchainConfirmed?: boolean;
+    /** Block number of on-chain confirmation */
+    onchainBlock?: number;
+    /** Score submission transaction hash (direct mode) */
+    scoreTxHash?: string;
+    /** Commit transaction hash (commit-reveal mode) */
+    commitTxHash?: string;
+    /** Reveal transaction hash (commit-reveal mode) */
+    revealTxHash?: string;
+}
+/**
+ * Error information for a failed workflow.
+ */
+interface WorkflowError {
+    /** Step where the error occurred */
+    step: string;
+    /** Human-readable error message */
+    message: string;
+    /** Optional error code */
+    code?: string;
+}
+/**
+ * Status of a workflow.
+ */
+interface WorkflowStatus {
+    /** Unique workflow identifier (UUID) */
+    workflowId: string;
+    /** Type of workflow */
+    workflowType: WorkflowType;
+    /** Current state */
+    state: WorkflowState;
+    /** Current step name */
+    step: string;
+    /** Unix timestamp of creation */
+    createdAt: number;
+    /** Unix timestamp of last update */
+    updatedAt: number;
+    /** Progress information */
+    progress: WorkflowProgress;
+    /** Error information (if state is FAILED) */
+    error?: WorkflowError;
+}
+/**
+ * Gateway health response payload.
+ */
+interface GatewayHealthResponse {
+    status: string;
+    timestamp?: number;
+}
+/**
+ * Gateway auth mode.
+ */
+type GatewayAuthMode = 'apiKey' | 'signature';
+/**
+ * Gateway signature auth input.
+ */
+interface GatewaySignatureAuth {
+    /** Precomputed signature for the request (server validates against address + timestamp). */
+    address: string;
+    signature: string;
+    /** Optional Unix epoch in milliseconds; defaults to Date.now() when omitted. */
+    timestamp?: number;
+}
+/**
+ * Gateway auth configuration.
+ */
+interface GatewayAuthConfig {
+    authMode?: GatewayAuthMode;
+    apiKey?: string;
+    signature?: GatewaySignatureAuth;
+}
+/**
+ * Gateway retry configuration.
+ */
+interface GatewayRetryConfig {
+    /** Retries are disabled by default; enable explicitly for transient errors only. */
+    enabled?: boolean;
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+    jitter?: boolean;
+    jitterRatio?: number;
+}
+/**
+ * Gateway client configuration.
+ */
+interface GatewayClientConfig {
+    /** Gateway API URL (preferred key, e.g. "https://gateway.chaoscha.in"). */
+    baseUrl?: string;
+    /** Legacy alias for baseUrl (kept for backward compatibility). */
+    gatewayUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Request timeout in milliseconds (alias of timeout) */
+    timeoutMs?: number;
+    /** Request timeout in seconds (alias of timeout) */
+    timeoutSeconds?: number;
+    /** Maximum time to wait for workflow completion in milliseconds (default: 300000) */
+    maxPollTime?: number;
+    /** Maximum time to wait for workflow completion in milliseconds (alias of maxPollTime) */
+    maxPollTimeMs?: number;
+    /** Maximum time to wait for workflow completion in seconds (alias of maxPollTime) */
+    maxPollTimeSeconds?: number;
+    /** Interval between status polls in milliseconds (default: 2000) */
+    pollInterval?: number;
+    /** Interval between status polls in milliseconds (alias of pollInterval) */
+    pollIntervalMs?: number;
+    /** Interval between status polls in seconds (alias of pollInterval) */
+    pollIntervalSeconds?: number;
+    /** Optional default headers merged into each request */
+    headers?: Record<string, string>;
+    /** Optional auth configuration */
+    auth?: GatewayAuthConfig;
+    /** Optional retry configuration (disabled by default) */
+    retry?: GatewayRetryConfig;
+}
+interface PendingWorkItem {
+    work_id: string;
+    agent_id: number;
+    epoch: number | null;
+    submitted_at: string;
+    evidence_anchor: string | null;
+    derivation_root: string | null;
+}
+interface PendingWorkResponse {
+    version: string;
+    data: {
+        studio: string;
+        work: PendingWorkItem[];
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+interface WorkEvidenceResponse {
+    version: string;
+    data: {
+        work_id: string;
+        thread_root: string;
+        dkg_evidence: EvidencePackage[];
+    };
+}
+/**
+ * @deprecated XMTP functionality has moved to the Gateway service.
+ * This type is kept for backward compatibility only.
+ * Do NOT implement XMTP client in SDK - use Gateway instead.
+ */
+interface XMTPMessageData {
+    messageId: string;
+    fromAgent: string;
+    toAgent: string;
+    content: any;
+    timestamp: number;
+    parentIds: string[];
+    artifactIds: string[];
+    signature: string;
+}
+/**
+ * @deprecated DKG functionality has moved to the Gateway service.
+ * This type is kept for backward compatibility only.
+ * Do NOT implement DKG in SDK - Gateway constructs the graph.
+ */
+interface DKGNodeData {
+    author: string;
+    sig: string;
+    ts: number;
+    xmtpMsgId: string;
+    artifactIds: string[];
+    payloadHash: string;
+    parents: string[];
+    content?: string;
+    nodeType?: string;
+    metadata?: Record<string, any>;
+    vlc?: string;
+    canonicalHash?: string;
+}
+
+export { AgentRole as A, extractAgencySignals as B, type ContractAddresses as C, type DKGNodeData as D, composeScoreVector as E, type FeedbackParams as F, type GatewayClientConfig as G, rangeFit as H, type IntegrityProof as I, type EvidencePackage as J, type WorkEvidenceVerificationResult as K, type WorkVerificationResult as L, type AgencySignals as M, NetworkConfig as N, type VerifierAssessment as O, type PendingWorkResponse as P, type ScoreRange as Q, type EngineeringStudioPolicy as R, ScoreSubmissionMode as S, type TEEAttestation as T, type UploadOptions as U, type ValidationRequestParams as V, type WalletConfig as W, type X402PaymentParams as X, type WorkMandate as Y, type SignalExtractionContext as Z, type NetworkInfo as a, type GatewayHealthResponse as b, type WorkflowStatus as c, type WorkEvidenceResponse as d, type ChaosChainSDKConfig as e, type AgentMetadata as f, type AgentRegistration as g, PaymentMethod as h, type UploadResult as i, type WorkflowError as j, type FeedbackRecord as k, type ValidationRequest as l, type X402Payment as m, type StorageProvider as n, type ComputeProvider as o, type TransactionResult as p, ValidationStatus as q, WorkflowType as r, WorkflowState as s, type WorkflowProgress as t, type PendingWorkItem as u, type XMTPMessageData as v, computeDepth as w, derivePoAScores as x, validateEvidenceGraph as y, verifyWorkEvidence as z };