@reap-protocol/sdk 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,103 @@
+# @reap-protocol/sdk
+
+**The official TypeScript/Node.js SDK for the Reap Protocol: The Agentic Commerce Grid.**
+
+The Reap Protocol enables AI Agents to search for products, register them on-chain, and execute atomic purchases without needing to understand smart contract ABIs. It acts as the bridge between Web2 products data and Web3 commerce settlement.
+
+## 📦 Installation
+```bash
+npm install @reap-protocol/sdk ethers axios
+```
+
+## 🚀 Quick Start
+
+This example demonstrates the full Agentic Commerce Loop: Identity -> Discovery -> Settlement.
+
+### 1. Setup
+
+If using TypeScript, ensure your tsconfig.json targets ES2020 or higher.
+
+### 2. The Agent Code (agent.ts)
+```typescript
+import { ReapClient } from "@reap-protocol/sdk";
+
+// Load your private key securely
+const PRIVATE_KEY = process.env.MY_WALLET_KEY || "";
+
+async function main() {
+  // 1. Initialize the Agent
+  // (Points to official middleware by default)
+  const client = new ReapClient(PRIVATE_KEY);
+  console.log("🤖 Agent Online");
+
+  try {
+    // 2. Identity (One-time setup)
+    // Registers your wallet as an authorized Agent on the Protocol
+    console.log("🆔 Checking Identity...");
+    await client.registerIdentity();
+
+    // 3. JIT Stocking (Discovery)
+    // Searches Web2 (Reap Deals), registers items on-chain, and returns inventory
+    console.log("📦 Stocking Shelf with 'Gaming Laptop'...");
+    const result = await client.stockShelf("Gaming Laptop");
+    
+    const inventory = result.items;
+    console.log(`   🔍 Found ${inventory.length} items on-chain.`);
+
+    if (inventory.length > 0) {
+        // 4. Decision Logic
+        // Example: Pick the first available item
+        const target = inventory[0];
+        console.log(`   🎯 Selected: ${target.name} ($${target.price})`);
+        console.log(`      ID: ${target.id}`);
+
+        // 5. Agentic Cart (Settlement)
+        // Automatically approves USDC and executes the atomic purchase
+        console.log("💸 Buying Item...");
+        const receipt = await client.buyProduct(target.id);
+        
+        if (receipt) {
+            console.log(`🎉 SUCCESS! Transaction Hash: ${receipt.hash}`);
+        }
+    } else {
+        console.log("❌ No items found.");
+    }
+
+  } catch (e: any) {
+    console.error("❌ Error:", e.message);
+  }
+}
+
+main();
+```
+
+### 3. Run It
+```bash
+# Install execution tools if you haven't already
+npm install --save-dev ts-node typescript @types/node
+
+# Run
+npx ts-node agent.ts
+```
+
+## 🔧 Configuration
+
+You can override defaults for custom RPCs or self-hosted middleware.
+```typescript
+const client = new ReapClient(
+  "YOUR_PRIVATE_KEY",
+  "https://base-sepolia.g.alchemy.com/v2/YOUR_KEY", // Custom RPC
+  "https://api.reap.deals"    // Middleware URL
+);
+```
+
+## ✨ Features
+
+* **JIT Stocking**: "Just-In-Time" inventory system. If an agent searches for an item not yet on the blockchain, the Protocol indexes it in real-time.
+* **Agentic Cart**: Automatically routes purchases through the Protocol's batch processor.
+* **Protocol Negotiation**: Built-in support for HTTP 402 Payment Negotiation loops.
+* **Gas Optimized**: Checks on-chain state before sending registration transactions.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reap-protocol/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/src/README.md

@@ -11,7 +11,8 @@ npm install @reap-protocol/sdk ethers axios
 
 ## 🚀 Quick Start
 
-This example demonstrates the full Agentic Commerce Loop: Identity -> Discovery -> Settlement.
+This example demonstrates the full Agentic Commerce Loop: Identity -> Discovery -> Smart Sync -> Settlement.
+
 
 ### 1. Setup
 
@@ -23,11 +24,14 @@ import { ReapClient } from "@reap-protocol/sdk";
 
 // Load your private key securely
 const PRIVATE_KEY = process.env.MY_WALLET_KEY || "";
