verex

Zod — Runtime Validation + Type Inference (env / ABI / external inputs)

Goal: validate every external input at the boundary — env vars, JSON from RPC/APIs, request bodies, agent tool args — with Zod, getting runtime failure-fast and inferred TS types from a single schema definition.

Source: jay’s Zod note, pasted in session 2026-07-17 (no source file). Not yet a dependency anywhere in the monorepo (checked 2026-07-17) — this is a fresh adoption item.

Why

TypeScript types vanish at runtime; process.env and JSON are any-shaped at the edges. One Zod schema gives both: parse-or-throw at startup and the static type (z.infer<typeof Env>) — no drift between validation and types.

Canonical example (from the note)

import { z } from "zod";
const Env = z.object({
  RPC_URL: z.string().url(),
  CHAIN_ID: z.coerce.number().int().positive(),
  VEREX_ADDR: z.string().regex(/^0x[a-fA-F0-9]{40}$/),
});
export const env = Env.parse(process.env); // throws immediately on failure

Key details worth copying: z.coerce.number() (env values are strings), the 0x-address regex, and parsing once at module load so a bad config kills the process at startup, not mid-trade.

Adoption map (per package)

| Package | What to validate | Notes | |—|—|—| | shared | Address, Hex, TxHash schemas + a common parseEnv() helper | Put schemas in @verex/sdk (types already flow from there) so all packages share them | | sdk | RPC/JSON inputs at the SDK boundary (order payloads, market params) | Complements viem’s own types — Zod covers what arrives as raw JSON | | api (S4) | Env + request/response validation on Fastify routes | fastify-type-provider-zod — schemas become both validation and OpenAPI-ready types | | cli | Env (RPC_URL, CHAIN_ID, addresses) + command args | Also the natural home for the audit item A2 (chainId guard) — a CHAIN_ID: z.literal(31337) dev schema is the guard | | mm-agent (S2.5) | config.ts per-market config loader (spread, max exposure, on/off) | Malformed market config must fail at startup, never mid-quote | | web | NEXT_PUBLIC_* env at build/boot | Client env is stringly-typed too |

Dev items

• Add zod + shared schemas (Address, Hex, parseEnv) to @verex/sdk
• CLI env schema — folds in audit item A2’s chainId guard (§11.3)
• MM-agent config loader on Zod (when mm-agent lands, S2.5)
• API: fastify-type-provider-zod on all routes (at S4, when packages/api starts)
• Web NEXT_PUBLIC_* env schema
• (you) Confirm placement: schemas in @verex/sdk vs a new @verex/schema package — recommend sdk until a second consumer needs schemas without the SDK

Sequencing & estimate

Not a standalone phase — adopt incrementally: shared schemas + CLI env now (~0.5d, and it closes audit A2), then each package as it’s built (api at S4, mm-agent at S2.5). Near-zero marginal cost when done at package-creation time; expensive to retrofit later.