feat(scripting): add zod schemas and viem transform helpers

package.json

@@ -47,7 +47,8 @@
       "pbkdf2": "3.1.3",
       "sha.js": "2.4.12",
       "cipher-base": "1.0.5",
-      "tmp": "0.2.5"
+      "tmp": "0.2.5",
+      "zod": "4.3.6"
     }
   }
 }

src/package.json

@@ -54,13 +54,14 @@
     "viem": "^1.20.0"
   },
   "dependencies": {
-    "@ethersproject/abstract-provider": "^5.7.0",
-    "@ethersproject/providers": "^5.7.2",
     "@arbitrum/sdk": "^4.0.4",
     "@arbitrum/token-bridge-contracts": "^1.2.2",
+    "@ethersproject/abstract-provider": "^5.7.0",
+    "@ethersproject/providers": "^5.7.2",
     "@offchainlabs/fund-distribution-contracts": "^1.0.1",
     "@safe-global/protocol-kit": "^4.1.7",
     "abitype": "^0.9.8",
-    "ethers": "^5.7.2"
+    "ethers": "^5.7.2",
+    "zod": "^4.3.6"
   }
 }

src/scripting/schemas/common.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+
+export const hexSchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]*$/, 'Invalid hex string')
+  .transform((val) => val as `0x${string}`);
+
+export const addressSchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{40}$/, 'Invalid Ethereum address')
+  .transform((val) => val as `0x${string}`);
+
+export const privateKeySchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{64}$/, 'Invalid private key')
+  .transform((val) => val as `0x${string}`);
+
+// z.coerce.bigint() calls BigInt() which throws a raw SyntaxError on invalid
+// input, bypassing zod's error pipeline -- safeParse can throw, and the error
+// has no field path context. Regex guard makes the BigInt() call provably safe.
+export const bigintSchema = z
+  .string()
+  .regex(/^-?\d+$/, 'Expected a numeric string')
+  .transform(BigInt);
+
+export const rollupCreatorVersionSchema = z.enum(['v3.2', 'v2.1']);
+
+export const sequencerInboxMaxTimeVariationSchema = z.object({
+  delayBlocks: bigintSchema,
+  futureBlocks: bigintSchema,
+  delaySeconds: bigintSchema,
+  futureSeconds: bigintSchema,
+});
+
+export const gasOptionsSchema = z.object({
+  base: bigintSchema.optional(),
+  percentIncrease: bigintSchema.optional(),
+});
+
+export const gasLimitSchema = z.object({
+  gasLimit: gasOptionsSchema.optional(),
+});
+
+export const tokenBridgeRetryableGasOverridesSchema = z.object({
+  maxSubmissionCostForFactory: gasOptionsSchema.optional(),
+  maxGasForFactory: gasOptionsSchema.optional(),
+  maxSubmissionCostForContracts: gasOptionsSchema.optional(),
+  maxGasForContracts: gasOptionsSchema.optional(),
+  maxGasPrice: bigintSchema.optional(),
+});
+
+export const setWethGatewayGasOverridesSchema = z.object({
+  gasLimit: gasOptionsSchema.optional(),
+  maxFeePerGas: gasOptionsSchema.optional(),
+  maxSubmissionCost: gasOptionsSchema.optional(),
+});
+
+export const coreContractsSchema = z.object({
+  rollup: addressSchema,
+  nativeToken: addressSchema,
+  inbox: addressSchema,
+  outbox: addressSchema,
+  rollupEventInbox: addressSchema,
+  challengeManager: addressSchema,
+  adminProxy: addressSchema,
+  sequencerInbox: addressSchema,
+  bridge: addressSchema,
+  upgradeExecutor: addressSchema,
+  validatorUtils: addressSchema.optional(),
+  validatorWalletCreator: addressSchema,
+  deployedAtBlockNumber: z.number(),
+});
+
+export const bufferConfigSchema = z.object({
+  threshold: bigintSchema,
+  max: bigintSchema,
+  replenishRateInBasis: bigintSchema,
+});
+
+const globalStateSchema = z.object({
+  bytes32Vals: z.tuple([hexSchema, hexSchema]),
+  u64Vals: z.tuple([bigintSchema, bigintSchema]),
+});
+
+export const assertionStateSchema = z.object({
+  globalState: globalStateSchema,
+  machineStatus: z.number(),
+  endHistoryRoot: hexSchema,
+});
+
+export const prepareChainConfigArbitrumParamsSchema = z.object({
+  InitialChainOwner: addressSchema,
+  DataAvailabilityCommittee: z.boolean().optional(),
+  InitialArbOSVersion: z.number().optional(),
+  MaxCodeSize: z.number().optional(),
+  MaxInitCodeSize: z.number().optional(),
+});
+
+const chainConfigArbitrumParamsSchema = prepareChainConfigArbitrumParamsSchema.required().extend({
+  EnableArbOS: z.boolean(),
+  AllowDebugPrecompiles: z.boolean(),
+  GenesisBlockNum: z.number(),
+});
+
+export const chainConfigSchema = z.object({
+  chainId: z.number(),
+  homesteadBlock: z.number(),
+  daoForkBlock: z.null(),
+  daoForkSupport: z.boolean(),
+  eip150Block: z.number(),
+  eip150Hash: z.string(),
+  eip155Block: z.number(),
+  eip158Block: z.number(),
+  byzantiumBlock: z.number(),
+  constantinopleBlock: z.number(),
+  petersburgBlock: z.number(),
+  istanbulBlock: z.number(),
+  muirGlacierBlock: z.number(),
+  berlinBlock: z.number(),
+  londonBlock: z.number(),
+  clique: z.object({ period: z.number(), epoch: z.number() }),
+  arbitrum: chainConfigArbitrumParamsSchema,
+});