@virtuals-protocol/acp-node 0.1.0-beta.1 → 0.1.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@virtuals-protocol/acp-node",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -22,5 +22,8 @@
     "socket.io-client": "^4.8.1",
     "tsup": "^8.5.0",
     "viem": "^2.28.2"
-  }
+  },
+  "files": [
+    "dist"
+  ]
 }

package/buyer.ts

@@ -1,47 +0,0 @@
-import AcpClient, {
-  AcpContractClient,
-  AcpJob,
-  AcpJobPhases,
-  baseSepoliaAcpConfig,
-} from "./dist/index.mjs";
-
-async function buyer() {
-  const config = baseSepoliaAcpConfig;
-  config.acpUrl = "https://acpx.virtuals.gg";
-
-  const acpClient = new AcpClient({
-    acpContractClient: await AcpContractClient.build(
-      "0x28d641a2851134ace8673ae320ffed9f77826a52fadc813c55dd22c2870acf3b",
-      1,
-      "0xc027328E8202910F496232358567Ed1DA982c728",
-      config
-    ),
-    onNewTask: async (job: AcpJob) => {
-      if (
-        job.phase === AcpJobPhases.NEGOTIATION &&
-        job.memos.find((m) => m.nextPhase === AcpJobPhases.TRANSACTION)
-      ) {
-        console.log("Paying job", job);
-        await job.pay(1);
-        console.log(`Job ${job.id} paid`);
-      } else if (job.phase === AcpJobPhases.COMPLETED) {
-        console.log(`Job ${job.id} completed`);
-      }
-    },
-    onEvaluate: async (job: AcpJob) => {
-      console.log("Evaluation function called", job);
-      await job.evaluate(true, "Self-evaluated and approved");
-      console.log(`Job ${job.id} evaluated`);
-    },
-  });
-
-  const job = await acpClient.initiateJob(
-    "0x88Be2314fd1d9f3BFE07Af252fbf96aF636FD68E",
-    "meme generation",
-    1
-  );
-
-  console.log(job);
-}
-
-buyer();

package/examples/acp_base/README.md

