@portkey/ca-agent-skills 1.1.0

package/lib/aelf-client.ts

@@ -0,0 +1,281 @@
+import AElf from 'aelf-sdk';
+import type { WalletInfo, TransactionResult } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types (aelf-sdk does not ship clean TS types, see ./aelf-sdk.d.ts)
+// ---------------------------------------------------------------------------
+
+export interface AElfWallet {
+  address: string;
+  privateKey: string;
+  mnemonic?: string;
+  BIP44Path?: string;
+  childWallet?: unknown;
+  keyPair?: unknown;
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type AElfInstance = InstanceType<typeof AElf>;
+export type AElfContract = Record<string, any>;
+
+// ---------------------------------------------------------------------------
+// Instance & contract caches
+// ---------------------------------------------------------------------------
+
+const aelfInstanceCache: Record<string, AElfInstance> = {};
+const contractCache: Record<string, AElfContract> = {};
+
+// ---------------------------------------------------------------------------
+// Wallet helpers
+// ---------------------------------------------------------------------------
+
+/** Create a brand-new wallet (manager keypair). */
+export function createWallet(): WalletInfo {
+  const w = AElf.wallet.createNewWallet();
+  return {
+    address: w.address,
+    privateKey: w.privateKey,
+    mnemonic: w.mnemonic,
+  };
+}
+
+/** Restore a wallet from a private key string. */
+export function getWalletByPrivateKey(privateKey: string): AElfWallet {
+  return AElf.wallet.getWalletByPrivateKey(privateKey) as AElfWallet;
+}
+
+// ---------------------------------------------------------------------------
+// AElf instance
+// ---------------------------------------------------------------------------
+
+/** Get (or create) an AElf SDK instance for the given RPC URL. */
+export function getAelfInstance(rpcUrl: string): AElfInstance {
+  if (!aelfInstanceCache[rpcUrl]) {
+    aelfInstanceCache[rpcUrl] = new AElf(new AElf.providers.HttpProvider(rpcUrl, 20_000));
+  }
+  return aelfInstanceCache[rpcUrl];
+}
+
+// ---------------------------------------------------------------------------
+// Contract instance
+// ---------------------------------------------------------------------------
+
+/**
+ * Get (or create) a contract instance.
+ * - For view-only calls, `wallet` can be any wallet (a default one is fine).
+ * - For send calls, `wallet` must be the manager wallet that owns the CA.
+ */
+export async function getContractInstance(
+  rpcUrl: string,
+  contractAddress: string,
+  wallet: AElfWallet,
+): Promise<AElfContract> {
+  const key = `${rpcUrl}|${contractAddress}|${wallet.address}`;
+  if (!contractCache[key]) {
+    const instance = getAelfInstance(rpcUrl);
+    contractCache[key] = await instance.chain.contractAt(contractAddress, wallet);
+  }
+  return contractCache[key];
+}
+
+// ---------------------------------------------------------------------------
+// Contract call helpers
+// ---------------------------------------------------------------------------
+
+/** Call a read-only (view) method on a contract. */
+export async function callViewMethod<T = unknown>(
+  rpcUrl: string,
+  contractAddress: string,
+  methodName: string,
+  params?: Record<string, unknown>,
+): Promise<T> {
+  // View methods don't require a real identity — use a random ephemeral wallet.
+  // NEVER hard-code a real private key here.
+  const defaultWallet = createWallet();
+  const contract = await getContractInstance(rpcUrl, contractAddress, defaultWallet);
+
+  const method = contract[methodName];
+  if (!method || typeof method?.call !== 'function') {
+    throw new Error(`Contract method "${methodName}" not found at ${contractAddress}`);
+  }
+
+  const result = await method.call(params ?? {});
+  if (result && typeof result === 'object' && 'error' in result && result.error) {
+    throw new Error(`View call ${methodName} failed: ${JSON.stringify(result.error)}`);
+  }
+  // aelf-sdk wraps result in { result } or returns directly
+  return ((result && typeof result === 'object' && 'result' in result ? result.result : result) ?? result) as T;
+}
+
+/** Call a state-changing (send) method on a contract. Returns the TX result. */
+export async function callSendMethod(
+  rpcUrl: string,
+  contractAddress: string,
+  wallet: AElfWallet,
+  methodName: string,
+  params: Record<string, unknown>,
+): Promise<{ transactionId: string; data: TransactionResult }> {
+  const contract = await getContractInstance(rpcUrl, contractAddress, wallet);
+
+  const method = contract[methodName];
+  if (!method || typeof method !== 'function') {
+    throw new Error(`Contract method "${methodName}" not found at ${contractAddress}`);
+  }
+
+  const sendResult = await method(params);
+  const txId = sendResult?.result?.TransactionId || sendResult?.TransactionId;
+
+  if (sendResult && typeof sendResult === 'object' && 'error' in sendResult && sendResult.error) {
+    throw new Error(
+      `Send call ${methodName} failed: ${JSON.stringify(sendResult.error)}`,
+    );
+  }
+
+  if (!txId) {
+    throw new Error(`Send call ${methodName} did not return a TransactionId`);
+  }
+
+  // Wait for TX to be mined, then fetch result
+  await sleep(1000);
+  const txResult = await getTxResult(rpcUrl, txId);
+  return { transactionId: txId, data: txResult };
+}
+
+// ---------------------------------------------------------------------------
+// ManagerForwardCall parameter encoding
+// ---------------------------------------------------------------------------
+
+/**
+ * Encode parameters for ManagerForwardCall.
+ *
+ * ManagerForwardCall expects `args` as protobuf-encoded bytes of the target
+ * method's input type. This function:
+ * 1. Fetches the target contract's FileDescriptorSet
+ * 2. Finds the target method's input protobuf type
+ * 3. Encodes the args using that type
+ *
+ * Returns the full ManagerForwardCall params ready to be sent.
+ */
+export async function encodeManagerForwardCallParams(
+  rpcUrl: string,
+  params: {
+    caHash: string;
+    contractAddress: string;
+    methodName: string;
+    args: Record<string, unknown>;
+  },
+): Promise<Record<string, unknown>> {
+  const instance = getAelfInstance(rpcUrl);
+
+  // Get target contract's protobuf descriptors
+  const fds = await instance.chain.getContractFileDescriptorSet(params.contractAddress);
+  const root = AElf.pbjs.Root.fromDescriptor(fds, 'proto3');
+
+  // Find the method's input type across all services
+  let inputType: unknown = null;
+  const cleanMethodName = params.methodName.replace('.', '');
+
+  for (const svc of root.nestedArray) {
+    if ((svc as { methods?: Record<string, unknown> }).methods) {
+      const service = svc as { methods: Record<string, { resolvedRequestType?: unknown }> };
+      const method = service.methods[cleanMethodName];
+      if (method?.resolvedRequestType) {
+        inputType = method.resolvedRequestType;
+        break;
+      }
+    }
+    // Also check nested namespaces
+    if ((svc as { nestedArray?: unknown[] }).nestedArray) {
+      for (const nested of (svc as { nestedArray: { methods?: Record<string, { resolvedRequestType?: unknown }> }[] }).nestedArray) {
+        if (nested.methods?.[cleanMethodName]?.resolvedRequestType) {
+          inputType = nested.methods[cleanMethodName].resolvedRequestType;
+          break;
+        }
+      }
+    }
+  }
+
+  if (!inputType) {
+    throw new Error(
+      `Method "${params.methodName}" not found in contract ${params.contractAddress}`,
+    );
+  }
+
+  // Encode args using protobuf
+  const type = inputType as {
+    fromObject: (obj: unknown) => unknown;
+    encode: (msg: unknown) => { finish: () => Uint8Array };
+  };
+
+  let input = params.args;
+  // Apply aelf-sdk transforms if available
+  if (AElf.utils?.transform?.transformMapToArray) {
+    input = AElf.utils.transform.transformMapToArray(inputType, input);
+  }
+  if (AElf.utils?.transform?.transform && AElf.utils?.transform?.INPUT_TRANSFORMERS) {
+    input = AElf.utils.transform.transform(
+      inputType,
+      input,
+      AElf.utils.transform.INPUT_TRANSFORMERS,
+    );
+  }
+
+  const message = type.fromObject(input);
+  const encodedArgs = type.encode(message).finish();
+
+  return {
+    caHash: params.caHash,
+    contractAddress: params.contractAddress,
+    methodName: params.methodName,
+    args: encodedArgs,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Transaction result polling
+// ---------------------------------------------------------------------------
+
+const TX_RESULT_MAX_RETRIES = 20;
+const TX_RESULT_RETRY_DELAY = 1500;
+
+/** Poll for a transaction result until it is mined or fails. */
+export async function getTxResult(
+  rpcUrl: string,
+  txId: string,
+  maxRetries = TX_RESULT_MAX_RETRIES,
+): Promise<TransactionResult> {
+  const instance = getAelfInstance(rpcUrl);
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const result = await instance.chain.getTxResult(txId);
+      if (result.Status === 'MINED' || result.Status === 'FAILED') {
+        if (result.Status === 'FAILED') {
+          throw new Error(`Transaction ${txId} FAILED: ${result.Error || 'Unknown error'}`);
+        }
+        return result as TransactionResult;
+      }
+    } catch (err: unknown) {
+      // If the error is our own FAILED error, re-throw
+      if (err instanceof Error && err.message.includes('FAILED')) throw err;
+      // Otherwise it might be "not found yet", keep retrying
+    }
+    await sleep(TX_RESULT_RETRY_DELAY);
+  }
+
+  throw new Error(`Transaction ${txId} not confirmed after ${maxRetries} retries`);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Clear all caches (useful for testing). */
+export function clearCaches(): void {
+  for (const key of Object.keys(aelfInstanceCache)) delete aelfInstanceCache[key];
+  for (const key of Object.keys(contractCache)) delete contractCache[key];
+}

package/lib/aelf-sdk.d.ts

@@ -0,0 +1,103 @@
+declare module 'aelf-sdk' {
+  interface HttpProvider {
+    new (host: string, timeout?: number): HttpProvider;
+  }
+
+  interface WalletModule {
+    createNewWallet(): {
+      address: string;
+      privateKey: string;
+      mnemonic: string;
+      BIP44Path: string;
+      childWallet: unknown;
+      keyPair: unknown;
+    };
+    getWalletByPrivateKey(privateKey: string): {
+      address: string;
+      privateKey: string;
+      keyPair: unknown;
+    };
+  }
+
+  interface ChainModule {
+    contractAt(
+      contractAddress: string,
+      wallet: { address: string; privateKey?: string },
+    ): Promise<Record<string, any>>;
+    getTxResult(txId: string): Promise<Record<string, any>>;
+    getContractFileDescriptorSet(address: string): Promise<any>;
+  }
+
+  interface PbjsModule {
+    Root: {
+      fromDescriptor(descriptor: any, syntax?: string): any;
+    };
+  }
+
+  interface UtilsModule {
+    transform?: {
+      transformMapToArray(type: any, params: any): any;
+      transform(type: any, params: any, transformers: any): any;
+      INPUT_TRANSFORMERS: any;
+    };
+  }
+
+  class AElf {
+    constructor(provider: HttpProvider);
+    chain: ChainModule;
+    currentProvider: { host: string };
+    static providers: { HttpProvider: new (host: string, timeout?: number) => HttpProvider };
+    static wallet: WalletModule;
+    static pbjs: PbjsModule;
+    static utils: UtilsModule;
+  }
+
+  export default AElf;
+}
+
+declare module 'aelf-sdk/src/util/keyStore.js' {
+  interface KeystoreWalletInfo {
+    privateKey: string;
+    mnemonic: string;
+    address?: string;
+    nickName?: string;
+  }
+
+  interface KeystoreObject {
+    version: number;
+    type: string;
+    nickName?: string;
+    address: string;
+    crypto: {
+      cipher: string;
+      ciphertext: string;
+      cipherparams: { iv: string };
+      mnemonicEncrypted: string;
+      kdf: string;
+      kdfparams: {
+        r: number;
+        n: number;
+        p: number;
+        dklen: number;
+        salt: string;
+      };
+      mac: string;
+    };
+  }
+
+  export function getKeystore(
+    walletInfo: KeystoreWalletInfo,
+    password: string,
+    option?: Record<string, unknown>,
+  ): KeystoreObject;
+
+  export function unlockKeystore(
+    keyStore: KeystoreObject | Record<string, unknown>,
+    password: string,
+  ): KeystoreWalletInfo;
+
+  export function checkPassword(
+    keyStore: KeystoreObject | Record<string, unknown>,
+    password: string,
+  ): boolean;
+}

package/lib/config.ts

@@ -0,0 +1,46 @@
+import type { NetworkType, PortkeyConfig, NetworkDefaults } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Network defaults
+// ---------------------------------------------------------------------------
+
+const NETWORK_DEFAULTS: Record<NetworkType, NetworkDefaults> = {
+  mainnet: {
+    apiUrl: 'https://aa-portkey.portkey.finance',
+    graphqlUrl: 'https://indexer-api.aefinder.io/api/app/graphql/portkey',
+  },
+  testnet: {
+    apiUrl: 'https://aa-portkey-test.portkey.finance',
+    graphqlUrl: 'https://test-indexer-api.aefinder.io/api/app/graphql/portkey',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Config builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a PortkeyConfig with the following priority (high -> low):
+ *   1. Function parameter `override`
+ *   2. CLI arguments (handled by the caller)
+ *   3. MCP env block (handled by the caller)
+ *   4. Environment variables: PORTKEY_NETWORK, PORTKEY_API_URL, PORTKEY_GRAPHQL_URL
+ *   5. Code defaults (mainnet)
+ */
+export function getConfig(override?: Partial<PortkeyConfig> & { network?: NetworkType }): PortkeyConfig {
+  const network: NetworkType =
+    override?.network || (process.env.PORTKEY_NETWORK as NetworkType) || 'mainnet';
+
+  const defaults = NETWORK_DEFAULTS[network];
+  if (!defaults) {
+    throw new Error(`Unknown network: ${network}. Expected "mainnet" or "testnet".`);
+  }
+
+  return {
+    network,
+    apiUrl: override?.apiUrl || process.env.PORTKEY_API_URL || defaults.apiUrl,
+    graphqlUrl: override?.graphqlUrl || process.env.PORTKEY_GRAPHQL_URL || defaults.graphqlUrl,
+  };
+}
+
+export { NETWORK_DEFAULTS };

package/lib/http.ts

@@ -0,0 +1,197 @@
+import type { PortkeyConfig } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface HttpRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  params?: Record<string, string | number | boolean | undefined>;
+  data?: unknown;
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+
+interface ApiResponse<T = unknown> {
+  code: string;
+  message: string;
+  data: T;
+}
+
+// ---------------------------------------------------------------------------
+// HttpError — structured error for precise matching
+// ---------------------------------------------------------------------------
+
+export class HttpError extends Error {
+  /** HTTP status code (e.g. 400, 404, 500) */
+  statusCode: number;
+  /** Portkey API error code (e.g. '3002'), if present */
+  errorCode: string | null;
+  /** Raw response body text */
+  responseBody: string;
+
+  constructor(statusCode: number, statusText: string, body: string) {
+    // Try to extract API error code and message from JSON body
+    let errorCode: string | null = null;
+    let apiMessage = '';
+    try {
+      const parsed = JSON.parse(body);
+      errorCode = parsed?.code ?? parsed?.Code ?? null;
+      apiMessage = parsed?.message ?? parsed?.Message ?? '';
+    } catch {
+      apiMessage = body;
+    }
+
+    super(`HTTP ${statusCode} ${statusText}: ${apiMessage || body}`);
+    this.name = 'HttpError';
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.responseBody = body;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP client
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TIMEOUT = 20_000;
+
+/**
+ * Lightweight HTTP client for Portkey Backend API.
+ *
+ * Usage:
+ *   const client = createHttpClient(config);
+ *   const result = await client.get('/api/app/wallet/getRegisterInfo', { params: { ... } });
+ *   const result = await client.post('/api/app/account/sendVerificationRequest', { data: { ... } });
+ */
+export function createHttpClient(config: PortkeyConfig) {
+  const baseUrl = config.apiUrl.replace(/\/$/, '');
+
+  async function request<T = unknown>(endpoint: string, options: HttpRequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, data, headers = {}, timeout = DEFAULT_TIMEOUT } = options;
+
+    // Build URL with query params
+    let url = `${baseUrl}${endpoint}`;
+    if (params) {
+      const searchParams = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+          searchParams.set(key, String(value));
+        }
+      }
+      const qs = searchParams.toString();
+      if (qs) url += `?${qs}`;
+    }
+
+    // Build fetch options
+    const fetchOptions: RequestInit = {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+    };
+
+    if (data && method !== 'GET') {
+      fetchOptions.body = JSON.stringify(data);
+    }
+
+    // Timeout via AbortController
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    fetchOptions.signal = controller.signal;
+
+    try {
+      const response = await fetch(url, fetchOptions);
+      clearTimeout(timer);
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new HttpError(response.status, response.statusText, text);
+      }
+
+      const json = await response.json() as ApiResponse<T> | T;
+
+      // Portkey API wraps some responses in { code, message, data }
+      if (json && typeof json === 'object' && 'code' in json) {
+        const wrapped = json as ApiResponse<T>;
+        if (wrapped.code !== '20000' && wrapped.code !== '0') {
+          throw new Error(`API error [${wrapped.code}]: ${wrapped.message}`);
+        }
+        return wrapped.data;
+      }
+
+      return json as T;
+    } catch (err: unknown) {
+      clearTimeout(timer);
+      if (err instanceof DOMException && err.name === 'AbortError') {
+        throw new Error(`Request timeout after ${timeout}ms: ${method} ${url}`);
+      }
+      throw err;
+    }
+  }
+
+  return {
+    get<T = unknown>(endpoint: string, options?: Omit<HttpRequestOptions, 'method' | 'data'>) {
+      return request<T>(endpoint, { ...options, method: 'GET' });
+    },
+    post<T = unknown>(endpoint: string, options?: Omit<HttpRequestOptions, 'method'>) {
+      return request<T>(endpoint, { ...options, method: 'POST' });
+    },
+    put<T = unknown>(endpoint: string, options?: Omit<HttpRequestOptions, 'method'>) {
+      return request<T>(endpoint, { ...options, method: 'PUT' });
+    },
+    del<T = unknown>(endpoint: string, options?: Omit<HttpRequestOptions, 'method'>) {
+      return request<T>(endpoint, { ...options, method: 'DELETE' });
+    },
+    /** Raw request with full control */
+    request,
+  };
+}
+
+export type HttpClient = ReturnType<typeof createHttpClient>;
+
+// ---------------------------------------------------------------------------
+// SSRF protection — validate user-supplied RPC URLs
+// ---------------------------------------------------------------------------
+
+const PRIVATE_IP_PATTERNS = [
+  /^localhost$/i,
+  /^127\./,
+  /^10\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^192\.168\./,
+  /^0\./,
+  /^\[::1\]/,
+  /^\[fd/i,      // IPv6 unique-local
+  /^\[fe80:/i,   // IPv6 link-local
+];
+
+/**
+ * Validate a user-supplied RPC URL to prevent SSRF attacks.
+ * - Requires https:// (or http:// only for known aelf domains)
+ * - Blocks private/internal IP ranges and localhost
+ *
+ * Throws if the URL is unsafe.
+ */
+export function validateRpcUrl(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid RPC URL: ${url}`);
+  }
+
+  // Only allow http(s)
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`RPC URL must use http(s) protocol, got: ${parsed.protocol}`);
+  }
+
+  // Block private/internal addresses
+  const hostname = parsed.hostname;
+  for (const pattern of PRIVATE_IP_PATTERNS) {
+    if (pattern.test(hostname)) {
+      throw new Error(`RPC URL must not point to a private/internal address: ${hostname}`);
+    }
+  }
+}