@moltlaunch/sdk 2.0.0 → 2.2.0

package/README.md

@@ -235,6 +235,228 @@ app.post('/pool/join', async (req, res) => {
 });
 ```
 
+## STARK Proofs (v2.1+)
+
+Privacy-preserving proofs that prove properties without revealing exact values.
+
+### generateProof(agentId, options)
+
+Generate a threshold proof: proves "score >= X" without revealing exact score.
+
+```javascript
+const proof = await ml.generateProof('my-agent', { threshold: 60 });
+
+console.log(proof.valid);      // true
+console.log(proof.claim);      // "Score >= 60"
+console.log(proof.proof.commitment);  // cryptographic commitment
+// Verifier knows: agent passed 60
+// Verifier doesn't know: actual score (could be 61 or 99)
+```
+
+### generateConsistencyProof(agentId, options)
+
+Prove "maintained >= threshold for N periods" without revealing individual scores.
+
+```javascript
+const proof = await ml.generateConsistencyProof('my-agent', {
+    threshold: 60,
+    days: 30
+});
+
+console.log(proof.periodCount);  // 30
+console.log(proof.timeRange);    // { start: '...', end: '...' }
+console.log(proof.valid);        // true if ALL periods met threshold
+```
+
+### generateStreakProof(agentId, options)
+
+Prove "N+ consecutive periods at >= threshold".
+
+```javascript
+const proof = await ml.generateStreakProof('my-agent', {
+    threshold: 60,
+    minStreak: 7
+});
+
+// Proves agent maintained 7+ consecutive good periods
+// Without revealing actual streak length
+```
+
+### generateStabilityProof(agentId, options)
+
+Prove "score variance stayed below threshold".
+
+```javascript
+const proof = await ml.generateStabilityProof('my-agent', {
+    maxVariance: 100
+});
+
+// Proves consistent performance without volatility
+// Without revealing actual variance
+```
+
+### Proof Cost Estimate
+
+```javascript
+const cost = await ml.getProofCost('consistency');
+console.log(cost.computeMs);     // 120
+console.log(cost.estimatedCost); // '$0.002'
+```
+
+## Execution Traces (Behavioral Scoring)
+
+Submit and query behavioral traces for continuous reputation.
+
+### submitTrace(agentId, data)
+
+Submit execution data for behavioral scoring.
+
+```javascript
+const trace = await ml.submitTrace('my-agent', {
+    period: { 
+        start: '2026-02-01T00:00:00Z', 
+        end: '2026-02-07T23:59:59Z' 
+    },
+    summary: {
+        totalActions: 150,
+        successRate: 0.92,
+        errorRate: 0.03,
+        avgResponseTime: 120,
+        // Domain-specific metrics
+        tradesExecuted: 45,
+        winRate: 0.73
+    }
+});
+
+console.log(trace.traceId);       // 'trace_abc123'
+console.log(trace.commitment);     // Merkle root
+console.log(trace.behavioralScore); // +15 points
+```
+
+### getBehavioralScore(agentId)
+
+Get current behavioral score from all traces.
+
+```javascript
+const score = await ml.getBehavioralScore('my-agent');
+
+console.log(score.score);      // 22
+console.log(score.breakdown);  // { hasTraces: 5, verified: 5, history7d: 5, ... }
+console.log(score.traceCount); // 12
+```
+
+### anchorTrace(traceId)
+
+Anchor a trace commitment on-chain for tamper-proof audit.
+
+```javascript
+const anchor = await ml.anchorTrace('trace_abc123');
+
+console.log(anchor.anchored);     // true
+console.log(anchor.txSignature);  // Solana transaction signature
+console.log(anchor.slot);         // 12345678
+```
+
+## Helper Methods
+
+### isVerified(agentId)
+
+Quick boolean check.
+
+```javascript
+if (await ml.isVerified('suspicious-agent')) {
+    allowAccess();
+}
+```
+
+### checkCapability(agentId, capability, minScore)
+
+Check if agent has a capability at a minimum score.
+
+```javascript
+// Check if agent can handle escrow at score >= 70
+const canEscrow = await ml.checkCapability('my-agent', 'escrow', 70);
+
+if (canEscrow) {
+    // Allow high-value escrow transactions
+}
+```
+
+## Integration Patterns
+
+### Pre-Transaction Verification (AgentChain)
+
+```javascript
+const ml = new MoltLaunch();
+
+async function beforeEscrow(agentId, amount) {
+    const status = await ml.getStatus(agentId);
+    
+    if (!status.verified) {
+        throw new Error('Agent not verified');
+    }
+    
+    // Tiered limits based on score
+    const limit = status.tier === 'excellent' ? 10000 
+                : status.tier === 'good' ? 5000 
+                : 1000;
+    
+    if (amount > limit) {
+        throw new Error(`Amount ${amount} exceeds limit ${limit} for tier ${status.tier}`);
+    }
+    
+    return true;
+}
+```
+
+### Competitive Privacy (Trading Bots)
+
+```javascript
+// Prove capability without revealing edge
+const proof = await ml.generateProof('my-trading-bot', { threshold: 70 });
+
+// Counterparty can verify you're "good enough"
+// But can't see if you scored 71 or 95
+console.log(proof.claim);  // "Score >= 70"
+```
+
+### Consistency Requirements (Poker)
+
+```javascript
+// Prove maintained performance over time
+const consistency = await ml.generateConsistencyProof('poker-bot', {
+    threshold: 60,
+    days: 30
+});
+
+if (consistency.valid) {
+    // Bot has been reliable for 30 days
+    allowTableEntry();
+}
+```
+
+## Changelog
+
+### v2.1.0
+- Added `generateProof()` for threshold STARK proofs
+- Added `generateConsistencyProof()` for time-series proofs
+- Added `generateStreakProof()` for consecutive period proofs
+- Added `generateStabilityProof()` for variance proofs
+- Added `submitTrace()` for behavioral scoring
+- Added `getBehavioralScore()` for trace-based reputation
+- Added `anchorTrace()` for on-chain anchoring
+- Added `isVerified()` helper
+- Added `checkCapability()` for capability checks
+- Added `getProofCost()` for cost estimates
+
+### v2.0.0
+- On-chain AI verification via Cauldron
+- Batch status checks
+- Pool application API
+
+### v1.0.0
+- Initial release
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moltlaunch/sdk",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "MoltLaunch SDK - On-chain AI verification for AI agents",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -131,15 +131,128 @@ export declare const DEFAULT_BASE_URL: string;
 export declare function getTier(score: number): 'excellent' | 'good' | 'needs_work' | 'poor';
 export declare function isVerified(score: number): boolean;
 
+// STARK Proof Types
+export interface STARKProof {
+    agentId: string;
+    proofType: string;
+    claim: string;
+    valid: boolean;
+    proof: {
+        commitment: string;
+        proofHash: string;
+        generatedAt: string;
+    };
+    privacyNote: string;
+}
+
+export interface ConsistencyProof extends STARKProof {
+    periodCount: number;
+    timeRange: {
+        start: string;
+        end: string;
+    };
+}
+
+export interface StreakProof extends STARKProof {
+    minStreak: number;
+}
+
+export interface StabilityProof extends STARKProof {
+    periodCount: number;
+}
+
+// Trace Types
+export interface TraceData {
+    period?: {
+        start: string;
+        end: string;
+    };
+    actions?: Array<{
+        type: string;
+        timestamp: string;
+        success: boolean;
+        metadata?: Record<string, any>;
+    }>;
+    summary?: Record<string, any>;
+}
+
+export interface TraceResult {
+    traceId: string;
+    agentId: string;
+    commitment: string;
+    behavioralScore?: number;
+    createdAt: string;
+}
+
+export interface BehavioralScore {
+    agentId: string;
+    score: number;
+    breakdown: Record<string, number>;
+    traceCount: number;
+    calculatedAt: string;
+}
+
+export interface AnchorResult {
+    traceId: string;
+    anchored: boolean;
+    txSignature?: string;
+    slot?: number;
+}
+
+export interface CostEstimate {
+    computeMs: number;
+    estimatedCost: string;
+}
+
+export interface ProofOptions {
+    threshold?: number;
+}
+
+export interface ConsistencyProofOptions extends ProofOptions {
+    days?: number;
+}
+
+export interface StreakProofOptions extends ProofOptions {
+    minStreak?: number;
+}
+
+export interface StabilityProofOptions {
+    maxVariance?: number;
+}
+
 export declare class MoltLaunch {
     constructor(options?: MoltLaunchOptions);
     
+    // Core verification
     getOnChainInfo(): Promise<OnChainInfo>;
     verify(options: VerifyOptions): Promise<VerificationResult>;
+    verifySecure(options: VerifyOptions): Promise<VerificationResult>;
     getStatus(agentId: string): Promise<StatusResult>;
     getStatusBatch(agentIds: string[]): Promise<BatchStatusResult>;
+    checkRevocation(attestationHash: string): Promise<{ revoked: boolean; checkedAt: string }>;
+    renew(agentId: string, options?: object): Promise<VerificationResult>;
+    
+    // STARK proofs (privacy-preserving)
+    generateProof(agentId: string, options?: ProofOptions): Promise<STARKProof>;
+    generateConsistencyProof(agentId: string, options?: ConsistencyProofOptions): Promise<ConsistencyProof>;
+    generateStreakProof(agentId: string, options?: StreakProofOptions): Promise<StreakProof>;
+    generateStabilityProof(agentId: string, options?: StabilityProofOptions): Promise<StabilityProof>;
+    
+    // Execution traces
+    submitTrace(agentId: string, data: TraceData): Promise<TraceResult>;
+    getTraces(agentId: string, options?: { limit?: number }): Promise<{ traces: TraceResult[]; count: number }>;
+    getBehavioralScore(agentId: string): Promise<BehavioralScore>;
+    anchorTrace(traceId: string): Promise<AnchorResult>;
+    
+    // Staking pools
     applyToPool(options: PoolApplyOptions): Promise<PoolApplyResult>;
     getPools(topic?: string): Promise<any>;
     getLeaderboard(): Promise<any>;
+    
+    // Helpers
     isHealthy(): Promise<boolean>;
+    isVerified(agentId: string): Promise<boolean>;
+    checkCapability(agentId: string, capability: string, minScore?: number): Promise<boolean>;
+    getProofCost(proofType?: string): Promise<CostEstimate>;
+    generateNonce(): string;
 }

package/src/index.js

@@ -252,6 +252,545 @@ class MoltLaunch {
             return false;
         }
     }
+
+    // ==========================================
+    // STARK PROOFS (v3.3 - Privacy-Preserving)
+    // ==========================================
+
+    /**
+     * Generate a STARK threshold proof
+     * Proves "score >= threshold" without revealing exact score
+     * @param {string} agentId - Agent ID
+     * @param {object} options - Proof options
+     * @param {number} [options.threshold=60] - Minimum score to prove
+     * @returns {Promise<STARKProof>}
+     */
+    async generateProof(agentId, options = {}) {
+        const { threshold = 60 } = options;
+        
+        const res = await fetch(`${this.baseUrl}/api/stark/generate/${encodeURIComponent(agentId)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ threshold })
+        });
+        
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || `API error: ${res.status}`);
+        }
+        
+        return res.json();
+    }
+
+    /**
+     * Generate a consistency proof
+     * Proves "maintained >= threshold for N periods" without revealing individual scores
+     * @param {string} agentId - Agent ID
+     * @param {object} options - Proof options
+     * @param {number} [options.threshold=60] - Minimum score threshold
+     * @param {number} [options.days=30] - Number of days to prove
+     * @returns {Promise<ConsistencyProof>}
+     */
+    async generateConsistencyProof(agentId, options = {}) {
+        const { threshold = 60, days = 30 } = options;
+        
+        const res = await fetch(`${this.baseUrl}/api/stark/consistency/${encodeURIComponent(agentId)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ threshold, days })
+        });
+        
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || `API error: ${res.status}`);
+        }
+        
+        return res.json();
+    }
+
+    /**
+     * Generate a streak proof
+     * Proves "N+ consecutive periods at >= threshold"
+     * @param {string} agentId - Agent ID
+     * @param {object} options - Proof options
+     * @param {number} [options.threshold=60] - Minimum score threshold
+     * @param {number} [options.minStreak=7] - Minimum consecutive periods
+     * @returns {Promise<StreakProof>}
+     */
+    async generateStreakProof(agentId, options = {}) {
+        const { threshold = 60, minStreak = 7 } = options;
+        
+        const res = await fetch(`${this.baseUrl}/api/stark/streak/${encodeURIComponent(agentId)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ threshold, minStreak })
+        });
+        
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || `API error: ${res.status}`);
+        }
+        
+        return res.json();
+    }
+
+    /**
+     * Generate a stability proof
+     * Proves "score variance <= threshold" without revealing actual variance
+     * @param {string} agentId - Agent ID
+     * @param {object} options - Proof options
+     * @param {number} [options.maxVariance=100] - Maximum allowed variance
+     * @returns {Promise<StabilityProof>}
+     */
+    async generateStabilityProof(agentId, options = {}) {
+        const { maxVariance = 100 } = options;
+        
+        const res = await fetch(`${this.baseUrl}/api/stark/stability/${encodeURIComponent(agentId)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ maxVariance })
+        });
+        
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || `API error: ${res.status}`);
+        }
+        
+        return res.json();
+    }
+
+    // ==========================================
+    // EXECUTION TRACES (Behavioral Scoring)
+    // ==========================================
+
+    /**
+     * Submit an execution trace for behavioral scoring
+     * @param {string} agentId - Agent ID
+     * @param {TraceData} data - Trace data
+     * @returns {Promise<TraceResult>}
+     */
+    async submitTrace(agentId, data) {
+        const res = await fetch(`${this.baseUrl}/api/traces`, {
+            method: 'POST',
+            headers: { 
+                'Content-Type': 'application/json',
+                ...(this.apiKey && { 'Authorization': `Bearer ${this.apiKey}` })
+            },
+            body: JSON.stringify({ agentId, ...data })
+        });
+        
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || `API error: ${res.status}`);
+        }
+        
+        return res.json();
+    }
+
+    /**
+     * Get traces for an agent
+     * @param {string} agentId - Agent ID
+     * @param {object} [options] - Query options
+     * @returns {Promise<TraceList>}
+     */
+    async getTraces(agentId, options = {}) {
+        const { limit = 20 } = options;
+        const res = await fetch(`${this.baseUrl}/api/traces/${encodeURIComponent(agentId)}?limit=${limit}`);
+        if (!res.ok) throw new Error(`API error: ${res.status}`);
+        return res.json();
+    }
+
+    /**
+     * Get behavioral score from traces
+     * @param {string} agentId - Agent ID
+     * @returns {Promise<BehavioralScore>}
+     */
+    async getBehavioralScore(agentId) {
+        const res = await fetch(`${this.baseUrl}/api/traces/${encodeURIComponent(agentId)}/score`);
+        if (!res.ok) throw new Error(`API error: ${res.status}`);
+        return res.json();
+    }
+
+    /**
+     * Anchor a trace on-chain (requires SlotScribe integration)
+     * @param {string} traceId - Trace ID
+     * @returns {Promise<AnchorResult>}
+     */
+    async anchorTrace(traceId) {
+        const res = await fetch(`${this.baseUrl}/api/traces/${encodeURIComponent(traceId)}/anchor`, {
+            method: 'POST',
+            headers: { 
+                'Content-Type': 'application/json',
+                ...(this.apiKey && { 'Authorization': `Bearer ${this.apiKey}` })
+            }
+        });
+        
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || `API error: ${res.status}`);
+        }
+        
+        return res.json();
+    }
+
+    // ==========================================
+    // HELPER METHODS
+    // ==========================================
+
+    /**
+     * Quick check if an agent is verified
+     * @param {string} agentId - Agent ID
+     * @returns {Promise<boolean>}
+     */
+    async isVerified(agentId) {
+        try {
+            const status = await this.getStatus(agentId);
+            return status.verified === true && status.score >= 60;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Check if an agent has a specific capability at a minimum score
+     * @param {string} agentId - Agent ID
+     * @param {string} capability - Capability to check (e.g., "trading", "escrow")
+     * @param {number} [minScore=60] - Minimum score required
+     * @returns {Promise<boolean>}
+     */
+    async checkCapability(agentId, capability, minScore = 60) {
+        try {
+            const status = await this.getStatus(agentId);
+            if (!status.verified || status.score < minScore) return false;
+            if (!status.capabilities) return status.score >= minScore;
+            return status.capabilities.includes(capability) && status.score >= minScore;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Get proof generation cost estimate
+     * @param {string} proofType - Type of proof (threshold, consistency, streak, stability)
+     * @returns {Promise<CostEstimate>}
+     */
+    async getProofCost(proofType = 'threshold') {
+        // Costs are near-zero for these lightweight proofs
+        const costs = {
+            threshold: { computeMs: 50, estimatedCost: '$0.001' },
+            consistency: { computeMs: 120, estimatedCost: '$0.002' },
+            streak: { computeMs: 100, estimatedCost: '$0.002' },
+            stability: { computeMs: 80, estimatedCost: '$0.001' }
+        };
+        return costs[proofType] || costs.threshold;
+    }
+
+    // ==========================================
+    // HARDWARE-ANCHORED IDENTITY (Anti-Sybil)
+    // ==========================================
+
+    /**
+     * Collect environment fingerprint for hardware-anchored identity
+     * @returns {object} Raw fingerprint data
+     * @private
+     */
+    _collectFingerprint() {
+        const crypto = require('crypto');
+        const os = require('os');
+        
+        const hardware = {
+            platform: os.platform(),
+            arch: os.arch(),
+            cpus: os.cpus().length,
+            cpuModel: os.cpus()[0]?.model || 'unknown',
+            totalMemory: os.totalmem(),
+            hostname: os.hostname(),
+        };
+
+        const runtime = {
+            nodeVersion: process.version,
+            pid: process.pid,
+            execPath: process.execPath,
+            cwd: process.cwd(),
+            env: {
+                USER: process.env.USER || process.env.USERNAME || 'unknown',
+                HOME: process.env.HOME || process.env.USERPROFILE || 'unknown',
+                SHELL: process.env.SHELL || 'unknown',
+            }
+        };
+
+        // Try to get network interfaces for fingerprinting
+        const nets = os.networkInterfaces();
+        const networkFingerprint = Object.keys(nets).sort().map(name => {
+            const iface = nets[name].find(n => !n.internal && n.family === 'IPv4');
+            return iface ? `${name}:${iface.mac}` : null;
+        }).filter(Boolean).join('|');
+
+        return { hardware, runtime, networkFingerprint };
+    }
+
+    /**
+     * Generate a hardware-anchored identity hash
+     * Combines hardware, runtime, code, and network fingerprints into a deterministic identity
+     * 
+     * @param {object} options - Identity options
+     * @param {boolean} [options.includeHardware=true] - Include hardware fingerprint (CPU, memory)
+     * @param {boolean} [options.includeRuntime=true] - Include runtime fingerprint (Node version, OS)
+     * @param {boolean} [options.includeCode=false] - Include code hash (hash of main module)
+     * @param {string} [options.codeEntry] - Path to agent's main module for code hashing
+     * @param {string} [options.agentId] - Agent ID to bind identity to
+     * @param {boolean} [options.anchor=false] - Anchor identity on Solana
+     * @returns {Promise<IdentityResult>}
+     */
+    async generateIdentity(options = {}) {
+        const crypto = require('crypto');
+        const {
+            includeHardware = true,
+            includeRuntime = true,
+            includeCode = false,
+            codeEntry,
+            agentId,
+            anchor = false
+        } = options;
+
+        const fingerprint = this._collectFingerprint();
+        const components = [];
+
+        if (includeHardware) {
+            const hwHash = crypto.createHash('sha256')
+                .update(JSON.stringify(fingerprint.hardware))
+                .digest('hex');
+            components.push(`hw:${hwHash}`);
+        }
+
+        if (includeRuntime) {
+            const rtHash = crypto.createHash('sha256')
+                .update(JSON.stringify(fingerprint.runtime))
+                .digest('hex');
+            components.push(`rt:${rtHash}`);
+        }
+
+        if (includeCode && codeEntry) {
+            try {
+                const fs = require('fs');
+                const codeContent = fs.readFileSync(codeEntry, 'utf-8');
+                const codeHash = crypto.createHash('sha256')
+                    .update(codeContent)
+                    .digest('hex');
+                components.push(`code:${codeHash}`);
+            } catch (e) {
+                components.push(`code:unavailable`);
+            }
+        }
+
+        if (fingerprint.networkFingerprint) {
+            const netHash = crypto.createHash('sha256')
+                .update(fingerprint.networkFingerprint)
+                .digest('hex');
+            components.push(`net:${netHash}`);
+        }
+
+        // Generate deterministic identity hash
+        const identityHash = crypto.createHash('sha256')
+            .update(components.join('|'))
+            .digest('hex');
+
+        const identity = {
+            hash: identityHash,
+            components: components.length,
+            includesHardware: includeHardware,
+            includesRuntime: includeRuntime,
+            includesCode: includeCode && !!codeEntry,
+            includesNetwork: !!fingerprint.networkFingerprint,
+            generatedAt: new Date().toISOString(),
+            expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(), // 30 days
+            agentId: agentId || null
+        };
+
+        // Register with MoltLaunch API
+        if (agentId) {
+            try {
+                const res = await fetch(`${this.baseUrl}/api/identity/register`, {
+                    method: 'POST',
+                    headers: { 
+                        'Content-Type': 'application/json',
+                        ...(this.apiKey && { 'Authorization': `Bearer ${this.apiKey}` })
+                    },
+                    body: JSON.stringify({
+                        agentId,
+                        identityHash,
+                        components: components.length,
+                        includesHardware: includeHardware,
+                        includesCode: includeCode
+                    })
+                });
+                
+                if (res.ok) {
+                    const registration = await res.json();
+                    identity.registered = true;
+                    identity.registrationId = registration.registrationId;
+                } else {
+                    identity.registered = false;
+                    identity.registrationError = `API ${res.status}`;
+                }
+            } catch (e) {
+                identity.registered = false;
+                identity.registrationError = e.message;
+            }
+        }
+
+        // Anchor on Solana if requested
+        if (anchor && agentId) {
+            try {
+                const res = await fetch(`${this.baseUrl}/api/anchor/verification`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        agentId,
+                        attestationHash: identityHash
+                    })
+                });
+                
+                if (res.ok) {
+                    const anchorResult = await res.json();
+                    identity.anchored = true;
+                    identity.anchorSignature = anchorResult.signature;
+                    identity.anchorExplorer = anchorResult.explorer;
+                } else {
+                    identity.anchored = false;
+                }
+            } catch (e) {
+                identity.anchored = false;
+                identity.anchorError = e.message;
+            }
+        }
+
+        return identity;
+    }
+
+    /**
+     * Verify an agent's identity against their registered fingerprint
+     * @param {string} agentId - Agent ID to verify
+     * @returns {Promise<IdentityVerification>}
+     */
+    async verifyIdentity(agentId) {
+        // Generate current fingerprint
+        const currentIdentity = await this.generateIdentity({ agentId });
+
+        // Check against registered identity
+        try {
+            const res = await fetch(`${this.baseUrl}/api/identity/${encodeURIComponent(agentId)}`);
+            if (!res.ok) {
+                return {
+                    valid: false,
+                    agentId,
+                    reason: 'No registered identity found',
+                    currentHash: currentIdentity.hash
+                };
+            }
+
+            const registered = await res.json();
+            const matches = registered.identityHash === currentIdentity.hash;
+
+            return {
+                valid: matches,
+                agentId,
+                currentHash: currentIdentity.hash,
+                registeredHash: registered.identityHash,
+                match: matches,
+                registeredAt: registered.registeredAt,
+                reason: matches ? 'Identity confirmed' : 'Identity mismatch — different hardware or code'
+            };
+        } catch (e) {
+            return {
+                valid: false,
+                agentId,
+                reason: e.message,
+                currentHash: currentIdentity.hash
+            };
+        }
+    }
+
+    /**
+     * Check if two agents have the same hardware fingerprint (Sybil detection)
+     * @param {string} agentId1 - First agent
+     * @param {string} agentId2 - Second agent
+     * @returns {Promise<SybilCheck>}
+     */
+    async checkSybil(agentId1, agentId2) {
+        try {
+            const [id1, id2] = await Promise.all([
+                fetch(`${this.baseUrl}/api/identity/${encodeURIComponent(agentId1)}`).then(r => r.json()),
+                fetch(`${this.baseUrl}/api/identity/${encodeURIComponent(agentId2)}`).then(r => r.json())
+            ]);
+
+            const sameIdentity = id1.identityHash === id2.identityHash;
+
+            return {
+                agentId1,
+                agentId2,
+                sameIdentity,
+                sybilRisk: sameIdentity ? 'HIGH' : 'LOW',
+                reason: sameIdentity 
+                    ? 'Same hardware fingerprint — likely same operator' 
+                    : 'Different hardware fingerprints — likely different operators',
+                recommendation: sameIdentity 
+                    ? 'Do not seat at same table' 
+                    : 'Safe to interact'
+            };
+        } catch (e) {
+            return {
+                agentId1,
+                agentId2,
+                sameIdentity: null,
+                sybilRisk: 'UNKNOWN',
+                reason: `Could not compare: ${e.message}`
+            };
+        }
+    }
+
+    /**
+     * Check a list of agents for Sybil clusters (table seating check)
+     * @param {string[]} agentIds - List of agent IDs to check
+     * @returns {Promise<SybilTableCheck>}
+     */
+    async checkTableSybils(agentIds) {
+        // Fetch all identities
+        const identities = {};
+        for (const id of agentIds) {
+            try {
+                const res = await fetch(`${this.baseUrl}/api/identity/${encodeURIComponent(id)}`);
+                if (res.ok) {
+                    const data = await res.json();
+                    identities[id] = data.identityHash;
+                }
+            } catch {
+                // Skip agents without identity
+            }
+        }
+
+        // Find clusters (same identity hash)
+        const hashToAgents = {};
+        for (const [agentId, hash] of Object.entries(identities)) {
+            if (!hashToAgents[hash]) hashToAgents[hash] = [];
+            hashToAgents[hash].push(agentId);
+        }
+
+        const clusters = Object.values(hashToAgents).filter(group => group.length > 1);
+        const flagged = clusters.flat();
+
+        return {
+            totalAgents: agentIds.length,
+            identifiedAgents: Object.keys(identities).length,
+            unidentifiedAgents: agentIds.filter(id => !identities[id]),
+            sybilClusters: clusters,
+            flaggedAgents: flagged,
+            safe: clusters.length === 0,
+            recommendation: clusters.length === 0 
+                ? 'No Sybil clusters detected — safe to proceed'
+                : `${clusters.length} Sybil cluster(s) detected — ${flagged.length} agents share hardware`
+        };
+    }
 }
 
 // Scoring helpers