Skip to main content
Glama

zenith-evm-mcp

Give any AI assistant safe, Zenith-aware superpowers. An MCP server and agent skill for Zenith EVM, the Ethereum-compatible execution environment of the Canton Network.

It lets Claude, Cursor, VS Code, Windsurf or any MCP client read Zenith, trace a transaction from EVM to the Canton update that settled it, check every Gateway send against Zenith's own "Before you send" checklist, verify contracts, and (only if you opt in) deploy and send on testnet.

Community-built and open source. Not an official Zenith product. Testnet only: never move anything of real value through Gateway.

Why

Zenith Gateway moves tokens between Zenith EVM and Canton atomically, and the docs warn many times that a wrong recipient loses tokens for good: a shortened party ID, a protocol party, an unregistered token, a send from inside a contract, a ZTH amount that is not a multiple of 10^8 wei. An AI agent following generic Ethereum habits will walk straight into these.

This server turns every one of those warnings into a check the agent cannot skip, and adds the Zenith-specific knowledge ordinary EVM tooling lacks.

> gateway_preflight  partyId=alice::1220abab…ab  token=ZTH  amount=0.5  from=0x5a2d…958c

BLOCKED: do not send. Failed: "Gateway knows the recipient party".
✓ Recipient is a full party ID (hint::1220<64 hex>)
✓ Recipient is not a Zenith protocol party or the Gateway party
✓ Token is registered with Gateway
✓ Amount is a valid positive number
✓ ZTH value is a multiple of 10^8 wei
· Inbox address agrees with the Gateway registry
✗ Gateway knows the recipient party
✓ Sent directly from a wallet, not through a contract
✓ Sender has enough balance
✓ The Zenith RPC accepts this exact transaction (eth_estimateGas)
✓ No testnet reset since this tool's baseline

That party ID is well formed and the network itself would accept the transfer, but no such party exists, so the ZTH would never arrive. The preflight catches it.

Related MCP server: mcp-gateway

Findings from validating against the testnet

Everything below was checked against the public testnet (chain 936485) and is built into the tools and the skill.

Finding

What the toolkit does

solc ≥ 0.8.31 compiles for Osaka by default; Zenith runs Prague, and Osaka's CLZ fails on-chain with EVM error: NotActivated.

Compiles for Prague, flags Osaka targets in foundry.toml/Hardhat configs and Osaka opcodes in bytecode.

The registry API cannot tell a mistyped party from a real one until its inbox is deployed, but the RPC's deposit guard can: a 1 wei eth_estimateGas to a known party's inbox is refused ("is a gateway inbox"), and accepted for an unknown one.

gateway_preflight and gateway_inbox use this to confirm Gateway knows the recipient. Nothing is ever sent.

The Gateway contract is unverified. Its events were matched by topic hash: Collected, NativeCollected, Minted, Released, MetadataSet, WrapperRegistered, OriginalRegistered.

Decodes Gateway activity, confirms deposits were credited, and lists crossings per token.

The explorer's Etherscan-compatible API verifies contracts (the deploy guide's table says verification is not supported).

zenith_verify_contract and zenith_deploy verify with the exact standard-JSON input.

Multicall3, Permit2, CreateX and the ERC-4337 EntryPoint are not deployed; Safe 1.3.0/1.4.1 and the CREATE2 deployer are.

Flags dependencies on missing contracts; generated viem/wagmi config disables multicall batching.

eth_call accepts state overrides; eth_simulateV1 and debug_* are not allowed.

The token pre-screen runs a probe contract at a real holder's address inside eth_call to measure exactly what a transfer moves.

What it catches

Each row is a named test in test/footguns, traced to the docs section it comes from.

Docs warning

Result

