cronos-agent-wallet 1.2.2 → 1.2.4

package/README.md

@@ -2,6 +2,32 @@
 
 The official SDK for building AI agents that can pay for resources on the Cronos blockchain using the x402 protocol.
 
+## Architecture
+
+This SDK employs a **Hybrid "Exoskeleton" Architecture**:
+- **Off-Chain**: Fast, free logic enforcement and state tracking (MongoDB).
+- **On-Chain**: Immutable security anchors (Registry & Policy) to prevent tampering.
+
+```mermaid
+graph TD
+    subgraph Agent SDK
+      Local[Local Policy Engine]
+      Anchor[On-Chain Policy Anchor (read-only)]
+      Executor[x402 Payment Executor]
+    end
+
+    subgraph Merchant Middleware
+      MRegistry[Merchant Registry (read-only)]
+      Verifier[x402 Verification]
+    end
+
+    Local -->|Checks Hash| Anchor
+    Local -->|Approves| Executor
+    Executor -->|Signed Claim| Verifier
+    Verifier -->|Verifies Identity| MRegistry
+    Verifier -->|Payment Tx| Cronos[Cronos EVM]
+```
+
 ## 🛡️ Security Features (v1.1.1)
 - **Zero Trust Payer:** Derives identity strictly from chain data.
 - **Strong Replay Protection:** Enforces cryptographic binding of `merchantId + route + nonce`.