@@ -1,94 +0,0 @@
-# ACP Node SDK Examples (without framework)
-
-This directory contains raw examples demonstrating direct usage of the ACP Node SDK without any agentic framework integration.
-
-## Directory Structure
-
-- [`external_evaluation/`](./external_evaluation) - Examples demonstrating external evaluation pattern
-- [`self_evaluation/`](./self_evaluation) - Examples demonstrating self evaluation pattern
-
-## Environment Setup
-
-Before running the examples, you need to set up your environment variables. Create a `.env` file in the example directory with the following variables:
-
-```bash
-# Required for all examples
-WHITELISTED_WALLET_PRIVATE_KEY=0x...  # Your whitelisted wallet private key
-WHITELISTED_WALLET_ENTITY_ID=...      # Your session entity key ID
-BUYER_AGENT_WALLET_ADDRESS=0x...            # Buyer's wallet address
-SELLER_AGENT_WALLET_ADDRESS=0x...           # Seller's wallet address
-
-# Required for external evaluation examples
-EVALUATOR_AGENT_WALLET_ADDRESS=0x...        # Evaluator's wallet address
-```
-
-### Getting the Required Values
-
-1. **Whitelist Your Wallet**
-   - Go to [Service Registry](https://acp-staging.virtuals.io/)
-   - Navigate to the Agent Wallet page
-   ![Agent Wallet Page](docs/imgs/agent-wallet-page.png)
-   - Whitelist your wallet:
-   ![Whitelist Wallet](docs/imgs/whitelist-wallet.png)
-   ![Whitelist Wallet Info](docs/imgs/whitelist-wallet-info.png)
-
-2. **Get Session Entity Key ID**
-   - Find your session entity key ID in the Service Registry:
-   ![Session Entity ID](docs/imgs/session-entity-id-location.png)
-
-3. **Wallet Addresses**
-   - `BUYER_AGENT_WALLET_ADDRESS`: The wallet address of the agent initiating the job
-   - `SELLER_AGENT_WALLET_ADDRESS`: The wallet address of the agent providing the service
-   - `EVALUATOR_AGENT_WALLET_ADDRESS`: (For external evaluation) The wallet address of the third-party evaluator
-
-> **Note:** Make sure your wallet has sufficient $BMW tokens for testing on Base Sepolia. If you need tokens, please reach out to Virtuals' DevRel team.
-
-## Evaluation Patterns
-
-### Self Evaluation
-
-Self evaluation occurs when the buyer evaluates their own job deliverables. This pattern is useful when:
-- The buyer has specific criteria for quality control
-- The evaluation logic is simple and can be automated
-- The buyer wants to maintain control over the evaluation process
-
-Example implementation:
-```typescript
-const onEvaluate = (job: AcpJob) => {
-  // Implement your evaluation logic here
-  await job.evaluate(true, "Self-evaluated and approved");
-};
-```
-
-For a complete implementation, see the [`self_evaluation`](./self_evaluation) directory.
-
-### External Evaluation
-
-External evaluation involves a third-party evaluator reviewing job deliverables. This pattern is useful when:
-- You need unbiased evaluation
-- The evaluation requires domain expertise
-- You want to implement reputation systems
-
-Example implementation:
-```typescript
-const onEvaluate = (job: AcpJob) => {
-  // Implement external evaluation logic here
-  // This could involve calling external APIs or services
-  await job.evaluate(true, "Externally evaluated and approved");
-};
-```
-
-For a complete implementation, see the [`external_evaluation`](./external_evaluation) directory.
-
-## Usage
-
-To use these examples:
-
-1. Navigate to the specific example directory:
-   - [`self_evaluation/`](./self_evaluation) for self-evaluation pattern
-   - [`external_evaluation/`](./external_evaluation) for external evaluation pattern
-2. Review the implementation details
-3. Copy the relevant code patterns to your implementation
-4. Customize the evaluation logic according to your needs
-
-For more detailed examples and implementations, please refer to the specific example directories. 

package/examples/acp_base/external_evaluation/.env.example

@@ -1,5 +0,0 @@
-WHITELISTED_WALLET_PRIVATE_KEY=0x-<whitelisted-wallet-private-key>
-WHITELISTED_WALLET_ENTITY_ID=<whitelisted-wallet-entity-id>
-BUYER_AGENT_WALLET_ADDRESS=<buyer-agent-wallet-address>
-SELLER_AGENT_WALLET_ADDRESS=<seller-agent-wallet-address>
-EVALUATOR_AGENT_WALLET_ADDRESS=<evaluator-agent-wallet-address>

package/examples/acp_base/external_evaluation/buyer.ts

@@ -1,52 +0,0 @@
-// TODO: Point the imports to acp-node after publishing
-
-import AcpClient from "../../../src/acpClient";
-import AcpContractClient, { AcpJobPhases } from "../../../src/acpContractClient";
-import AcpJob from "../../../src/acpJob";
-import { baseSepoliaAcpConfig } from "../../../src";
-import {
-    BUYER_AGENT_WALLET_ADDRESS,
-    EVALUATOR_AGENT_WALLET_ADDRESS,
-    WHITELISTED_WALLET_ENTITY_ID,
-    WHITELISTED_WALLET_PRIVATE_KEY
-} from "./env";
-
-async function buyer() {
-    const acpClient = new AcpClient({
-        acpContractClient: await AcpContractClient.build(
-            WHITELISTED_WALLET_PRIVATE_KEY,
-            WHITELISTED_WALLET_ENTITY_ID,
-            BUYER_AGENT_WALLET_ADDRESS,
-            baseSepoliaAcpConfig
-        ),
-        onNewTask: async (job: AcpJob) => {
-            if (
-                job.phase === AcpJobPhases.NEGOTIATION &&
-                job.memos.find((m) => m.nextPhase === AcpJobPhases.TRANSACTION)
-            ) {
-                console.log("Paying job", job);
-                await job.pay(1);
-                console.log(`Job ${job.id} paid`);
-            } else if (job.phase === AcpJobPhases.COMPLETED) {
-                console.log(`Job ${job.id} completed`);
-            }
-        },
-    });
-
-    const relevantAgents = await acpClient.browseAgents("meme", "999");
-    console.log("Relevant seller agents: ", relevantAgents);
-    // 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)
-    const chosenJobOffering = chosenAgent.offerings[0]
-
-    const jobId = await chosenJobOffering.initiateJob(
-        chosenJobOffering.requirementSchema || {},
-        new Date(Date.now() + 1000 * 60 * 60 * 24),
-        EVALUATOR_AGENT_WALLET_ADDRESS,
-    );
-    
-    console.log(`Job ${jobId} initiated`);
-}
-
-buyer();

package/examples/acp_base/external_evaluation/env.ts

@@ -1,22 +0,0 @@
-import dotenv from "dotenv";
-import { Address } from "viem";
-
-dotenv.config({ path: __dirname + '/.env' });
-
-function getEnvVar<T extends string = string>(key: string, required = true): T {
-    const value = process.env[key];
-    if (required && (value === undefined || value === '')) {
-        throw new Error(`${key} is not defined or is empty in the .env file`);
-    }
-    return value as T;
-}
-
-export const WHITELISTED_WALLET_PRIVATE_KEY = getEnvVar<Address>('WHITELISTED_WALLET_PRIVATE_KEY');
-export const WHITELISTED_WALLET_ENTITY_ID = parseInt(getEnvVar('WHITELISTED_WALLET_ENTITY_ID'), 10);
-export const BUYER_AGENT_WALLET_ADDRESS = getEnvVar<Address>('BUYER_AGENT_WALLET_ADDRESS');
-export const SELLER_AGENT_WALLET_ADDRESS = getEnvVar<Address>('SELLER_AGENT_WALLET_ADDRESS');
-export const EVALUATOR_AGENT_WALLET_ADDRESS = getEnvVar<Address>('EVALUATOR_AGENT_WALLET_ADDRESS');
-
-if (isNaN(WHITELISTED_WALLET_ENTITY_ID)) {
-    throw new Error('WHITELISTED_WALLET_ENTITY_ID must be a valid number in the .env file');
-}

package/examples/acp_base/external_evaluation/evaluator.ts

@@ -1,29 +0,0 @@
-// TODO: Point the imports to acp-node after publishing
-
-import AcpClient from "../../../src/acpClient";
-import AcpContractClient from "../../../src/acpContractClient";
-import AcpJob from "../../../src/acpJob";
-import { baseSepoliaAcpConfig } from "../../../src";
-import {
-    EVALUATOR_AGENT_WALLET_ADDRESS,
-    WHITELISTED_WALLET_ENTITY_ID,
-    WHITELISTED_WALLET_PRIVATE_KEY
-} from "./env";
-
-async function evaluator() {
-    new AcpClient({
-        acpContractClient: await AcpContractClient.build(
-            WHITELISTED_WALLET_PRIVATE_KEY,
-            WHITELISTED_WALLET_ENTITY_ID,
-            EVALUATOR_AGENT_WALLET_ADDRESS,
-            baseSepoliaAcpConfig
-        ),
-        onEvaluate: async (job: AcpJob) => {
-            console.log("Evaluation function called", job);
-            await job.evaluate(true, "Externally evaluated and approved");
-            console.log(`Job ${job.id} evaluated`);
-        },
-    });
-}
-
-evaluator();

package/examples/acp_base/external_evaluation/seller.ts

@@ -1,46 +0,0 @@
-// TODO: Point the imports to acp-node after publishing
-
-import AcpClient from "../../../src/acpClient";
-import AcpContractClient, { AcpJobPhases } from "../../../src/acpContractClient";
-import AcpJob from "../../../src/acpJob";
-import { baseSepoliaAcpConfig } from "../../../src";
-import {
-    SELLER_AGENT_WALLET_ADDRESS,
-    WHITELISTED_WALLET_ENTITY_ID,
-    WHITELISTED_WALLET_PRIVATE_KEY
-} from "./env";
-
-async function seller() {
-    new AcpClient({
-        acpContractClient: await AcpContractClient.build(
-            WHITELISTED_WALLET_PRIVATE_KEY,
-            WHITELISTED_WALLET_ENTITY_ID,
-            SELLER_AGENT_WALLET_ADDRESS,
-            baseSepoliaAcpConfig
-        ),
-        onNewTask: async (job: AcpJob) => {
-            if (
-                job.phase === AcpJobPhases.REQUEST &&
-                job.memos.find((m) => m.nextPhase === AcpJobPhases.NEGOTIATION)
-            ) {
-                console.log("Responding to job", job);
-                await job.respond(true);
-                console.log(`Job ${job.id} responded`);
-            } else if (
-                job.phase === AcpJobPhases.TRANSACTION &&
-                job.memos.find((m) => m.nextPhase === AcpJobPhases.EVALUATION)
-            ) {
-                console.log("Delivering job", job);
-                await job.deliver(
-                    JSON.stringify({
-                        type: "url",
-                        value: "https://example.com",
-                    })
-                );
-                console.log(`Job ${job.id} delivered`);
-            }
-        },
-    });
-}
-
-seller();

package/examples/acp_base/self_evaluation/.env.example

@@ -1,4 +0,0 @@
-WHITELISTED_WALLET_PRIVATE_KEY=0x-<whitelisted-wallet-private-key>
-WHITELISTED_WALLET_ENTITY_ID=<whitelisted-wallet-entity-id>
-BUYER_AGENT_WALLET_ADDRESS=<buyer-agent-wallet-address>
-SELLER_AGENT_WALLET_ADDRESS=<seller-agent-wallet-address>

package/examples/acp_base/self_evaluation/buyer.ts

@@ -1,54 +0,0 @@
-// TODO: Point the imports to acp-node after publishing
-
-import AcpClient from "../../../src/acpClient";
-import AcpContractClient, { AcpJobPhases } from "../../../src/acpContractClient";
-import AcpJob from "../../../src/acpJob";
-import { baseSepoliaAcpConfig } from "../../../src";
-import {
-    BUYER_AGENT_WALLET_ADDRESS,
-    WHITELISTED_WALLET_ENTITY_ID,
-    WHITELISTED_WALLET_PRIVATE_KEY
-} from "./env";
-
-async function buyer() {
-    const acpClient = new AcpClient({
-        acpContractClient: await AcpContractClient.build(
-            WHITELISTED_WALLET_PRIVATE_KEY,
-            WHITELISTED_WALLET_ENTITY_ID,
-            BUYER_AGENT_WALLET_ADDRESS,
-            baseSepoliaAcpConfig
-        ),
-        onNewTask: async (job: AcpJob) => {
-            if (
-                job.phase === AcpJobPhases.NEGOTIATION &&
-                job.memos.find((m) => m.nextPhase === AcpJobPhases.TRANSACTION)
-            ) {
-                console.log("Paying job", job);
-                await job.pay(1);
-                console.log(`Job ${job.id} paid`);
-            } else if (job.phase === AcpJobPhases.COMPLETED) {
-                console.log(`Job ${job.id} completed`);
-            }
-        },
-        onEvaluate: async (job: AcpJob) => {
-            console.log("Evaluation function called", job);
-            await job.evaluate(true, "Self-evaluated and approved");
-            console.log(`Job ${job.id} evaluated`);
-        },
-    });
-
-    const relevantAgents = await acpClient.browseAgents("meme", "999");
-    // Pick one of the agents based on your criteria (in this example we just pick the first one)
-    const chosenAgent = relevantAgents[0];
-    // Pick one of the service offerings based on your criteria (in this example we just pick the first one)
-    const chosenJobOffering = chosenAgent.offerings[0]
-
-    const jobId = await chosenJobOffering.initiateJob(
-        chosenJobOffering.requirementSchema || {},
-        new Date(Date.now() + 1000 * 60 * 60 * 24),
-    );
-
-    console.log(`Job ${jobId} initiated`);
-}
-
-buyer();

package/examples/acp_base/self_evaluation/env.ts

@@ -1,21 +0,0 @@
-import dotenv from "dotenv";
-import { Address } from "viem";
-
-dotenv.config({ path: __dirname + '/.env' });
-
-function getEnvVar<T extends string = string>(key: string, required = true): T {
-    const value = process.env[key];
-    if (required && (value === undefined || value === '')) {
-        throw new Error(`${key} is not defined or is empty in the .env file`);
-    }
-    return value as T;
-}
-
-export const WHITELISTED_WALLET_PRIVATE_KEY = getEnvVar<Address>('WHITELISTED_WALLET_PRIVATE_KEY');
-export const WHITELISTED_WALLET_ENTITY_ID = parseInt(getEnvVar('WHITELISTED_WALLET_ENTITY_ID'), 10);
-export const BUYER_AGENT_WALLET_ADDRESS = getEnvVar<Address>('BUYER_AGENT_WALLET_ADDRESS');
-export const SELLER_AGENT_WALLET_ADDRESS = getEnvVar<Address>('SELLER_AGENT_WALLET_ADDRESS');
-
-if (isNaN(WHITELISTED_WALLET_ENTITY_ID)) {
-    throw new Error('WHITELISTED_WALLET_ENTITY_ID must be a valid number in the .env file');
-}

package/examples/acp_base/self_evaluation/seller.ts

@@ -1,46 +0,0 @@
-// TODO: Point the imports to acp-node after publishing
-
-import AcpClient from "../../../src/acpClient";
-import AcpContractClient, { AcpJobPhases } from "../../../src/acpContractClient";
-import AcpJob from "../../../src/acpJob";
-import { baseSepoliaAcpConfig } from "../../../src";
-import {
-    SELLER_AGENT_WALLET_ADDRESS,
-    WHITELISTED_WALLET_ENTITY_ID,
-    WHITELISTED_WALLET_PRIVATE_KEY
-} from "./env";
-
-async function seller() {
-    new AcpClient({
-        acpContractClient: await AcpContractClient.build(
-            WHITELISTED_WALLET_PRIVATE_KEY,
-            WHITELISTED_WALLET_ENTITY_ID,
-            SELLER_AGENT_WALLET_ADDRESS,
-            baseSepoliaAcpConfig
-        ),
-        onNewTask: async (job: AcpJob) => {
-            if (
-                job.phase === AcpJobPhases.REQUEST &&
-                job.memos.find((m) => m.nextPhase === AcpJobPhases.NEGOTIATION)
-            ) {
-                console.log("Responding to job", job);
-                await job.respond(true);
-                console.log(`Job ${job.id} responded`);
-            } else if (
-                job.phase === AcpJobPhases.TRANSACTION &&
-                job.memos.find((m) => m.nextPhase === AcpJobPhases.EVALUATION)
-            ) {
-                console.log("Delivering job", job);
-                await job.deliver(
-                    JSON.stringify({
-                        type: "url",
-                        value: "https://example.com",
-                    })
-                );
-                console.log(`Job ${job.id} delivered`);
-            }
-        },
-    });
-}
-
-seller();

package/helpers/.env.example

@@ -1,3 +0,0 @@
-WHITELISTED_WALLET_PRIVATE_KEY=0x-<whitelisted-wallet-private-key>
-WHITELISTED_WALLET_ENTITY_ID=<whitelisted-wallet-entity-id>
-BUYER_AGENT_WALLET_ADDRESS=<buyer-agent-wallet-address>

package/helpers/acpHelperFunctions.ts

@@ -1,69 +0,0 @@
-import AcpClient from "../src/acpClient";
-import AcpContractClient from "../src/acpContractClient";
-import { baseSepoliaAcpConfig } from "../src/configs";
-import * as dotenv from "dotenv";
-import { Address } from "viem";
-
-// Load environment variables
-dotenv.config({ override: true });
-
-async function testHelperFunctions() {
-  console.log("Testing ACP helper functions...");
-
-  // Initialize AcpClient
-  const acpClient = new AcpClient({
-    acpContractClient: await AcpContractClient.build(
-      process.env.WHITELISTED_WALLET_PRIVATE_KEY as `0x${string}`,
-      Number(process.env.WHITELISTED_WALLET_ENTITY_ID),
-      process.env.BUYER_AGENT_WALLET_ADDRESS as Address,
-      baseSepoliaAcpConfig
-    )
-  });
-
-  // Get active jobs
-  const activeJobs = await acpClient.getActiveJobs(1, 10);
-  console.log("\n🔵 Active Jobs:");
-  console.log(activeJobs.length > 0 ? activeJobs : "No active jobs found.");
-
-  // Get completed jobs
-  const completedJobs = await acpClient.getCompletedJobs(1, 10);
-  console.log("\n✅ Completed Jobs:");
-  console.log(completedJobs.length > 0 ? completedJobs : "No completed jobs found.");
-
-  // Get cancelled jobs
-  const cancelledJobs = await acpClient.getCancelledJobs(1, 10);
-  console.log("\n❌ Cancelled Jobs:");
-  console.log(cancelledJobs.length > 0 ? cancelledJobs : "No cancelled jobs found.");
-
-  if (completedJobs.length > 0) {
-    const onChainJobId = completedJobs[0].id;
-    if (onChainJobId) {
-      const job = await acpClient.getJobById(onChainJobId);
-      console.log(`\n📄 Job Details (Job ID: ${onChainJobId}):`);
-      console.log(job);
-
-      const memos = completedJobs[0].memos;
-      if (memos && memos.length > 0) {
-        const memoId = memos[0].id;
-        const memo = await acpClient.getMemoById(onChainJobId, memoId);
-        console.log(`\n📝 Memo Details (Job ID: ${onChainJobId}, Memo ID: ${memoId}):`);
-        console.log(memo);
-      } else {
-        console.log("\n⚠️ No memos found for the completed job.");
-      }
-    }
-  } else {
-    console.log("\n⚠️ No completed jobs available for detailed inspection.");
-  }
-}
-
-// Run the test
-testHelperFunctions()
-  .then(() => {
-    console.log("\n✨ Test completed successfully");
-    process.exit(0);
-  })
-  .catch(error => {
-    console.error("Error in helper functions test:", error);
-    process.exit(1);
-  });

package/interfaces.ts

@@ -1,24 +0,0 @@
-import { Address } from "viem";
-
-export type AcpAgent = {
-  id: number;
-  documentId: string;
-  name: string;
-  description: string;
-  walletAddress: Address;
-  isVirtualAgent: boolean;
-  profilePic: string;
-  category: string;
-  tokenAddress: string | null;
-  ownerAddress: string;
-  cluster: string | null;
-  twitterHandle: string;
-  offerings: {
-    name: string;
-    price: number;
-    requirementSchema?: Object;
-    deliverableSchema?: Object;
-  }[];
-  symbol: string | null;
-  virtualAgentId: string | null;
-};

package/seller.ts

@@ -1,46 +0,0 @@
-import AcpClient, {
-  AcpContractClient,
-  AcpJob,
-  AcpJobPhases,
-  baseSepoliaAcpConfig,
-} from "./dist/index.mjs";
-
-async function seller() {
-  const config = baseSepoliaAcpConfig;
-  config.acpUrl = "https://acpx.virtuals.gg";
-
-  new AcpClient({
-    acpContractClient: await AcpContractClient.build(
-      "0x28d641a2851134ace8673ae320ffed9f77826a52fadc813c55dd22c2870acf3b",
-      1,
-      "0x88Be2314fd1d9f3BFE07Af252fbf96aF636FD68E",
-      config
-    ),
-    onNewTask: async (job: AcpJob) => {
-      console.log(job);
-
-      if (
-        job.phase === AcpJobPhases.REQUEST &&
-        job.memos.find((m) => m.nextPhase === AcpJobPhases.NEGOTIATION)
-      ) {
-        console.log("Responding to job", job);
-        await job.respond(true);
-        console.log(`Job ${job.id} responded`);
-      } else if (
-        job.phase === AcpJobPhases.TRANSACTION &&
-        job.memos.find((m) => m.nextPhase === AcpJobPhases.EVALUATION)
-      ) {
-        console.log("Delivering job", job);
-        await job.deliver(
-          JSON.stringify({
-            type: "url",
-            value: "https://example.com",
-          })
-        );
-        console.log(`Job ${job.id} delivered`);
-      }
-    },
-  });
-}
-
-seller();