z (zodExtended) & schemas

The SDK exports the Zod 3 namespace as z, extended with one EVM-specific helper: z.address(). You define a task's input shape with z, and that schema both validates ctx.args at runtime and drives the args form in the Console.

import { defineTask, z } from '@thyme-labs/sdk'

Standard Zod

Everything in standard Zod is available: z.object, z.string, z.number, z.boolean, z.bigint, z.array, z.enum, .optional(), .default(), refinements, and transforms.

schema: z.object({
  oracleAddress: z.address(),
  threshold: z.coerce.bigint().positive(),
  label: z.string().optional(),
  retries: z.number().int().default(3),
})

JSON inputs and bigint

Local args.json and cloud args are JSON. Represent token amounts and other large integers as decimal strings, then use z.coerce.bigint() so runtime validation produces a bigint. Plain z.bigint() requires an actual JavaScript bigint and rejects a JSON string. Do not use a JSON number for values outside JavaScript's safe integer range.

defineTask calls safeParseAsync before run and each callback, so defaults, transforms, and asynchronous refinements work in both environments. Form metadata extraction cannot represent every validation rule; the runtime schema is authoritative.

z.address()

z.address() validates an Ethereum address and normalizes it to a checksummed viem Address. It is defined as:

z.address() === z.string().refine(isAddress).transform(getAddress)

Validation semantics

Direct Zod parsing reports the message below; defineTask wraps validation issues in Invalid task arguments: ...:

Invalid Ethereum address

Because of the transform, the value you read from ctx.args is always the checksummed form, ready to pass to viem.

async run(ctx) {
  const { oracleAddress } = ctx.args // typed as Address, checksummed
}

InferSchema

InferSchema<T> is a convenience alias for z.infer<T> — the parsed type of a schema. You rarely need it directly inside a task (the type flows through defineTask automatically), but it is useful when extracting helper functions:

import { z, type InferSchema } from '@thyme-labs/sdk'
 
const schema = z.object({ targetAddress: z.address() })
type Args = InferSchema<typeof schema> // { targetAddress: Address }
 
function process(args: Args) { /* ... */ }

How schemas become args

On upload, the CLI extracts your Zod schema into a JSON Schema stored on the function. The Console renders an args form from it:

• Flat primitives map directly.
• Nested z.object() recurses; z.array() models its items.
• optional / default / nullish fields drop from required.
• z.address() becomes { type: 'string', pattern: '^0x[a-fA-F0-9]{40}$' }.

For extraction coverage and limitations, see source-schema extraction. For supplying args locally and in the cloud, see Args.

Related

• defineTask — how the schema drives ctx.args inference.
• Args — local args.json and the Console args form.