@@ -64,9 +90,23 @@ async function main() {
 | `chainId` | `number` | Yes | Chain ID (e.g., 338). Sent to backend for negotiation. |
 | `usdcAddress` | `string` | Yes | ERC20 Token Address used for payment. |
 | `dailyLimit` | `number` | No | Max USDC allowed to spend per 24h. Default: 1.0 |
+| `strictPolicy` | `boolean` | No | If `true`, Agent crashes if local config hash != on-chain hash. Default: `true`. |
+| `anchors` | `object` | No | On-chain registry addresses. Auto-filled for Cronos Testnet. |
+| `analyticsUrl` | `string` | No | URL for centralized logging of payment decisions (e.g. `https://api.myapp.com/analytics`). |
 | `allowedMerchants` | `string[]` | No | List of Merchant IDs to trust. If empty, allows all. |
 | `trustedFacilitators` | `string[]` | No | List of Gateway URLs to trust (e.g., localhost). |
 
+## 🛡️ Security Workflow (Strict Mode)
+
+When `strictPolicy` is `true`, you must register your configuration hash on-chain whenever you change limits.
+
+1.  **Define Limits**: Set `dailyLimit` in your code.
+2.  **Seal Policy**: Run the setup script to write the hash to the `AgentPolicyRegistry`.
+    ```bash
+    npx ts-node set_policy.ts
+    ```
+3.  **Run Agent**: The Agent verifies `Local Hash == On-Chain Hash` before making any payment.
+
 ## API Reference
 
 ### `agent.fetch<T>(url, options): Promise<T>`

package/dist/AgentClient.js

@@ -28,12 +28,7 @@ class AgentClient {
         // 1. Create executor (chain-specific)
         const executor = new CronosUsdcExecutor_1.CronosUsdcExecutor(config.rpcUrl, config.privateKey, config.usdcAddress, config.chainId);
         // 2. Create wallet (policy + persistence)
-        this.wallet = new AgentWallet_1.AgentWallet(executor.getAddress(), executor, {
-            dailyLimit: config.dailyLimit,
-            maxPerTransaction: config.maxPerTransaction,
-            trustedFacilitators: config.trustedFacilitators,
-            allowedMerchants: config.allowedMerchants,
-        });
+        this.wallet = new AgentWallet_1.AgentWallet(executor.getAddress(), executor, executor.getProvider(), executor.getSigner(), config);
         // 3. Context passed per request
         this.context = {
             chainId: config.chainId,

package/dist/config.d.ts

@@ -1,3 +1,8 @@
+export interface OnChainAnchors {
+    merchantRegistry?: string;
+    agentPolicyRegistry?: string;
+    policyVerifier?: string;
+}
 export interface AgentConfig {
     privateKey: string;
     rpcUrl: string;
@@ -8,5 +13,15 @@ export interface AgentConfig {
     allowedMerchants?: string[];
     trustedFacilitators?: string[];
     analyticsUrl?: string;
+    anchors?: OnChainAnchors;
+    strictPolicy?: boolean;
     merchantId?: string;
 }
+export declare const AGENT_CONFIG_DEFAULTS: {
+    anchors: {
+        merchantRegistry: string;
+        agentPolicyRegistry: string;
+        policyVerifier: string;
+    };
+    strictPolicy: boolean;
+};

package/dist/config.js

@@ -1,2 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_CONFIG_DEFAULTS = void 0;
+exports.AGENT_CONFIG_DEFAULTS = {
+    // Cronos Testnet Anchors
+    anchors: {
+        merchantRegistry: "0x1948175dDB81DA08a4cf17BE4E0C95B97dD11F5c",
+        agentPolicyRegistry: "0xce3b58c9ae8CA4724d6FA8684d2Cb89546FF4E43",
+        policyVerifier: "0xFCb2D2279256B62A1E4E07BCDed26B6546bBc33b"
+    },
+    strictPolicy: true // 🛡️ ENFORCE: Agent will fail if policy hash mismatches chain
+};

package/dist/internal/AgentWallet.d.ts

@@ -1,5 +1,7 @@
-import { PaymentRequest, WalletContext, AgentWalletConfig } from "./types";
+import { PaymentRequest, WalletContext } from "./types";
 import { PaymentExecutor } from "./executors";
+import { AgentConfig } from "../config";
+import { ethers } from "ethers";
 /**
  * AgentWallet
  * ------------
@@ -12,6 +14,9 @@ import { PaymentExecutor } from "./executors";
 export declare class AgentWallet {
     private readonly address;
     private readonly executor;
+    private readonly provider;
+    private readonly wallet;
+    private readonly config;
     private dailyLimit;
     private maxPerTransaction;
     private spentToday;
@@ -20,16 +25,25 @@ export declare class AgentWallet {
     private trustedFacilitatorOrigins;
     private stopped;
     private isInitialized;
+    /**
+     * Replay protection
+     * key -> timestamp
+     */
     /**
      * Replay protection
      * key -> timestamp
      */
     private paidRequests;
-    constructor(address: string, executor: PaymentExecutor, config?: AgentWalletConfig);
+    private policyRegistry?;
+    constructor(address: string, executor: PaymentExecutor, provider: ethers.Provider, wallet: ethers.Wallet, config: AgentConfig);
     private getTodayDate;
     init(): Promise<void>;
     private loadState;
     private saveState;
+    /**
+     * Checks if the local policy matches the on-chain anchor.
+     */
+    private verifyPolicyAnchor;
     getAddress(): string;
     private getHeader;
     private canonicalOrigin;

package/dist/internal/AgentWallet.js

@@ -4,6 +4,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentWallet = void 0;
+const PolicyRegistryAdapter_1 = require("./PolicyRegistryAdapter");
+const ethers_1 = require("ethers");
+// Helper to hash policy config
+function hashPolicy(config) {
+    const policyData = {
+        dailyLimit: config.dailyLimit || 0,
+        maxPerTransaction: config.maxPerTransaction || 0
+    };
+    return ethers_1.ethers.keccak256(ethers_1.ethers.toUtf8Bytes(JSON.stringify(policyData)));
+}
 const mongoose_1 = __importDefault(require("mongoose"));
 const models_1 = require("./models");
 /**
@@ -18,6 +28,9 @@ const models_1 = require("./models");
 class AgentWallet {
     address;
     executor;
+    provider;
+    wallet;
+    config;
     // ---------------- CONFIG ----------------
     // Reduced limit for testing persistence (0.5 USDC)
     dailyLimit = 0.5;
@@ -33,14 +46,23 @@ class AgentWallet {
     ]);
     stopped = false;
     isInitialized = false;
+    /**
+     * Replay protection
+     * key -> timestamp
+     */
     /**
      * Replay protection
      * key -> timestamp
      */
     paidRequests = new Map();
-    constructor(address, executor, config) {
+    // On-Chain Adapter
+    policyRegistry;
+    constructor(address, executor, provider, wallet, config) {
         this.address = address;
         this.executor = executor;
+        this.provider = provider;
+        this.wallet = wallet;
+        this.config = config;
         if (config) {
             if (config.dailyLimit !== undefined)
                 this.dailyLimit = config.dailyLimit;
@@ -50,6 +72,17 @@ class AgentWallet {
                 this.allowedMerchants = new Set(config.allowedMerchants);
             if (config.trustedFacilitators)
                 this.trustedFacilitatorOrigins = new Set(config.trustedFacilitators);
+            // Initialize On-Chain Adapter if configured
+            if (config.anchors?.agentPolicyRegistry) {
+                this.policyRegistry = new PolicyRegistryAdapter_1.PolicyRegistryAdapter(config.anchors.agentPolicyRegistry, provider, wallet);
+                // Non-blocking check for setup/warning
+                this.verifyPolicyAnchor().catch(err => {
+                    console.error("[AgentWallet] Policy Anchor Warning:", err.message);
+                    if (config.strictPolicy) {
+                        process.exit(1); // Strict mode: fail fast
+                    }
+                });
+            }
         }
         this.lastResetDate = this.getTodayDate();
     }
@@ -141,6 +174,42 @@ class AgentWallet {
             console.error("[WALLET] Failed to save state to DB", error);
         }
     }
+    /**
+     * Checks if the local policy matches the on-chain anchor.
+     */
+    async verifyPolicyAnchor() {
+        if (!this.policyRegistry)
+            return;
+        try {
+            console.log("[AgentWallet] Verifying policy against on-chain anchor...");
+            const onChain = await this.policyRegistry.getPolicy(this.address);
+            // Check 1: Freeze status
+            if (onChain.isFrozen) {
+                this.stopped = true;
+                throw new Error("Agent policy is FROZEN on-chain. Emergency stop activated.");
+            }
+            // Check 2: Hash mismatch
+            const localHash = hashPolicy(this.config);
+            // Note: We check if on-chain hash is set (non-zero) before enforcing
+            if (onChain.policyHash !== ethers_1.ethers.ZeroHash && onChain.policyHash !== localHash) {
+                const msg = `Policy Hash Mismatch! Local: ${localHash}, Chain: ${onChain.policyHash}`;
+                if (this.config?.strictPolicy) {
+                    throw new Error(msg);
+                }
+                else {
+                    console.warn(`[AgentWallet] WARN: ${msg}. Running in PERMISSIVE mode.`);
+                }
+            }
+            else {
+                console.log("[AgentWallet] ✅ Policy verified on-chain.");
+            }
+        }
+        catch (error) {
+            console.error("[AgentWallet] Anchor check failed:", error.message);
+            if (this.config?.strictPolicy)
+                throw error;
+        }
+    }
     // ---------------- PUBLIC ----------------
     getAddress() {
         return this.address;

package/dist/internal/CronosUsdcExecutor.d.ts

@@ -1,4 +1,5 @@
 import "dotenv/config";
+import { ethers } from "ethers";
 import { PaymentExecutor } from "./executors";
 import { PaymentRequest } from "./types";
 export declare class CronosUsdcExecutor implements PaymentExecutor {
@@ -11,4 +12,6 @@ export declare class CronosUsdcExecutor implements PaymentExecutor {
     private withRetry;
     execute(request: PaymentRequest): Promise<string>;
     getAddress(): string;
+    getProvider(): ethers.JsonRpcProvider;
+    getSigner(): ethers.Wallet;
 }

package/dist/internal/CronosUsdcExecutor.js

@@ -114,5 +114,11 @@ nonce = ${request.nonce}`);
     getAddress() {
         return this.wallet.address;
     }
+    getProvider() {
+        return this.provider;
+    }
+    getSigner() {
+        return this.wallet;
+    }
 }
 exports.CronosUsdcExecutor = CronosUsdcExecutor;

package/dist/internal/PolicyRegistryAdapter.d.ts

@@ -0,0 +1,32 @@
+import { ethers, Provider, Wallet } from "ethers";
+export interface OnChainPolicy {
+    dailySpendLimit: bigint;
+    maxPerTransaction: bigint;
+    policyHash: string;
+    isFrozen: boolean;
+    lastUpdated: bigint;
+}
+export interface PolicyInput {
+    dailySpendLimit: bigint;
+    maxPerTransaction: bigint;
+    policyHash: string;
+}
+export declare class PolicyRegistryAdapter {
+    private address;
+    private provider;
+    private signer?;
+    private contract;
+    constructor(address: string, provider: Provider, signer?: Wallet | undefined);
+    /**
+     * Reads the policy for the given agent from the blockchain.
+     * @param agentAddress The address to query
+     * @returns The policy struct or null if not found
+     */
+    getPolicy(agentAddress: string): Promise<OnChainPolicy>;
+    /**
+     * Writes the policy to the blockchain.
+     * @warning This is a gas-consuming transaction.
+     * @warning Should strictly be used during SETUP or RECOVERY, not during normal agent operation.
+     */
+    setPolicy(policy: PolicyInput): Promise<ethers.TransactionReceipt>;
+}

package/dist/internal/PolicyRegistryAdapter.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyRegistryAdapter = void 0;
+const ethers_1 = require("ethers");
+const ABI = [
+    "function getPolicy(address agentAddress) external view returns (uint256 dailySpendLimit, uint256 maxPerTransaction, bytes32 policyHash, bool isFrozen, uint256 lastUpdated)",
+    "function setPolicy(uint256 dailySpendLimit, uint256 maxPerTransaction, bytes32 policyHash) external",
+    "event PolicySet(address indexed agent, uint256 dailySpendLimit, uint256 maxPerTransaction, bytes32 policyHash, uint256 timestamp)"
+];
+class PolicyRegistryAdapter {
+    address;
+    provider;
+    signer;
+    contract;
+    constructor(address, provider, signer) {
+        this.address = address;
+        this.provider = provider;
+        this.signer = signer;
+        this.contract = new ethers_1.Contract(address, ABI, signer || provider);
+    }
+    /**
+     * Reads the policy for the given agent from the blockchain.
+     * @param agentAddress The address to query
+     * @returns The policy struct or null if not found
+     */
+    async getPolicy(agentAddress) {
+        return this.contract.getPolicy(agentAddress);
+    }
+    /**
+     * Writes the policy to the blockchain.
+     * @warning This is a gas-consuming transaction.
+     * @warning Should strictly be used during SETUP or RECOVERY, not during normal agent operation.
+     */
+    async setPolicy(policy) {
+        if (!this.signer) {
+            throw new Error("PolicyRegistryAdapter: No signer available for setPolicy");
+        }
+        // Runtime Guard: We add a parameter or check logic to prevent accidental usage.
+        // For now, explicit naming and documentation is the primary guard, plus the requirement of a signer.
+        const tx = await this.contract.setPolicy(policy.dailySpendLimit, policy.maxPerTransaction, policy.policyHash);
+        return tx.wait();
+    }
+}
+exports.PolicyRegistryAdapter = PolicyRegistryAdapter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cronos-agent-wallet",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [