@andrewkimjoseph/celina-sdk 0.2.11 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrewkimjoseph/celina-sdk",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Celina SDK — Celo mainnet reads and unsigned transaction preparation for frontend apps.",
   "type": "module",
   "sideEffects": false,
@@ -11,10 +11,19 @@
       "types": "./build/index.d.ts",
       "import": "./build/index.js",
       "default": "./build/index.js"
+    },
+    "./testing": {
+      "types": "./tests/testing-entry.ts",
+      "import": "./tests/testing-entry.ts",
+      "default": "./tests/testing-entry.ts"
     }
   },
   "files": [
     "build/",
+    "tests/catalog/",
+    "tests/fixtures/",
+    "tests/helpers/",
+    "tests/testing-entry.ts",
     "README.md",
     "LICENSE"
   ],

package/tests/README.md

@@ -0,0 +1,72 @@
+# Celina operations test framework
+
+Live Celo mainnet smoke tests driven by a single operation catalog in `tests/catalog/operations.ts`. Add one `OperationSpec` when you ship a new SDK method or MCP tool.
+
+## Commands
+
+```bash
+# celina-sdk
+npm test          # live mainnet SDK smoke (catalog)
+npm run test:unit # pure helpers (no RPC)
+
+# celina-mcp
+npm test          # build + live MCP smoke + registry parity
+npm run test:unit # MCP helper unit tests
+```
+
+## Environment matrix
+
+| Variable | Effect |
+|----------|--------|
+| *(none)* | Read-only mainnet smoke tests |
+| `CELO_RPC_URL_MAINNET` | Optional RPC override (default: `https://forno.celo.org`) |
+| `ETH_RPC_URL_MAINNET` | ENS resolution on Ethereum |
+| `CELO_PRIVATE_KEY` | Enables estimates and prepare flows that need a signer address |
+| `CELINA_TEST_WRITES=1` | **Plus** `CELO_PRIVATE_KEY`: runs on-chain writes (`send_token`, `execute_mento_fx`, Aave supply/withdraw) |
+| `SELF_AGENT_PRIVATE_KEY` | Self auth tools (`sign_self_request`, `authenticated_self_fetch`, `get_self_identity`) |
+| `CELINA_TEST_SELF_VERIFY=1` | **Plus** `SELF_AGENT_PRIVATE_KEY`: builds signed fixture for `verify_self_request` |
+| `CELINA_TEST_SELF_SESSION` | Poll a pending Self session via `check_self_registration` |
+| `CELINA_TEST_DESTRUCTIVE=1` | Self lifecycle mutations (`register_self_agent`, `refresh_self_proof`, `deregister_self_agent`) |
+
+Writes and destructive Self flows are **off by default** so `npm test` does not spend funds or mutate agent state accidentally.
+
+## Adding a new operation
+
+1. Implement the SDK service method in `src/services/` (if applicable).
+2. Add the MCP wrapper in `celina-mcp/src/tools/` (if exposed).
+3. Append one `OperationSpec` to `tests/catalog/domains/*.ts` (aggregated in `operations.ts`).
+4. Run `npm test` in `celina-sdk`, then `celina-mcp`.
+5. `registry-parity.test.ts` fails if an MCP tool lacks a catalog entry.
+
+`celina-mcp` imports the shared catalog via `@andrewkimjoseph/celina-sdk/testing` (published with the SDK package).
+
+### OperationSpec shape
+
+```ts
+{
+  id: "domain.methodName",
+  domain: "token",
+  layer: "read" | "write" | "prepare",
+  requiresEnv?: ["CELO_PRIVATE_KEY" | "SELF_AGENT_PRIVATE_KEY"],
+  requiresWrites?: true,       // needs CELINA_TEST_WRITES=1
+  requiresDestructive?: true,  // needs CELINA_TEST_DESTRUCTIVE=1
+  sdk?: { invoke(client, fixtures) { ... } },
+  mcp?: { tool: "snake_case_tool", arguments(fixtures) { ... } },
+  assert(result, fixtures) { ... },
+  skip?: () => string | undefined,
+}
+```
+
+At least one of `sdk` or `mcp` must be set. SDK-only prepare methods (no MCP tool yet) still belong in the catalog for SDK regression.
+
+## Fixtures
+
+Stable mainnet constants live in `tests/fixtures/mainnet.ts`. A recent transaction hash is resolved once per process from the latest block.
+
+## Architecture
+
+```
+fixtures/mainnet.ts ──► catalog/operations.ts ──► sdk-operations.test.ts
+                                              └──► celina-mcp/mcp-tools.test.ts
+                                              └──► registry-parity.test.ts
+```