+const CHAIN_RPC = "https://api.avax-test.network/ext/bc/C/rpc"; 
 
 async function main() {
   // 1. Initialize the Agent
-  // (Points to official middleware by default)
-  const client = new ReapClient(PRIVATE_KEY);
+  const client = new ReapClient(PRIVATE_KEY, CHAIN_RPC);
+  
+  // Wait for Chain ID initialization
+  await new Promise(r => setTimeout(r, 1000));
   console.log("🤖 Agent Online");
 
   try {
@@ -36,25 +40,36 @@ async function main() {
     console.log("🆔 Checking Identity...");
     await client.registerIdentity();
 
-    // 3. JIT Stocking (Discovery)
-    // Searches Web2 (Reap Deals), registers items on-chain, and returns inventory
-    console.log("📦 Stocking Shelf with 'Gaming Laptop'...");
-    const result = await client.stockShelf("Gaming Laptop");
+    // 3. Discovery (Dry Run Mode)
+    // Pass 'true' to get the items AND the transactions without executing them yet.
+    console.log("📦 Browsing for 'Gaming Laptop'...");
+    
+    // dryRun = true
+    const result = await client.stockShelf("Gaming Laptop", true); 
     
-    const inventory = result.items;
-    console.log(`   🔍 Found ${inventory.length} items on-chain.`);
+    const inventory = result.items || [];
+    const transactions = result.transactions || [];
+
+    console.log(`   🔍 Found ${inventory.length} items.`);
 
     if (inventory.length > 0) {
         // 4. Decision Logic
-        // Example: Pick the first available item
-        const target = inventory[0];
-        console.log(`   🎯 Selected: ${target.name} ($${target.price})`);
-        console.log(`      ID: ${target.id}`);
+        // Pick the first item and its corresponding registration transaction
+        const targetItem = inventory[0];
+        const targetTx = transactions[0]; 
+
+        console.log(`   🎯 Selected: ${targetItem.name} ($${targetItem.price})`);
 
-        // 5. Agentic Cart (Settlement)
+        // 5. Smart Sync (The "Gas Saver")
+        // Checks the Holocron (Index) first. 
+        // If the item exists, it skips registration. 
+        // If not, it executes the targetTx and indexes it.
+        await client.smartSync(targetItem, targetTx);
+
+        // 6. Agentic Cart (Settlement)
         // Automatically approves USDC and executes the atomic purchase
         console.log("💸 Buying Item...");
-        const receipt = await client.buyProduct(target.id);
+        const receipt = await client.buyProduct(targetItem.id);
         
         if (receipt) {
             console.log(`🎉 SUCCESS! Transaction Hash: ${receipt.hash}`);
@@ -80,23 +95,40 @@ npm install --save-dev ts-node typescript @types/node
 npx ts-node agent.ts
 ```
 
+## 🕵️ Agent Discovery (New)
+
+You can now search for other AI Agents (MCP, x402, A2A).
+
+```typescript
+// 1. Search for Agents
+// Registries: 'mcp' (AI Models), 'x402' (Payment Agents), 'a2a' (Autonomous)
+const agents = await client.searchAgents("ecommerce", "x402");
+
+if (agents.length > 0) {
+    const targetAgent = agents[0];
+    console.log(`Found: ${targetAgent.name}`);
+}
+```
+
 ## 🔧 Configuration
 
 You can override defaults for custom RPCs or self-hosted middleware.
 ```typescript
 const client = new ReapClient(
   "YOUR_PRIVATE_KEY",
-  "https://base-sepolia.g.alchemy.com/v2/YOUR_KEY", // Custom RPC
-  "https://api.reap.deals"    // Middleware URL
+  "https://avax-fuji.g.alchemy.com/v2/YOUR_KEY", // Custom RPC
+  "https://avax2.api.reap.deals"    // Middleware URL
 );
 ```
 
 ## ✨ Features
 
+* **Agent Discovery**: Search thousands of AI Agents from MCP, x402, and A2A registries.
 * **JIT Stocking**: "Just-In-Time" inventory system. If an agent searches for an item not yet on the blockchain, the Protocol indexes it in real-time.
 * **Agentic Cart**: Automatically routes purchases through the Protocol's batch processor.
 * **Protocol Negotiation**: Built-in support for HTTP 402 Payment Negotiation loops.
-* **Gas Optimized**: Checks on-chain state before sending registration transactions.
+
+
 
 ## License
 

package/src/index.ts

@@ -1,31 +1,90 @@
 import { ethers } from "ethers";
-import axios, { AxiosRequestConfig } from "axios";
+import axios from "axios";
+
+// ==========================================
+// CONSTANTS & CONFIGURATION
+// ==========================================
+
+const HOLOCRON_ROUTER_ADDRESS = "0x2cEC5Bf3a0D3fEe4E13e8f2267176BdD579F4fd8";
+
+const NETWORKS: Record<string, string> = {
+  "BASE": "https://sepolia.base.org",
+  "AVAX": "https://api.avax-test.network/ext/bc/C/rpc",
+  "CELO": "https://forno.celo-sepolia.celo-testnet.org"
+};
+
+const HOLOCRON_ABI = [
+  "function checkExistence(uint256 _c) view returns (bool)",
+  "function stock(uint256 _c) external"
+];
+
+// --- Agent Registry Configuration ---
+export type AgentRegistry = 'mcp' | 'x402' | 'a2a';
+
+const REGISTRY_MAP: Record<AgentRegistry, string> = {
+  "mcp": "pulsemcp",
+  "x402": "coinbase-x402-bazaar",
+  "a2a": "a2a-registry"
+};
+
+const SEARCH_API_URL = "https://www.reap.deals/api/search-agents";
+
+// ==========================================
+// REAP CLIENT CLASS
+// ==========================================
 
 export class ReapClient {
   private wallet: ethers.Wallet;
   private builderUrl: string;
   private provider: ethers.JsonRpcProvider;
+  private holocron: ethers.Contract;
+  private chainId: number = 43113;
 
   constructor(
     privateKey: string, 
     chainRpc: string = "https://avalanche-fuji.drpc.org", 
-    builderUrl: string = "https://api.reap.deals"
+    builderUrl: string = "https://avax2.api.reap.deals"
   ) {
     this.provider = new ethers.JsonRpcProvider(chainRpc);
     this.wallet = new ethers.Wallet(privateKey, this.provider);
-    this.builderUrl = builderUrl.replace(/\/$/, ""); // Remove trailing slash
-    console.log(`🤖 Reap Agent Online: ${this.wallet.address}`);
+    this.builderUrl = builderUrl.replace(/\/$/, ""); 
+    
+    // Initialize Holocron Contract
+    this.holocron = new ethers.Contract(HOLOCRON_ROUTER_ADDRESS, HOLOCRON_ABI, this.wallet);
+    
+    this.init();
   }
 
   /**
-   * Core Logic: Signs and Broadcasts transactions sequentially.
-   * Uses manual nonce management to prevent RPC lag errors.
+   * Async initialization to fetch Chain ID
+   */
+  private async init() {
+    try {
+      const net = await this.provider.getNetwork();
+      this.chainId = Number(net.chainId);
+      console.log(`🤖 Reap Agent Online: ${this.wallet.address} (Chain: ${this.chainId})`);
+    } catch (e) {
+      console.error("⚠️ Failed to fetch chain ID. Defaulting to 43113.");
+    }
+  }
+
+  // ==========================================
+  // CORE TRANSACTION LOGIC
+  // ==========================================
+
+  /**
+   * Execute Transactions with Nonce & Gas Fixes.
+   * Handles sequential nonce increments locally to prevent RPC lag.
    */
   private async executeTransactions(txList: any[]) {
     let lastReceipt;
     
     // 1. Fetch Nonce ONCE
     let currentNonce = await this.provider.getTransactionCount(this.wallet.address, "pending");
+    
+    // 2. Gas Price Buffer (1.1x) for fast propagation
+    const feeData = await this.provider.getFeeData();
+    const gasPrice = feeData.gasPrice ? (feeData.gasPrice * 110n) / 100n : undefined;
 
     for (const txData of txList) {
       const label = txData.label || "Transaction";
@@ -35,33 +94,29 @@ export class ReapClient {
         to: txData.to,
         data: txData.data,
         value: BigInt(txData.value),
-        gasLimit: 500000, // Safety limit
+        gasLimit: 500000, // Safe default limit
         nonce: currentNonce,
-        chainId: (await this.provider.getNetwork()).chainId
+        chainId: this.chainId,
+        gasPrice: gasPrice 
       };
 
       try {
-        // 2. Sign & Send
         const response = await this.wallet.sendTransaction(tx);
         console.log(`   🚀 Broadcasting: ${response.hash}`);
         
-        // 3. Wait
         const receipt = await response.wait();
         
-        // 4. Check Status (1 = Success, 0 = Revert)
         if (receipt && receipt.status === 0) {
             throw new Error(`Transaction Reverted! Hash: ${receipt.hash}`);
         }
 
         console.log(`   ✅ Settled on-chain.`);
         lastReceipt = receipt;
-        
-        // 5. Increment Nonce
         currentNonce++;
 
       } catch (e: any) {
         console.error(`   ❌ Tx Failed: ${e.message}`);
-       
+        // Stop execution if payment or approval fails. Continue for others if needed.
         if (label.includes("Approve") || label.includes("Payment")) throw e;
       }
     }
@@ -70,23 +125,125 @@ export class ReapClient {
 
   private async callBuilder(endpoint: string, payload: any) {
     try {
-      const { data } = await axios.post(`${this.builderUrl}${endpoint}`, payload);
-      return data;
+        // Inject Chain ID for Middleware routing
+        payload.chain_id = this.chainId;
+        const { data } = await axios.post(`${this.builderUrl}${endpoint}`, payload);
+        return data;
     } catch (error: any) {
       const msg = error.response?.data?.detail || error.message;
       throw new Error(`Reap Protocol Error: ${msg}`);
     }
   }
 
-  // --- PUBLIC API ---
+  // ==========================================
+  // HOLOCRON & SMART SYNC
+  // ==========================================
+
+  /**
+   * Check if a coordinate exists in the Holocron Registry.
+   */
+  async checkHolocron(coordinate: string) {
+    console.log(`🔎 Scanning Holocron for ${coordinate}...`);
+    
+    let exists = false;
+    try {
+        exists = await this.holocron.checkExistence(BigInt(coordinate));
+    } catch (e) { exists = false; }
+
+    console.log(`   • Holocron Index: ${exists ? '✅ FOUND' : '❌ EMPTY'}`);
+    return exists;
+  }
+
+  /**
+   * Internal method to execute the 'stock' function on the Holocron.
+   */
+  private async indexToHolocron(coordinate: string) {
+    console.log(`   📝 Indexing Coordinate ${coordinate} to Holocron...`);
+    
+    const nonce = await this.provider.getTransactionCount(this.wallet.address, "pending");
+    const feeData = await this.provider.getFeeData();
+    const gasPrice = feeData.gasPrice ? (feeData.gasPrice * 110n) / 100n : undefined;
 
-  async getProduct(productId: string) {
-    const safeId = encodeURIComponent(productId);
-    const { data } = await axios.get(`${this.builderUrl}/read/product/${safeId}`);
-    return data;
+    const tx = await this.holocron.stock(BigInt(coordinate), {
+        gasLimit: 150000,
+        nonce,
+        gasPrice
+    });
+    
+    console.log(`   🚀 Broadcast Holocron TX: ${tx.hash}`);
+    await tx.wait();
+    console.log("   ✅ Index Updated.");
+    
+    // Small sleep to let RPC sync
+    await new Promise(r => setTimeout(r, 2000));
   }
 
- // ... inside ReapClient class ...
+  /**
+   * Smart Sync: Checks Holocron first.
+   * If item exists -> Skip registration (Save Gas).
+   * If missing -> Execute registration TX -> Index to Holocron.
+   */
+  async smartSync(item: any, transaction: any) {
+    const coordinate = item.id;
+    
+    // 1. Check Status
+    const onHolocron = await this.checkHolocron(coordinate);
+
+    if (onHolocron) {
+        console.log("⚡️ Fast Path: Item is indexed. Skipping registration.");
+        return;
+    }
+
+    console.log("\n🐢 Syncing to Chain (Full Path)...");
+
+    // 2. Register Data (if transaction exists)
+    if (transaction) {
+        console.log("   🔸 Registering Data on-chain...");
+        // Wrap single transaction in array
+        await this.executeTransactions([transaction]);
+    } else {
+        console.log("   ⚠️ No registration transaction provided. Skipping to index.");
+    }
+
+    // 3. Index on Holocron
+    await this.indexToHolocron(coordinate);
+  }
+
+  // ==========================================
+  // AGENT DISCOVERY (NEW)
+  // ==========================================
+
+  /**
+   * Search for AI Agents across different registries (MCP, x402, A2A).
+   * @param query Keywords to search for (e.g. "customer support", "ecommerce")
+   * @param registry 'mcp' | 'x402' | 'a2a'
+   * @param limit Max results (default 40)
+   */
+  async searchAgents(query: string, registry: AgentRegistry = 'mcp', limit: number = 40) {
+    console.log(`🔎 Searching Registry [${REGISTRY_MAP[registry]}] for: "${query}"...`);
+    
+    try {
+        const payload = {
+            limit: limit,
+            query: query,
+            registry: REGISTRY_MAP[registry] // Maps 'mcp' -> 'pulsemcp', etc.
+        };
+
+        const response = await axios.post(SEARCH_API_URL, payload);
+        const hits = response.data.hits || [];
+        
+        console.log(`   ✅ Found ${hits.length} agents.`);
+        return hits;
+
+    } catch (error: any) {
+        console.error("   ❌ Search Failed:", error.message);
+        return [];
+    }
+  }
+
+  // ==========================================
+  // PUBLIC API (Commerce & Identity)
+  // ==========================================
 
   async registerIdentity(profileUri: string = "ipfs://default") {
     console.log("🆔 Registering Protocol Identity...");
@@ -96,40 +253,45 @@ export class ReapClient {
     });
 
     if (res.status === "already_registered") {
-        console.log(`   ✅ Already Registered (Agent #${res.agent_id}). Skipping transaction.`);
+        console.log(`   ✅ Already Registered (Agent #${res.agent_id}). Skipping.`);
         return null;
     }
-
     return this.executeTransactions(res.transactions);
   }
 
-async stockShelf(productQuery: string) {
-    console.log(`📦 Stocking Shelf: '${productQuery}'`);
+  /**
+   * Search for Products/Inventory.
+   * Use dryRun=true to get items without executing on-chain registration immediately.
+   */
+  async stockShelf(productQuery: string, dryRun: boolean = false) {
+    console.log(`📦 Stocking Shelf: '${productQuery}' (Dry Run: ${dryRun})`);
+    
     const res = await this.callBuilder("/build/inventory/stock", {
       product_query: productQuery,
       provider_address: this.wallet.address
     });
 
+    const items = res.meta?.items || [];
+    const transactions = res.transactions || [];
+
     if (res.status === "payment_required") {
-        console.log("🛑 402 Payment Required via JSON Spec.");
-        console.log(`   🧾 Invoice: ${res.meta.description}`);
-    } else {
-        console.log(`   🔍 Found ${res.meta.count || 0} items.`);
+        console.log("🛑 402 Payment Required.");
+        if (dryRun) return { receipt: null, items: [] };
+        const receipt = await this.executeTransactions(transactions);
+        return { receipt, items: [] };
     }
 
-    const receipt = await this.executeTransactions(res.transactions);
+    if (dryRun) {
+        console.log(`   👀 Preview: Found ${items.length} items. Cached ${transactions.length} TXs.`);
+        return { receipt: null, items, transactions };
+    }
 
-    // --- THE FIX: Return both Receipt AND Items ---
-    return {
-        receipt,
-        items: res.meta?.items || []
-    };
-    // ----------------------------------------------
+    const receipt = await this.executeTransactions(transactions);
+    return { receipt, items };
   }
 
   async buyProduct(productId: string) {
     console.log(`💸 Initiating Agentic Cart (Single Item): ${productId}`);
-    // Route to batch endpoint
     const res = await this.callBuilder("/build/commerce/batch", {
       product_ids: [productId]
     });
@@ -143,36 +305,4 @@ async stockShelf(productQuery: string) {
     });
     return this.executeTransactions(res.transactions);
   }
-
-  async fetch(url: string, config: AxiosRequestConfig = {}) {
-    console.log(`🌍 Accessing ${url}...`);
-    try {
-      return await axios.get(url, config);
-    } catch (error: any) {
-      if (error.response && error.response.status === 402) {
-        console.log("🛑 x402 Payment Required. Engaging Protocol...");
-        const header = error.response.headers["www-authenticate"];
-
-        if (header && header.includes("X402")) {
-            const match = header.match(/resource_id="([^"]+)"/);
-            if (match && match[1]) {
-                const rid = match[1];
-                
-                // Pay Protocol
-                const receipt = await this.buyProduct(rid);
-                
-                if (!receipt) throw new Error("Payment Transaction failed");
-                const proof = receipt.hash;
-                
-                console.log(`   🔄 Submitting Proof for Reactive Release: ${proof}`);
-
-                // Release Data
-                const newConfig = { ...config, headers: { ...config.headers, "Authorization": `X402-Proof ${proof}` } };
-                return await axios.get(url, newConfig);
-            }
-        }
-      }
-      throw error;
-    }
-  }
 }