@moltlaunch/sdk 2.0.0 → 2.1.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.1.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,238 @@ 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;
+    }
 }
 
 // Scoring helpers