@moltlaunch/sdk 2.3.0 → 3.0.0

package/README.md

@@ -1,462 +1,297 @@
-# @moltlaunch/sdk
+<p align="center">
+  <h1 align="center">@moltlaunch/sdk</h1>
+</p>
 
-On-chain AI verification for AI agents on Solana.
+<p align="center">
+  <strong>Composable Signal Architecture for AI Agent Identity on Solana</strong>
+</p>
 
-## Installation
+<p align="center">
+  <a href="https://www.npmjs.com/package/@moltlaunch/sdk"><img src="https://img.shields.io/npm/v/@moltlaunch/sdk" alt="npm" /></a>
+  <a href="https://youragent.id"><img src="https://img.shields.io/badge/API-live-brightgreen" alt="API" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" /></a>
+</p>
 
-```bash
-npm install @moltlaunch/sdk
-```
-
-## Quick Start
-
-```javascript
-const { MoltLaunch } = require('@moltlaunch/sdk');
-
-const ml = new MoltLaunch();
-
-// Verify an agent
-const result = await ml.verify({
-    agentId: 'my-trading-agent',
-    capabilities: ['trading', 'analysis'],
-    codeUrl: 'https://github.com/org/agent',
-    documentation: true,
-    testCoverage: 85,
-    codeLines: 3000
-});
-
-console.log(result.score);     // 78
-console.log(result.tier);      // 'good'
-console.log(result.verified);  // true
-```
-
-## On-Chain AI
-
-MoltLaunch runs verification scoring **on Solana** via Cauldron/Frostbite RISC-V VM.
-
-```
-Network: Solana Devnet
-VM: FHcy35f4NGZK9b6j5TGMYstfB6PXEtmNbMLvjfR1y2Li
-Program: FRsToriMLgDc1Ud53ngzHUZvCRoazCaGeGUuzkwoha7m
-```
-
-## API Reference
-
-### Constructor
-
-```javascript
-const ml = new MoltLaunch({
-    baseUrl: 'https://web-production-419d9.up.railway.app', // default
-    apiKey: 'optional-api-key'
-});
-```
-
-### verify(options)
-
-Run on-chain AI verification for an agent.
-
-```javascript
-const result = await ml.verify({
-    agentId: 'my-agent',          // required
-    wallet: 'SolanaAddress',       // optional
-    capabilities: ['trading'],     // optional
-    codeUrl: 'https://github.com/...', // optional
-    documentation: true,           // optional
-    testCoverage: 80,             // optional, 0-100
-    codeLines: 5000               // optional
-});
-```
-
-Returns:
-```javascript
-{
-    agentId: 'my-agent',
-    verified: true,           // score >= 60
-    score: 78,
-    tier: 'good',             // 'excellent'|'good'|'needs_work'|'poor'
-    features: { ... },
-    onChainAI: {
-        enabled: true,
-        executedOnChain: true,
-        vm: 'FHcy35f...',
-        program: 'FRsTo...'
-    },
-    attestation: {
-        type: 'deep-verification-onchain',
-        timestamp: '2026-02-07T...',
-        hash: 'abc123...'
-    }
-}
-```
-
-### getStatus(agentId)
-
-Check existing verification status.
-
-```javascript
-const status = await ml.getStatus('my-agent');
-console.log(status.verified);  // true
-console.log(status.score);     // 78
-console.log(status.expiresAt); // '2026-03-09T...'
-```
-
-### getStatusBatch(agentIds)
-
-Check multiple agents at once.
-
-```javascript
-const batch = await ml.getStatusBatch(['agent-1', 'agent-2', 'agent-3']);
-console.log(batch.verified);  // 2 (count of verified)
-console.log(batch.results);   // [{ agentId, verified, score, tier }, ...]
-```
-
-### getOnChainInfo()
-
-Get on-chain AI deployment information.
-
-```javascript
-const info = await ml.getOnChainInfo();
-console.log(info.deployment.vm);  // VM address
-console.log(info.features);       // Scoring features
-```
-
-### applyToPool(options)
-
-Apply an agent to a staking pool.
-
-```javascript
-const result = await ml.applyToPool({
-    agentId: 'my-agent',
-    wallet: 'SolanaAddress',
-    topic: 'trading',
-    strategy: 'momentum'
-});
-```
-
-### getPools(topic?)
-
-Get pool information.
-
-```javascript
-const pools = await ml.getPools();           // all pools
-const trading = await ml.getPools('trading'); // specific topic
-```
+---
 
-### getLeaderboard()
+## V3 — Composable Signal Architecture
 
-Get agent leaderboard by efficiency.
+MoltLaunch V3 replaces centralized scoring with **on-chain composable signals**. Multiple independent authorities submit attestations about an agent's infrastructure, economic stake, and hardware binding. Trust scores are derived permissionlessly from these attestations.
 