Shortened party ID (hint without ::namespace, or a console's … display)

Blocked

Protocol party (m-, r-, b-) or the Gateway party as recipient

Blocked

Well-formed party that Gateway does not know

Blocked

Token not in /v1/registries

Blocked

ZTH not a multiple of 10^8 wei

Blocked, with the nearest sendable amount

wZTH back to EVM not in whole gwei; Canton amount with > 10 decimals

Refused, never rounded

Wrapper of a Canton token to a party without a standing acceptance

Blocked, with the network's own -32003 reason and the fix

Sending from a contract (router, multicall, smart wallet)

Warned: the RPC only checks a transaction's own call

Testnet reset (stored inboxes become invalid)

Warned on every preflight and health check

Deposit held by Gateway, or evicted after ~10 minutes

Explained, with "do not resend" or the exact nonce to resend at

eth_getLogs over more than 1,000 blocks

Chunked automatically

An idle chain mistaken for a stalled one

Reported as idle, using Gateway's producer progress

Fee-on-transfer, rebasing, blocklist, hook or upgradeable tokens submitted for registration

Flagged by the eligibility pre-screen

block.number as a clock, prevrandao randomness, blob opcodes, many confirmations, WebSockets, filters

Flagged by zenith_check_compat

Quick start

Requires Node.js 20 or later.

npx -y github:shedybaba/zenith-evm-mcp --doctor

--doctor checks the RPC, explorer, Gateway and faucet, and whether write tools are enabled.

Add it to your AI app

Claude Code

claude mcp add zenith -- npx -y github:shedybaba/zenith-evm-mcp

Claude Desktop, Cursor and Windsurf (claude_desktop_config.json, .cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "zenith": { "command": "npx", "args": ["-y", "github:shedybaba/zenith-evm-mcp"] }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "zenith": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:shedybaba/zenith-evm-mcp"]
    }
  }
}

More in examples/. Then ask things like:

  • "Is Zenith healthy right now?"

  • "Trace 0x… and show me the Canton update that settled it."

  • "I want to send 2 DevUSD to alice::1220…. Is that safe?"

  • "Check my project for anything that behaves differently on Zenith."

  • "Could this ERC-20 be registered with Gateway?"

Tools

Full reference: docs/tools.md (generated from the code).

Area

Tools

Network

zenith_network_info, zenith_health

Chain and explorer

zenith_get_account, zenith_get_transaction, zenith_read_contract, zenith_get_logs, zenith_decode

Gateway

gateway_tokens, gateway_inbox, gateway_preflight, gateway_deposit_status, gateway_mailbox, gateway_convert, gateway_activity, gateway_token_eligibility

Developer

zenith_check_compat, zenith_project_config, zenith_verify_contract

Write (opt-in)

zenith_deploy, zenith_send

Resources: zenith://network, zenith://limits, zenith://gateway/tokens, zenith://gateway/checklist, zenith://differences. Prompts: deploy_and_verify, send_to_canton_safely, investigate_missing_deposit, audit_token_for_gateway, port_ethereum_app.

Write tools (opt-in)

zenith_deploy and zenith_send are disabled unless you give the server a testnet-only key:

mkdir -p ~/.config/zenith-evm-mcp
printf 'ZENITH_PRIVATE_KEY=0x<testnet key>\n' > ~/.config/zenith-evm-mcp/testnet.env
chmod 600 ~/.config/zenith-evm-mcp/testnet.env

Then add "env": { "ZENITH_KEY_FILE": "~/.config/zenith-evm-mcp/testnet.env" } to the server's config. Fund the address with ZTH from the faucet.

Guards:

  • Refuses to sign unless the RPC reports chain 936485.

  • Simulates first and only sends when called again with confirm: true.

  • Per-session spend cap (ZENITH_SPEND_CAP_ZTH, default 1 ZTH).

  • Sends to a Canton party go through gateway_preflight, and blocked sends are refused. A plain send to a Gateway inbox is refused, so the checks cannot be bypassed.

  • zenith_deploy compiles .sol files for Prague, refuses bytecode with unsupported opcodes, and verifies the source automatically.

Agent skill

skills/zenith-evm is a standalone agent skill: workflow, core invariants and references for the network, the differences from Ethereum, Gateway, tooling and resets. It is useful even without the server. Copy the folder into your agent's skills directory (for Claude Code, ~/.claude/skills/zenith-evm). It follows the same layout as Zenith's own daml-skill, covering the EVM and Gateway side.

Using it as a library

import { createContext, checkPartyId, loadGatewayTokens } from "zenith-evm-mcp";

const ctx = createContext();
console.log(checkPartyId("alice").issues[0]?.message);
console.log((await loadGatewayTokens(ctx)).map((t) => t.key));

How it works

  • src/core: plain TypeScript, no MCP. Rate-limited JSON-RPC client (600 calls/min, 4 in flight, batches of 20, retries), explorer and Gateway API clients, party and unit rules, preflight, deposit tracking, eligibility probe, compiler, compatibility scanner.

  • src/tools: thin MCP wrappers with zod-validated inputs and structured JSON outputs.

  • Preflight separates gathering facts (network calls) from evaluating rules (pure functions), so every rule is unit-tested offline.

Development

npm install
npm run check          # typecheck, lint, format, offline tests
npm run test:live      # read-only tests against the public testnet
npm run test:live:write  # deploy → verify → trace → call (needs ZENITH_KEY_FILE with faucet ZTH)
npm run docs           # regenerate docs/tools.md

