feat: implement coinbase mass payments across base/sol/eth/pol/arb

Author: monilpat

.env.example

@@ -91,5 +91,10 @@ STARKNET_ADDRESS=
 STARKNET_PRIVATE_KEY=
 STARKNET_RPC_URL=
 
-# Coinbase Commerce
-COINBASE_COMMERCE_KEY=
+# Coinbase
+COINBASE_COMMERCE_KEY= # from coinbase developer portal
+COINBASE_API_KEY= # from coinbase developer portal
+COINBASE_PRIVATE_KEY= # from coinbase developer portal
+# if not configured it will be generated and written to runtime.character.settings.secrets.COINBASE_GENERATED_WALLET_ID and runtime.character.settings.secrets.COINBASE_GENERATED_WALLET_HEX_SEED
+COINBASE_GENERATED_WALLET_ID= # not your address but the wallet id from generating a wallet through the plugin
+COINBASE_GENERATED_WALLET_HEX_SEED= # not your address but the wallet hex seed from generating a wallet through the plugin and calling export

.gitignore

@@ -40,3 +40,5 @@ characters/
 packages/core/src/providers/cache
 packages/core/src/providers/cache/*
 cache/*
+packages/plugin-coinbase/src/plugins/transactions.csv
+packages/plugin-coinbase/package-lock.json

agent/src/index.ts

@@ -25,7 +25,10 @@ import {
 import { bootstrapPlugin } from "@ai16z/plugin-bootstrap";
 import { solanaPlugin } from "@ai16z/plugin-solana";
 import { nodePlugin } from "@ai16z/plugin-node";
-import { coinbaseCommercePlugin } from "@ai16z/plugin-coinbase";
+import {
+    coinbaseCommercePlugin,
+    coinbaseMassPaymentsPlugin,
+} from "@ai16z/plugin-coinbase";
 import Database from "better-sqlite3";
 import fs from "fs";
 import readline from "readline";
@@ -254,6 +257,12 @@ export function createAgent(
             process.env.COINBASE_COMMERCE_KEY
                 ? coinbaseCommercePlugin
                 : null,
+            (character.settings.secrets?.COINBASE_API_KEY ||
+                process.env.COINBASE_API_KEY) &&
+            (character.settings.secrets?.COINBASE_PRIVATE_KEY ||
+                process.env.COINBASE_PRIVATE_KEY)
+                ? coinbaseMassPaymentsPlugin
+                : null,
         ].filter(Boolean),
         providers: [],
         actions: [],

docs/docs/packages/plugins.md

@@ -196,7 +196,7 @@ Integrates Solana blockchain functionality:
 - `walletProvider` - Wallet management
 - `trustScoreProvider` - Transaction trust metrics
 
-#### 5. Coinbase Commerce Plugin (`@eliza/plugin-coinbase-commerce`)
+#### 5. Coinbase Commerce Plugin (`@eliza/plugin-coinbase`)
 
 Integrates Coinbase Commerce for payment and transaction management:
 
@@ -211,6 +211,218 @@ This plugin enables Eliza to interact with the Coinbase Commerce API to create a
 
 ---
 
+#### 6. Coinbase MassPayments Plugin (`@eliza/plugin-coinbase`)
+
+This plugin facilitates the processing of cryptocurrency mass payouts using the Coinbase SDK. It enables the creation and management of mass payouts to multiple wallet addresses, logging all transaction details to a CSV file for further analysis.
+
+**Actions:**
+
+- `SEND_MASS_PAYOUT`
+  Sends cryptocurrency mass payouts to multiple wallet addresses.
+  - **Inputs**:
+    - `receivingAddresses` (array of strings): Wallet addresses to receive funds.
+    - `transferAmount` (number): Amount to send to each address (in smallest currency unit, e.g., Wei for ETH).
+    - `assetId` (string): Cryptocurrency asset ID (e.g., `ETH`, `BTC`).
+    - `network` (string): Blockchain network (e.g., `base`, `sol`, `eth`, `arb`, `pol`).
+  - **Outputs**: Logs transaction results (success/failure) in a CSV file.
+  - **Example**:
+    ```json
+    {
+      "receivingAddresses": [
+        "0xA0ba2ACB5846A54834173fB0DD9444F756810f06",
+        "0xF14F2c49aa90BaFA223EE074C1C33b59891826bF"
+      ],
+      "transferAmount": 5000000000000000,
+      "assetId": "ETH",
+      "network": "eth"
+    }
+    ```
+
+**Providers:**
+
+- `massPayoutProvider`
+  Retrieves details of past transactions from the generated CSV file.
+  - **Outputs**: A list of transaction records including the following fields:
+    - `address`: Recipient wallet address.
+    - `amount`: Amount sent.
+    - `status`: Transaction status (`Success` or `Failed`).
+    - `errorCode`: Error code (if any).
+    - `transactionUrl`: URL for transaction details (if available).
+
+**Description:**
+
+The Coinbase MassPayments plugin streamlines cryptocurrency distribution, ensuring efficient and scalable payouts to multiple recipients on supported blockchain networks.
+
+Supported networks:
+
+- `base` (Base blockchain)
+- `sol` (Solana)
+- `eth` (Ethereum)
+- `arb` (Arbitrum)
+- `pol` (Polygon)
+
+**Usage Instructions:**
+
+1. **Configure the Plugin**
+   Add the plugin to your character’s configuration:
+
+   ```typescript
+   import { coinbaseMassPaymentsPlugin } from "@eliza/plugin-coinbase-masspayments";
+
+   const character = {
+     plugins: [coinbaseMassPaymentsPlugin],
+   };
+   ```
+
+2. **Ensure Secure Configuration**
+   Set the following environment variables or runtime settings to ensure the plugin functions securely:
+
+   - `COINBASE_API_KEY`: API key for Coinbase SDK.
+   - `COINBASE_PRIVATE_KEY`: Private key for secure transactions.
+
+---
+
+### Wallet Management
+
+The plugin automatically handles wallet creation or uses an existing wallet if the required details are provided during the first run.
+
+1. **Wallet Generation on First Run**
+   If no wallet information is provided (`COINBASE_GENERATED_WALLET_HEX_SEED` and `COINBASE_GENERATED_WALLET_ID`), the plugin will:
+
+   - **Generate a new wallet** using the Coinbase SDK.
+   - Automatically **export the wallet details** (`seed` and `walletId`) and securely store them in `runtime.character.settings.secrets` or other configured storage.
+   - Log the wallet’s default address for reference.
+
+2. **Using an Existing Wallet**
+   If wallet information is available during the first run:
+   - Provide `COINBASE_GENERATED_WALLET_HEX_SEED` and `COINBASE_GENERATED_WALLET_ID` via `runtime.character.settings.secrets` or environment variables.
+   - The plugin will **import the wallet** and use it for processing mass payouts.
+
+---
+
+### Required Configurations
+
+The following configurations must be provided for wallet management:
+
+- **Environment Variables or Secrets**:
+  - `COINBASE_GENERATED_WALLET_HEX_SEED`: Hexadecimal seed of the wallet.
+  - `COINBASE_GENERATED_WALLET_ID`: Unique wallet ID.
+  - These variables must be securely stored in `runtime.character.settings.secrets` or as environment variables.
+
+---
+
+### Wallet Creation Process
+
+1. **Automatic Wallet Creation**
+   When no wallet details are available:
+
+   - A new wallet is created using the Coinbase SDK.
+   - The wallet’s `seed` and `walletId` are retrieved using the following logic:
+     ```typescript
+     const walletData: WalletData = wallet.export();
+     runtime.character.settings.secrets.COINBASE_GENERATED_WALLET_HEX_SEED =
+       walletData.seed;
+     runtime.character.settings.secrets.COINBASE_GENERATED_WALLET_ID =
+       walletData.walletId;
+     ```
+   - The default wallet address is logged:
+     ```typescript
+     const walletAddress = wallet.getDefaultAddress();
+     elizaLogger.log("Created and stored new wallet:", walletAddress);
+     ```
+
+2. **Using Existing Wallet Details**
+   When the wallet details are provided:
+   - The wallet is imported using the following logic:
+     ```typescript
+     wallet = await Wallet.import({
+       seed: storedSeed,
+       walletId: storedWalletId,
+     });
+     elizaLogger.log("Imported existing wallet:", wallet.getDefaultAddress());
+     ```
+
+---
+
+### Example Configuration
+
+#### Automatic Wallet Generation:
+
+No existing wallet information is passed. The plugin creates and stores a new wallet:
+
+```typescript
+runtime.character.settings.secrets = {
+  // Empty settings for first run
+};
+```
+
+Output Log:
+
+```plaintext
+[INFO] Created and stored new wallet: 0x1234567890abcdef1234567890abcdef12345678
+```
+
+#### Using Existing Wallet Information:
+
+Existing wallet details are passed into the runtime:
+
+```typescript
+runtime.character.settings.secrets = {
+  COINBASE_GENERATED_WALLET_HEX_SEED:
+    "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+  COINBASE_GENERATED_WALLET_ID: "wallet-id-123",
+};
+```
+
+Output Log:
+
+```plaintext
+[INFO] Imported existing wallet: 0x1234567890abcdef1234567890abcdef12345678
+```
+
+---
+
+3. **Example Call**
+   An example of using the `SEND_MASS_PAYOUT` action:
+
+   ```typescript
+   const response = await runtime.triggerAction("SEND_MASS_PAYOUT", {
+     receivingAddresses: [
+       "0xA0ba2ACB5846A54834173fB0DD9444F756810f06",
+       "0xF14F2c49aa90BaFA223EE074C1C33b59891826bF",
+     ],
+     transferAmount: 5000000000000000, // 0.005 ETH
+     assetId: "ETH",
+     network: "eth",
+   });
+   console.log("Mass payout response:", response);
+   ```
+
+4. **Transaction Logging**
+   All transactions (successful and failed) are logged to a `transactions.csv` file in the plugin’s working directory:
+   ```plaintext
+   Address,Amount,Status,Error Code,Transaction URL
+   0xA0ba2ACB5846A54834173fB0DD9444F756810f06,5000000000000000,Success,,https://etherscan.io/tx/0x...
+   ```
+
+**Example Output:**
+
+When successful, a response similar to the following will be returned:
+
+```json
+{
+  "text": "Mass payouts completed successfully.\n- Successful Transactions: 2\n- Failed Transactions: 0\nCheck the CSV file for more details."
+}
+```
+
+**Best Practices:**
+
+- **Secure Secrets Storage**: Ensure `COINBASE_API_KEY` and `COINBASE_PRIVATE_KEY` are stored securely in `runtime.character.settings.secrets` or environment variables. Either add `COINBASE_GENERATED_WALLET_HEX_SEED`, and `COINBASE_GENERATED_WALLET_ID` from a previous run, or it will be dynamically created
+- **Validation**: Always validate input parameters, especially `receivingAddresses` and `network`, to ensure compliance with expected formats and supported networks.
+- **Error Handling**: Monitor logs for failed transactions or errors in the payout process and adjust retry logic as needed.
+
+---
+
 ### Writing Custom Plugins
 
 Create a new plugin by implementing the Plugin interface:

package.json

@@ -24,6 +24,8 @@
         "prepare": "husky install"
     },
     "devDependencies": {
+        "@commitlint/cli": "^18.4.4",
+        "@commitlint/config-conventional": "^18.4.4",
         "concurrently": "^9.1.0",
         "husky": "^9.1.6",
         "lerna": "^8.1.5",
@@ -32,9 +34,7 @@
         "typedoc": "^0.26.11",
         "typescript": "5.6.3",
         "vite": "^5.4.11",
-        "vitest": "^2.1.5",
-        "@commitlint/cli": "^18.4.4",
-        "@commitlint/config-conventional": "^18.4.4"
+        "vitest": "^2.1.5"
     },
     "pnpm": {
         "overrides": {
@@ -45,6 +45,8 @@
         "node": ">=22"
     },
     "dependencies": {
+        "@coinbase/coinbase-sdk": "^0.10.0",
+        "csv-parse": "^5.6.0",
         "ollama-ai-provider": "^0.16.1",
         "optional": "^0.1.4",
         "sharp": "^0.33.5",