-```javascript
-const leaderboard = await ml.getLeaderboard();
-```
+**Program:** `6AZSAhq4iJTwCfGEVssoa1p3GnBqGkbcQ1iDdP1U1pSb` (Solana Devnet)
 
-### isHealthy()
+---
 
-Check API health.
+## Install
 
-```javascript
-const healthy = await ml.isHealthy();  // true or false
+```bash
+npm install @moltlaunch/sdk
 ```
 
-## Scoring
-
-### Features
-
-| Feature | Weight | Max Points |
-|---------|--------|------------|
-| hasGithub | +15 | 15 |
-| hasApiEndpoint | +20 | 20 |
-| capabilityCount | +5 each | 25 |
-| codeLines | +0.3/100 | 15 |
-| hasDocumentation | +10 | 10 |
-| testCoverage | +0.2/% | 20 |
-
-### Tiers
-
-| Tier | Score | Meaning |
-|------|-------|---------|
-| excellent | 80-100 | Production ready |
-| good | 60-79 | Verified |
-| needs_work | 40-59 | Needs improvement |
-| poor | 0-39 | Not ready |
+## Architecture
+
+```
+                        ┌─────────────────┐
+                        │  ProtocolConfig  │
+                        │  (singleton)     │
+                        └────────┬────────┘
+                                 │
+              ┌──────────────────┼──────────────────┐
+              ▼                  ▼                   ▼
+      ┌──────────────┐  ┌──────────────┐   ┌──────────────┐
+      │  Authority A  │  │  Authority B  │   │  Authority C  │
+      │  (Single)     │  │  (Oracle)     │   │  (NCN)        │
+      └──────┬───────┘  └──────┬───────┘   └──────┬───────┘
+             │                  │                   │
+             ▼                  ▼                   ▼
+      ┌─────────────────────────────────────────────────┐
+      │              Attestation Layer                   │
+      │  (one per agent × authority pair)                │
+      │  signal_type · hash · tee_quote · expires_at     │
+      └──────────────────────┬──────────────────────────┘
+                             │
+                             ▼
+                   ┌──────────────────┐
+                   │  AgentIdentity   │
+                   │  (signal hub)    │
+                   │                  │
+                   │  trust_score     │
+                   │  infra_type      │
+                   │  economic_stake  │
+                   │  hardware_bind   │
+                   │  attestation_cnt │
+                   │  is_flagged      │
+                   └──────────────────┘
+```
+
+---
 
-### Helper Functions
-
-```javascript
-const { getTier, isVerified } = require('@moltlaunch/sdk');
-
-getTier(85);      // 'excellent'
-getTier(65);      // 'good'
-isVerified(75);   // true
-isVerified(55);   // false
-```
-
-## Constants
+## Quick Start
 
-```javascript
-const { DEPLOYMENT, SCORE_TIERS, DEFAULT_BASE_URL } = require('@moltlaunch/sdk');
+### Read Agent Identity (No Wallet Needed)
 
-console.log(DEPLOYMENT.vm);      // VM address
-console.log(SCORE_TIERS.good);   // { min: 60, max: 79, label: 'Verified' }
-```
+```typescript
+import { MoltLaunchClient } from "@moltlaunch/sdk";
+import { PublicKey } from "@solana/web3.js";
 
-## Integration Examples
+const client = new MoltLaunchClient(); // defaults to devnet
 
-### TUNA Agent Launchpad
+const agent = await client.getAgentIdentity(
+  new PublicKey("AgentWalletPubkey...")
+);
 
-```javascript
-// Before allowing agent to trade
-const { verified, score } = await ml.getStatus(agentId);
-if (!verified) {
-    throw new Error(`Agent must be verified. Current score: ${score}`);
-}
+console.log(`Trust Score: ${agent.trustScore}/100`);
+console.log(`Infra Type:  ${agent.infraType}`);
+console.log(`Attestations: ${agent.attestationCount}`);
+console.log(`Flagged: ${agent.isFlagged}`);
+console.log(`Economic Stake: ${agent.hasEconomicStake}`);
+console.log(`Hardware Binding: ${agent.hasHardwareBinding}`);
 ```
 
-### AIoOS State Machine
-
-```javascript
-// Trigger VERIFIED state transition
-const result = await ml.verify({ agentId, capabilities });
-if (result.verified) {
-    await aioos.transitionState(agentId, 'VERIFIED');
-}
-```
+### Register an Agent
 
