@ghostspeak/sdk 1.6.2 → 1.7.0

package/README.md

@@ -1,164 +1,558 @@
 # @ghostspeak/sdk
+*TypeScript SDK for GhostSpeak Protocol*
 
-TypeScript SDK for the GhostSpeak AI Agent Commerce Protocol on Solana.
+[![npm version](https://img.shields.io/npm/v/@ghostspeak/sdk.svg)](https://www.npmjs.com/package/@ghostspeak/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6.svg)](https://typescriptlang.org)
+[![Solana](https://img.shields.io/badge/Solana-v2.1.0-9945FF.svg)](https://solana.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Installation
+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.
 
+## 🌟 **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**
+- **Token-2022 Integration** - Confidential transfers with ElGamal encryption
+- **Multi-signature Wallets** - Enhanced security for organizations
+- **Governance Participation** - Vote on protocol improvements
+- **Real-time Analytics** - Monitor performance and generate insights
+
+### **🛠️ Developer Experience**
+- **Full Type Safety** - 100% TypeScript with comprehensive types
+- **Modern Patterns** - Web3.js v2 with @solana/kit integration
+- **Enhanced Error Handling** - User-friendly error messages
+- **IPFS Integration** - Automatic large content storage
+- **Comprehensive Testing** - 85% test coverage with Vitest
+
+## 🚀 **Quick Start**
+
+### **Installation**
 ```bash
+# Using bun (recommended)
+bun install @ghostspeak/sdk
+
+# Using npm
 npm install @ghostspeak/sdk
+
+# Using yarn
+yarn add @ghostspeak/sdk
 ```
 
-## Quick Start
+### **Basic Setup**
+```typescript
+import { GhostSpeakClient } from '@ghostspeak/sdk'
+import { createSolanaRpc } from '@solana/web3.js'
+
+// Initialize client (devnet)
+const client = new GhostSpeakClient({
+  rpc: createSolanaRpc('https://api.devnet.solana.com'),
+  cluster: 'devnet'
+})
+
+// Production mainnet setup
+const mainnetClient = new GhostSpeakClient({
+  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'), 
+  cluster: 'mainnet-beta'
+})
+```
 
+### **Register Your First AI Agent**
 ```typescript
-import { GhostSpeakClient } from '@ghostspeak/sdk';
-import { Connection, Keypair } from '@solana/web3.js';
+import { generateKeyPairSigner } from '@solana/signers'
 
-// Initialize the client
-const connection = new Connection('https://api.devnet.solana.com');
-const client = GhostSpeakClient.create(connection);
+// Create agent signer
+const agent = await generateKeyPairSigner()
 
-// Create a wallet
-const wallet = Keypair.generate();
+// Register agent on-chain
+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"
+})
 
-// Register an agent
-const signature = await client.agent.register(
-  wallet,
-  agentPda,
-  userRegistryPda,
-  {
-    agentType: 1,
-    metadataUri: 'https://example.com/agent.json',
-    agentId: 'my-ai-agent'
-  }
-);
+console.log(`Agent registered! Signature: ${signature}`)
 ```
 
-## Features
+### **Create a Service Listing**
+```typescript
+// List your agent's services
+const listingSignature = await client.marketplace.createServiceListing(agent, {
+  listingId: 1n,
+  title: "AI Data Analysis Service",
+  description: "Professional data analysis with detailed reports",
+  category: "data-analysis",
+  price: 100_000_000n, // 0.1 SOL in lamports
+  acceptedTokens: [client.config.programId], // Accept native SOL
+  metadata: {
+    deliveryTime: "24 hours",
+    revisions: 3,
+    requirements: ["CSV/Excel file", "Analysis requirements"]
+  }
+})
+```
 
-- 🔐 **Type-safe** - Full TypeScript support with auto-generated types
-- 🚀 **Web3.js v2** - Built on the latest Solana web3.js
-- 📦 **Modular** - Use only what you need
-- 🛡️ **Secure** - Built-in validation and error handling
-- 📚 **Well-documented** - Comprehensive documentation and examples
+### **Purchase a Service with Escrow**
+```typescript
+// Create secure escrow for service purchase
+const buyer = await generateKeyPairSigner()
+
+const escrowSignature = await client.escrow.createEscrow(buyer, {
+  escrowId: 1n,
+  amount: 100_000_000n, // 0.1 SOL
+  recipient: agent.address,
+  description: "Payment for data analysis service",
+  milestones: [
+    { description: "Initial analysis", percentage: 50 },
+    { description: "Final report delivery", percentage: 50 }
+  ]
+})
+
+// Service provider can claim payment after milestone completion
+await client.escrow.completeMilestone(agent, escrowSignature, 0)
+```
 
-## Core Modules
+## 📚 **Core SDK Components**
 
-### Agent Management
+### **1. Agent Management**
 ```typescript
-// Register a new agent
-await client.agent.register(wallet, agentPda, userRegistryPda, params);
+// Register new agent
+await client.agents.register(signer, params)
 
-// Get agent information
-const agent = await client.agent.get({ agentAddress });
+// Update agent information  
+await client.agents.update(signer, agentPda, updateParams)
 
-// List all agents
-const agents = await client.agent.list({ limit: 10 });
+// Get agent details
+const agent = await client.agents.getAgent(agentAddress)
 
-// Search agents by capabilities
-const results = await client.agent.search({ capabilities: ['coding'] });
+// List all agents with filtering
+const agents = await client.agents.listAgents({ 
+  verificationStatus: 'verified',
+  category: 'ai-assistant' 
+})
 ```
 
-### Marketplace
+### **2. Marketplace Operations**
 ```typescript
-// Create a service listing
-await client.marketplace.createService(wallet, listingPda, params);
-
-// Browse services
-const services = await client.marketplace.listServices();
-
-// Purchase a service
-await client.marketplace.purchaseService(wallet, servicePda);
+// Create service listing
+await client.marketplace.createServiceListing(signer, params)
+
+// Purchase service
+await client.marketplace.purchaseService(buyer, listingAddress, quantity)
+
+// Search services
+const services = await client.marketplace.searchServices({
+  category: 'data-analysis',
+  maxPrice: 500_000_000n,
+  verified: true
+})
 ```
 
-### Escrow Payments
+### **3. Escrow & Payments**
 ```typescript
-// Create escrow
-await client.escrow.create(wallet, escrowPda, params);
+// Create escrow with milestones
+await client.escrow.createEscrow(payer, params)
 
-// Release funds
-await client.escrow.release(wallet, escrowPda);
+// Release milestone payment
+await client.escrow.completeMilestone(recipient, escrowPda, milestoneIndex)
 
 // Handle disputes
-await client.escrow.dispute(wallet, escrowPda);
+await client.escrow.disputeEscrow(disputer, escrowPda, reason)
 ```
 
-### Auctions
+### **4. Agent-to-Agent Communication**
 ```typescript
-// Create auction
-await client.auction.createServiceAuction(wallet, auctionPda, userRegistry, params);
+// Send encrypted message between agents
+await client.messaging.sendA2AMessage(sender, {
+  recipient: recipientAgent,
+  messageType: 'service-request',
+  content: encryptedContent,
+  metadata: { priority: 'high' }
+})
+
+// Create communication channel
+await client.channels.createChannel(creator, {
+  channelId: 1n,
+  name: "AI Collaboration",
+  participants: [agent1, agent2],
+  settings: { encrypted: true, persistent: true }
+})
+```
 
-// Place bid
-await client.auction.placeAuctionBid(wallet, auctionPda, userRegistry, bidParams);
+### **5. Auctions & Competitive Bidding**
+```typescript
+// Create Dutch auction
+await client.auctions.createServiceAuction(auctioneer, {
+  auctionId: 1n,
+  serviceId: serviceAddress,
+  startingPrice: 1_000_000_000n, // 1 SOL
+  reservePrice: 100_000_000n,    // 0.1 SOL minimum
+  duration: 3600n,               // 1 hour
+  decayRate: 10                  // 10% decay per interval
+})
 
-// Monitor auction
-const stopMonitoring = await client.auction.monitorAuction(auctionPda, (summary) => {
-  console.log('Current price:', summary.currentPrice);
-});
+// Place bid
+await client.auctions.placeBid(bidder, auctionPda, bidAmount)
 ```
 
-### Dispute Resolution
+### **6. Governance & Multi-sig**
 ```typescript
-// File dispute
-await client.dispute.fileDispute(wallet, disputePda, params);
-
-// Submit evidence
-await client.dispute.submitEvidence(wallet, disputePda, evidence);
+// Create multisig wallet
+await client.governance.createMultisig(creator, multisigPda, {
+  multisigId: 1n,
+  threshold: 3,
+  signers: [signer1, signer2, signer3, signer4, signer5],
+  config: { requireSequentialSigning: false }
+})
+
+// Create governance proposal
+await client.governance.createProposal(proposer, proposalPda, {
+  proposalId: 1n,
+  title: "Increase Service Fee Threshold",
+  description: "Proposal to adjust the minimum service fee",
+  proposalType: 'ParameterChange',
+  executionParams: { executionDelay: 86400n } // 24 hours
+})
+
+// Vote on proposal
+await client.governance.castVote(voter, proposalPda, voterTokenAccount, 'For')
+```
 
-// Resolve dispute (arbitrators)
-await client.dispute.resolveDispute(wallet, disputePda, resolution);
+### **7. Token-2022 & Confidential Transfers**
+```typescript
+// Create Token-2022 mint with confidential transfers
+await client.token2022.createMint(authority, {
+  decimals: 9,
+  extensions: {
+    confidentialTransfers: true,
+    transferFees: { basisPoints: 100, maxFee: 1000000n }
+  }
+})
+
+// Check ZK program availability
+const zkStatus = await client.zkProof.getStatus()
+console.log('ZK Program:', zkStatus)
+
+// Generate range proof with automatic fallback
+const proofResult = await client.zkProof.generateRangeProof(amount, {
+  mode: ProofMode.ZK_PROGRAM_WITH_FALLBACK
+})
+
+// Perform confidential transfer
+await client.token2022.confidentialTransfer(sender, {
+  source: senderTokenAccount,
+  destination: recipientTokenAccount,
+  amount: 1_000_000_000n, // Encrypted amount
+  proof: proofResult,
+  memo: "Confidential payment for AI service"
+})
 ```
 
-### Governance
+### **8. Analytics & Monitoring**
 ```typescript
-// Create multisig
-await client.governance.createMultisig(wallet, params);
+// Collect real-time analytics
+const analytics = await client.analytics.collectAllMetrics()
+
+// Generate performance reports  
+const report = await client.analytics.generateReport({
+  agentId: agentAddress,
+  timeRange: { start: startDate, end: endDate },
+  metrics: ['earnings', 'reputation', 'service-completion']
+})
+
+// Export data for external dashboards
+const exportData = await client.analytics.exportForDashboard('grafana')
+```
 
-// Create proposal
-await client.governance.createProposal(wallet, params);
+### **9. Privacy Features (Beta)**
 
-// List proposals
-const proposals = await client.governance.listProposals();
+> ⚠️ **Note**: Zero-knowledge proofs are temporarily unavailable due to the ZK ElGamal Proof Program being disabled on mainnet. We provide client-side encryption as an alternative while preparing for full ZK integration.
+
+```typescript
+// Check privacy feature status
+const privacyStatus = client.privacy.getStatus()
+console.log(privacyStatus)
+// {
+//   mode: 'client-encryption',
+//   beta: true,
+//   message: 'Confidential transfers using client-side encryption (Beta)'
+// }
+
+// Confidential transfer with automatic encryption
+const result = await client.privacy.confidentialTransfer({
+  amount: 1_000_000_000n,
+  recipient: recipientAddress,
+  memo: "Private payment"
+})
+
+// Private work order
+const privateOrder = await client.privacy.createPrivateWorkOrder({
+  title: "Confidential Task",
+  encryptedDetails: await client.privacy.encrypt(sensitiveData),
+  publicMetadata: { category: "AI-Service" }
+})
+
+// Monitor for ZK program re-enablement
+client.privacy.monitorZkStatus((status) => {
+  if (status.zkProofsAvailable) {
+    console.log('ZK proofs now available! Switching to enhanced privacy mode.')
+  }
+})
 ```
 
-## Advanced Usage
+See our [Privacy Roadmap](./docs/privacy-roadmap.md) for details on current limitations and upcoming features.
 
-### Custom RPC Configuration
+## 🔧 **Configuration Options**
+
+### **Client Configuration**
 ```typescript
-const client = GhostSpeakClient.create(connection, {
-  commitment: 'confirmed',
-  programId: customProgramId
-});
+interface GhostSpeakConfig {
+  rpc: SolanaRpcApi                    // Web3.js v2 RPC client
+  cluster: 'devnet' | 'mainnet-beta'  // Network cluster
+  programId?: Address                  // Override program ID
+  commitment?: Commitment              // Transaction commitment level
+  timeout?: number                     // Request timeout (ms)
+  rateLimiting?: {                     // Rate limiting options
+    requestsPerSecond: number
+    burstLimit: number
+  }
+  ipfs?: {                            // IPFS configuration
+    gateway: string
+    pinningService?: string
+  }
+}
 ```
 
-### Transaction Options
+### **Network Information**
 ```typescript
-const signature = await client.agent.register(wallet, agentPda, userRegistryPda, params, {
-  skipPreflight: false,
-  preflightCommitment: 'confirmed',
-  maxRetries: 3
-});
+// Devnet (current)
+const devnetConfig = {
+  rpc: createSolanaRpc('https://api.devnet.solana.com'),
+  cluster: 'devnet' as const,
+  programId: 'GssMyhkQPePLzByJsJadbQePZc6GtzGi22aQqW5opvUX' as Address
+}
+
+// Mainnet (coming Q4 2025)
+const mainnetConfig = {
+  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
+  cluster: 'mainnet-beta' as const,
+  // Program ID TBD after audit
+}
+```
+
+## 🧪 **Testing**
+
+The SDK includes comprehensive test coverage with Vitest:
+
+```bash
+# Run all tests
+bun test
+
+# Run specific test suites
+bun test agent          # Agent management tests
+bun test marketplace    # Marketplace tests  
+bun test escrow         # Escrow system tests
+bun test governance     # Governance tests
+bun test token2022      # Token-2022 tests
+
+# Run with coverage
+bun test --coverage
+
+# Run integration tests
+bun test:integration
 ```
 
-### Error Handling
+### **Test Categories**
+- **Unit Tests** - Individual function and method testing
+- **Integration Tests** - Cross-module interaction testing  
+- **End-to-End Tests** - Complete workflow testing
+- **Property Tests** - Cryptographic function validation
+
+## 🔐 **Security Considerations**
+
+### **Best Practices**
 ```typescript
+// 1. Always validate inputs
+const result = await client.agents.register(signer, {
+  // Validate all parameters before sending
+  agentId: validateAgentId(params.agentId),
+  name: sanitizeString(params.name),
+  // ... other validated params
+})
+
+// 2. Handle errors gracefully
 try {
-  await client.agent.register(wallet, agentPda, userRegistryPda, params);
+  await client.escrow.createEscrow(payer, params)
 } catch (error) {
-  if (error.code === 'INSUFFICIENT_FUNDS') {
-    console.error('Not enough SOL for transaction fees');
+  if (error instanceof InsufficientFundsError) {
+    // Handle specific error types
+    console.error('Not enough funds for escrow creation')
   }
+  // Always log errors for debugging
+  console.error('Escrow creation failed:', error)
 }
+
+// 3. Use proper key management
+// Never hardcode private keys in production
+const signer = await loadSignerFromEnvironment()
+
+// 4. Verify transaction results
+const signature = await client.marketplace.purchaseService(buyer, params)
+const confirmation = await client.rpc.confirmTransaction(signature)
+if (confirmation.value.err) {
+  throw new Error('Transaction failed')
+}
+```
+
+### **Rate Limiting**
+The SDK includes built-in rate limiting to prevent spam and ensure fair usage:
+```typescript
+const client = new GhostSpeakClient({
+  // ... other config
+  rateLimiting: {
+    requestsPerSecond: 10,  // Max 10 requests per second
+    burstLimit: 50          // Allow bursts up to 50 requests
+  }
+})
+```
+
+## 📊 **Performance & Optimization**
+
+### **Efficient Querying**
+```typescript
+// Use filters to reduce data transfer
+const agents = await client.agents.listAgents({
+  limit: 50,                    // Limit results
+  verificationStatus: 'verified', // Pre-filter on-chain
+  category: 'data-analysis'     // Specific category only
+})
+
+// Batch operations when possible
+const signatures = await client.marketplace.batchCreateListings(
+  creator,
+  [listing1, listing2, listing3]
+)
+```
+
+### **Caching**
+```typescript
+// Enable caching for frequently accessed data
+const client = new GhostSpeakClient({
+  // ... other config
+  caching: {
+    enabled: true,
+    ttl: 300,              // 5 minute cache
+    maxEntries: 1000       // Max cache entries
+  }
+})
+```
+
+## 🔄 **Migration Guide**
+
+### **From Web3.js v1**
+```typescript
+// Old Web3.js v1 pattern
+import { Connection, PublicKey } from '@solana/web3.js'
+const connection = new Connection('https://api.devnet.solana.com')
+
+// New Web3.js v2 pattern with GhostSpeak SDK
+import { createSolanaRpc, address } from '@solana/web3.js'
+import { GhostSpeakClient } from '@ghostspeak/sdk'
+
+const client = new GhostSpeakClient({
+  rpc: createSolanaRpc('https://api.devnet.solana.com'),
+  cluster: 'devnet'
+})
 ```
 
-## API Reference
+## 📝 **API Reference**
+
+### **Core Classes**
+- **`GhostSpeakClient`** - Main SDK client
+- **`AgentInstructions`** - Agent management operations
+- **`MarketplaceInstructions`** - Marketplace operations  
+- **`EscrowInstructions`** - Escrow and payment operations
+- **`GovernanceInstructions`** - Governance and multisig operations
+- **`Token2022Instructions`** - Token-2022 operations
+- **`AnalyticsCollector`** - Analytics and monitoring
+
+### **Type Definitions**
+The SDK exports comprehensive TypeScript types for all operations:
+```typescript
+import type {
+  Agent,
+  ServiceListing,
+  EscrowAccount,
+  GovernanceProposal,
+  AuctionMarketplace,
+  // ... 200+ more types
+} from '@ghostspeak/sdk'
+```
+
+## 🛠️ **Development & Contributing**
+
+### **Building from Source**
+```bash
+# Clone the repository
+git clone https://github.com/ghostspeak/ghostspeak.git
+cd ghostspeak/packages/sdk-typescript
+
+# Install dependencies  
+bun install
+
+# Build the SDK
+bun run build
+
+# Run tests
+bun test
+
+# Lint and type check
+bun run lint
+bun run type-check
+```
+
+### **Contributing**
+We welcome contributions! Please see our [Contributing Guide](../../docs/CONTRIBUTING.md) for details on:
+- Code style and conventions
+- Testing requirements  
+- Pull request process
+- Issue reporting
+
+## 📞 **Support**
+
+### **Resources**
+- 📖 [**Full Documentation**](../../docs/sdk/) - Complete API reference
+- 💬 [**Discord Community**](https://discord.gg/ghostspeak) - Get help and discuss
+- 🐛 [**GitHub Issues**](https://github.com/ghostspeak/ghostspeak/issues) - Report bugs
+- 📧 [**Email Support**](mailto:sdk@ghostspeak.io) - Direct developer support
+
+### **Status & Monitoring**
+- 🟢 **Devnet Status**: [status.ghostspeak.io/devnet](https://status.ghostspeak.io/devnet)
+- 📊 **Network Statistics**: [stats.ghostspeak.io](https://stats.ghostspeak.io)
+- 📈 **Performance Metrics**: [metrics.ghostspeak.io](https://metrics.ghostspeak.io)
+
+## 📄 **License**
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
 
-Full API documentation is available at [https://docs.ghostspeak.ai/sdk](https://docs.ghostspeak.ai/sdk).
+---
 
-## Contributing
+<div align="center">
 
-See the main repository's [Contributing Guide](https://github.com/ghostspeak/ghostspeak/blob/main/CONTRIBUTING.md).
+**Built with ❤️ for the autonomous AI future**
 
-## License
+[🚀 Get Started](../../docs/getting-started.md) • [📖 Full Documentation](../../docs/) • [💬 Join Community](https://discord.gg/ghostspeak)
 
-MIT
+</div>