@eforest-finance/agent-skills 0.2.0 → 0.3.0

package/.env.example

@@ -1,8 +1,16 @@
+# ---- Wallet Configuration (pick ONE mode) ----
+
+# Mode 1: EOA (direct private key signing)
 # aelf wallet private key (hex string, 64 chars)
-# Used for signing transactions on aelf blockchain.
 # WARNING: Never commit real private keys to version control.
 AELF_PRIVATE_KEY=your_private_key_here
 
+# Mode 2: CA (Portkey Contract Account via ManagerForwardCall)
+# PORTKEY_PRIVATE_KEY=your_manager_private_key
+# PORTKEY_CA_HASH=your_ca_hash
+# PORTKEY_CA_ADDRESS=your_ca_address
+# PORTKEY_ORIGIN_CHAIN_ID=AELF
+
 # Optional: override environment (default: mainnet)
 # AELF_ENV=testnet
 

package/README.md

@@ -13,7 +13,7 @@ AI Agent Kit for aelf token lifecycle on [eForest](https://www.eforest.finance).
 ### Prerequisites
 
 - [Bun](https://bun.sh) >= 1.0
-- An aelf wallet private key with ELF balance
+- An aelf wallet private key (EOA) or Portkey CA wallet credentials
 
 ### Install
 
@@ -76,6 +76,8 @@ Then edit the generated config to replace `<YOUR_PRIVATE_KEY>` with your actual
 
 If you prefer manual configuration, add this to your MCP settings:
 
+**EOA mode** (direct private key signing):
+
 ```json
 {
   "mcpServers": {
@@ -91,6 +93,25 @@ If you prefer manual configuration, add this to your MCP settings:
 }
 ```
 
+**CA mode** (Portkey Contract Account):
+
+```json
+{
+  "mcpServers": {
+    "eforest-token": {
+      "command": "bun",
+      "args": ["run", "/path/to/eforest-agent-skills/src/mcp/server.ts"],
+      "env": {
+        "PORTKEY_PRIVATE_KEY": "your_manager_private_key",
+        "PORTKEY_CA_HASH": "your_ca_hash",
+        "PORTKEY_CA_ADDRESS": "your_ca_address",
+        "EFOREST_NETWORK": "mainnet"
+      }
+    }
+  }
+}
+```
+
 ## OpenClaw
 
 ```bash
@@ -176,7 +197,10 @@ bun test:integration  # Integration tests only
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `AELF_PRIVATE_KEY` | aelf wallet private key | (required) |
+| `AELF_PRIVATE_KEY` | aelf wallet private key (EOA mode) | — |
+| `PORTKEY_PRIVATE_KEY` | Portkey Manager private key (CA mode) | — |
+| `PORTKEY_CA_HASH` | Portkey CA hash (CA mode) | — |
+| `PORTKEY_CA_ADDRESS` | Portkey CA address (CA mode) | — |
 | `EFOREST_NETWORK` / `AELF_ENV` | `mainnet` or `testnet` | `mainnet` |
 | `EFOREST_API_URL` / `AELF_API_URL` | Backend API URL | auto |
 | `EFOREST_RPC_URL` / `AELF_RPC_URL` | AELF MainChain RPC | auto |

package/lib/aelf-client.ts

@@ -5,6 +5,7 @@
  */
 
 import AElf from 'aelf-sdk';
+import type { AelfSigner } from '@portkey/aelf-signer';
 import { TX_POLL_INTERVAL_MS, TX_POLL_MAX_RETRIES } from './types';
 
 // ============================================================================
@@ -23,16 +24,24 @@ export function getWallet(privateKey?: string): any {
   const key =
     process.env.AELF_PRIVATE_KEY ||
     process.env.EFOREST_PRIVATE_KEY ||
+    process.env.PORTKEY_PRIVATE_KEY ||
     privateKey;
 
   if (!key) {
     throw new Error(
-      'Private key is required. Set AELF_PRIVATE_KEY env var or pass --private-key.',
+      'Private key is required. Set AELF_PRIVATE_KEY (EOA) or PORTKEY_PRIVATE_KEY (CA) env var, or pass --private-key.',
     );
   }
   return AElf.wallet.getWalletByPrivateKey(key);
 }
 
+// Singleton view wallet for read-only calls (no real identity needed)
+let _viewWallet: any = null;
+function getViewWallet(): any {
+  if (!_viewWallet) _viewWallet = AElf.wallet.createNewWallet();
+  return _viewWallet;
+}
+
 // ============================================================================
 // Contract
 // ============================================================================
@@ -105,32 +114,36 @@ export async function getTxResult(
 // Contract Call Helpers
 // ============================================================================
 
+/**
+ * Send a state-changing contract call via AelfSigner.
+ * Supports both EOA (direct signing) and CA (ManagerForwardCall) transparently.
+ */
 export async function callContractSend(
   rpcUrl: string,
   contractAddress: string,
   methodName: string,
   params: any,
-  wallet: any,
+  signer: AelfSigner,
 ): Promise<{ TransactionId: string; txResult: any }> {
-  const contract = await getContractInstance(rpcUrl, contractAddress, wallet);
-  const tx = await contract[methodName](params);
-  const transactionId = tx.TransactionId || tx.transactionId || tx;
-  if (!transactionId || typeof transactionId !== 'string') {
-    throw new Error(
-      `Failed to get TransactionId from ${methodName}. Response: ${JSON.stringify(tx)}`,
-    );
-  }
-  await sleep(TX_POLL_INTERVAL_MS);
-  return getTxResult(rpcUrl, transactionId);
+  const result = await signer.sendContractCall(rpcUrl, contractAddress, methodName, params);
+  return {
+    TransactionId: result.transactionId,
+    txResult: result.txResult,
+  };
 }
 
+/**
+ * Read-only contract call. Wallet parameter is optional — uses an internal
+ * ephemeral wallet if not provided.
+ */
 export async function callContractView(
   rpcUrl: string,
   contractAddress: string,
   methodName: string,
   params: any,
-  wallet: any,
+  wallet?: any,
 ): Promise<any> {
-  const contract = await getContractInstance(rpcUrl, contractAddress, wallet);
+  const w = wallet || getViewWallet();
+  const contract = await getContractInstance(rpcUrl, contractAddress, w);
   return await contract[methodName].call(params);
 }

package/lib/config.ts

@@ -16,6 +16,7 @@ import { existsSync, readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
+import { createSignerFromEnv } from '@portkey/aelf-signer';
 import type { CmsConfigItems, ResolvedConfig } from './types';
 import { ENV_PRESETS } from './types';
 import { getWallet } from './aelf-client';
@@ -124,8 +125,11 @@ export async function getNetworkConfig(opts?: {
       '',
   };
 
+  // Unified signer: detects EOA/CA mode from env vars automatically
+  const signer = createSignerFromEnv();
+  // Raw wallet for API auth (fetchAuthToken needs keyPair for signature)
   const wallet = getWallet(o.privateKey);
-  const walletAddress = wallet.address;
+  const walletAddress = signer.address;
 
   return {
     apiUrl,
@@ -133,6 +137,7 @@ export async function getNetworkConfig(opts?: {
     connectUrl,
     rpcUrls,
     contracts: cmsConfig,
+    signer,
     wallet,
     walletAddress,
   };

package/lib/types.ts

@@ -104,7 +104,11 @@ export interface ResolvedConfig {
   connectUrl: string;
   rpcUrls: Record<string, string>;
   contracts: CmsConfigItems;
-  wallet: any; // aelf-sdk wallet instance
+  /** Unified signer — supports both EOA and CA wallets. Use for all contract calls. */
+  signer: import('@portkey/aelf-signer').AelfSigner;
+  /** Raw wallet for API auth (fetchAuthToken). For CA: manager wallet. */
+  wallet: any;
+  /** Identity address: CA address (CA mode) or wallet address (EOA mode). */
   walletAddress: string;
 }
 

package/openclaw.json

@@ -3,7 +3,7 @@
     {
       "name": "aelf-buy-seed",
       "command": "bun run create_token_skill.ts buy-seed --symbol {{symbol}} --issuer {{issuer}} --env {{env}} {{#if force}}--force {{force}}{{/if}} {{#if privateKey}}--private-key {{privateKey}}{{/if}} {{#if dryRun}}--dry-run{{/if}}",
-      "description": "Purchase a SEED on the aelf MainChain. A SEED is a prerequisite for creating a token on aelf blockchain. IMPORTANT: By default this tool REFUSES to buy and outputs the SEED price. You MUST first run with --dry-run to check the price, then ASK THE USER if they want to proceed, then re-run with --force to confirm. Workflow: (1) dry-run to see price, (2) show price to user and ask for confirmation, (3) run with --force or --force <maxELF> to execute. --force with no value buys unconditionally. --force 2 buys only if price <= 2 ELF. The full buy flow is: query price -> check ELF balance -> approve ELF -> call SymbolRegister.Buy -> parse SEED symbol from tx logs. IMPORTANT: The output includes 'seedSymbol' (e.g. 'SEED-321') which is the real on-chain SEED identifier. You MUST use this seedSymbol value for the subsequent create-token --seed-symbol parameter, NOT the token symbol name. Requires AELF_PRIVATE_KEY env var or --private-key. Output: JSON with {success, transactionId, seedSymbol, data} on success, or '[ERROR] ...' with price info on refusal.",
+      "description": "Purchase a SEED on the aelf MainChain. A SEED is a prerequisite for creating a token on aelf blockchain. IMPORTANT: By default this tool REFUSES to buy and outputs the SEED price. You MUST first run with --dry-run to check the price, then ASK THE USER if they want to proceed, then re-run with --force to confirm. Workflow: (1) dry-run to see price, (2) show price to user and ask for confirmation, (3) run with --force or --force <maxELF> to execute. --force with no value buys unconditionally. --force 2 buys only if price <= 2 ELF. The full buy flow is: query price -> check ELF balance -> approve ELF -> call SymbolRegister.Buy -> parse SEED symbol from tx logs. IMPORTANT: The output includes 'seedSymbol' (e.g. 'SEED-321') which is the real on-chain SEED identifier. You MUST use this seedSymbol value for the subsequent create-token --seed-symbol parameter, NOT the token symbol name. Requires wallet env vars: AELF_PRIVATE_KEY (EOA) or PORTKEY_PRIVATE_KEY + PORTKEY_CA_HASH + PORTKEY_CA_ADDRESS (CA). Output: JSON with {success, transactionId, seedSymbol, data} on success, or '[ERROR] ...' with price info on refusal.",
       "working_directory": "scripts/skills",
       "parameters": {
         "symbol": {
@@ -30,7 +30,7 @@
         "privateKey": {
           "type": "string",
           "required": false,
-          "description": "aelf wallet private key. Prefer using AELF_PRIVATE_KEY env var instead."
+          "description": "aelf wallet private key. Prefer using AELF_PRIVATE_KEY (EOA) or PORTKEY_PRIVATE_KEY (CA) env var instead."
         },
         "dryRun": {
           "type": "boolean",
@@ -43,7 +43,7 @@
     {
       "name": "aelf-create-token",
       "command": "bun run create_token_skill.ts create-token --symbol {{symbol}} --token-name '{{tokenName}}' --seed-symbol {{seedSymbol}} --total-supply {{totalSupply}} --decimals {{decimals}} {{#if issuer}}--issuer {{issuer}}{{/if}} --issue-chain {{issueChain}} {{#if isBurnable}}--is-burnable{{else}}--no-is-burnable{{/if}} {{#if tokenImage}}--token-image '{{tokenImage}}'{{/if}} --env {{env}} {{#if privateKey}}--private-key {{privateKey}}{{/if}} {{#if dryRun}}--dry-run{{/if}}",
-      "description": "Create a new fungible token (FT) on the aelf blockchain using an owned SEED. The full flow is: (1) Check and approve SEED allowance for the TokenAdapter contract, (2) Call TokenAdapter.CreateToken on MainChain, (3) Query GetTokenInfo for proxyIssuer, (4) Save token metadata to backend, (5) Sync token to the issue chain (with graceful degradation on timeout). IMPORTANT: --seed-symbol must be the SEED-{number} value from buy-seed output (e.g. 'SEED-321'), NOT the token name. --issuer is OPTIONAL and defaults to your wallet address. NOTE: The on-chain issuer will be a proxy account created by TokenAdapter, NOT the address you pass. The output includes 'proxyIssuer' which is needed by issue-token. Cross-chain sync to side chain may take several minutes; if it times out, the output includes a warning but success=true (token was created on MainChain). Requires AELF_PRIVATE_KEY env var or --private-key. Output: JSON with {success, transactionId, proxyIssuer, crossChainSynced, data} on success.",
+      "description": "Create a new fungible token (FT) on the aelf blockchain using an owned SEED. The full flow is: (1) Check and approve SEED allowance for the TokenAdapter contract, (2) Call TokenAdapter.CreateToken on MainChain, (3) Query GetTokenInfo for proxyIssuer, (4) Save token metadata to backend, (5) Sync token to the issue chain (with graceful degradation on timeout). IMPORTANT: --seed-symbol must be the SEED-{number} value from buy-seed output (e.g. 'SEED-321'), NOT the token name. --issuer is OPTIONAL and defaults to your wallet address. NOTE: The on-chain issuer will be a proxy account created by TokenAdapter, NOT the address you pass. The output includes 'proxyIssuer' which is needed by issue-token. Cross-chain sync to side chain may take several minutes; if it times out, the output includes a warning but success=true (token was created on MainChain). Requires wallet env vars: AELF_PRIVATE_KEY (EOA) or PORTKEY_PRIVATE_KEY + PORTKEY_CA_HASH + PORTKEY_CA_ADDRESS (CA). Output: JSON with {success, transactionId, proxyIssuer, crossChainSynced, data} on success.",
       "working_directory": "scripts/skills",
       "parameters": {
         "symbol": {
@@ -101,7 +101,7 @@
         "privateKey": {
           "type": "string",
           "required": false,
-          "description": "aelf wallet private key. Prefer using AELF_PRIVATE_KEY env var instead."
+          "description": "aelf wallet private key. Prefer using AELF_PRIVATE_KEY (EOA) or PORTKEY_PRIVATE_KEY (CA) env var instead."
         },
         "dryRun": {
           "type": "boolean",
@@ -156,7 +156,7 @@
         "privateKey": {
           "type": "string",
           "required": false,
-          "description": "aelf wallet private key. Prefer using AELF_PRIVATE_KEY env var instead."
+          "description": "aelf wallet private key. Prefer using AELF_PRIVATE_KEY (EOA) or PORTKEY_PRIVATE_KEY (CA) env var instead."
         },
         "dryRun": {
           "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eforest-finance/agent-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI Agent Kit for aelf token lifecycle on eForest: buy-seed, create-token, issue-token. Supports CLI, MCP, and SDK.",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "@portkey/aelf-signer": "^1.0.0",
     "aelf-sdk": "^3.2.44",
     "axios": "^1.7.0",
     "commander": "^12.1.0",

package/src/core/issue.ts

@@ -133,7 +133,6 @@ export async function issueToken(
       multiTokenAddr,
       'GetTokenInfo',
       { symbol: opts.symbol },
-      config.wallet,
     );
     proxyIssuerAddress =
       typeof tokenInfo?.issuer === 'string' ? tokenInfo.issuer : '';
@@ -151,7 +150,6 @@ export async function issueToken(
     proxyAddr,
     'GetProxyAccountByProxyAccountAddress',
     proxyIssuerAddress,
-    config.wallet,
   );
 
   const proxyAccountHash = proxyAccountResult?.proxyAccountHash;
@@ -175,7 +173,7 @@ export async function issueToken(
       methodName: 'Issue',
       args: Buffer.from(encodedArgs).toString('base64'),
     },
-    config.wallet,
+    config.signer,
   );
 
   return {

package/src/core/seed.ts

@@ -170,7 +170,6 @@ export async function buySeed(
       multiTokenAddr,
       'GetBalance',
       { symbol: 'ELF', owner: config.walletAddress },
-      config.wallet,
     );
     const balanceELF =
       Number(balance?.balance ?? 0) / 10 ** ELF_DECIMALS;
@@ -193,7 +192,6 @@ export async function buySeed(
         owner: config.walletAddress,
         spender: contractAddr,
       },
-      config.wallet,
     );
     if (Number(allowance?.allowance ?? 0) < priceInSmallUnits) {
       await callContractSend(
@@ -205,7 +203,7 @@ export async function buySeed(
           symbol: 'ELF',
           amount: String(priceInSmallUnits),
         },
-        config.wallet,
+        config.signer,
       );
     }
   }
@@ -216,7 +214,7 @@ export async function buySeed(
     contractAddr,
     'Buy',
     { symbol: params.symbol, issueTo: params.issueTo },
-    config.wallet,
+    config.signer,
   );
 
   const seedSymbol = parseSeedSymbolFromLogs(result.txResult?.Logs);

package/src/core/token.ts

@@ -127,7 +127,6 @@ export async function createToken(
       owner: config.walletAddress,
       spender: tokenAdapterAddr,
     },
-    config.wallet,
   );
 
   // Approve if needed
@@ -141,7 +140,7 @@ export async function createToken(
         symbol: opts.seedSymbol,
         amount: '1',
       },
-      config.wallet,
+      config.signer,
     );
   }
 
@@ -151,7 +150,7 @@ export async function createToken(
     tokenAdapterAddr,
     'CreateToken',
     createParams,
-    config.wallet,
+    config.signer,
   );
 
   const createTxId = createResult.TransactionId;
@@ -164,7 +163,6 @@ export async function createToken(
       multiTokenAddr,
       'GetTokenInfo',
       { symbol: opts.symbol },
-      config.wallet,
     );
     proxyIssuer =
       typeof tokenInfo?.issuer === 'string' ? tokenInfo.issuer : '';

package/src/mcp/server.ts

@@ -4,22 +4,18 @@
  *
  * Registers core functions as Model Context Protocol (MCP) tools.
  * Each tool maps to a core function with Zod input validation.
+ * Supports both EOA and CA (Portkey) wallets via @portkey/aelf-signer.
  *
  * Usage:
  *   bun run src/mcp/server.ts          # stdio transport (default)
  *   EFOREST_NETWORK=testnet bun run src/mcp/server.ts
  *
- * MCP config example (for AI clients):
- *   {
- *     "mcpServers": {
- *       "eforest-token": {
- *         "command": "bun",
- *         "args": ["run", "src/mcp/server.ts"],
- *         "cwd": "<path-to-skills-dir>",
- *         "env": { "AELF_PRIVATE_KEY": "xxx", "EFOREST_NETWORK": "mainnet" }
- *       }
- *     }
- *   }
+ * MCP config example — EOA mode:
+ *   { "env": { "AELF_PRIVATE_KEY": "xxx", "EFOREST_NETWORK": "mainnet" } }
+ *
+ * MCP config example — CA (Portkey) mode:
+ *   { "env": { "PORTKEY_PRIVATE_KEY": "xxx", "PORTKEY_CA_HASH": "xxx",
+ *              "PORTKEY_CA_ADDRESS": "xxx", "EFOREST_NETWORK": "mainnet" } }
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -72,7 +68,8 @@ const server = new McpServer({
 // --- aelf-buy-seed ---
 server.tool(
   'aelf-buy-seed',
-  `Purchase a SEED on aelf MainChain. Returns seedSymbol (e.g. "SEED-321") needed for create-token.
+  `Purchase a SEED on aelf MainChain. Supports both EOA and CA (Portkey) wallets.
+Returns seedSymbol (e.g. "SEED-321") needed for create-token.
 Performs pre-flight availability check, ELF balance check, and Approve before Buy.
 Price safety: requires --force or force param. Use force=2 for max 2 ELF.`,
   {
@@ -120,6 +117,7 @@ Price safety: requires --force or force param. Use force=2 for max 2 ELF.`,
 server.tool(
   'aelf-create-token',
   `Create a new FT token on aelf using an owned SEED (from buy-seed output seedSymbol).
+Supports both EOA and CA (Portkey) wallets.
 Handles SEED Approve, TokenAdapter.CreateToken, backend save, and cross-chain sync.
 Returns proxyIssuer (proxy account address) needed for issue-token.
 Cross-chain sync has graceful degradation: success=true even if sync times out.`,
@@ -172,7 +170,7 @@ Cross-chain sync has graceful degradation: success=true even if sync times out.`
 // --- aelf-issue-token ---
 server.tool(
   'aelf-issue-token',
-  `Issue tokens to an address via Proxy ForwardCall.
+  `Issue tokens to an address via Proxy ForwardCall. Supports both EOA and CA (Portkey) wallets.
 Because TokenAdapter creates a proxy account as on-chain issuer, this routes through ProxyContract.
 Auto-detects proxyIssuer from GetTokenInfo if not provided.
 Steps: GetTokenInfo → GetProxyAccount → encode IssueInput → ForwardCall.`,