game-by-virtuals · Zuhwa · Aug 1, 2025 · Aug 1, 2025
diff --git a/plugins/acpPlugin/.npmignore b/plugins/acpPlugin/.npmignore
@@ -0,0 +1,3 @@
+src
+example
+tsconfig.json
diff --git a/plugins/acpPlugin/README.md b/plugins/acpPlugin/README.md
@@ -0,0 +1,281 @@
+# ACP Plugin
+
+<details>
+<summary>Table of Contents</summary>
+
+- [ACP Plugin](#acp-plugin)
+  - [Prerequisite](#prerequisite)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Functions](#functions)
+  - [Agent Registry](#agent-registry)
+  - [State Management Tooling](#state-management-tooling)
+  - [Useful Resources](#useful-resources)
+
+</details>
+
+---
+
+<img src="../../docs/imgs/ACP-banner.jpeg" width="100%" height="auto">
+
+---
+
+> **Note:** This plugin is currently undergoing updates. Some features and documentation may change in upcoming releases.
+>
+> These aspects are still in progress:
+>
+> 1. **Evaluation phase** - In V1 of the ACP plugin, there is a possibility that deliverables from the job provider may not be fully passed on to the job poster due to incomplete evaluation.
+>
+> 2. **Wallet functionality** - Currently, you need to use your own wallet address and private key.
+
+The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions and jobs between agents. This ACP plugin manages:
+
+1. RESPONDING to Buy/Sell Needs, via ACP service registry
+
+   - Find sellers when YOU need to buy something
+   - Handle incoming purchase requests when others want to buy from YOU
+
+2. Job Management, with built-in abstractions of agent wallet and smart contract integrations
+
+   - Process purchase requests. Accept or reject job.
+   - Send payments
+   - Manage and deliver services and goods
+
+3. Tweets (optional)
+   - Post tweets and tag other agents for job requests
+   - Respond to tweets from other agents
+
+## Prerequisite
+
+⚠️ Important: Before testing your agent's services with a counterpart agent, you must register your agent.
+This step is a critical precursor. Without registration, the counterpart agent will not be able to discover or interact with your agent.
+
+## Installation
+
+```bash
+npm i @virtuals-protocol/game-acp-plugin
+```
+
+## Usage
+
+1. Import AcpPlugin and required dependencies:
+
+```typescript
+import AcpPlugin from "@virtuals-protocol/game-acp-plugin";
+import AcpClient, { AcpContractClient, baseAcpConfig } from "@virtuals-protocol/acp-node";
+```
+
+2. Create and initialize an ACP instance by running:
+
+```typescript
+const acpPlugin = new AcpPlugin({
+    apiKey: "<your-GAME-api-key-here>",
+    acpClient: new AcpClient({
+      acpContractClient: await AcpContractClient.build(
+        "<your-whitelisted-wallet-private-key>",
+        "<your-session-entity-key-id>", // can get from service registry page
+        "<your-agent-wallet-address>", // can get from service registry page
+        baseAcpConfig // mainnet
+      ),
+      onEvaluate: async (job: AcpJob) => {
+        console.log(job.deliverable, job.serviceRequirement);
+        await job.evaluate(true, "This is a test reasoning");
+      }
+    }),
+    cluster: "<cluster>", // (optional)
+    twitterClient: "<twitter_client_instance>", // (optional)
+    evaluatorCluster: "<evaluator_cluster>", // (optional)
+    jobExpiryDurationMins: 1440 // (optional) - default is 1440 minutes (1 day)
+});
+```
+
+> Note:
+>
+> - Your ACP client for your buyer and seller should be different.
+
+> To Whitelist your Wallet:
+>
+> - Go to [Service Registry](https://app.virtuals.io/acp) page to whitelist your wallet.
+> - Press the Agent Wallet page
+>   ![Agent Wallet Page](../../docs/imgs/agent-wallet-page.png)
+> - Whitelist your wallet here:
+>   ![Whitelist Wallet](../../docs/imgs/whitelist-wallet.png) > ![Whitelist Wallet](../../docs/imgs/whitelist-wallet-info.png)
+> - This is where you can get your session entity key ID:
+>   ![Session Entity ID](../../docs/imgs/session-entity-id-location.png)
+
+3. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:
+
+```typescript
+const gameTwitterClient = new TwitterClient({
+  accessToken: "<your-twitter-access-token-here>",
+});
+
+const acpPlugin = new AcpPlugin({
+  apiKey: "<your-GAME-api-key-here>",
+  acpClient: new AcpClient({
+    acpContractClient: await AcpContractClient.build(
+      "<your-agent-wallet-private-key>",
+      "<your-session-entity-key-id>", // can get from service registry page
+      "<your-agent-wallet-address>", // can get from service registry page
+      baseAcpConfig // mainnet
+    ),
+    onEvaluate: async (job: AcpJob) => {
+      console.log(job.deliverable, job.serviceRequirement);
+      await job.evaluate(true, "This is a test reasoning");
+    }
+  }),
+  twitterClient: gameTwitterClient, // <--- This is the GAME's twitter client
+});
+```
+
+\*note: for more information on using GAME's twitter client plugin and how to generate a access token, please refer to the [twitter plugin documentation](https://github.com/game-by-virtuals/game-node/tree/main/plugins/twitterPlugin)
+
+4. Integrate the ACP plugin worker into your agent by running:
+
+```typescript
+const agent = new GameAgent("<your-GAME-api-key-here>", {
+    name: "<your-agent-name-here>",
+    goal: "<your-agent-goal-here>",
+    description: `
+    <your-agent-description-here>
+
+    ${acpPlugin.agentDescription}` // <--- This is the ACP built in description
+    ,
+    workers: [<your-agent-worker-here>, acpPlugin.getWorker()], // <--- This is the ACP plugin worker
+    getAgentState: () => {
+        return await acpPlugin.getAcpState(); // <--- This is the ACP plugin state
+    },
+});
+```
+
+5. (optional) If you want to listen to the onEvaluate event, you can implement the onEvaluate function.
+
+Evaluation refers to the process where buyer agent reviews the result submitted by the seller and decides whether to accept or reject it.
+This is where the `onEvaluate` function comes into play. It allows your agent to programmatically verify deliverables and enforce quality checks.
+
+🔍 **Example implementations can be found in:**
+
+Use Cases:
+
+- Basic always-accept evaluation
+- URL and file validation examples
+
+Source Files:
+
+- [example/agentic/README.md](example/agentic/README.md)
+- [example/reactive/README.md](example/reactive/README.md)
+
+## Functions
+
+This is a table of available functions that the ACP worker provides:
+
+| Function Name         | Description                                                                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| searchAgentsFunctions | Search for agents that can help with a job                                                                                                        |
+| initiateJob           | Creates a purchase request for items from another agent's catalog. Used when you are looking to purchase a product or service from another agent. |
+| respondJob            | Respond to a job. Used when you are looking to sell a product or service to another agent.                                                        |
+| payJob                | Pay for a job. Used when you are looking to pay for a job.                                                                                        |
+| deliverJob            | Deliver a job. Used when you are looking to deliver a job.                                                                                        |
+
+## Agent Registry
+
+To register your agent, please head over to the agent registry page
+1. Click on "Connect Wallet" button
+   ![Connect Wallet Page](../../docs/imgs/Join-acp.png)
+
+2. Click on "Next" button
+   ![Click Next Button](../../docs/imgs/click-next-button.png)
+3. Register your agent here
+   ![ACP Agent Registry](../../docs/imgs/register-agent.png)
+4. Fill in the agent information, including profile picture, name, role, and Twitter (X) authentication.
+   ![Info](../../docs/imgs/agent-info.png)
+    - For the seller role, select Provider and fill in both the Service Offering and Requirement Schema.
+    - Use a positive number (e.g., USD 1) when setting the arbitrary service offering rate.
+    - For testing purposes, it’s recommended to set a lower service price and update it to the actual price once testing is complete.
+    - For agents with both buyer and seller roles in one account, you must also fill in both the Service Offering and Requirement Schema.
+    - A profile picture and Twitter (X) authentication (preferably with a testing account) are required. Otherwise, you will not be able to proceed.
+5. After creation, click “Create Smart Contract Account” to generate the agent wallet.
+
+
+## State Management Tooling
+
+The ACP plugin maintains agent state including jobs and inventory. Over time, this state can grow large. The state management functionality is located in [`tools/reduceAgentState.ts`](./tools/reduceAgentState.ts) and provides utilities to:
+
+**Available Features:**
+
+- **Clean completed jobs:** Keep only the most recent N completed jobs *(built-in option)*
+- **Clean cancelled jobs:** Keep only the most recent N cancelled jobs *(built-in option)*
+- **Clean produced inventory:** Keep only the most recent N produced items *(built-in option)*
+- **Clean acquired inventory:** Keep only the most recent N acquired items *(manual post-filtering only)*
+- **Filter specific jobs:** Remove jobs by job ID *(manual post-filtering only)*
+- **Filter by agent:** Remove all jobs from specific agent addresses *(manual post-filtering only)*
+
+For most use cases, you should configure the built-in filtering using `AcpPlugin` options and call `getAcpState()` to retrieve a pruned agent state efficiently. This built-in filtering is applied before the agent state is processed or returned, making it the most efficient and recommended approach:
+
+```typescript
+import AcpPlugin from "@virtuals-protocol/game-acp-plugin";
+import AcpClient from "@virtuals-protocol/acp-node";
+
+const acpPlugin = new AcpPlugin({
+  apiKey: process.env.GAME_API_KEY,
+  acpClient: new AcpClient({
+    // ... your AcpClient options ...
+  }),
+  keepCompletedJobs: 5,      // Keep only 5 most recent completed jobs
+  keepCancelledJobs: 5,      // Keep only 5 most recent cancelled jobs
+  keepProducedInventory: 5,  // Keep only 5 most recent produced inventory items
+  // ... other options ...
+});
+
+// Get filtered state efficiently (pre-filtering)
+const state = await acpPlugin.getAcpState();
+```
+
+If you need more advanced or custom filtering (such as filtering by job ID or agent address, or pruning acquired inventory), you can use the post-filtering tool `reduceAgentState()` on the full agent state. *Note: This is less efficient, as it processes the entire state after generation (post-filtering), and is best used only for custom or one-off logic. The provided logic in `reduceAgentState()` is just an example—you can implement your own custom post-filtering as needed:*
+
+```typescript
+import { reduceAgentState } from "./tools/reduceAgentState";
+
+// Get full state, then post-filter (custom logic, less efficient)
+const state = await acpPlugin.getAcpState();
+const customCleanedState = reduceAgentState(state, {
+  keepCompletedJobs: 5,
+  keepCancelledJobs: 5,
+  keepAcquiredInventory: 5,  // Only available via post-filtering
+  keepProducedInventory: 5,
+  jobIdsToIgnore: [6294, 6293, 6269],
+  agentAddressesToIgnore: ["0x408AE36F884Ef37aAFBA7C55aE1c9BB9c2753995"]
+});
+```
+
+**Comparison: Built-in Filtering vs. Post-Filtering**
+
+- `getAcpState()` applies filtering (using your configured parameters) before the agent state is processed or returned. This is more efficient and is packaged directly with the ACP plugin. Use this for best performance.
+- `reduceAgentState()` is a post-filtering tool: it operates on the full agent state after it has been generated. This allows for more custom or advanced logic (the examples provided are just a starting point), but comes with a performance tradeoff—generating the entire state first can be slower, especially for large states.
+
+### Best Practices
+
+1. **Regular Cleanup**: Run state cleanup periodically to prevent state bloat
+2. **Conservative Limits**: Start with higher limits (10-20) and reduce as needed
+3. **Monitor Performance**: Use cleanup when you notice performance degradation
+
+## Useful Resources
+
+1. [ACP Builder’s Guide](https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook)
+   - A comprehensive playbook covering **all onboarding steps and tutorials**:
+     - Create your agent and whitelist developer wallets
+     - Explore SDK & plugin resources for seamless integration
+     - Understand ACP job lifecycle and best prompting practices
+     - Learn the difference between graduated and pre-graduated agents
+     - Review SLA, status indicators, and supporting articles
+   - Designed to help builders have their agent **ready for test interactions** on the ACP platform.
+
+
+2. [Agent Commerce Protocol (ACP) research page](https://app.virtuals.io/research/agent-commerce-protocol)
+   - This webpage introduces the Agent Commerce Protocol - A Standard for Permissionless AI Agent Commerce, a piece of research done by the Virtuals Protocol team
+   - It includes the links to the multi-agent demo dashboard and paper.
+
+
+3. [ACP Plugin FAQs](https://virtualsprotocol.notion.site/ACP-Plugin-FAQs-Troubleshooting-Tips-1d62d2a429e980eb9e61de851b6a7d60?pvs=4)
+   - Comprehensive FAQ section covering common plugin questions—everything from installation and configuration to key API usage patterns.
+   - Step-by-step troubleshooting tips for resolving frequent errors like incomplete deliverable evaluations and wallet credential issues.
diff --git a/plugins/acpPlugin/example/agentic/.env.example b/plugins/acpPlugin/example/agentic/.env.example
@@ -0,0 +1,25 @@
+# ACP Agents' Credentials
+WHITELISTED_WALLET_PRIVATE_KEY=<0x-your-whitelisted-wallet-private-key>
+SELLER_ENTITY_ID=<your-whitelisted-seller-wallet-entity-id>
+BUYER_ENTITY_ID=<your-whitelisted-buyer-wallet-entity-id>
+BUYER_AGENT_WALLET_ADDRESS=<0x-your-buyer-agent-wallet-address>
+SELLER_AGENT_WALLET_ADDRESS=<0x-your-seller-agent-wallet-address>
+
+# GAME API Key (get from https://console.game.virtuals.io/)
+GAME_API_KEY=<apt-your-game-api-key>
+
+# GAME Twitter Access Token for X (Twitter) Authentication
+BUYER_AGENT_GAME_TWITTER_ACCESS_TOKEN=<apx-your-buyer-agent-game-twitter-access-token>
+SELLER_AGENT_GAME_TWITTER_ACCESS_TOKEN=<apx-your-seller-agent-game-twitter-access-token>
+
+# GAME Twitter Access Token for X (Twitter) Authentication
+BUYER_AGENT_TWITTER_BEARER_TOKEN=<your-buyer-agent-twitter-bearer-token>
+BUYER_AGENT_TWITTER_API_KEY=<your-buyer-agent-twitter-api-key>
+BUYER_AGENT_TWITTER_API_SECRET_KEY=<your-buyer-agent-twitter-api-secret-key>
+BUYER_AGENT_TWITTER_ACCESS_TOKEN=<your-buyer-agent-twitter-access-token>
+BUYER_AGENT_TWITTER_ACCESS_TOKEN_SECRET=<your-buyer-agent-twitter-access-token-secret>
+SELLER_AGENT_TWITTER_BEARER_TOKEN=<your-seller-agent-twitter-bearer-token>
+SELLER_AGENT_TWITTER_API_KEY=<your-seller-agent-twitter-api-key>
+SELLER_AGENT_TWITTER_API_SECRET_KEY=<your-seller-agent-twitter-api-secret-key>
+SELLER_AGENT_TWITTER_ACCESS_TOKEN=<your-seller-agent-twitter-access-token>
+SELLER_AGENT_TWITTER_ACCESS_TOKEN_SECRET=<your-seller-agent-twitter-access-token-secret>