See CONTRIBUTING.md and SECURITY.md.

License

MIT © shedybaba. Built by shedybaba.

Available Tools

20 tools
gateway_activityRecent Gateway crossingsA
Read-only

Recent token crossings between Zenith EVM and Canton, decoded from the Gateway contract's own events (Collected, NativeCollected, Minted, Released), with per-token counts by direction.

Inputs: limit, includeSetup.

gateway_convertConvert amounts between Zenith EVM and CantonB
Read-only

Exact amount conversion for a Gateway token, in either direction, with the crossing rules applied: one EVM base unit is 1e-10 on Canton, 18-decimal tokens show 10^8 times larger on Canton (DORIGe-8), ZTH crosses in multiples of 10^8 wei and wZTH back in whole gwei. Never rounds silently.

Inputs: token (required), amount (required), direction (required), unit.

gateway_deposit_statusTrack a Gateway depositA
Read-only

Follows a Zenith EVM → Canton deposit by transaction hash: held by Gateway (with reason and eviction time), evicted (with the nonce to resend at), mined and waiting for the inbox, credited (with the Gateway collection event), or not a deposit. Gives the exact next step from the docs' Common problems table.

Inputs: hash (required), from.

gateway_inboxCanton party → inbox addressA
Read-only

Checks a Canton party ID and computes its inbox: the EVM address that delivers to that party on Canton. Rejects shortened IDs, protocol parties (m-, r-, b-) and the Gateway party, says whether the inbox is deployed, and cross-checks the registry API.

Inputs: partyId (required).

gateway_mailboxMailbox party for Canton → EVMA
Read-only

Derives the mailbox party for an EVM address and token (the Canton party you transfer to, to move that token to that EVM address) and reports its state: absent, requested, active and so on. Explains how to request it.

Inputs: token (required), evmAddress (required).

gateway_preflightCheck a send to Canton (Before-you-send checklist)A
Read-only

Runs every rule in Zenith's "Before you send" checklist for a transfer from Zenith EVM to a Canton party, then dry-runs the exact transaction against the network (eth_estimateGas) to surface its own refusal reason. Returns pass/fail per check with fixes, the amount that arrives on Canton, and the unsigned transaction. Never sends anything. ALWAYS call this before sending to a Canton party.

Inputs: token (required), amount (required), partyId (required), from, +1 more.

gateway_token_eligibilityPre-screen an ERC-20 for Gateway registrationA
Read-only

Checks an ERC-20 against Zenith's registration criteria: verified source, deployment transaction, not upgradeable, no fee/burn/reflection/rebase/hook/blocklist functions (bytecode selector scan), and a simulated transfer from a real holder (eth_call with a state override) proving it moves exactly the amount. Prepares what Zenith asks for in a request.

Inputs: address (required).

gateway_tokensTokens Gateway can moveA
Read-only

Every token registered with Zenith Gateway, with both sides: EVM address, symbol and decimals; Canton instrument, symbol and scale; how each direction works and what the recipient needs (for example a standing acceptance for wrappers of Canton tokens).

Inputs: no named parameters.

zenith_check_compatCheck code for Zenith gotchasA
Read-only

Scans Solidity, TypeScript/JavaScript or deployed bytecode for things that behave differently on Zenith: block.number used as a clock (blocks only come with transactions), prevrandao randomness, blob opcodes, Osaka-only opcodes and compiler targets (Zenith runs Prague), dependencies on Multicall3/Permit2/EntryPoint/CreateX (not deployed), WebSockets, filters and subscriptions (not available), waiting for many confirmations (can hang), and unbounded getLogs ranges.

Inputs: path, source, address, language.

zenith_decodeDecode calldata, an event or a revertA
Read-only

