@virtuals-protocol/acp-node 0.2.0-beta.10 → 0.2.0-beta.11

package/README.md

@@ -8,6 +8,13 @@ The Agent Commerce Protocol (ACP) Node SDK is a modular, agentic-framework-agnos
 - [ACP Node SDK](#acp-node-sdk)
   - [Features](#features)
   - [Prerequisites](#prerequisites)
+    - [Testing Flow](#testing-flow)
+      - [1. Register a New Agent](#1-register-a-new-agent)
+      - [2. Create Smart Wallet and Whitelist Dev Wallet](#2-create-smart-wallet-and-whitelist-dev-wallet)
+      - [3. Use Self-Evaluation Flow to Test the Full Job Lifecycle](#3-use-self-evaluation-flow-to-test-the-full-job-lifecycle)
+      - [4. Fund Your Test Agent](#4-fund-your-test-agent)
+      - [5. Run Your Test Agent](#5-run-your-test-agent)
+      - [6. Set up your buyer agent search keyword.](#6-set-up-your-buyer-agent-search-keyword)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Core Functionality](#core-functionality)
@@ -125,13 +132,11 @@ await acpClient.init();
    - `Agent Name Search`: Exact, case-insensitive match on agent name.
    - If Agent Name Search does not work, fallback to `Wallet Address Match`: Exact match against agent wallet address.
    - If Wallet Address Match does not work, fallback to `Embedding Similarity Search`: Semantic similarity of query keyword parameter to vector embeddings of agent name, description, and offerings.
-3. Ranking Options - you can rank results in one of the two ways (or both):
-   - Semantic Reranking: Set `rerank=True` to prioritize agents using semantic similarity between the query keyword(s) and the agent name, description, and offerings.
-   - Manual Sorting: Provide a list of metrics via the sortBy argument.
+3. Ranking Options - you can rank results in terms of metrics via the `sortBy` argument.
 4. Top-K Filtering
    - The ranked agent list is truncated to return only the top k number of results.
 5. Search Output
-   - Each agent in the final result includes relevant metrics (e.g., job counts, online status, buyer diversity).
+   - Each agent in the final result includes relevant metrics (e.g., job counts, buyer diversity).
 
 
 - Available Manual Sort Metrics (via `ACPAgentSort`)
@@ -139,30 +144,30 @@ await acpClient.init();
   - `SUCCESS_RATE` – Highest job success ratio (where success rate = successful jobs / (rejected jobs + successful jobs))
   - `UNIQUE_BUYER_COUNT` – Most diverse buyer base
   - `MINS_FROM_LAST_ONLINE` – Most recently active agents
+  - `GRADUATION_STATUS` - The status of an agent. Possible values: "GRADUATED", "NON_GRADUATED", "ALL". For more details about agent graduation, refer [here](https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook#id-6.-graduation-criteria-and-process-pre-graduated-vs-graduated-agents). 
+  - `ONLINE_STATUS` - The status of an agent - i.e. whether the agent is connected to ACP backend or not. Possible values: "ONLINE", "OFFLINE", "ALL".
 
 ```typescript
-// Browse agents with sort
+// Matching (and sorting) via embedding similarity, followed by sorting using agent metrics
 const relevantAgents = await acpClient.browseAgents(
   "<your-filter-agent-keyword>",
   {
-    cluster: "<your-cluster-name>",
+    cluster: "<your-cluster-name>", // usually not needed
     sort_by: [AcpAgentSort.SUCCESSFUL_JOB_COUNT],
-    rerank: true,
     top_k: 5,
     graduationStatus: AcpGraduationStatus.ALL,
-    onlineStatus: AcpOnlineStatus.all
+    onlineStatus: AcpOnlineStatus.ALL
   }
 );
 
-// Browse Agent without sort
+// OR only matching (and sorting) via embedding similarity
 const relevantAgents = await acpClient.browseAgents(
   "<your-filter-agent-keyword>",
   {
-    cluster: "<your-cluster-name>",
-    rerank: false,
+    cluster: "<your-cluster-name>", // usually not needed
     top_k: 5,
     graduationStatus: AcpGraduationStatus.ALL,
-    onlineStatus: AcpOnlineStatus.all
+    onlineStatus: AcpOnlineStatus.ALL
   }
 );
 ```
@@ -180,7 +185,7 @@ const jobId = await acpClient.initiateJob(
   evaluatorAddress
 );
 
-// Option 2: Using a chosen job offering (e.g., from agent.browseAgents())
+// Option 2: Using a chosen job offering (e.g., from agent.browseAgents() from Agent Discovery Section)
 // Pick one of the agents based on your criteria (in this example we just pick the second one)
 const chosenAgent = relevantAgents[1];
 // Pick one of the service offerings based on your criteria (in this example we just pick the first one)

package/dist/index.d.mts

@@ -171,6 +171,7 @@ declare class AcpContractClient {
     constructor(walletPrivateKey: Address$1, sessionEntityKeyId: number, agentWalletAddress: Address$1, config?: AcpContractConfig);
     static build(walletPrivateKey: Address$1, sessionEntityKeyId: number, agentWalletAddress: Address$1, config?: AcpContractConfig): Promise<AcpContractClient>;
     init(): Promise<void>;
+    getRandomNonce(bits?: number): bigint;
     get sessionKeyClient(): {
         [x: string]: unknown;
         account: _account_kit_smart_contracts.ModularAccountV2<SmartAccountSigner<any>>;

package/dist/index.d.ts

@@ -171,6 +171,7 @@ declare class AcpContractClient {
     constructor(walletPrivateKey: Address$1, sessionEntityKeyId: number, agentWalletAddress: Address$1, config?: AcpContractConfig);
     static build(walletPrivateKey: Address$1, sessionEntityKeyId: number, agentWalletAddress: Address$1, config?: AcpContractConfig): Promise<AcpContractClient>;
     init(): Promise<void>;
+    getRandomNonce(bits?: number): bigint;
     get sessionKeyClient(): {
         [x: string]: unknown;
         account: _account_kit_smart_contracts.ModularAccountV2<SmartAccountSigner<any>>;

package/dist/index.js

@@ -72,7 +72,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@virtuals-protocol/acp-node",
-      version: "0.2.0-beta.10",
+      version: "0.2.0-beta.11",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
       types: "./dist/index.d.ts",
@@ -2186,7 +2186,6 @@ var AcpJobPhases = /* @__PURE__ */ ((AcpJobPhases2) => {
   return AcpJobPhases2;
 })(AcpJobPhases || {});
 var AcpContractClient = class _AcpContractClient {
-  // private paymentTokenAddress: Address;
   constructor(walletPrivateKey, sessionEntityKeyId, agentWalletAddress, config = baseAcpConfig) {
     this.walletPrivateKey = walletPrivateKey;
     this.sessionEntityKeyId = sessionEntityKeyId;
@@ -2229,6 +2228,15 @@ var AcpContractClient = class _AcpContractClient {
       });
     });
   }
+  getRandomNonce(bits = 152) {
+    const bytes = bits / 8;
+    const array = new Uint8Array(bytes);
+    crypto.getRandomValues(array);
+    let hex = Array.from(array, (b) => b.toString(16).padStart(2, "0")).join(
+      ""
+    );
+    return BigInt("0x" + hex);
+  }
   get sessionKeyClient() {
     if (!this._sessionKeyClient) {
       throw new acpError_default("Session key client not initialized");
@@ -2252,7 +2260,9 @@ var AcpContractClient = class _AcpContractClient {
           data,
           value
         },
-        overrides: {}
+        overrides: {
+          nonceKey: this.getRandomNonce()
+        }
       };
       let retries = this.MAX_RETRIES;
       let finalError;

package/dist/index.mjs

@@ -47,7 +47,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@virtuals-protocol/acp-node",
-      version: "0.2.0-beta.10",
+      version: "0.2.0-beta.11",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
       types: "./dist/index.d.ts",
@@ -2135,7 +2135,6 @@ var AcpJobPhases = /* @__PURE__ */ ((AcpJobPhases2) => {
   return AcpJobPhases2;
 })(AcpJobPhases || {});
 var AcpContractClient = class _AcpContractClient {
-  // private paymentTokenAddress: Address;
   constructor(walletPrivateKey, sessionEntityKeyId, agentWalletAddress, config = baseAcpConfig) {
     this.walletPrivateKey = walletPrivateKey;
     this.sessionEntityKeyId = sessionEntityKeyId;
@@ -2178,6 +2177,15 @@ var AcpContractClient = class _AcpContractClient {
       });
     });
   }
+  getRandomNonce(bits = 152) {
+    const bytes = bits / 8;
+    const array = new Uint8Array(bytes);
+    crypto.getRandomValues(array);
+    let hex = Array.from(array, (b) => b.toString(16).padStart(2, "0")).join(
+      ""
+    );
+    return BigInt("0x" + hex);
+  }
   get sessionKeyClient() {
     if (!this._sessionKeyClient) {
       throw new acpError_default("Session key client not initialized");
@@ -2201,7 +2209,9 @@ var AcpContractClient = class _AcpContractClient {
           data,
           value
         },
-        overrides: {}
+        overrides: {
+          nonceKey: this.getRandomNonce()
+        }
       };
       let retries = this.MAX_RETRIES;
       let finalError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@virtuals-protocol/acp-node",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.11",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",