Zeta Dev Doctor

Zeta Dev Doctor is a ZetaChain-native diagnostics CLI PoC for Universal App workflows.

Package: @idoa/dev-doctor-zeta
Binary: zeta-doctor

What It Does

The CLI focuses on the first debugging steps for ZetaChain development:

• checks local environment readiness
• validates ZetaChain config
• probes ZetaChain RPC and API reachability
• performs static Gateway preflight checks
• provides a minimal CCTX lookup flow
• emits AI-ready JSON for LLM-assisted debugging

Included in This PoC

• doctor Full preflight run.
• doctor env Node.js, package manager, and optional ZetaChain CLI checks.
• doctor preflight Environment, config, endpoint, and Gateway checks.
• doctor cctx --hash <txHash> Minimal CCTX lookup and interpretation.
• doctor json JSON output mode for the full preflight run.

Out of Scope

• full explorer functionality
• wallet-backed transaction submission
• real cross-chain writes
• full Gateway execution
• exhaustive CCTX lifecycle decoding

Install

Global install:

npm i -g @idoa/dev-doctor-zeta

Then run:

zeta-doctor doctor

Without global install:

npx @idoa/dev-doctor-zeta doctor
npx @idoa/dev-doctor-zeta doctor env

Usage

After installation, the published package exposes the zeta-doctor binary.

zeta-doctor doctor
zeta-doctor doctor env
zeta-doctor doctor preflight
zeta-doctor doctor cctx --hash 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
zeta-doctor doctor json

Optional flags:

zeta-doctor doctor preflight --config zeta-doctor.config.json
zeta-doctor doctor preflight --json

Config

The CLI looks for zeta-doctor.config.json by default.

Start from zeta-doctor.config.example.json in this repo/package and copy it to zeta-doctor.config.json.

Example:

{
  "network": "athens3",
  "zetaRpcUrl": "https://zetachain-athens-evm.blockpi.network/v1/rpc/public",
  "zetaApiUrl": "https://zetachain-athens.blockpi.network/lcd",
  "connectedChain": "base-sepolia",
  "explorerBaseUrl": "https://athens.explorer.zetachain.com",
  "gatewayAddress": "0x1111111111111111111111111111111111111111",
  "requestTimeoutMs": 5000
}

Required fields:

• network
• zetaRpcUrl
• zetaApiUrl
• connectedChain
• explorerBaseUrl

Optional fields:

• gatewayAddress
• requestTimeoutMs

Example Output

Human output:

Zeta Dev Doctor (2026-03-22T12:00:00.000Z)
Status: DEGRADED | Score: 84/100
Checks: 7 | Pass: 5 | Warn: 2 | Fail: 0 | Skip: 0

Target: athens3 -> base-sepolia

[PASS] Node.js runtime
  Root cause: runtime_ready
  Node.js 20.18.0 satisfies the minimum 20.0.0 requirement.
[PASS] ZetaChain API reachability
  Root cause: api_reachable
  API responded in 172ms with HTTP 200.
[WARN] Gateway config preflight
  Root cause: gateway_address_missing
  No gatewayAddress was configured. Core preflight can still run, but gateway-specific validation is limited.
  Next step: Add gatewayAddress if your Universal App depends on Gateway-based deposits or calls.

JSON output:

{
  "aiReport": {
    "schemaVersion": "1.0.0",
    "generatedAt": "2026-03-22T12:00:00.000Z",
    "tool": {
      "name": "zeta-doctor",
      "packageName": "@idoa/dev-doctor-zeta",
      "chain": "zetachain"
    },
    "target": {
      "network": "athens3",
      "connectedChain": "base-sepolia",
      "configPath": "/workspace/zeta-doctor.config.json",
      "cwd": "/workspace"
    },
    "status": "degraded",
    "score": 84,
    "summary": {
      "total": 7,
      "passed": 5,
      "warned": 2,
      "failed": 0,
      "skipped": 0,
      "highestSeverity": "warning"
    },
    "findings": [
      {
        "id": "gateway.preflight",
        "title": "Gateway config preflight",
        "status": "warn",
        "severity": "warning",
        "rootCauseLabel": "gateway_address_missing",
        "confidence": 0.85,
        "summary": "No gatewayAddress was configured. Core preflight can still run, but gateway-specific validation is limited.",
        "recommendedActions": [
          "Add gatewayAddress if your Universal App depends on Gateway-based deposits or calls."
        ],
        "promptReadyExplanation": "Gateway checks are partial because no gateway address was supplied in config.",
        "evidence": [
          "GATEWAY_OPTIONAL_MISSING: No gatewayAddress was configured. Core preflight can still run, but gateway-specific validation is limited."
        ]
      }
    ],
    "recommendedActions": [
      "Add gatewayAddress if your Universal App depends on Gateway-based deposits or calls."
    ],
    "promptReadyExplanation": "ZetaChain Universal App preflight finished with status degraded and score 84/100. Summary: 5 pass, 2 warn, 0 fail, 0 skip. Primary diagnostic labels: gateway.preflight=gateway_address_missing."
  }
}

Shared Architecture

This package reuses the shared chain-dev-doctor-core packages and keeps ZetaChain-specific logic in the adapter layer:

• src/checks
• src/config
• src/services
• src/reporters
• src/commands
• src/adapters

Shared packages:

• @idoa/dev-doctor-core
• @idoa/dev-doctor-types
• @idoa/dev-doctor-utils
• @idoa/dev-doctor-reporter
• @idoa/dev-doctor-cli-kit

Local Development

Install dependencies and run validation:

npm install
npm run build
npm run typecheck
npm run lint
npm run test

Local CLI testing before publishing:

cp zeta-doctor.config.example.json zeta-doctor.config.json
npm run build
node dist/cli.js doctor
node dist/cli.js doctor env
node dist/cli.js doctor preflight
node dist/cli.js doctor json
node dist/cli.js doctor cctx --hash 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Use the final binary name locally:

npm link
zeta-doctor doctor
zeta-doctor doctor env