@portkey/aelf-signer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Portkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# @portkey/aelf-signer
+
+> Unified signer interface for the aelf blockchain — supports both EOA (direct signing) and CA (Portkey Contract Account via ManagerForwardCall).
+
+[中文文档](./README.zh-CN.md)
+
+---
+
+## Why
+
+DApp skills on aelf (Awaken DEX, eForest NFT, etc.) currently only work with EOA wallets. Portkey CA wallet users cannot use these skills because CA transactions require wrapping every contract call in `ManagerForwardCall`.
+
+`@portkey/aelf-signer` solves this by providing a common `AelfSigner` interface that DApp skills can accept instead of raw `wallet: any`. The signer handles signing details internally — EOA signs directly, CA wraps in ManagerForwardCall — making the wallet type completely transparent to the DApp skill.
+
+## Install
+
+```bash
+bun add @portkey/aelf-signer
+# or
+npm install @portkey/aelf-signer
+```
+
+## Quick Start
+
+### Auto-detect from Environment
+
+```typescript
+import { createSignerFromEnv, callViewMethod } from '@portkey/aelf-signer';
+
+// Automatically creates EoaSigner or CaSigner based on env vars
+const signer = createSignerFromEnv();
+
+console.log(`Identity: ${signer.address}`);       // EOA address or CA address
+console.log(`Signing key: ${signer.keyAddress}`);  // Same for EOA, Manager address for CA
+console.log(`Is CA: ${signer.isCa}`);
+
+// Send a contract call (transparent: EOA direct or CA via ManagerForwardCall)
+const result = await signer.sendContractCall(
+  'https://aelf-public-node.aelf.io',
+  tokenContractAddress,
+  'Transfer',
+  { to: recipient, symbol: 'ELF', amount: '100000000', memo: '' },
+);
+console.log(`TX: ${result.transactionId}`);
+
+// View calls don't need a signer
+const balance = await callViewMethod(rpcUrl, tokenContract, 'GetBalance', {
+  symbol: 'ELF',
+  owner: signer.address,
+});
+```
+
+### EOA Mode
+
+```typescript
+import { createEoaSigner } from '@portkey/aelf-signer';
+
+const signer = createEoaSigner(process.env.AELF_PRIVATE_KEY!);
+// signer.address === signer.keyAddress === wallet address
+```
+
+### CA Mode
+
+```typescript
+import { createCaSigner } from '@portkey/aelf-signer';
+
+const signer = createCaSigner({
+  managerPrivateKey: process.env.PORTKEY_PRIVATE_KEY!,
+  caHash: process.env.PORTKEY_CA_HASH!,
+  caAddress: process.env.PORTKEY_CA_ADDRESS!,
+  // Optional: provide directly to avoid API lookup
+  caContractAddress: process.env.PORTKEY_CA_CONTRACT_ADDRESS,
+  // Optional: defaults to mainnet
+  portkeyApiUrl: 'https://aa-portkey.portkey.finance',
+});
+
+// signer.address = CA address (on-chain identity)
+// signer.keyAddress = Manager address (signing key)
+```
+
+## Environment Variables
+
+### EOA Mode
+
+```bash
+# Set one of:
+AELF_PRIVATE_KEY=<64-char hex private key>
+# or
+PORTKEY_PRIVATE_KEY=<64-char hex private key>
+```
+
+### CA Mode
+
+```bash
+# All three required:
+PORTKEY_PRIVATE_KEY=<manager private key hex>
+PORTKEY_CA_HASH=<CA hash>
+PORTKEY_CA_ADDRESS=<CA address>
+
+# Optional:
+PORTKEY_CA_CONTRACT_ADDRESS=<CA contract address on target chain>
+PORTKEY_API_URL=<Portkey API URL, defaults to mainnet>
+```
+
+Detection priority:
+1. If `PORTKEY_CA_HASH` + `PORTKEY_CA_ADDRESS` + `PORTKEY_PRIVATE_KEY` all set -> **CA mode**
+2. If `AELF_PRIVATE_KEY` set -> **EOA mode**
+3. If only `PORTKEY_PRIVATE_KEY` set -> **EOA mode** (fallback)
+
+## API Reference
+
+### `AelfSigner` Interface
+
+```typescript
+interface AelfSigner {
+  readonly address: string;      // Identity address
+  readonly keyAddress: string;   // Signing key address
+  readonly isCa: boolean;        // Whether CA mode
+
+  sendContractCall(
+    rpcUrl: string,
+    contractAddress: string,
+    methodName: string,
+    params: Record<string, unknown>,
+  ): Promise<SendResult>;
+
+  signMessage(message: string): string;
+}
+```
+
+- `address`: The identity on chain. For EOA: wallet address. For CA: CA address. Use for `owner`, `from` fields.
+- `keyAddress`: The address of the actual signing key. For EOA: same as `address`. For CA: Manager address. Use for API auth.
+- `sendContractCall()`: Send a state-changing contract call. EOA signs directly; CA wraps in `ManagerForwardCall` with protobuf encoding.
+- `signMessage()`: SHA256-hash and sign a message. Returns hex signature.
+
+### Factory Functions
+
+| Function | Description |
+|----------|-------------|
+| `createSignerFromEnv()` | Auto-detect signer type from env vars |
+| `createEoaSigner(privateKey)` | Create EOA signer |
+| `createCaSigner(config)` | Create CA signer |
+| `isEoaSigner(signer)` | Type guard for EoaSigner |
+| `isCaSigner(signer)` | Type guard for CaSigner |
+| `getSigningAddress(signer)` | Get `keyAddress` |
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `callViewMethod(rpcUrl, addr, method, params?)` | Read-only contract call (no signer needed) |
+| `pollTxResult(rpcUrl, txId)` | Poll for transaction result |
+| `getAelfInstance(rpcUrl)` | Get cached AElf SDK instance |
+| `fetchChainInfo(apiUrl?)` | Fetch chain info from Portkey API |
+| `clearCaches()` | Clear all caches (for testing) |
+
+## For DApp Skill Developers
+
+### Before (wallet-only)
+
+```typescript
+// awaken-agent-skills/src/core/trade.ts (before)
+export async function executeSwap(config, wallet: any, params) {
+  const account = wallet.address;  // Only works with EOA
+  await approveToken(config, wallet, ...);
+  await callSendMethod(rpcUrl, contract, 'Swap', wallet, args);
+}
+```
+
+### After (signer-compatible)
+
+```typescript
+// awaken-agent-skills/src/core/trade.ts (after)
+import type { AelfSigner } from '@portkey/aelf-signer';
+
+export async function executeSwap(config, signer: AelfSigner, params) {
+  const account = signer.address;  // caAddress for CA, walletAddress for EOA
+  await signer.sendContractCall(rpcUrl, tokenContract, 'Approve', { ... });
+  await signer.sendContractCall(rpcUrl, swapContract, 'Swap', { ... });
+}
+```
+
+### MCP Server Integration
+
+```typescript
+// awaken-agent-skills/src/mcp/server.ts
+import { createSignerFromEnv } from '@portkey/aelf-signer';
+
+// In tool handler:
+const signer = createSignerFromEnv(); // Auto-detects EOA or CA
+const result = await executeSwap(config, signer, params);
+```
+
+## Architecture
+
+```
+@portkey/aelf-signer
+├── src/
+│   ├── types.ts          # AelfSigner interface, result types
+│   ├── utils.ts          # AElf SDK wrappers, TX polling, view calls
+│   ├── eoa-signer.ts     # EoaSigner: direct private key signing
+│   ├── ca-signer.ts      # CaSigner: ManagerForwardCall + protobuf encoding
+│   ├── factory.ts        # createSignerFromEnv, type guards
+│   └── index.ts          # Re-exports
+└── __tests__/
+    └── unit/
+        └── signer.test.ts
+```
+
+### How CaSigner Works
+
+When `CaSigner.sendContractCall(rpcUrl, contractAddr, method, params)` is called:
+
+1. **Resolve CA contract address** — from config or auto-discovered via Portkey API
+2. **Fetch protobuf descriptors** — `getContractFileDescriptorSet` for the target contract
+3. **Find input type** — locate the method's input message type in the protobuf schema
+4. **Encode params** — apply aelf-sdk transforms + protobuf encoding to bytes
+5. **Call ManagerForwardCall** — on the CA contract with `{ caHash, contractAddress, methodName, args }`
+6. **Poll TX result** — wait for mining, return result
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,223 @@
+# @portkey/aelf-signer
+
+> aelf 区块链统一签名接口 — 同时支持 EOA（直接私钥签名）和 CA（Portkey 合约账户，通过 ManagerForwardCall 代理签名）。
+
+[English](./README.md)
+
+---
+
+## 为什么需要
+
+aelf 上的 DApp skill（如 Awaken DEX、eForest NFT 等）目前只支持 EOA 钱包。Portkey CA 钱包用户无法使用这些 skill，因为 CA 交易需要将每个合约调用包装在 `ManagerForwardCall` 中。
+
+`@portkey/aelf-signer` 提供统一的 `AelfSigner` 接口，DApp skill 接受此接口替代原始的 `wallet: any` 参数。签名细节由 signer 内部处理 — EOA 直接签名，CA 则包装为 ManagerForwardCall — 对 DApp skill 完全透明。
+
+## 安装
+
+```bash
+bun add @portkey/aelf-signer
+# 或
+npm install @portkey/aelf-signer
+```
+
+## 快速开始
+
+### 从环境变量自动检测
+
+```typescript
+import { createSignerFromEnv, callViewMethod } from '@portkey/aelf-signer';
+
+// 根据环境变量自动创建 EoaSigner 或 CaSigner
+const signer = createSignerFromEnv();
+
+console.log(`身份地址: ${signer.address}`);       // EOA 地址或 CA 地址
+console.log(`签名密钥: ${signer.keyAddress}`);    // EOA 相同, CA 为 Manager 地址
+console.log(`是否 CA: ${signer.isCa}`);
+
+// 发送合约调用（透明处理：EOA 直签或 CA 通过 ManagerForwardCall）
+const result = await signer.sendContractCall(
+  'https://aelf-public-node.aelf.io',
+  tokenContractAddress,
+  'Transfer',
+  { to: recipient, symbol: 'ELF', amount: '100000000', memo: '' },
+);
+console.log(`交易 ID: ${result.transactionId}`);
+
+// View 调用不需要 signer
+const balance = await callViewMethod(rpcUrl, tokenContract, 'GetBalance', {
+  symbol: 'ELF',
+  owner: signer.address,
+});
+```
+
+### EOA 模式
+
+```typescript
+import { createEoaSigner } from '@portkey/aelf-signer';
+
+const signer = createEoaSigner(process.env.AELF_PRIVATE_KEY!);
+// signer.address === signer.keyAddress === 钱包地址
+```
+
+### CA 模式
+
+```typescript
+import { createCaSigner } from '@portkey/aelf-signer';
+
+const signer = createCaSigner({
+  managerPrivateKey: process.env.PORTKEY_PRIVATE_KEY!,
+  caHash: process.env.PORTKEY_CA_HASH!,
+  caAddress: process.env.PORTKEY_CA_ADDRESS!,
+  // 可选：直接提供以避免 API 查询
+  caContractAddress: process.env.PORTKEY_CA_CONTRACT_ADDRESS,
+  // 可选：默认为主网
+  portkeyApiUrl: 'https://aa-portkey.portkey.finance',
+});
+
+// signer.address = CA 地址（链上身份）
+// signer.keyAddress = Manager 地址（签名密钥）
+```
+
+## 环境变量
+
+### EOA 模式
+
+```bash
+# 设置其一：
+AELF_PRIVATE_KEY=<64位 hex 私钥>
+# 或
+PORTKEY_PRIVATE_KEY=<64位 hex 私钥>
+```
+
+### CA 模式
+
+```bash
+# 三个都必须设置：
+PORTKEY_PRIVATE_KEY=<Manager 私钥 hex>
+PORTKEY_CA_HASH=<CA hash>
+PORTKEY_CA_ADDRESS=<CA 地址>
+
+# 可选：
+PORTKEY_CA_CONTRACT_ADDRESS=<目标链的 CA 合约地址>
+PORTKEY_API_URL=<Portkey API 地址, 默认主网>
+```
+
+检测优先级：
+1. 若 `PORTKEY_CA_HASH` + `PORTKEY_CA_ADDRESS` + `PORTKEY_PRIVATE_KEY` 全部设置 -> **CA 模式**
+2. 若 `AELF_PRIVATE_KEY` 已设置 -> **EOA 模式**
+3. 若仅 `PORTKEY_PRIVATE_KEY` 已设置 -> **EOA 模式**（降级）
+
+## API 参考
+
+### `AelfSigner` 接口
+
+```typescript
+interface AelfSigner {
+  readonly address: string;      // 身份地址
+  readonly keyAddress: string;   // 签名密钥地址
+  readonly isCa: boolean;        // 是否 CA 模式
+
+  sendContractCall(
+    rpcUrl: string,
+    contractAddress: string,
+    methodName: string,
+    params: Record<string, unknown>,
+  ): Promise<SendResult>;
+
+  signMessage(message: string): string;
+}
+```
+
+- `address`: 链上身份地址。EOA 为钱包地址，CA 为合约账户地址。用于 `owner`、`from` 等字段。
+- `keyAddress`: 实际签名密钥的地址。EOA 等于 `address`，CA 为 Manager 地址。用于 API 认证。
+- `sendContractCall()`: 发送合约写入调用。EOA 直接签名；CA 将参数 protobuf 编码后包装为 `ManagerForwardCall`。
+- `signMessage()`: SHA256 哈希并签名消息。返回 hex 签名。
+
+### 工厂函数
+
+| 函数 | 说明 |
+|------|------|
+| `createSignerFromEnv()` | 从环境变量自动检测 signer 类型 |
+| `createEoaSigner(privateKey)` | 创建 EOA signer |
+| `createCaSigner(config)` | 创建 CA signer |
+| `isEoaSigner(signer)` | EoaSigner 类型守卫 |
+| `isCaSigner(signer)` | CaSigner 类型守卫 |
+| `getSigningAddress(signer)` | 获取 `keyAddress` |
+
+### 工具函数
+
+| 函数 | 说明 |
+|------|------|
+| `callViewMethod(rpcUrl, addr, method, params?)` | 只读合约调用（无需 signer） |
+| `pollTxResult(rpcUrl, txId)` | 轮询交易结果 |
+| `getAelfInstance(rpcUrl)` | 获取缓存的 AElf SDK 实例 |
+| `fetchChainInfo(apiUrl?)` | 从 Portkey API 获取链信息 |
+| `clearCaches()` | 清除所有缓存（测试用） |
+
+## DApp Skill 开发者指南
+
+### 改造前（仅支持钱包）
+
+```typescript
+// awaken-agent-skills/src/core/trade.ts（改造前）
+export async function executeSwap(config, wallet: any, params) {
+  const account = wallet.address;  // 只支持 EOA
+  await approveToken(config, wallet, ...);
+  await callSendMethod(rpcUrl, contract, 'Swap', wallet, args);
+}
+```
+
+### 改造后（兼容 signer）
+
+```typescript
+// awaken-agent-skills/src/core/trade.ts（改造后）
+import type { AelfSigner } from '@portkey/aelf-signer';
+
+export async function executeSwap(config, signer: AelfSigner, params) {
+  const account = signer.address;  // CA 返回 caAddress, EOA 返回 walletAddress
+  await signer.sendContractCall(rpcUrl, tokenContract, 'Approve', { ... });
+  await signer.sendContractCall(rpcUrl, swapContract, 'Swap', { ... });
+}
+```
+
+### MCP 服务集成
+
+```typescript
+// awaken-agent-skills/src/mcp/server.ts
+import { createSignerFromEnv } from '@portkey/aelf-signer';
+
+// 在 tool handler 中:
+const signer = createSignerFromEnv(); // 自动检测 EOA 或 CA
+const result = await executeSwap(config, signer, params);
+```
+
+## 架构
+
+```
+@portkey/aelf-signer
+├── src/
+│   ├── types.ts          # AelfSigner 接口, 结果类型
+│   ├── utils.ts          # AElf SDK 封装, TX 轮询, view 调用
+│   ├── eoa-signer.ts     # EoaSigner: 直接私钥签名
+│   ├── ca-signer.ts      # CaSigner: ManagerForwardCall + protobuf 编码
+│   ├── factory.ts        # createSignerFromEnv, 类型守卫
+│   └── index.ts          # 统一导出
+└── __tests__/
+    └── unit/
+        └── signer.test.ts
+```
+
+### CaSigner 工作原理
+
+当调用 `CaSigner.sendContractCall(rpcUrl, contractAddr, method, params)` 时：
+
+1. **解析 CA 合约地址** — 从配置获取或通过 Portkey API 自动发现
+2. **获取 protobuf 描述** — 目标合约的 `getContractFileDescriptorSet`
+3. **查找 input 类型** — 在 protobuf schema 中定位方法的输入消息类型
+4. **编码参数** — 应用 aelf-sdk transform + protobuf 编码为字节
+5. **调用 ManagerForwardCall** — 在 CA 合约上发起 `{ caHash, contractAddress, methodName, args }`
+6. **轮询交易结果** — 等待出块，返回结果
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@portkey/aelf-signer",
+  "version": "1.0.0",
+  "description": "Unified signer interface for aelf blockchain — supports both EOA (direct signing) and CA (Portkey Contract Account via ManagerForwardCall).",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test __tests__/",
+    "test:unit": "bun test __tests__/unit/"
+  },
+  "dependencies": {
+    "aelf-sdk": "^3.5.1-beta.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}