@t54-labs/clawcredit-sdk 0.1.0

package/SKILL.md

@@ -0,0 +1,106 @@
+# ClawCredit Integration Skill
+
+## 1. Overview
+This skill allows Open Claw Agents to access **ClawCredit**, a decentralized credit service.
+By integrating the `@clawcredit/sdk`, agents can:
+1.  **Get a Credit Line**: Prove your worth (code, prompt, environment) and get funded.
+2.  **Pay for Services**: Use your credit to pay other agents/merchants via x402.
+3.  **Build Credit**: Good repayment and low-risk behavior increases your limit.
+
+## 2. Prerequisites
+- **Node.js Environment** (The SDK is a Node.js package).
+- **Invitation Code**: You need a valid `invite_code` to register.
+
+## 3. Installation
+Instruct the user (or run this in your shell if allowed) to install the SDK:
+
+```bash
+npm install @t54-labs/clawcredit-sdk
+```
+
+## 4. Usage Guide
+
+### Step 1: Initialization & Registration (with Code Audit)
+You must register to receive your initial Credit Line.
+**IMPORTANT**: Use the `audit()` wrapper on your core logic functions. This proves to the Risk Engine that your code is safe.
+
+```javascript
+const { ClawCredit, audit } = require('@t54-labs/clawcredit-sdk');
+
+// 1. Audit your core functions (Optional but recommended for higher limit)
+function myCoreLogic(input) {
+  // ... implementation ...
+}
+const safeLogic = audit(myCoreLogic);
+
+// 2. Initialize Client
+const credit = new ClawCredit({
+  agentName: "MyAgentName" 
+});
+
+// 3. Register
+await credit.register({
+  inviteCode: "YOUR_INVITE_CODE", 
+  coreCode: "const agent = ...", 
+  systemPrompt: "You are a helpful assistant...",
+  runtimeEnv: "node-v22",
+  model: "gpt-5.2" // Optional
+});
+```
+
+### Step 2: Enable Reasoning Trace
+To ensure your transactions are approved, you must allow ClawCredit to trace your reasoning process.
+Wrap your OpenAI client with `wrapOpenAI`.
+
+```javascript
+const OpenAI = require('openai');
+const { wrapOpenAI, withTrace } = require('@t54-labs/clawcredit-sdk');
+
+// Wrap the client
+const openai = wrapOpenAI(new OpenAI({ apiKey: '...' }));
+
+// Wrap your execution loop
+await withTrace(async () => {
+    // Call LLM
+    const completion = await openai.chat.completions.create({
+        messages: [{ role: "user", content: "Buy me a coffee service" }],
+        model: "gpt-5.2",
+    });
+
+    // If the LLM decides to call a tool (pay), the SDK will automatically 
+    // attach the 'messages' and 'completion' as proof of reasoning.
+    
+    // ... logic to call credit.pay() ...
+});
+```
+
+### Step 3: Making Payments (Settlement via x402)
+When you need to pay a merchant (another Agent or Service), use `pay()`.
+If you used `withTrace` and `wrapOpenAI`, the reasoning is attached automatically.
+
+```javascript
+const transactionResult = await credit.pay({
+  transaction: {
+    recipient: "merchant_address_or_id",
+    amount: 5.00, // USD
+    chain: "BASE",
+    asset: "USDC"
+  },
+  request_body: {
+    service_name: "PremiumSearch",
+    params: { query: "latest crypto prices" }
+  },
+  // Optional. If provided, it increases the approval rate.
+  // context: { reasoning_process: "..." }
+});
+
+if (transactionResult.status === 'success') {
+  console.log("Payment successful! Result:", transactionResult.merchant_response);
+}
+```
+
+## 5. Settlement & Chains
+ClawCredit handles the blockchain complexity.
+- Your credit is denominated in **USD**.
+- Settlements occur on **Base (USDC)**, **Solana (USDC)**, or **XRPL (RLUSD)**.
+- The merchant receives the crypto; you spend your Credit.

package/index.js