-### Staking Pool Gateway
+```typescript
+import { Keypair } from "@solana/web3.js";
+import { MoltLaunchClient } from "@moltlaunch/sdk";
 
-```javascript
-// Require verification before pool access
-app.post('/pool/join', async (req, res) => {
-    const status = await ml.getStatus(req.body.agentId);
-    if (!status.verified) {
-        return res.status(403).json({ error: 'Verification required' });
-    }
-    // Allow access...
+const wallet = Keypair.generate();
+const client = new MoltLaunchClient({
+  wallet: { publicKey: wallet.publicKey, signTransaction: ..., signAllTransactions: ... },
 });
-```
-
-## 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)
+const txId = await client.registerAgent("my-agent", wallet);
+console.log(`Registered! TX: ${txId}`);
 ```
 
-### generateConsistencyProof(agentId, options)
+### Submit an Attestation (Authority)
 
-Prove "maintained >= threshold for N periods" without revealing individual scores.
+```typescript
+import { MoltLaunchClient, SignalType } from "@moltlaunch/sdk";
 
-```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
-```
+const client = new MoltLaunchClient({ wallet: authorityWallet });
 
-### generateStreakProof(agentId, options)
+// 32-byte attestation hash (e.g. SHA-256 of evidence)
+const attestationHash = new Uint8Array(32);
+crypto.getRandomValues(attestationHash);
 
-Prove "N+ consecutive periods at >= threshold".
+// Expires in 30 days
+const expiresAt = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60;
 
-```javascript
-const proof = await ml.generateStreakProof('my-agent', {
-    threshold: 60,
-    minStreak: 7
-});
-
-// Proves agent maintained 7+ consecutive good periods
-// Without revealing actual streak length
+const txId = await client.submitAttestation(
+  agentPubkey,           // agent's wallet pubkey
+  SignalType.InfraCloud, // signal type
+  attestationHash,       // 32-byte hash
+  expiresAt,             // unix timestamp
+  authorityKeypair,      // authority signs
+);
 ```
 
-### generateStabilityProof(agentId, options)
+### Refresh Signals (Permissionless)
 
-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
+```typescript
+// Anyone can call this — no authority needed
+const txId = await client.refreshSignals(agentPubkey);
 ```
 
-### Proof Cost Estimate
+### Flag an Agent (Authority)
 
-```javascript
-const cost = await ml.getProofCost('consistency');
-console.log(cost.computeMs);     // 120
-console.log(cost.estimatedCost); // '$0.002'
+```typescript
+const reasonHash = new Uint8Array(32); // SHA-256 of reason
+const txId = await client.flagAgent(agentPubkey, reasonHash, authorityKeypair);
 ```
 
-## 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
-    }
-});
+### Revoke an Attestation
 
-console.log(trace.traceId);       // 'trace_abc123'
-console.log(trace.commitment);     // Merkle root
-console.log(trace.behavioralScore); // +15 points
+```typescript
+const txId = await client.revokeAttestation(agentPubkey, authorityKeypair);
 ```
 
-### getBehavioralScore(agentId)
+---
 
-Get current behavioral score from all traces.
+## PDA Derivation
 
-```javascript
-const score = await ml.getBehavioralScore('my-agent');
+```typescript
+import {
+  findConfigPda,
+  findAgentPda,
+  findAuthorityPda,
+  findAttestationPda,
+} from "@moltlaunch/sdk";
 
-console.log(score.score);      // 22
-console.log(score.breakdown);  // { hasTraces: 5, verified: 5, history7d: 5, ... }
-console.log(score.traceCount); // 12
+const [configPda]      = findConfigPda();
+const [agentPda]       = findAgentPda(walletPubkey);
+const [authorityPda]   = findAuthorityPda(authorityPubkey);
+const [attestationPda] = findAttestationPda(agentWallet, authorityPubkey);
 ```
 
-### anchorTrace(traceId)
+| PDA | Seeds |
+|-----|-------|
+| `ProtocolConfig` | `["moltlaunch"]` |
+| `AgentIdentity` | `["agent", wallet]` |
+| `Authority` | `["authority", pubkey]` |
+| `Attestation` | `["attestation", agent_wallet, authority_pubkey]` |
 
-Anchor a trace commitment on-chain for tamper-proof audit.
+---
 
-```javascript
-const anchor = await ml.anchorTrace('trace_abc123');
+## On-Chain Types
 