Decodes raw hex using the contract's verified ABI, a signature you give, ERC-20, or the Gateway's events and errors (including the inbox's NotWholeQuanta error).

Inputs: data (required), kind (required), topics, address, +1 more.

zenith_deployDeploy a contract (testnet, opt-in)A

Deploys a contract to Zenith testnet from a .sol file (compiled for Prague and verified automatically), a Foundry/Hardhat artifact or bytecode. Without confirm it only simulates and shows the cost. Requires a testnet key configured by the user; refuses any other chain and respects the session spend cap.

Inputs: abi, runs, verify, confirm, +8 more.

zenith_get_accountAccount or contract detailsB
Read-only

Balance, nonce, wallet vs contract, and for contracts: verified source, proxy implementation, ERC-20 metadata, and whether the address is a Gateway inbox. Also lists token holdings and recent transactions from the explorer.

Inputs: address (required), recentTransactions, includeTokenHoldings.

zenith_get_logsGet decoded event logsA
Read-only

Event logs for a contract and/or event over any block range, decoded. The public RPC only serves 1,000 blocks per call and has no filters or WebSockets, so the range is walked in chunks from newest to oldest; use nextToBlock to continue. Defaults to the last 1,000 blocks.

Inputs: event, address, maxLogs, toBlock, +1 more.

zenith_get_transactionTrace a transaction (EVM and Canton)A
Read-only

Status, fee, decoded call and events (verified ABIs, ERC-20 and the Gateway's own events), whether it was a Gateway deposit, and the Canton update that settled it: update ID, command ID, settlement time. If it was never mined, explains why using Gateway's pending-transaction index.

Inputs: hash (required), includeCantonLink.

zenith_healthZenith network healthA
Read-only

One verdict for whether Zenith is working: healthy, idle (no traffic but the block producer is alive; blocks are only made when there are transactions), degraded, or possible-reset (the testnet was reset, so stored inbox addresses and holdings are invalid). Checks the RPC, the explorer's services, the Gateway producer and synchronizer, and the faucet (amount, cooldown, GitHub-account rule).

Inputs: no named parameters.

zenith_network_infoZenith network infoA
Read-only

Chain ID, endpoints (RPC, explorer, faucet, Gateway API, docs), latest block and its age, gas price, the Gateway deployment (contract, party, deployment ID, genesis hash) and the public RPC limits. Call this first when working with Zenith EVM.

Inputs: no named parameters.

zenith_project_configTooling config for ZenithA
Read-only

Ready-to-paste configuration for Foundry, Hardhat 3, Hardhat 2, viem, wagmi, MetaMask and .env, with the Zenith RPC, chain ID, explorer verification and the right EVM version (prague) already set, plus the notes that matter (no multicall, polling watchers, one-receipt finality).

Inputs: tools.

zenith_read_contractCall a view functionA
Read-only

Calls a contract function without sending a transaction. Give either a full signature (e.g. "balanceOf(address) view returns (uint256)") or just the function name if the contract is verified on the explorer (ERC-20 names work for any token). Arguments are converted to the right types.

Inputs: address (required), function (required), abi, args, +1 more.

zenith_sendSend a transaction (testnet, opt-in)A

Sends ZTH, an ERC-20 transfer or a contract call on Zenith testnet. For a transfer to a Canton party, set gatewayPartyId (with token and amount): the full Gateway preflight runs first and blocked sends are refused. Plain sends to a Gateway inbox are refused so the checks cannot be skipped. Without confirm it only simulates.

Inputs: to, args, token, amount, +4 more.

zenith_verify_contractVerify a contract on the Zenith explorerA
Idempotent

Verifies a deployed contract through the explorer's Etherscan-compatible API. From a .sol file it compiles locally with the given settings, checks the bytecode matches the deployed code, then submits the exact standard-JSON input and waits for the result. Also accepts a standard-JSON input file (for example from forge verify-contract --show-standard-json-input).

Inputs: address (required), runs, optimize, evmVersion, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools have clear distinct roles, especially the gateway_* transfer/status tools versus the zenith_* chain utilities. A few pairs overlap conceptually, such as gateway_deposit_status vs zenith_get_transaction and gateway_activity vs zenith_get_logs, but the descriptions clarify when each should be used.

    Naming Consistency4/5

    Names are consistently snake_case and grouped by gateway_ and zenith_ prefixes. The pattern mixes noun phrases like gateway_tokens and zenith_network_info with verb phrases like zenith_get_logs and gateway_convert, but it remains predictable and readable.

    Tool Count4/5

    20 tools is above the typical 3-15 range but reflects a broad EVM plus Canton Gateway domain. Each tool appears to serve a specific workflow such as preflight, deploy, verify, logs, config, or sending, so the count is justified rather than padded.

    Completeness4/5

    Coverage is broad: network info, account/contract reads, logs, decoded transactions, gateway transfer preflight and status, deployment, verification, project config, compatibility checks, and sending. Minor gaps exist, such as no faucet request tool or explicit transaction replacement/cancel, but core lifecycle workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables querying Pharos blockchain data (EVM-compatible) through MCP, with read-only tools for blocks, transactions, balances, and contract calls, plus optional transaction broadcasting when self-hosted.
      14
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables proof-carrying project execution through a read-only remote MCP endpoint and WebMCP tools for managing Project Passports, task graphs, evidence-backed provider comparisons, route approvals, artifacts, verification records, and checkpoints without executing external providers.
      MIT