@@ -0,0 +1,156 @@
+const axios = require('axios');
+const { v4: uuidv4 } = require('uuid');
+const { audit, getAuditedSnapshot } = require('./lib/audit');
+const { wrapOpenAI, withTrace, getTraceContext } = require('./lib/monitor');
+
+class ClawCredit {
+    constructor(config = {}) {
+        this.serviceUrl = config.serviceUrl || 'https://api.clawcredit.com'; // Default production URL
+        this.agentName = config.agentName;
+        this.apiToken = config.apiToken; // Token stored after registration
+        this.agentId = config.agentId;
+    }
+
+    /**
+     * Register the agent to get a credit limit.
+     * Requires Invitation Code and Audit Materials.
+     */
+    async register({ inviteCode, coreCode, systemPrompt, runtimeEnv, model }) {
+        if (!inviteCode) throw new Error("Invitation Code is required.");
+        
+        // Include audited functions if available (via audit decorator)
+        const auditedFunctions = getAuditedSnapshot();
+
+        try {
+            const payload = {
+                agent_name: this.agentName,
+                invite_code: inviteCode,
+                audit_material: {
+                    core_code: coreCode, // Main entry code provided manually
+                    audited_functions: auditedFunctions, // Auto-collected functions
+                    system_prompt: systemPrompt,
+                    runtime_env: runtimeEnv,
+                    model: model || null
+                }
+            };
+            
+            const res = await axios.post(`${this.serviceUrl}/v1/agent/register`, payload);
+            
+            // Save credentials
+            this.agentId = res.data.agent_id;
+            this.apiToken = res.data.api_token;
+            
+            return {
+                agent_id: this.agentId,
+                credit_limit: res.data.credit_limit,
+                message: "Registration successful. Credit line issued."
+            };
+        } catch (error) {
+            this._handleError(error);
+        }
+    }
+
+    /**
+     * Get current Balance and Credit Score.
+     */
+    async getBalance() {
+        this._ensureAuth();
+        try {
+            const res = await axios.get(`${this.serviceUrl}/v1/credit/balance`, {
+                headers: { 'Authorization': `Bearer ${this.apiToken}` }
+            });
+            return res.data; 
+            // Returns: { available_usd: 100.00, credit_score: 650, pending_bills: 0 }
+        } catch (error) {
+            this._handleError(error);
+        }
+    }
+
+    /**
+     * Pay a merchant using ClawCredit.
+     * Settlements are handled via x402 on Base/Solana/XRPL.
+     */
+    async pay({ transaction, request_body, context }) {
+        this._ensureAuth();
+        
+        // 1. Try to get Trace Context from AsyncLocalStorage
+        const autoTrace = getTraceContext();
+        
+        // 2. Merge Manual Context with Auto Trace
+        let reasoning = null;
+        if (context && context.reasoning_process) {
+            reasoning = context.reasoning_process;
+        }
+        
+        // We do NOT set 'reasoning' to raw messages because it expects a String.
+        // The backend will check 'raw_trace' if 'reasoning_process' is null.
+        
+        const finalAuditContext = {
+            reasoning_process: reasoning, // Explicit reasoning string or null
+            raw_trace: autoTrace.last_llm_call || {}, // Full messages/tools/response
+            current_task: (context && context.current_task) || "unknown",
+            timestamp: Date.now()
+        };
+
+        // Validate: We need *some* proof of reasoning.
+        if (!finalAuditContext.reasoning_process && !finalAuditContext.raw_trace.messages) {
+             throw new Error("Payment rejected: No 'reasoning_process' provided and no active LLM trace found.");
+        }
+
+        if (!transaction || !transaction.recipient || !transaction.amount || !transaction.chain || !transaction.asset) {
+            throw new Error("Payment rejected: transaction must include recipient, amount, chain, and asset.");
+        }
+        if (!request_body) {
+            throw new Error("Payment rejected: request_body is required.");
+        }
+
+        const txRequest = {
+            transaction: {
+                recipient: transaction.recipient,
+                amount: transaction.amount,
+                chain: transaction.chain,
+                asset: transaction.asset
+            },
+            request_body: request_body,
+            audit_context: finalAuditContext
+        };
+
+        try {
+            // 3. Send Transaction Request to ClawCredit Service
+            const res = await axios.post(`${this.serviceUrl}/v1/transaction/pay`, txRequest, {
+                headers: { 'Authorization': `Bearer ${this.apiToken}` }
+            });
+            
+            return {
+                status: 'success',
+                tx_hash: res.data.tx_hash,      // Blockchain Tx Hash (Base/Solana/XRPL)
+                chain: res.data.chain,          // e.g. "BASE"
+                merchant_response: res.data.merchant_response // The actual service result (e.g. search results)
+            };
+
+        } catch (error) {
+            this._handleError(error);
+        }
+    }
+
+    _ensureAuth() {
+        if (!this.apiToken) {
+            throw new Error("ClawCredit: Not authenticated. Please call register() first.");
+        }
+    }
+
+    _handleError(error) {
+        if (error.response) {
+            throw new Error(`ClawCredit API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+        }
+        throw error;
+    }
+}
+
+// Export the Main Class and the Helper Functions
+module.exports = { 
+    ClawCredit,
+    audit,
+    wrapOpenAI,
+    withTrace
+};

package/lib/audit.js

@@ -0,0 +1,53 @@
+const crypto = require('crypto');
+const { auditedEntities } = require('./store');
+
+/**
+ * Normalizes code by removing extra whitespace to ensure consistent hashing.
+ */
+function normalizeCode(code) {
+    return code.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * "Decorator" wrapper to audit a function.
+ * Since JS decorators aren't standard yet in all envs, we use a wrapper function.
+ * Usage: const safeFn = audit(originalFn);
+ */
+function audit(fn, nameOverride = null) {
+    if (typeof fn !== 'function') {
+        throw new Error("ClawCredit Audit: Argument must be a function");
+    }
+
+    const name = nameOverride || fn.name || 'anonymous';
+    const source = fn.toString();
+    const hash = crypto.createHash('sha256').update(normalizeCode(source)).digest('hex');
+
+    // Register metadata
+    auditedEntities.push({
+        name: name,
+        hash: hash,
+        source: source,
+        timestamp: Date.now()
+    });
+
+    // Return the original function (pass-through)
+    // We could wrap it to track execution, but for "Code Audit", static capture is sufficient.
+    return fn;
+}
+
+/**
+ * Get all audited functions formatted for submission
+ */
+function getAuditedSnapshot() {
+    return auditedEntities.map(e => ({
+        function_name: e.name,
+        function_code: e.source,
+        hash: e.hash
+    }));
+}
+
+module.exports = {
+    audit,
+    getAuditedSnapshot
+};
+

package/lib/monitor.js

@@ -0,0 +1,87 @@
+const { traceStorage } = require('./store');
+
+/**
+ * Wraps an OpenAI client instance to capture prompts and tools.
+ * Mimics the Python SDK's monkey-patching approach but for Node.js object.
+ */
+function wrapOpenAI(openaiInstance) {
+    if (!openaiInstance || !openaiInstance.chat || !openaiInstance.chat.completions) {
+        console.warn("ClawCredit: Invalid OpenAI instance provided. Skipping wrapper.");
+        return openaiInstance;
+    }
+
+    const originalCreate = openaiInstance.chat.completions.create.bind(openaiInstance.chat.completions);
+
+    // Overwrite the create method
+    openaiInstance.chat.completions.create = async function(params, options) {
+        // 1. Capture Context (Prompt & Tools)
+        const traceData = {
+            messages: params.messages || [],
+            tools: params.tools || [],
+            model: params.model,
+            timestamp: Date.now()
+        };
+
+        // Store in AsyncLocalStorage so it's accessible in the same async flow (e.g. during payment)
+        // We use 'enterWith' or run the promise inside 'run'.
+        // However, 'enterWith' is discouraged. Better to store it if we can wrapping the whole execution.
+        // But for "Context retrieval" later, we assume the Agent flow is:
+        // LLM -> Tool Call (Payment).
+        // If we are INSIDE the Tool Call, we want the LLM context that triggered it.
+        // Wait, the Python SDK stores it BEFORE the LLM call, but the tool is called BY the LLM response processing.
+        // So the flow is: User -> LLM -> Response(ToolCall) -> Agent executes Tool.
+        
+        // In Python's contextvars, the context propagates if set properly. 
+        // Here, we just want to save "what was the last LLM call made in this flow".
+        
+        // Let's just update the store if we are already in a store context, OR create a new one?
+        // Actually, typically the Agent Framework loop runs in some scope. 
+        // If we want to capture "Reasoning", we need the messages that LED to this tool call.
+        
+        // Strategy:
+        // We save the inputs to a global-ish store keyed by something, or rely on the user 
+        // to pass the trace. But the requirement is "Trace Agent's reasoning".
+        
+        // Let's start by saving it to the store.
+        const store = traceStorage.getStore() || {};
+        store.last_llm_call = traceData;
+        
+        // If we are not inside a run(), this store might be lost. 
+        // For now, we assume the user might wrap their main loop with traceStorage.run().
+        // If not, we might need a fallback or side-channel. 
+        // But let's stick to the "best effort" AsyncLocalStorage.
+        
+        // 2. Execute Original
+        const response = await originalCreate(params, options);
+
+        // 3. Capture Output (Reasoning/CoT)
+        if (store.last_llm_call) {
+            store.last_llm_call.response = response;
+            // Extract reasoning if present (e.g. O1 model or explicit CoT field)
+            // or just the content.
+        }
+
+        return response;
+    };
+
+    return openaiInstance;
+}
+
+/**
+ * Run a function within a Trace Context.
+ * The Agent should wrap its "Step" or "Loop" with this.
+ */
+function withTrace(fn) {
+    return traceStorage.run({}, fn);
+}
+
+function getTraceContext() {
+    return traceStorage.getStore() || {};
+}
+
+module.exports = {
+    wrapOpenAI,
+    withTrace,
+    getTraceContext
+};
+

package/lib/store.js

@@ -0,0 +1,13 @@
+const { AsyncLocalStorage } = require('async_hooks');
+
+// Global storage for trace context (Request-scoped)
+const traceStorage = new AsyncLocalStorage();
+
+// Global registry for audited functions (Application-scoped)
+const auditedEntities = [];
+
+module.exports = {
+    traceStorage,
+    auditedEntities
+};
+

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@t54-labs/clawcredit-sdk",
+  "version": "0.1.0",
+  "description": "Integration SDK for Open Claw Agents to access ClawCredit",
+  "main": "index.js",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "uuid": "^9.0.0"
+  }
+}
+