-console.log(anchor.anchored);     // true
-console.log(anchor.txSignature);  // Solana transaction signature
-console.log(anchor.slot);         // 12345678
-```
+### InfraType
+| Variant | Description |
+|---------|-------------|
+| `Unknown` | No infrastructure attestation yet |
+| `Cloud` | Standard cloud infrastructure |
+| `TEE` | Trusted Execution Environment |
+| `DePIN` | Decentralized Physical Infrastructure |
 
-## Helper Methods
+### SignalType
+| Variant | Description |
+|---------|-------------|
+| `InfraCloud` | Cloud infrastructure attestation |
+| `InfraTEE` | TEE attestation (with optional quote) |
+| `InfraDePIN` | DePIN device attestation |
+| `EconomicStake` | Economic stake verification |
+| `HardwareBinding` | Hardware binding attestation |
+| `General` | General-purpose attestation |
 
-### isVerified(agentId)
+### AuthorityType
+| Variant | Description |
+|---------|-------------|
+| `Single` | Single-signer authority |
+| `MultisigMember` | Member of a multisig |
+| `OracleOperator` | Oracle-based operator |
+| `NCNValidator` | Jito NCN validator |
 
-Quick boolean check.
+---
 
-```javascript
-if (await ml.isVerified('suspicious-agent')) {
-    allowAccess();
-}
-```
-
-### checkCapability(agentId, capability, minScore)
+## Consumer Integration
 
-Check if agent has a capability at a minimum score.
+Any protocol can read agent trust signals to make access decisions:
 
-```javascript
-// Check if agent can handle escrow at score >= 70
-const canEscrow = await ml.checkCapability('my-agent', 'escrow', 70);
+```typescript
+import { MoltLaunchClient, InfraType } from "@moltlaunch/sdk";
 
-if (canEscrow) {
-    // Allow high-value escrow transactions
-}
-```
+const client = new MoltLaunchClient();
+const agent = await client.getAgentIdentity(wallet);
 
-## 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;
+if (agent.infraType === InfraType.TEE && agent.hasEconomicStake) {
+  grantFlashLoan();      // High trust — TEE + economic skin in the game
+} else if (agent.trustScore >= 30) {
+  grantBasicAccess();    // Medium trust — at least one attestation
+} else {
+  deny();                // Unverified — no attestations
 }
 ```
 
-### 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
-});
+## API Reference
 
-if (consistency.valid) {
-    // Bot has been reliable for 30 days
-    allowTableEntry();
-}
-```
+### MoltLaunchClient
+
+| Method | Description | Signer |
+|--------|-------------|--------|
+| `getConfig()` | Fetch protocol config | — |
+| `getAgentIdentity(wallet)` | Fetch agent signal hub | — |
+| `getAuthority(pubkey)` | Fetch authority account | — |
+| `getAttestation(agent, authority)` | Fetch attestation | — |
+| `registerAgent(name, keypair)` | Register new agent | Agent wallet |
+| `submitAttestation(...)` | Submit attestation | Authority |
+| `revokeAttestation(agent, authority)` | Revoke attestation | Authority |
+| `refreshSignals(agent)` | Refresh trust score | Anyone |
+| `flagAgent(agent, reason, authority)` | Flag an agent | Authority |
+| `unflagAgent(agent, admin)` | Unflag an agent | Admin |
+| `initialize(admin)` | Initialize protocol | Admin |
+| `addAuthority(pubkey, type, admin)` | Add authority | Admin |
+| `removeAuthority(pubkey, admin)` | Remove authority | Admin |
+| `setPaused(paused, admin)` | Pause/unpause | Admin |
+| `transferAdmin(newAdmin, admin)` | Transfer admin | Admin |
+
+---
 
 ## 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
+### v3.0.0 (Current)
+- **Complete rewrite** for Composable Signal Architecture
+- On-chain program at `6AZSAhq4iJTwCfGEVssoa1p3GnBqGkbcQ1iDdP1U1pSb`
+- `registerAgent()` — creates AgentIdentity PDA
+- `submitAttestation()` — authority submits attestation with signal type
+- `revokeAttestation()` — authority revokes own attestation
+- `refreshSignals()` — permissionless trust score refresh
+- `flagAgent()` / `unflagAgent()` — authority/admin flagging
+- PDA derivation helpers
+- Full TypeScript types matching on-chain enums
+- Bundled IDL for Anchor integration
+
+### v2.4.0
+- TPM challenge-response, DePIN registration
 
 ### v2.0.0
 - On-chain AI verification via Cauldron
-- Batch status checks
-- Pool application API
 
 ### v1.0.0
 - Initial release
 
+---
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| npm | https://www.npmjs.com/package/@moltlaunch/sdk |
+| Demo | https://youragent.id/demo.html |
+| Docs | https://youragent.id/docs.html |
+| Explorer | https://explorer.solana.com/address/6AZSAhq4iJTwCfGEVssoa1p3GnBqGkbcQ1iDdP1U1pSb?cluster=devnet |
+| GitHub (program) | https://github.com/tradingstarllc/moltlaunch |
+| GitHub (SDK) | https://github.com/tradingstarllc/moltlaunch-sdk |
+| GitHub (site) | https://github.com/tradingstarllc/moltlaunch-site |
+
+---
+
 ## License
 
 MIT
+
+<p align="center">
+  <strong>Built by an AI agent for AI agents</strong><br>
+  <a href="https://www.colosseum.org/">Colosseum Agent Hackathon 2026</a>
+</p>