package/tests/catalog/domains/blockchain.ts

@@ -0,0 +1,91 @@
+import { expect } from "vitest";
+import type { OperationSpec } from "../types.js";
+import { assertArray, assertHasKeys } from "../../helpers/assert.js";
+
+function expectNumberLike(value: unknown): void {
+  expect(value).toBeDefined();
+  expect(Number(value)).not.toBeNaN();
+}
+
+export const blockchainOperations: OperationSpec[] = [
+  {
+    id: "blockchain.getNetworkStatus",
+    domain: "blockchain",
+    layer: "read",
+    sdk: {
+      invoke: (client) => client.blockchain.getNetworkStatus(),
+    },
+    mcp: {
+      tool: "get_network_status",
+      arguments: () => ({}),
+    },
+    assert: (result) => {
+      const obj = assertHasKeys(result, ["network", "chainId", "blockNumber"]);
+      expectNumberLike(obj.blockNumber);
+    },
+  },
+  {
+    id: "blockchain.getBlock",
+    domain: "blockchain",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.blockchain.getBlock(Number(fx.latestBlockNumber)),
+    },
+    mcp: {
+      tool: "get_block",
+      arguments: (fx) => ({
+        blockId: Number(fx.latestBlockNumber),
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["number", "hash"]);
+    },
+  },
+  {
+    id: "blockchain.getLatestBlocks",
+    domain: "blockchain",
+    layer: "read",
+    sdk: {
+      invoke: (client) => client.blockchain.getLatestBlocks(3, 0),
+    },
+    mcp: {
+      tool: "get_latest_blocks",
+      arguments: () => ({ count: 3, offset: 0 }),
+    },
+    assert: (result) => {
+      const blocks = assertArray(result);
+      expect(blocks.length).toBeGreaterThan(0);
+    },
+  },
+  {
+    id: "blockchain.getTransaction",
+    domain: "blockchain",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) => client.blockchain.getTransaction(fx.knownTxHash),
+    },
+    mcp: {
+      tool: "get_transaction",
+      arguments: (fx) => ({ hash: fx.knownTxHash }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["hash", "from"]);
+    },
+  },
+  {
+    id: "account.getAccount",
+    domain: "blockchain",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) => client.account.getAccount(fx.wallet),
+    },
+    mcp: {
+      tool: "get_account",
+      arguments: (fx) => ({ address: fx.wallet }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["address", "balanceWei"]);
+    },
+  },
+];

package/tests/catalog/domains/chain-ext.ts

@@ -0,0 +1,219 @@
+import { expect } from "vitest";
+import type { OperationSpec } from "../types.js";
+import { assertArray, assertHasKeys } from "../../helpers/assert.js";
+
+export const governanceOperations: OperationSpec[] = [
+  {
+    id: "governance.getGovernanceProposals",
+    domain: "governance",
+    layer: "read",
+    sdk: {
+      invoke: (client) =>
+        client.governance.getGovernanceProposals({ page: 1, pageSize: 5 }),
+    },
+    mcp: {
+      tool: "get_governance_proposals",
+      arguments: () => ({ page: 1, pageSize: 5 }),
+    },
+    assert: (result) => {
+      const obj = assertHasKeys(result, ["proposals", "pagination"]);
+      expect(Array.isArray(obj.proposals)).toBe(true);
+    },
+  },
+  {
+    id: "governance.getProposalDetails",
+    domain: "governance",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.governance.getProposalDetails(fx.proposalId),
+    },
+    mcp: {
+      tool: "get_proposal_details",
+      arguments: (fx) => ({ proposalId: fx.proposalId }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["proposal"]);
+    },
+  },
+];
+
+export const stakingOperations: OperationSpec[] = [
+  {
+    id: "staking.getStakingBalances",
+    domain: "staking",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) => client.staking.getStakingBalances(fx.wallet),
+    },
+    mcp: {
+      tool: "get_staking_balances",
+      arguments: (fx) => ({ address: fx.wallet }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["address", "groups"]);
+    },
+  },
+  {
+    id: "staking.getActivatableStakes",
+    domain: "staking",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) => client.staking.getActivatableStakes(fx.wallet),
+    },
+    mcp: {
+      tool: "get_activatable_stakes",
+      arguments: (fx) => ({ address: fx.wallet }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["activatableGroups"]);
+    },
+  },
+  {
+    id: "staking.getValidatorGroups",
+    domain: "staking",
+    layer: "read",
+    sdk: {
+      invoke: (client) =>
+        client.staking.getValidatorGroups({ page: 1, pageSize: 5 }),
+    },
+    mcp: {
+      tool: "get_validator_groups",
+      arguments: () => ({ page: 1, pageSize: 5 }),
+    },
+    assert: (result) => {
+      const obj = assertHasKeys(result, ["groups"]);
+      assertArray(obj.groups);
+    },
+  },
+  {
+    id: "staking.getValidatorGroupDetails",
+    domain: "staking",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.staking.getValidatorGroupDetails(fx.validatorGroup),
+    },
+    mcp: {
+      tool: "get_validator_group_details",
+      arguments: (fx) => ({ groupAddress: fx.validatorGroup }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["address", "name"]);
+    },
+  },
+  {
+    id: "staking.getTotalStakingInfo",
+    domain: "staking",
+    layer: "read",
+    sdk: {
+      invoke: (client) => client.staking.getTotalStakingInfo(),
+    },
+    mcp: {
+      tool: "get_total_staking_info",
+      arguments: () => ({}),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["totalVotes"]);
+    },
+  },
+];
+
+export const nftOperations: OperationSpec[] = [
+  {
+    id: "nft.getNftInfo",
+    domain: "nft",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.nft.getNftInfo(fx.saidContract, fx.saidTokenId),
+    },
+    mcp: {
+      tool: "get_nft_info",
+      arguments: (fx) => ({
+        contractAddress: fx.saidContract,
+        tokenId: fx.saidTokenId,
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["contractAddress", "tokenId"]);
+    },
+  },
+  {
+    id: "nft.getNftBalance",
+    domain: "nft",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.nft.getNftBalance(fx.saidContract, fx.saidOwner),
+    },
+    mcp: {
+      tool: "get_nft_balance",
+      arguments: (fx) => ({
+        contractAddress: fx.saidContract,
+        address: fx.saidOwner,
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["balance"]);
+    },
+  },
+];
+
+export const contractOperations: OperationSpec[] = [
+  {
+    id: "contract.callFunction",
+    domain: "contract",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.contract.callFunction({
+          contractAddress: fx.usdm,
+          abi: fx.erc20SymbolAbi,
+          functionName: "symbol",
+          functionArgs: [],
+        }),
+    },
+    mcp: {
+      tool: "call_contract_function",
+      arguments: (fx) => ({
+        contractAddress: fx.usdm,
+        abi: fx.erc20SymbolAbi,
+        functionName: "symbol",
+        functionArgs: [],
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["result"]);
+    },
+  },
+  {
+    id: "contract.estimateGas",
+    domain: "contract",
+    layer: "read",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    sdk: {
+      invoke: (client, fx) =>
+        client.contract.estimateGas({
+          contractAddress: fx.usdm,
+          abi: fx.erc20SymbolAbi,
+          functionName: "symbol",
+          functionArgs: [],
+          fromAddress: fx.signerAddress ?? fx.wallet,
+        }),
+    },
+    mcp: {
+      tool: "estimate_contract_gas",
+      arguments: (fx) => ({
+        contractAddress: fx.usdm,
+        abi: fx.erc20SymbolAbi,
+        functionName: "symbol",
+        functionArgs: [],
+        fromAddress: fx.signerAddress ?? fx.wallet,
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["gasEstimate"]);
+    },
+  },
+];

package/tests/catalog/domains/defi.ts

@@ -0,0 +1,264 @@
+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 mentoFxOperations: OperationSpec[] = [
+  {
+    id: "mentoFx.getFxQuote",
+    domain: "mentoFx",
+    layer: "read",
+    sdk: {
+      invoke: (client) => client.mentoFx.getFxQuote("USDm", "EURm", "1"),
+    },
+    mcp: {
+      tool: "get_mento_fx_quote",
+      arguments: () => ({
+        tokenIn: "USDm",
+        tokenOut: "EURm",
+        amount: "1",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["tokenIn", "tokenOut", "expectedOut"]);
+    },
+  },
+  {
+    id: "mentoFx.estimateFx",
+    domain: "mentoFx",
+    layer: "read",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    sdk: {
+      invoke: (client, fx) =>
+        client.mentoFx.estimateFx(fromAddress(fx), "USDm", "EURm", "1"),
+    },
+    mcp: {
+      tool: "estimate_mento_fx",
+      arguments: () => ({
+        tokenIn: "USDm",
+        tokenOut: "EURm",
+        amount: "1",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["fxGas", "expectedOut"]);
+    },
+  },
+  {
+    id: "mentoFx.prepareFx",
+    domain: "mentoFx",
+    layer: "prepare",
+    sdk: {
+      invoke: (client, fx) =>
+        client.mentoFx.prepareFx(fromAddress(fx), "USDm", "EURm", "1"),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["from", "steps", "summary"]);
+    },
+  },
+  {
+    id: "mentoFx.executeFx",
+    domain: "mentoFx",
+    layer: "write",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    requiresWrites: true,
+    mcp: {
+      tool: "execute_mento_fx",
+      arguments: () => ({
+        tokenIn: "USDm",
+        tokenOut: "EURm",
+        amount: "0.01",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["hash"]);
+    },
+  },
+];
+
+export const uniswapOperations: OperationSpec[] = [
+  {
+    id: "uniswap.getSwapQuote",
+    domain: "uniswap",
+    layer: "read",
+    sdk: {
+      invoke: (client) => client.uniswap.getSwapQuote("CELO", "USDC", "0.001"),
+    },
+    mcp: {
+      tool: "get_uniswap_quote",
+      arguments: () => ({
+        tokenIn: "CELO",
+        tokenOut: "USDC",
+        amount: "0.001",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["tokenIn", "tokenOut", "expectedOut", "protocol"]);
+    },
+  },
+  {
+    id: "uniswap.estimateSwap",
+    domain: "uniswap",
+    layer: "read",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    sdk: {
+      invoke: (client, fx) =>
+        client.uniswap.estimateSwap(
+          fromAddress(fx),
+          "CELO",
+          "USDC",
+          "0.001",
+        ),
+    },
+    mcp: {
+      tool: "estimate_uniswap_swap",
+      arguments: () => ({
+        tokenIn: "CELO",
+        tokenOut: "USDC",
+        amount: "0.001",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["swapGas", "expectedOut"]);
+    },
+  },
+  {
+    id: "uniswap.prepareSwap",
+    domain: "uniswap",
+    layer: "prepare",
+    sdk: {
+      invoke: (client, fx) =>
+        client.uniswap.prepareSwap(
+          fromAddress(fx),
+          "CELO",
+          "USDC",
+          "0.001",
+        ),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["from", "steps", "summary"]);
+    },
+  },
+  {
+    id: "uniswap.executeSwap",
+    domain: "uniswap",
+    layer: "write",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    requiresWrites: true,
+    mcp: {
+      tool: "execute_uniswap_swap",
+      arguments: () => ({
+        tokenIn: "CELO",
+        tokenOut: "USDC",
+        amount: "0.001",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["hash"]);
+    },
+  },
+];
+
+export const aaveOperations: OperationSpec[] = [
+  {
+    id: "aave.prepareSupply",
+    domain: "aave",
+    layer: "prepare",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    sdk: {
+      invoke: (client, fx) =>
+        client.aave.prepareSupply(fromAddress(fx), "USDm", "0.01"),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["from", "steps"]);
+    },
+  },
+  {
+    id: "aave.prepareWithdraw",
+    domain: "aave",
+    layer: "prepare",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    sdk: {
+      invoke: (client, fx) =>
+        client.aave.prepareWithdraw(fromAddress(fx), "USDm", "0.01"),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["from", "steps"]);
+    },
+  },
+  {
+    id: "aave.supply",
+    domain: "aave",
+    layer: "write",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    requiresWrites: true,
+    mcp: {
+      tool: "supply_aave",
+      arguments: () => ({
+        token: "USDm",
+        amount: "0.01",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["hash"]);
+    },
+  },
+  {
+    id: "aave.withdraw",
+    domain: "aave",
+    layer: "write",
+    requiresEnv: ["CELO_PRIVATE_KEY"],
+    requiresWrites: true,
+    mcp: {
+      tool: "withdraw_aave",
+      arguments: () => ({
+        token: "USDm",
+        amount: "0.01",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["hash"]);
+    },
+  },
+];
+
+export const ensOperations: OperationSpec[] = [
+  {
+    id: "ens.resolveEns",
+    domain: "ens",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) => client.ens.resolveEns(fx.ensName, "celo"),
+    },
+    mcp: {
+      tool: "resolve_ens",
+      arguments: (fx) => ({
+        name: fx.ensName,
+        chain: "celo",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["name", "address"]);
+    },
+  },
+];
+
+export const gooddollarOperations: OperationSpec[] = [
+  {
+    id: "gooddollar.getWhitelistingInfo",
+    domain: "gooddollar",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) => client.gooddollar.getWhitelistingInfo(fx.wallet),
+    },
+    mcp: {
+      tool: "get_gooddollar_whitelisting_info",
+      arguments: (fx) => ({ address: fx.wallet }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["isCurrentlyWhitelisted"]);
+    },
+  },
+];

package/tests/catalog/domains/self.ts

@@ -0,0 +1,161 @@
+import type { OperationSpec } from "../types.js";
+import { assertHasKeys } from "../../helpers/assert.js";
+
+const SELF_DEMO_VERIFY_URL =
+  "https://app.ai.self.xyz/api/demo/verify?network=celo-mainnet";
+
+export const selfOperations: OperationSpec[] = [
+  {
+    id: "self.verifySelfAgent",
+    domain: "self",
+    layer: "read",
+    mcp: {
+      tool: "verify_self_agent",
+      arguments: (fx) => ({
+        agent_address: fx.selfAgentAddress,
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["verified"]);
+    },
+  },
+  {
+    id: "self.lookupSelfAgent",
+    domain: "self",
+    layer: "read",
+    mcp: {
+      tool: "lookup_self_agent",
+      arguments: (fx) => ({
+        agent_id: fx.selfAgentId,
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["agentId"]);
+    },
+  },
+  {
+    id: "self.verifySelfRequest",
+    domain: "self",
+    layer: "read",
+    requiresEnv: ["SELF_AGENT_PRIVATE_KEY"],
+    mcp: {
+      tool: "verify_self_request",
+      arguments: (fx) => fx.selfVerifyRequestArgs ?? {},
+    },
+    skip: () =>
+      process.env.CELINA_TEST_SELF_VERIFY === "1"
+        ? undefined
+        : "Set CELINA_TEST_SELF_VERIFY=1 (MCP suite enriches signed fixture in beforeAll)",
+    assert: (result) => {
+      assertHasKeys(result, ["valid"]);
+    },
+  },
+  {
+    id: "self.registerSelfAgent",
+    domain: "self",
+    layer: "write",
+    requiresDestructive: true,
+    mcp: {
+      tool: "register_self_agent",
+      arguments: () => ({
+        mode: "wallet-free",
+        agent_name: "celina-test",
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["sessionId"]);
+    },
+  },
+  {
+    id: "self.checkSelfRegistration",
+    domain: "self",
+    layer: "read",
+    mcp: {
+      tool: "check_self_registration",
+      arguments: () => ({
+        session_id: process.env.CELINA_TEST_SELF_SESSION ?? "missing-session",
+      }),
+    },
+    skip: () =>
+      process.env.CELINA_TEST_SELF_SESSION
+        ? undefined
+        : "Set CELINA_TEST_SELF_SESSION to poll a pending Self session",
+    assert: (result) => {
+      assertHasKeys(result, ["status"]);
+    },
+  },
+  {
+    id: "self.getSelfIdentity",
+    domain: "self",
+    layer: "read",
+    requiresEnv: ["SELF_AGENT_PRIVATE_KEY"],
+    mcp: {
+      tool: "get_self_identity",
+      arguments: () => ({}),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["agentAddress"]);
+    },
+  },
+  {
+    id: "self.refreshSelfProof",
+    domain: "self",
+    layer: "write",
+    requiresEnv: ["SELF_AGENT_PRIVATE_KEY"],
+    requiresDestructive: true,
+    mcp: {
+      tool: "refresh_self_proof",
+      arguments: () => ({}),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["sessionId"]);
+    },
+  },
+  {
+    id: "self.deregisterSelfAgent",
+    domain: "self",
+    layer: "write",
+    requiresEnv: ["SELF_AGENT_PRIVATE_KEY"],
+    requiresDestructive: true,
+    mcp: {
+      tool: "deregister_self_agent",
+      arguments: () => ({}),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["sessionId"]);
+    },
+  },
+  {
+    id: "self.signSelfRequest",
+    domain: "self",
+    layer: "read",
+    requiresEnv: ["SELF_AGENT_PRIVATE_KEY"],
+    mcp: {
+      tool: "sign_self_request",
+      arguments: () => ({
+        method: "GET",
+        url: SELF_DEMO_VERIFY_URL,
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["headers"]);
+    },
+  },
+  {
+    id: "self.authenticatedSelfFetch",
+    domain: "self",
+    layer: "read",
+    requiresEnv: ["SELF_AGENT_PRIVATE_KEY"],
+    mcp: {
+      tool: "authenticated_self_fetch",
+      arguments: () => ({
+        method: "POST",
+        url: SELF_DEMO_VERIFY_URL,
+        body: JSON.stringify({ ping: true }),
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["status"]);
+    },
+  },
+];

package/tests/catalog/domains/token.ts

@@ -0,0 +1,74 @@
+import { expect } from "vitest";
+import type { OperationSpec } from "../types.js";
+import { assertHasKeys } from "../../helpers/assert.js";
+
+export const tokenOperations: OperationSpec[] = [
+  {
+    id: "token.getBalances",
+    domain: "token",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.token.getBalances(fx.wallet, ["CELO", "USDm"]),
+    },
+    mcp: {
+      tool: "get_celo_balances",
+      arguments: (fx) => ({
+        address: fx.wallet,
+        tokens: ["CELO", "USDm"],
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["address", "balances"]);
+    },
+  },
+  {
+    id: "token.getStablecoinBalances",
+    domain: "token",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) => client.token.getStablecoinBalances(fx.wallet),
+    },
+    mcp: {
+      tool: "get_stablecoin_balances",
+      arguments: (fx) => ({ address: fx.wallet }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["address", "stablecoins"]);
+    },
+  },
+  {
+    id: "token.getTokenInfo",
+    domain: "token",
+    layer: "read",
+    sdk: {
+      invoke: (client) => client.token.getTokenInfo("USDm"),
+    },
+    mcp: {
+      tool: "get_token_info",
+      arguments: () => ({ token: "USDm" }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["symbol", "decimals"]);
+    },
+  },
+  {
+    id: "token.getTokenBalance",
+    domain: "token",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.token.getTokenBalance("USDm", fx.wallet),
+    },
+    mcp: {
+      tool: "get_token_balance",
+      arguments: (fx) => ({
+        token: "USDm",
+        address: fx.wallet,
+      }),
+    },
+    assert: (result) => {
+      assertHasKeys(result, ["formatted", "symbol"]);
+    },
+  },
+];

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";