@andrewkimjoseph/celina-sdk 0.2.10 → 0.2.12

package/tests/catalog/domains/transaction.ts

@@ -0,0 +1,111 @@
+import { parseEther } from "viem";
+import type { OperationSpec } from "../types.js";
+import { assertHasKeys } from "../../helpers/assert.js";
+
+function fromAddress(fx: Parameters<OperationSpec["assert"]>[1]): `0x${string}` {
+  return fx.signerAddress ?? fx.wallet;
+}
+
+export const transactionOperations: OperationSpec[] = [
+  {
+    id: "transaction.getGasFeeData",
+    domain: "transaction",
+    layer: "read",
+    sdk: {
+      invoke: (client) => client.transaction.getGasFeeData(),
+    },
+    mcp: {
+      tool: "get_gas_fee_data",
+      arguments: () => ({}),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["network"]);
+    },
+  },
+  {
+    id: "transaction.estimateTransaction",
+    domain: "transaction",
+    layer: "read",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    sdk: {
+      invoke: (client, fx) =>
+        client.transaction.estimateTransaction({
+          from: fromAddress(fx),
+          to: fx.wallet,
+          value: parseEther("0.001").toString(),
+        }),
+    },
+    mcp: {
+      tool: "estimate_transaction",
+      arguments: (fx) => ({
+        from: fromAddress(fx),
+        to: fx.wallet,
+        value: parseEther("0.001").toString(),
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["gasLimit"]);
+    },
+  },
+  {
+    id: "transaction.estimateSend",
+    domain: "transaction",
+    layer: "read",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    sdk: {
+      invoke: (client, fx) =>
+        client.transaction.estimateSend(
+          fromAddress(fx),
+          fx.wallet,
+          "CELO",
+          "0.001",
+        ),
+    },
+    mcp: {
+      tool: "estimate_send",
+      arguments: () => ({
+        to: "0x471EcE3750Da237f93B8E339c536989b8978a438",
+        token: "CELO",
+        amount: "0.001",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["gas"]);
+    },
+  },
+  {
+    id: "transaction.prepareSend",
+    domain: "transaction",
+    layer: "prepare",
+    sdk: {
+      invoke: (client, fx) =>
+        client.transaction.prepareSend(
+          fromAddress(fx),
+          fx.wallet,
+          "CELO",
+          "0.001",
+        ),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["from", "steps", "summary"]);
+    },
+  },
+  {
+    id: "transaction.sendToken",
+    domain: "transaction",
+    layer: "write",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    requiresWrites: true,
+    mcp: {
+      tool: "send_token",
+      arguments: () => ({
+        to: "0x471EcE3750Da237f93B8E339c536989b8978a438",
+        token: "CELO",
+        amount: "0.000001",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["hash"]);
+    },
+  },
+];

package/tests/catalog/index.ts

@@ -0,0 +1,7 @@
+export type { OperationSpec, OperationLayer, EnvRequirement } from "./types.js";
+export {
+  OPERATIONS,
+  MCP_OPERATIONS,
+  SDK_OPERATIONS,
+  MCP_TOOL_NAMES,
+} from "./operations.js";

package/tests/catalog/operations.ts

@@ -0,0 +1,46 @@
+import { blockchainOperations } from "./domains/blockchain.js";
+import { tokenOperations } from "./domains/token.js";
+import { transactionOperations } from "./domains/transaction.js";
+import {
+  aaveOperations,
+  ensOperations,
+  gooddollarOperations,
+  mentoFxOperations,
+  uniswapOperations,
+} from "./domains/defi.js";
+import {
+  contractOperations,
+  governanceOperations,
+  nftOperations,
+  stakingOperations,
+} from "./domains/chain-ext.js";
+import { selfOperations } from "./domains/self.js";
+import type { OperationSpec } from "./types.js";
+
+export const OPERATIONS: OperationSpec[] = [
+  ...blockchainOperations,
+  ...tokenOperations,
+  ...transactionOperations,
+  ...mentoFxOperations,
+  ...uniswapOperations,
+  ...aaveOperations,
+  ...ensOperations,
+  ...gooddollarOperations,
+  ...governanceOperations,
+  ...stakingOperations,
+  ...nftOperations,
+  ...contractOperations,
+  ...selfOperations,
+];
+
+export const MCP_OPERATIONS = OPERATIONS.filter(
+  (spec): spec is OperationSpec & { mcp: NonNullable<OperationSpec["mcp"]> } =>
+    Boolean(spec.mcp),
+);
+
+export const SDK_OPERATIONS = OPERATIONS.filter(
+  (spec): spec is OperationSpec & { sdk: NonNullable<OperationSpec["sdk"]> } =>
+    Boolean(spec.sdk),
+);
+
+export const MCP_TOOL_NAMES = MCP_OPERATIONS.map((spec) => spec.mcp.tool);

package/tests/catalog/types.ts

@@ -0,0 +1,27 @@
+import type { CelinaClient } from "@andrewkimjoseph/celina-sdk";
+import type { MainnetFixtures } from "../fixtures/mainnet.js";
+
+export type OperationLayer = "read" | "write" | "prepare";
+
+export type EnvRequirement = "CELO_PRIVATE_KEY" | "SELF_AGENT_PRIVATE_KEY";
+
+export interface OperationSpec {
+  /** Stable id, e.g. `token.getTokenBalance`. */
+  id: string;
+  domain: string;
+  layer: OperationLayer;
+  requiresEnv?: EnvRequirement[];
+  /** On-chain writes (`send_token`, `execute_mento_fx`, Aave supply/withdraw). */
+  requiresWrites?: boolean;
+  /** Self register / deregister / refresh flows. */
+  requiresDestructive?: boolean;
+  sdk?: {
+    invoke: (client: CelinaClient, fx: MainnetFixtures) => Promise<unknown>;
+  };
+  mcp?: {
+    tool: string;
+    arguments: (fx: MainnetFixtures) => Record<string, unknown>;
+  };
+  assert: (result: unknown, fx: MainnetFixtures) => void;
+  skip?: () => string | undefined;
+}

package/tests/fixtures/mainnet.ts

@@ -0,0 +1,93 @@
+import type { CelinaClient } from "@andrewkimjoseph/celina-sdk";
+import { getSignerAddress } from "../helpers/env.js";
+
+export interface MainnetFixtures {
+  wallet: `0x${string}`;
+  usdm: `0x${string}`;
+  saidContract: `0x${string}`;
+  saidOwner: `0x${string}`;
+  saidTokenId: string;
+  validatorGroup: `0x${string}`;
+  proposalId: number;
+  ensName: string;
+  selfAgentId: number;
+  /** Known registered Self agent for read-only verification. */
+  selfAgentAddress: `0x${string}`;
+  erc20SymbolAbi: readonly [
+    {
+      readonly type: "function";
+      readonly name: "symbol";
+      readonly stateMutability: "view";
+      readonly inputs: readonly [];
+      readonly outputs: readonly [{ readonly type: "string" }];
+    },
+  ];
+  knownTxHash: `0x${string}`;
+  latestBlockNumber: bigint;
+  signerAddress?: `0x${string}`;
+  /** Populated by MCP enrichment when SELF_AGENT_PRIVATE_KEY is set. */
+  selfVerifyRequestArgs?: Record<string, unknown>;
+}
+
+export const MAINNET_STATIC = {
+  wallet: "0x471EcE3750Da237f93B8E339c536989b8978a438" as const,
+  usdm: "0x765DE816845861e75A25fCA122bb6898B8B1282a" as const,
+  saidContract: "0xaC3DF9ABf80d0F5c020C06B04Cced27763355944" as const,
+  saidOwner: "0x62fD20ca524C13Ce836Def1c0FF8e5119476868D" as const,
+  saidTokenId: "1",
+  validatorGroup: "0x0861a61Bf679A30680510EcC238ee43B82C5e843" as const,
+  proposalId: 293,
+  ensName: "celina.eth",
+  selfAgentId: 1,
+  selfAgentAddress: "0xC1C860804EFdA544fe79194d1a37e60b846CEdeb" as const,
+  erc20SymbolAbi: [
+    {
+      type: "function",
+      name: "symbol",
+      stateMutability: "view",
+      inputs: [],
+      outputs: [{ type: "string" }],
+    },
+  ] as const,
+};
+
+let cachedFixtures: MainnetFixtures | null = null;
+
+/** Load stable mainnet fixtures, resolving a recent tx hash once per process. */
+export async function getMainnetFixtures(
+  client: CelinaClient,
+): Promise<MainnetFixtures> {
+  if (cachedFixtures) {
+    return cachedFixtures;
+  }
+
+  const status = await client.blockchain.getNetworkStatus();
+  const latestBlockNumber = BigInt(status.blockNumber);
+  const block = await client.blockchain.getBlock(Number(latestBlockNumber), {
+    includeTransactions: true,
+  });
+
+  const txs = block.transactions as Array<{ hash?: `0x${string}` } | string>;
+  const firstTx = txs[0];
+  const knownTxHash =
+    typeof firstTx === "string"
+      ? (firstTx as `0x${string}`)
+      : (firstTx?.hash as `0x${string}`);
+
+  if (!knownTxHash) {
+    throw new Error("Could not resolve a mainnet transaction hash from latest block");
+  }
+
+  cachedFixtures = {
+    ...MAINNET_STATIC,
+    knownTxHash,
+    latestBlockNumber,
+    signerAddress: getSignerAddress(),
+  };
+
+  return cachedFixtures;
+}
+
+export function resetMainnetFixturesCache(): void {
+  cachedFixtures = null;
+}

package/tests/helpers/assert.ts

@@ -0,0 +1,30 @@
+import { expect } from "vitest";
+
+export function assertDefined(result: unknown): asserts result is NonNullable<unknown> {
+  expect(result).toBeDefined();
+  expect(result).not.toBeNull();
+}
+
+export function assertObject(result: unknown): Record<string, unknown> {
+  assertDefined(result);
+  expect(typeof result).toBe("object");
+  expect(Array.isArray(result)).toBe(false);
+  return result as Record<string, unknown>;
+}
+
+export function assertArray(result: unknown): unknown[] {
+  assertDefined(result);
+  expect(Array.isArray(result)).toBe(true);
+  return result as unknown[];
+}
+
+export function assertHasKeys(
+  result: unknown,
+  keys: string[],
+): Record<string, unknown> {
+  const obj = assertObject(result);
+  for (const key of keys) {
+    expect(obj).toHaveProperty(key);
+  }
+  return obj;
+}

package/tests/helpers/env.ts

@@ -0,0 +1,38 @@
+import { privateKeyToAccount } from "viem/accounts";
+
+export interface TestConfig {
+  rpcUrl: string;
+  ethRpcUrl?: string;
+}
+
+export function hasCeloWallet(): boolean {
+  return Boolean(process.env.CELO_PRIVATE_KEY);
+}
+
+export function hasSelfAgentKey(): boolean {
+  return Boolean(process.env.SELF_AGENT_PRIVATE_KEY);
+}
+
+export function allowsTestWrites(): boolean {
+  return process.env.CELINA_TEST_WRITES === "1";
+}
+
+export function allowsDestructiveTests(): boolean {
+  return process.env.CELINA_TEST_DESTRUCTIVE === "1";
+}
+
+export function getSignerAddress(): `0x${string}` | undefined {
+  const key = process.env.CELO_PRIVATE_KEY;
+  if (!key) {
+    return undefined;
+  }
+  return privateKeyToAccount(key as `0x${string}`).address;
+}
+
+/** RPC URLs aligned with celina-mcp `loadConfig()`. */
+export function loadTestConfig(): TestConfig {
+  return {
+    rpcUrl: process.env.CELO_RPC_URL_MAINNET ?? "https://forno.celo.org",
+    ethRpcUrl: process.env.ETH_RPC_URL_MAINNET,
+  };
+}

package/tests/helpers/gating.ts

@@ -0,0 +1,36 @@
+import type { OperationSpec } from "../catalog/types.js";
+import {
+  allowsDestructiveTests,
+  allowsTestWrites,
+  hasCeloWallet,
+  hasSelfAgentKey,
+} from "./env.js";
+
+const ENV_CHECKS: Record<
+  NonNullable<OperationSpec["requiresEnv"]>[number],
+  () => boolean
+> = {
+  CELO_PRIVATE_KEY: hasCeloWallet,
+  SELF_AGENT_PRIVATE_KEY: hasSelfAgentKey,
+};
+
+/** Returns a skip reason when the operation should not run, otherwise undefined. */
+export function getOperationSkipReason(spec: OperationSpec): string | undefined {
+  if (spec.requiresDestructive && !allowsDestructiveTests()) {
+    return "Set CELINA_TEST_DESTRUCTIVE=1 to run destructive Self lifecycle tests";
+  }
+
+  if (spec.requiresWrites && !allowsTestWrites()) {
+    return "Set CELINA_TEST_WRITES=1 to run on-chain write tests";
+  }
+
+  if (spec.requiresEnv) {
+    for (const requirement of spec.requiresEnv) {
+      if (!ENV_CHECKS[requirement]()) {
+        return `Missing ${requirement}`;
+      }
+    }
+  }
+
+  return spec.skip?.() ?? undefined;
+}

package/tests/testing-entry.ts

@@ -0,0 +1,22 @@
+export type {
+  EnvRequirement,
+  OperationLayer,
+  OperationSpec,
+} from "./catalog/types.js";
+export {
+  MCP_OPERATIONS,
+  MCP_TOOL_NAMES,
+  OPERATIONS,
+  SDK_OPERATIONS,
+} from "./catalog/operations.js";
+export { getMainnetFixtures, type MainnetFixtures } from "./fixtures/mainnet.js";
+export {
+  allowsDestructiveTests,
+  allowsTestWrites,
+  getSignerAddress,
+  hasCeloWallet,
+  hasSelfAgentKey,
+  loadTestConfig,
+  type TestConfig,
+} from "./helpers/env.js";
+export { getOperationSkipReason } from "./helpers/gating.js";