@ghostspeak/sdk 2.0.6 → 2.0.8

package/README.md

@@ -6,28 +6,41 @@
 [![Solana](https://img.shields.io/badge/Solana-v2.3.13-9945FF.svg)](https://solana.com)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-The official TypeScript SDK for [GhostSpeak Protocol](https://github.com/ghostspeak/ghostspeak) - a production-ready decentralized AI agent commerce protocol built on Solana. This SDK provides a comprehensive, type-safe interface for interacting with GhostSpeak smart contracts using modern Web3.js v2 patterns.
+The official TypeScript SDK for [GhostSpeak Protocol](https://github.com/ghostspeak/ghostspeak) - a decentralized **Verifiable Credentials (VC)**, **Reputation**, and **Identity Layer** for AI agents on Solana. Build trust in AI interactions with on-chain credentials, verifiable reputation scores, and tamper-proof identity management.
 
 ## 🌟 **Features**
 
-### **🤖 AI Agent Management**
-- **Registration & Identity** - Secure on-chain agent registration with verification
-- **Service Listings** - Monetize AI capabilities through the marketplace
-- **Reputation System** - Build trust through successful transactions
-- **Compressed NFT Creation** - 5000x cost reduction for agent assets
-
-### **💼 Commerce & Marketplace**
-- **Service Discovery** - Find and hire AI agents for any task
-- **Advanced Escrow** - Secure payments with milestone support and dispute resolution
-- **Dutch Auctions** - Time-based price decay for competitive bidding
-- **Work Order Management** - Complete project lifecycle with automated payments
-
-### **🔐 Advanced Features**
-- **x402 Payment Protocol** - HTTP 402 instant micropayments for agent services
-- **Token-2022 Integration** - Advanced token features with stablecoin support
-- **Multi-signature Wallets** - Enhanced security for organizations
-- **Governance Participation** - Vote on protocol improvements
-- **Real-time Analytics** - Monitor performance and generate insights
+### **🔐 Identity & Credentials**
+- **On-Chain Agent Identity** - Immutable agent registration on Solana
+- **Verifiable Credentials** - Issue W3C-compliant credentials for AI agents
+- **Credential Verification** - Cryptographically verify agent credentials
+- **Multi-Level Verification** - Basic, Verified, and Elite trust levels
+- **W3C DID Support** - Full Decentralized Identifier (DID) implementation 🆕
+- **Cross-Chain DIDs** - Export DIDs to W3C format for multi-chain verification 🆕
+
+### **⭐ Reputation System**
+- **Ghost Score** - Comprehensive reputation algorithm (0-1000)
+- **On-Chain Reputation** - Tamper-proof reputation tracking
+- **Multi-Factor Scoring** - Credentials, transactions, verification, staking
+- **Reputation Decay** - Time-based decay for inactive agents
+- **Granular Tags** - 80+ automatic tags with confidence scoring 🆕
+- **Multi-Source Aggregation** - Combine reputation from PayAI, GitHub, and custom sources 🆕
+- **Conflict Detection** - Automatic detection of conflicting reputation data 🆕
+
+### **🔐 Authorization System** 🆕
+- **Pre-Signed Authorizations** - Agents pre-authorize facilitators (e.g., PayAI) for reputation updates
+- **Off-Chain by Default** - FREE signature-based authorizations with no blockchain fees
+- **Optional On-Chain Storage** - Immutable audit trail for ~0.002 SOL (configurable)
+- **Flexible Fee Structures** - Default, custom, and tiered pricing models
+- **Usage Limits** - Built-in index limits and expiration for security
+- **Cost Estimation** - Calculate fees before transactions
+- **Facilitator Integration** - Seamless PayAI and X402 protocol support
+
+### **🎫 Credential Management**
+- **Issue Credentials** - Grant verifiable credentials to agents
+- **Revoke Credentials** - Remove invalid or expired credentials
+- **Credential Types** - KYC, service-specific, performance-based
+- **Batch Operations** - Issue multiple credentials efficiently
 
 ### **🛠️ Developer Experience**
 - **Full Type Safety** - 100% TypeScript with comprehensive types
@@ -76,18 +89,59 @@ import { generateKeyPairSigner } from '@solana/signers'
 // Create agent signer
 const agent = await generateKeyPairSigner()
 
-// Register agent on-chain
+// Register agent on-chain with identity
 const signature = await client.agents.register(agent, {
-  agentId: 1n,
   name: "My AI Assistant",
   description: "Specialized in data analysis and report generation",
   capabilities: ["data-analysis", "report-generation", "text-processing"],
-  serviceEndpoint: "https://my-agent.example.com/api"
+  serviceEndpoint: "https://my-agent.example.com/api",
+  metadata: {
+    version: "1.0.0",
+    model: "GPT-4",
+    provider: "OpenAI"
+  }
 })
 
 console.log(`Agent registered! Signature: ${signature}`)
 ```
 
+### **Issue a Verifiable Credential**
+```typescript
+// Issue a credential to an agent
+const credentialSignature = await client.credentials.issueCredential(issuer, {
+  agentAddress: agent.address,
+  credentialType: "KYC_VERIFIED",
+  issuer: issuer.address,
+  issuanceDate: Date.now(),
+  expirationDate: Date.now() + (365 * 24 * 60 * 60 * 1000), // 1 year
+  metadata: {
+    verificationType: "identity",
+    verificationLevel: "advanced"
+  }
+})
+
+console.log(`Credential issued! Signature: ${credentialSignature}`)
+```
+
+### **Calculate Ghost Score (Reputation)**
+```typescript
+// Get comprehensive reputation score
+const reputation = await client.reputation.getAgentReputation(agent.address)
+
+console.log(`Ghost Score: ${reputation.ghostScore}/1000`)
+console.log(`Breakdown:`)
+console.log(`- Credentials: ${reputation.components.credentialScore}`)
+console.log(`- Transactions: ${reputation.components.transactionScore}`)
+console.log(`- Verification: ${reputation.components.verificationScore}`)
+console.log(`- Staking: ${reputation.components.stakingScore}`)
+
+// Get automatic reputation tags
+const metrics = await client.reputation.convertMetricsForTagging(onChainMetrics)
+const tags = await client.reputation.calculateTagsForAgent(metrics)
+
+console.log(`Tags: ${tags.map(t => t.tagName).join(', ')}`)
+```
+
 ### **Create a Service Listing**
 ```typescript
 // List your agent's services
@@ -128,21 +182,30 @@ await client.escrow.completeMilestone(agent, escrowSignature, 0)
 
 ## 📚 **Core SDK Components**
 
-### **1. Agent Management**
+### **1. Agent Management & DIDs**
 ```typescript
 // Register new agent
 await client.agents.register(signer, params)
 
-// Update agent information  
+// Create DID for agent (W3C-compliant)
+await client.did.create(signer, {
+  controller: signer.address,
+  network: 'devnet'
+})
+
+// Export DID to W3C format for cross-chain use
+const w3cDid = await client.did.exportW3C(signer.address)
+
+// Update agent information
 await client.agents.update(signer, agentPda, updateParams)
 
 // Get agent details
 const agent = await client.agents.getAgent(agentAddress)
 
 // List all agents with filtering
-const agents = await client.agents.listAgents({ 
+const agents = await client.agents.listAgents({
   verificationStatus: 'verified',
-  category: 'ai-assistant' 
+  category: 'ai-assistant'
 })
 ```
 
@@ -262,12 +325,204 @@ await client.token2022.confidentialTransfer(sender, {
 })
 ```
 
-### **8. Analytics & Monitoring**
+### **8. Authorization System (PayAI Integration)** 🆕
+
+Pre-authorize facilitators to update your agent's reputation with built-in security limits.
+
+```typescript
+// Create off-chain authorization (FREE)
+const authorization = await client.authorization.createAuthorization({
+  authorizedSource: payAIFacilitatorAddress,
+  indexLimit: 1000, // Allow 1000 reputation updates
+  expiresIn: 30 * 24 * 60 * 60, // 30 days
+  network: 'mainnet-beta'
+}, agentKeypair)
+
+// Share with facilitator webhook
+await fetch('https://payai.example.com/register-agent', {
+  method: 'POST',
+  body: JSON.stringify({
+    agentAddress: authorization.agentAddress,
+    authorization: client.authorization.serializeAuthorization(authorization)
+  })
+})
+
+// Estimate on-chain storage cost (optional)
+const cost = await client.authorization.estimateStorageCost({
+  authorizedSource: payAIFacilitatorAddress,
+  expiresIn: 30 * 24 * 60 * 60
+})
+console.log(`On-chain storage: ${cost} SOL`) // 0.002 SOL
+
+// Store on-chain for audit trail (optional, ~0.002 SOL)
+const signature = await client.authorization.storeAuthorizationOnChain(
+  authorization,
+  agentSigner,
+  {
+    storageFee: 1500000n, // Custom: 0.0015 SOL
+    feePayedByAgent: true
+  }
+)
+
+// Verify authorization signature
+const isValid = await client.authorization.verifySignature(authorization)
+
+// Check authorization status
+const status = client.authorization.getAuthorizationStatus(authorization, 0)
+console.log(`Remaining uses: ${status.remainingUses}/${authorization.indexLimit}`)
+```
+
+**See:** [Authorization Storage Guide](./docs/AUTHORIZATION_STORAGE.md) for complete documentation.
+
+### **9. External ID Resolution (REST API)** 🆕
+
+Resolve cross-platform identities to Ghost addresses using the GhostSpeak Public API. Faster than on-chain lookups for read operations.
+
+```typescript
+import { ExternalIdResolver } from '@ghostspeak/sdk'
+
+// Initialize resolver for devnet
+const resolver = new ExternalIdResolver({
+  cluster: 'devnet' // Uses https://api-devnet.ghostspeak.ai
+})
+
+// Production mainnet
+const mainnetResolver = new ExternalIdResolver({
+  cluster: 'mainnet-beta' // Uses https://api.ghostspeak.ai
+})
+
+// Custom API URL
+const customResolver = new ExternalIdResolver({
+  apiUrl: 'https://custom-api.example.com'
+})
+```
+
+#### **Resolve External IDs to Ghost Addresses**
+
+```typescript
+// Quick resolve - returns Ghost address
+const ghostAddress = await resolver.resolve('payai', 'agent-123')
+console.log(`Ghost Address: ${ghostAddress}`)
+
+// Full lookup - returns mapping + Ghost data
+const result = await resolver.lookup('payai', 'agent-123')
+console.log(`Platform: ${result.mapping.platform}`)
+console.log(`External ID: ${result.mapping.externalId}`)
+console.log(`Ghost Address: ${result.mapping.ghostAddress}`)
+console.log(`Verified: ${result.mapping.verified}`)
+
+if (result.ghost) {
+  console.log(`Name: ${result.ghost.name}`)
+  console.log(`Ghost Score: ${result.ghost.ghostScore}`)
+  console.log(`Status: ${result.ghost.status}`)
+}
+```
+
+#### **Fetch Ghost Data via API**
+
+```typescript
+// Get full Ghost profile (faster than on-chain query)
+const ghost = await resolver.getGhost(ghostAddress)
+console.log(`Agent: ${ghost.name}`)
+console.log(`Owner: ${ghost.owner}`)
+console.log(`Reputation: ${ghost.reputationScore}`)
+console.log(`External IDs:`, ghost.externalIdentifiers)
+
+// Get Ghost Score breakdown
+const score = await resolver.getGhostScore(ghostAddress)
+console.log(`Score: ${score.score}/${score.maxScore}`)
+score.components.forEach(c => {
+  console.log(`- ${c.source}: ${c.score} (weight: ${c.weight})`)
+})
+
+// Get detailed reputation data
+const reputation = await resolver.getGhostReputation(ghostAddress)
+console.log('Reputation breakdown:', reputation)
+```
+
+#### **Batch Operations**
+
+```typescript
+// Resolve multiple external IDs in parallel
+const identifiers = [
+  { platform: 'payai', externalId: 'agent-1' },
+  { platform: 'elizaos', externalId: 'eliza-bot' },
+  { platform: 'github', externalId: 'ai-assistant-007' }
+]
+
+const addresses = await resolver.resolveBatch(identifiers)
+addresses.forEach((addr, i) => {
+  if (addr) {
+    console.log(`${identifiers[i].platform}:${identifiers[i].externalId} → ${addr}`)
+  } else {
+    console.log(`${identifiers[i].platform}:${identifiers[i].externalId} → Not found`)
+  }
+})
+```
+
+#### **Check Existence & List External IDs**
+
+```typescript
+// Check if external ID exists
+const exists = await resolver.exists('payai', 'agent-123')
+console.log(`Exists: ${exists}`)
+
+// Get all external IDs for a Ghost
+const externalIds = await resolver.getExternalIds(ghostAddress)
+externalIds.forEach(id => {
+  console.log(`${id.platform}:${id.externalId} (verified: ${id.verified})`)
+})
+```
+
+#### **API Health Check**
+
+```typescript
+// Check API availability and network status
+const health = await resolver.checkHealth()
+console.log(`Status: ${health.status}`)
+console.log(`Network: ${health.network}`)
+console.log(`RPC Connected: ${health.rpc.connected}`)
+console.log(`RPC Latency: ${health.rpc.latency}ms`)
+```
+
+#### **Error Handling**
+
+```typescript
+import {
+  ExternalIdNotFoundError,
+  GhostNotFoundError,
+  GhostSpeakError
+} from '@ghostspeak/sdk'
+
+try {
+  const address = await resolver.resolve('payai', 'non-existent')
+} catch (error) {
+  if (error instanceof ExternalIdNotFoundError) {
+    console.error(`No Ghost found for ${error.platform}:${error.externalId}`)
+  } else if (error instanceof GhostNotFoundError) {
+    console.error(`Ghost not found: ${error.message}`)
+  } else if (error instanceof GhostSpeakError) {
+    console.error(`API Error [${error.code}]: ${error.message}`)
+  }
+}
+```
+
+#### **Supported Platforms**
+
+- `payai` - PayAI Network agents
+- `elizaos` - ElizaOS framework agents
+- `github` - GitHub-verified agents
+- `twitter` - Twitter/X-verified agents
+- Custom platforms (defined by facilitators)
+
+**Performance:** API lookups are **10-50x faster** than on-chain queries, ideal for real-time integrations.
+
+### **10. Analytics & Monitoring**
 ```typescript
 // Collect real-time analytics
 const analytics = await client.analytics.collectAllMetrics()
 
-// Generate performance reports  
+// Generate performance reports
 const report = await client.analytics.generateReport({
   agentId: agentAddress,
   timeRange: { start: startDate, end: endDate },
@@ -278,7 +533,7 @@ const report = await client.analytics.generateReport({
 const exportData = await client.analytics.exportForDashboard('grafana')
 ```
 
-### **9. Privacy Features (Production)**
+### **11. Privacy Features (Production)**
 
 > 🔒 **Privacy**: Client-side ElGamal encryption is the standard for confidential transfers in GhostSpeak. It provides robust privacy verification via the x402 payment layer.
 
@@ -525,7 +780,10 @@ const client = new GhostSpeakClient({
 ### **Core Classes**
 - **`GhostSpeakClient`** - Main SDK client
 - **`AgentInstructions`** - Agent management operations
-- **`MarketplaceInstructions`** - Marketplace operations  
+- **`DidModule`** - W3C DID document management 🆕
+- **`ReputationModule`** - Reputation calculation and tag management 🆕
+- **`AuthorizationModule`** - Pre-signed authorizations for facilitators 🆕
+- **`MarketplaceInstructions`** - Marketplace operations
 - **`EscrowInstructions`** - Escrow and payment operations
 - **`GovernanceInstructions`** - Governance and multisig operations
 - **`Token2022Instructions`** - Token-2022 operations
@@ -536,6 +794,13 @@ The SDK exports comprehensive TypeScript types for all operations:
 ```typescript
 import type {
   Agent,
+  DidDocument,
+  VerificationMethod,
+  ServiceEndpoint,
+  TagScore,
+  ReputationMetrics,
+  ReputationAuthorization,
+  OnChainStorageConfig,
   ServiceListing,
   EscrowAccount,
   GovernanceProposal,