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

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>>;
@@ -8427,11 +8428,12 @@ declare class AcpMemo {
     content: string;
     nextPhase: AcpJobPhases;
     status: AcpMemoStatus;
+    senderAddress: Address;
     signedReason?: string | undefined;
     expiry?: Date | undefined;
     payableDetails?: PayableDetails | undefined;
     structuredContent: GenericPayload | undefined;
-    constructor(acpClient: AcpClient, id: number, type: MemoType, content: string, nextPhase: AcpJobPhases, status: AcpMemoStatus, signedReason?: string | undefined, expiry?: Date | undefined, payableDetails?: PayableDetails | undefined);
+    constructor(acpClient: AcpClient, id: number, type: MemoType, content: string, nextPhase: AcpJobPhases, status: AcpMemoStatus, senderAddress: Address, signedReason?: string | undefined, expiry?: Date | undefined, payableDetails?: PayableDetails | undefined);
     get payloadType(): PayloadType | undefined;
     getStructuredContent<T>(): GenericPayload<T> | undefined;
     create(jobId: number, isSecured?: boolean): Promise<`0x${string}`>;
@@ -8673,6 +8675,7 @@ declare class AcpClient {
     responseFundsTransfer(memoId: number, accept: boolean, reason?: string): Promise<`0x${string}`>;
     deliverJob(jobId: number, deliverable: IDeliverable): Promise<`0x${string}`>;
     getActiveJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
+    getPendingMemoJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCompletedJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCancelledJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getJobById(jobId: number): Promise<AcpJob | undefined>;

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>>;
@@ -8427,11 +8428,12 @@ declare class AcpMemo {
     content: string;
     nextPhase: AcpJobPhases;
     status: AcpMemoStatus;
+    senderAddress: Address;
     signedReason?: string | undefined;
     expiry?: Date | undefined;
     payableDetails?: PayableDetails | undefined;
     structuredContent: GenericPayload | undefined;
-    constructor(acpClient: AcpClient, id: number, type: MemoType, content: string, nextPhase: AcpJobPhases, status: AcpMemoStatus, signedReason?: string | undefined, expiry?: Date | undefined, payableDetails?: PayableDetails | undefined);
+    constructor(acpClient: AcpClient, id: number, type: MemoType, content: string, nextPhase: AcpJobPhases, status: AcpMemoStatus, senderAddress: Address, signedReason?: string | undefined, expiry?: Date | undefined, payableDetails?: PayableDetails | undefined);
     get payloadType(): PayloadType | undefined;
     getStructuredContent<T>(): GenericPayload<T> | undefined;
     create(jobId: number, isSecured?: boolean): Promise<`0x${string}`>;
@@ -8673,6 +8675,7 @@ declare class AcpClient {
     responseFundsTransfer(memoId: number, accept: boolean, reason?: string): Promise<`0x${string}`>;
     deliverJob(jobId: number, deliverable: IDeliverable): Promise<`0x${string}`>;
     getActiveJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
+    getPendingMemoJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCompletedJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCancelledJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getJobById(jobId: number): Promise<AcpJob | undefined>;

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.12",
       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;
@@ -2939,13 +2949,14 @@ var acpJob_default = AcpJob;
 
 // src/acpMemo.ts
 var AcpMemo = class {
-  constructor(acpClient, id, type, content, nextPhase, status, signedReason, expiry, payableDetails) {
+  constructor(acpClient, id, type, content, nextPhase, status, senderAddress, signedReason, expiry, payableDetails) {
     this.acpClient = acpClient;
     this.id = id;
     this.type = type;
     this.content = content;
     this.nextPhase = nextPhase;
     this.status = status;
+    this.senderAddress = senderAddress;
     this.signedReason = signedReason;
     this.expiry = expiry;
     this.payableDetails = payableDetails;
@@ -3086,6 +3097,7 @@ var AcpClient = class {
                   memo.content,
                   memo.nextPhase,
                   memo.status,
+                  memo.senderAddress,
                   memo.signedReason,
                   memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                   memo.payableDetails
@@ -3119,6 +3131,7 @@ var AcpClient = class {
                   memo.content,
                   memo.nextPhase,
                   memo.status,
+                  memo.senderAddress,
                   memo.signedReason,
                   memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                   memo.payableDetails
@@ -3365,6 +3378,7 @@ var AcpClient = class {
                 memo.content,
                 memo.nextPhase,
                 memo.status,
+                memo.senderAddress,
                 memo.signedReason,
                 memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                 memo.payableDetails
@@ -3379,6 +3393,51 @@ var AcpClient = class {
       }
     });
   }
+  getPendingMemoJobs(page = 1, pageSize = 10) {
+    return __async(this, null, function* () {
+      let url = `${this.acpUrl}/api/jobs/pending-memos?pagination[page]=${page}&pagination[pageSize]=${pageSize}`;
+      try {
+        const response = yield fetch(url, {
+          headers: {
+            "wallet-address": this.acpContractClient.walletAddress
+          }
+        });
+        const data = yield response.json();
+        if (data.error) {
+          throw new acpError_default(data.error.message);
+        }
+        return data.data.map((job) => {
+          return new acpJob_default(
+            this,
+            job.id,
+            job.clientAddress,
+            job.providerAddress,
+            job.evaluatorAddress,
+            job.price,
+            job.priceTokenAddress,
+            job.memos.map((memo) => {
+              return new acpMemo_default(
+                this,
+                memo.id,
+                memo.memoType,
+                memo.content,
+                memo.nextPhase,
+                memo.status,
+                memo.senderAddress,
+                memo.signedReason,
+                memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
+                typeof memo.payableDetails === "string" ? tryParseJson(memo.payableDetails) || void 0 : memo.payableDetails
+              );
+            }),
+            job.phase,
+            job.context
+          );
+        });
+      } catch (error) {
+        throw new acpError_default("Failed to get pending memo jobs", error);
+      }
+    });
+  }
   getCompletedJobs(page = 1, pageSize = 10) {
     return __async(this, null, function* () {
       let url = `${this.acpUrl}/api/jobs/completed?pagination[page]=${page}&pagination[pageSize]=${pageSize}`;
@@ -3409,6 +3468,7 @@ var AcpClient = class {
                 memo.content,
                 memo.nextPhase,
                 memo.status,
+                memo.senderAddress,
                 memo.signedReason,
                 memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                 memo.payableDetails
@@ -3453,6 +3513,7 @@ var AcpClient = class {
                 memo.content,
                 memo.nextPhase,
                 memo.status,
+                memo.senderAddress,
                 memo.signedReason,
                 memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                 memo.payableDetails
@@ -3500,6 +3561,7 @@ var AcpClient = class {
               memo.content,
               memo.nextPhase,
               memo.status,
+              memo.senderAddress,
               memo.signedReason,
               memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
               memo.payableDetails
@@ -3537,6 +3599,7 @@ var AcpClient = class {
           memo.content,
           memo.nextPhase,
           memo.status,
+          memo.senderAddress,
           memo.signedReason,
           memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
           memo.payableDetails

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.12",
       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;
@@ -2888,13 +2898,14 @@ var acpJob_default = AcpJob;
 
 // src/acpMemo.ts
 var AcpMemo = class {
-  constructor(acpClient, id, type, content, nextPhase, status, signedReason, expiry, payableDetails) {
+  constructor(acpClient, id, type, content, nextPhase, status, senderAddress, signedReason, expiry, payableDetails) {
     this.acpClient = acpClient;
     this.id = id;
     this.type = type;
     this.content = content;
     this.nextPhase = nextPhase;
     this.status = status;
+    this.senderAddress = senderAddress;
     this.signedReason = signedReason;
     this.expiry = expiry;
     this.payableDetails = payableDetails;
@@ -3035,6 +3046,7 @@ var AcpClient = class {
                   memo.content,
                   memo.nextPhase,
                   memo.status,
+                  memo.senderAddress,
                   memo.signedReason,
                   memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                   memo.payableDetails
@@ -3068,6 +3080,7 @@ var AcpClient = class {
                   memo.content,
                   memo.nextPhase,
                   memo.status,
+                  memo.senderAddress,
                   memo.signedReason,
                   memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                   memo.payableDetails
@@ -3314,6 +3327,7 @@ var AcpClient = class {
                 memo.content,
                 memo.nextPhase,
                 memo.status,
+                memo.senderAddress,
                 memo.signedReason,
                 memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                 memo.payableDetails
@@ -3328,6 +3342,51 @@ var AcpClient = class {
       }
     });
   }
+  getPendingMemoJobs(page = 1, pageSize = 10) {
+    return __async(this, null, function* () {
+      let url = `${this.acpUrl}/api/jobs/pending-memos?pagination[page]=${page}&pagination[pageSize]=${pageSize}`;
+      try {
+        const response = yield fetch(url, {
+          headers: {
+            "wallet-address": this.acpContractClient.walletAddress
+          }
+        });
+        const data = yield response.json();
+        if (data.error) {
+          throw new acpError_default(data.error.message);
+        }
+        return data.data.map((job) => {
+          return new acpJob_default(
+            this,
+            job.id,
+            job.clientAddress,
+            job.providerAddress,
+            job.evaluatorAddress,
+            job.price,
+            job.priceTokenAddress,
+            job.memos.map((memo) => {
+              return new acpMemo_default(
+                this,
+                memo.id,
+                memo.memoType,
+                memo.content,
+                memo.nextPhase,
+                memo.status,
+                memo.senderAddress,
+                memo.signedReason,
+                memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
+                typeof memo.payableDetails === "string" ? tryParseJson(memo.payableDetails) || void 0 : memo.payableDetails
+              );
+            }),
+            job.phase,
+            job.context
+          );
+        });
+      } catch (error) {
+        throw new acpError_default("Failed to get pending memo jobs", error);
+      }
+    });
+  }
   getCompletedJobs(page = 1, pageSize = 10) {
     return __async(this, null, function* () {
       let url = `${this.acpUrl}/api/jobs/completed?pagination[page]=${page}&pagination[pageSize]=${pageSize}`;
@@ -3358,6 +3417,7 @@ var AcpClient = class {
                 memo.content,
                 memo.nextPhase,
                 memo.status,
+                memo.senderAddress,
                 memo.signedReason,
                 memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                 memo.payableDetails
@@ -3402,6 +3462,7 @@ var AcpClient = class {
                 memo.content,
                 memo.nextPhase,
                 memo.status,
+                memo.senderAddress,
                 memo.signedReason,
                 memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
                 memo.payableDetails
@@ -3449,6 +3510,7 @@ var AcpClient = class {
               memo.content,
               memo.nextPhase,
               memo.status,
+              memo.senderAddress,
               memo.signedReason,
               memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
               memo.payableDetails
@@ -3486,6 +3548,7 @@ var AcpClient = class {
           memo.content,
           memo.nextPhase,
           memo.status,
+          memo.senderAddress,
           memo.signedReason,
           memo.expiry ? new Date(parseInt(memo.expiry) * 1e3) : void 0,
           memo.payableDetails

package/package.json

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