ox 1.7.5 → 1.8.1

package/src/zod/TxEnvelopeEip8141.ts

@@ -0,0 +1,102 @@
+/* eslint-disable jsdoc-js/require-jsdoc, jsdoc-js/require-description, jsdoc-js/require-example */
+import * as core_TxEnvelopeEip8141 from '../core/TxEnvelopeEip8141.js'
+import * as z_Address from './Address.js'
+import * as z_Frame from './Frame.js'
+import * as z_FrameSignature from './FrameSignature.js'
+import * as z_Hex from './Hex.js'
+import * as z_TxEnvelopeEip4844 from './TxEnvelopeEip4844.js'
+import * as z from 'zod/mini'
+
+/** Decoded EIP-8141 envelope schema. */
+export const Decoded = z
+  .object(
+    fields(z.bigint(), z.union([z.number(), z.bigint()]), z_Frame.Decoded),
+  )
+  .check(z.refine(core_TxEnvelopeEip8141.validate, 'Invalid frame transaction'))
+
+/** RPC EIP-8141 envelope schema. */
+export const Rpc = z
+  .object({
+    blobVersionedHashes: z.readonly(z.array(z_Hex.Hex)),
+    chainId: z_Hex.Hex,
+    frames: z.readonly(z.array(z_Frame.Rpc)),
+    from: z_Address.Address,
+    maxFeePerBlobGas: z_Hex.Hex,
+    maxFeePerGas: z_Hex.Hex,
+    maxPriorityFeePerGas: z_Hex.Hex,
+    nonce: z_Hex.Hex,
+    signatures: z.readonly(z.array(z_FrameSignature.Rpc)),
+    type: z.literal('0x6'),
+  })
+  .check(
+    z.refine((value) => {
+      try {
+        core_TxEnvelopeEip8141.fromRpc(value)
+        return true
+      } catch {
+        return false
+      }
+    }, 'Invalid frame transaction'),
+  )
+
+/** Codec between RPC and decoded EIP-8141 envelopes. */
+export const TxEnvelopeEip8141 = z.codec(Rpc, Decoded, {
+  decode: core_TxEnvelopeEip8141.fromRpc,
+  encode: core_TxEnvelopeEip8141.toRpc,
+})
+
+/** Encode-only EIP-8141 envelope codec accepting numberish values. */
+export const TxEnvelopeEip8141ToRpc = z.codec(
+  Rpc,
+  z
+    .object(
+      fields(
+        z.union([z_Hex.Hex, z.bigint(), z.number()]),
+        z.union([z_Hex.Hex, z.bigint(), z.number()]),
+        z_Frame.DecodedToRpc,
+      ),
+    )
+    .check(
+      z.refine((value) => {
+        try {
+          core_TxEnvelopeEip8141.fromRpc(core_TxEnvelopeEip8141.toRpc(value))
+          return true
+        } catch {
+          return false
+        }
+      }, 'Invalid frame transaction'),
+    ),
+  {
+    decode: core_TxEnvelopeEip8141.fromRpc,
+    encode: core_TxEnvelopeEip8141.toRpc,
+  },
+)
+
+/** Codec between serialized and decoded EIP-8141 envelopes. */
+export const serialized = z.codec(z_Hex.Hex, Decoded, {
+  decode: (value) =>
+    core_TxEnvelopeEip8141.deserialize(
+      value as core_TxEnvelopeEip8141.Serialized,
+    ),
+  encode: core_TxEnvelopeEip8141.serialize,
+})
+
+function fields<
+  uint extends z.ZodMiniType,
+  num extends z.ZodMiniType,
+  frame extends z.ZodMiniType,
+>(uint: uint, num: num, frame: frame) {
+  return {
+    blobVersionedHashes: z.optional(z.readonly(z.array(z_Hex.Hex))),
+    chainId: num,
+    frames: z.readonly(z.array(frame)),
+    maxFeePerBlobGas: z.optional(uint),
+    maxFeePerGas: z.optional(uint),
+    maxPriorityFeePerGas: z.optional(uint),
+    nonce: z.optional(uint),
+    sender: z_Address.Address,
+    sidecars: z.optional(z_TxEnvelopeEip4844.Sidecars),
+    signatures: z.optional(z.readonly(z.array(z_FrameSignature.Decoded))),
+    type: z.literal('eip8141'),
+  }
+}

package/src/zod/_test/Frame.test-d.ts

@@ -0,0 +1,41 @@
+import type {
+  Frame,
+  FrameReceipt,
+  FrameSignature,
+  Transaction,
+  TxEnvelopeEip8141,
+} from 'ox'
+import { z } from 'ox/zod'
+import { expectTypeOf, test } from 'vp/test'
+
+test('frame codecs preserve core types', () => {
+  expectTypeOf<z.output<typeof z.Frame.Frame>>().toEqualTypeOf<Frame.Frame>()
+  expectTypeOf<z.input<typeof z.Frame.Frame>>().toEqualTypeOf<Frame.Rpc>()
+  expectTypeOf<
+    z.output<typeof z.FrameSignature.FrameSignature>
+  >().toEqualTypeOf<FrameSignature.FrameSignature>()
+  expectTypeOf<
+    z.input<typeof z.FrameSignature.FrameSignature>
+  >().toEqualTypeOf<FrameSignature.Rpc>()
+  expectTypeOf<
+    z.output<typeof z.TxEnvelopeEip8141.TxEnvelopeEip8141>
+  >().toEqualTypeOf<TxEnvelopeEip8141.TxEnvelopeEip8141>()
+  expectTypeOf<
+    z.input<typeof z.TxEnvelopeEip8141.TxEnvelopeEip8141>
+  >().toEqualTypeOf<TxEnvelopeEip8141.Rpc>()
+  expectTypeOf<
+    z.output<typeof z.Transaction.Eip8141>
+  >().toEqualTypeOf<Transaction.Eip8141>()
+  expectTypeOf<
+    z.input<typeof z.Transaction.Eip8141>
+  >().toEqualTypeOf<Transaction.Eip8141Rpc>()
+  expectTypeOf<z.output<typeof z.Transaction.PendingEip8141>>().toEqualTypeOf<
+    Transaction.Eip8141<true>
+  >()
+  expectTypeOf<
+    z.output<typeof z.FrameReceipt.FrameReceipt>
+  >().toEqualTypeOf<FrameReceipt.FrameReceipt>()
+  expectTypeOf<
+    z.input<typeof z.FrameReceipt.FrameReceipt>
+  >().toEqualTypeOf<FrameReceipt.Rpc>()
+})

package/src/zod/_test/Frame.test.ts

@@ -0,0 +1,57 @@
+import { Frame } from 'ox'
+import { z } from 'ox/zod'
+import { describe, expect, test } from 'vp/test'
+
+describe('Frame', () => {
+  test('decodes RPC budgets and encodes named flags', () => {
+    const frame = Frame.from({
+      flags: 'approveExecutionAndPayment',
+      gas: 50_000n,
+      mode: 'verify',
+      to: '0x1111111111111111111111111111111111111111',
+    })
+    const rpc = z.encode(z.Frame.Frame, frame)
+    expect(rpc).toEqual({
+      data: '0x',
+      executionGasLimit: '0xc350',
+      flags: 3,
+      mode: 1,
+      stateGasLimit: '0x0',
+      target: '0x1111111111111111111111111111111111111111',
+      value: '0x0',
+    })
+    expect(z.decode(z.Frame.Frame, rpc)).toEqual({
+      data: '0x',
+      flags: 3,
+      gas: 50_000n,
+      mode: 1,
+      stateGas: 0n,
+      to: '0x1111111111111111111111111111111111111111',
+      value: 0n,
+    })
+  })
+  test('rejects invalid mode and budget', () => {
+    expect(z.safeParse(z.Frame.Decoded, { mode: 3 }).success).toBe(false)
+    expect(z.safeParse(z.Frame.Decoded, { gas: -1n }).success).toBe(false)
+  })
+  test('encodes numberish values', () => {
+    expect(
+      z.encode(z.Frame.FrameToRpc, { gas: '0xc350', stateGas: 0 })
+        .executionGasLimit,
+    ).toBe('0xc350')
+  })
+})
+
+describe('FrameToRpc validation', () => {
+  test.each([
+    { mode: 3 },
+    { flags: 8 },
+    { gas: 2n ** 64n },
+    { stateGas: -1 },
+    { gas: '0x10000000000000000' },
+  ])('rejects invalid frame %#', (frame) => {
+    expect(
+      z.safeEncode(z.Frame.FrameToRpc, frame as Frame.toRpc.Input).success,
+    ).toBe(false)
+  })
+})

package/src/zod/_test/FrameReceipt.test.ts

@@ -0,0 +1,75 @@
+import { FrameReceipt } from 'ox'
+import { z } from 'ox/zod'
+import { describe, expect, test } from 'vp/test'
+
+describe('FrameReceipt', () => {
+  test('safe codecs reject invalid gas without throwing', () => {
+    expect(
+      z.safeDecode(z.FrameReceipt.FrameReceipt, {
+        executionGasUsed: '0x',
+        logs: [],
+        stateGasUsed: '0x0',
+        status: 1,
+      }).success,
+    ).toBe(false)
+    expect(
+      z.safeEncode(z.FrameReceipt.FrameReceipt, {
+        gasUsed: -1n,
+        logs: [],
+        stateGasUsed: 0n,
+        status: 'success',
+      }).success,
+    ).toBe(false)
+    for (const gasUsed of [-1, Number.MAX_SAFE_INTEGER + 1, '0x'] as const)
+      expect(
+        z.safeEncode(z.FrameReceipt.FrameReceiptToRpc, {
+          gasUsed,
+          logs: [],
+          stateGasUsed: 0n,
+          status: 'success',
+        }).success,
+      ).toBe(false)
+  })
+
+  test('roundtrip', () => {
+    const rpc = {
+      executionGasUsed: '0x20000000000001',
+      logs: [],
+      stateGasUsed: '0x0',
+      status: 2,
+    } as const
+    const receipt = FrameReceipt.fromRpc(rpc)
+    expect(z.decode(z.FrameReceipt.FrameReceipt, rpc)).toEqual(receipt)
+    expect(z.encode(z.FrameReceipt.FrameReceipt, receipt)).toEqual(rpc)
+  })
+
+  test('invalid status', () => {
+    expect(
+      z.safeDecode(z.FrameReceipt.FrameReceipt, {
+        executionGasUsed: '0x0',
+        logs: [],
+        stateGasUsed: '0x0',
+        // @ts-expect-error Invalid RPC status.
+        status: 3,
+      }).success,
+    ).toBe(false)
+  })
+})
+
+describe('FrameReceiptToRpc', () => {
+  test('numberish gas', () => {
+    expect(
+      z.encode(z.FrameReceipt.FrameReceiptToRpc, {
+        gasUsed: 21000,
+        logs: [],
+        stateGasUsed: '0x0',
+        status: 'success',
+      }),
+    ).toEqual({
+      executionGasUsed: '0x5208',
+      logs: [],
+      stateGasUsed: '0x0',
+      status: 1,
+    })
+  })
+})

package/src/zod/_test/FrameSignature.test.ts

@@ -0,0 +1,94 @@
+import { FrameSignature, P256, Secp256k1, Hash } from 'ox'
+import { z } from 'ox/zod'
+import { describe, expect, test } from 'vp/test'
+import { accounts } from '../../../test/constants/accounts.js'
+
+describe('FrameSignature', () => {
+  test('safeDecode rejects malformed protocol signatures without throwing', () => {
+    expect(
+      z.safeDecode(z.FrameSignature.FrameSignature, {
+        msg: '0x',
+        scheme: 1,
+        signature: '0x01',
+      }).success,
+    ).toBe(false)
+  })
+
+  test('encodes omitted payloads', () => {
+    expect(
+      z.encode(z.FrameSignature.FrameSignature, {
+        scheme: 'arbitrary',
+        signature: '0xaabb',
+      }),
+    ).toEqual({ msg: '0x', scheme: 0, signature: '0xaabb' })
+    expect(
+      z.encode(z.FrameSignature.FrameSignature, {
+        scheme: 'secp256k1',
+      }),
+    ).toEqual({ msg: '0x', scheme: 1, signature: '0x' })
+    expect(
+      z.encode(z.FrameSignature.FrameSignature, {
+        scheme: 'p256',
+      }),
+    ).toEqual({ msg: '0x', scheme: 2, signature: '0x' })
+  })
+
+  test('arbitrary bytes', () => {
+    expect(
+      z.encode(z.FrameSignature.FrameSignature, FrameSignature.from('0xaabb')),
+    ).toEqual({ msg: '0x', scheme: 0, signature: '0xaabb' })
+    expect(
+      z.decode(z.FrameSignature.FrameSignature, {
+        msg: '0x',
+        scheme: 0,
+        signature: '0xaabb',
+      }),
+    ).toEqual(FrameSignature.from('0xaabb'))
+  })
+  test('secp256k1 signature', () => {
+    const entry = FrameSignature.from({
+      scheme: 'secp256k1',
+      signature: Secp256k1.sign({
+        payload: Hash.keccak256('0xdeadbeef'),
+        privateKey: accounts[0].privateKey,
+      }),
+    })
+    const rpc = z.encode(z.FrameSignature.FrameSignature, entry)
+    expect(rpc.scheme).toBe(1)
+    expect(z.decode(z.FrameSignature.FrameSignature, rpc)).toEqual(entry)
+  })
+  test('P-256 signature', () => {
+    const privateKey = accounts[0].privateKey
+    const entry = FrameSignature.from({
+      publicKey: P256.getPublicKey({ privateKey }),
+      scheme: 'p256',
+      signature: P256.sign({
+        payload: Hash.keccak256('0xdeadbeef'),
+        privateKey,
+      }),
+    })
+    const rpc = z.encode(z.FrameSignature.FrameSignature, entry)
+    expect(rpc.scheme).toBe(2)
+    expect(z.decode(z.FrameSignature.FrameSignature, rpc)).toEqual({
+      ...entry,
+      signature: { r: entry.signature.r, s: entry.signature.s },
+    })
+  })
+  test('rejects missing P-256 public key and invalid arbitrary signer', () => {
+    expect(
+      z.safeParse(z.FrameSignature.Decoded, {
+        payload: '0x',
+        scheme: 'p256',
+        signature: { r: '0x01', s: '0x02' },
+      }).success,
+    ).toBe(false)
+    expect(
+      z.safeParse(z.FrameSignature.Decoded, {
+        payload: '0x',
+        scheme: 'arbitrary',
+        signature: '0x',
+        signer: accounts[0].address,
+      }).success,
+    ).toBe(false)
+  })
+})

package/src/zod/_test/TxEnvelopeEip8141.test.ts

@@ -0,0 +1,116 @@
+import {
+  Frame,
+  FrameSignature,
+  TransactionEnvelope,
+  TxEnvelopeEip8141,
+} from 'ox'
+import { z } from 'ox/zod'
+import { describe, expect, test } from 'vp/test'
+import { accounts } from '../../../test/constants/accounts.js'
+
+describe('TxEnvelopeEip8141', () => {
+  test('signed codecs reject protocol signature placeholders', () => {
+    const envelope = TxEnvelopeEip8141.from({
+      chainId: 1,
+      frames: [{}],
+      sender: accounts[0].address,
+      signatures: [{ scheme: 'secp256k1' }],
+    })
+    expect(
+      z.safeDecode(
+        z.TransactionEnvelope.Signed,
+        TxEnvelopeEip8141.toRpc(envelope),
+      ).success,
+    ).toBe(false)
+    expect(z.safeEncode(z.TransactionEnvelope.Signed, envelope).success).toBe(
+      false,
+    )
+    expect(
+      z.safeEncode(z.TransactionEnvelope.SignedToRpc, envelope).success,
+    ).toBe(false)
+    expect(
+      z.safeParse(z.TransactionEnvelope.SignedDecoded, envelope).success,
+    ).toBe(false)
+  })
+
+  test('RPC codec preserves chain ID precision and signing payloads', () => {
+    const envelope = TxEnvelopeEip8141.from({
+      chainId: 9007199254740993n,
+      frames: [Frame.from({})],
+      sender: accounts[0].address,
+      signatures: [FrameSignature.from({ scheme: 'secp256k1' })],
+    })
+    const rpc = z.encode(z.TxEnvelopeEip8141.TxEnvelopeEip8141, envelope)
+    expect(rpc.chainId).toBe('0x20000000000001')
+    const decoded = z.decode(z.TransactionEnvelope.TransactionEnvelope, rpc)
+    expect(decoded.chainId).toBe(9007199254740993n)
+    expect(TransactionEnvelope.getSignPayload(decoded)).toBe(
+      TxEnvelopeEip8141.getSignPayload(envelope),
+    )
+  })
+  test('generic serialized codec supports unsigned frame entries', () => {
+    const envelope = TxEnvelopeEip8141.from({
+      chainId: 1,
+      frames: [Frame.from({})],
+      sender: '0x1111111111111111111111111111111111111111',
+    })
+    const serialized =
+      '0x06e70180941111111111111111111111111111111111111111c9c8808080c280808080c0c3808080c0'
+    expect(z.encode(z.TxEnvelopeEip8141.serialized, envelope)).toBe(serialized)
+    const decoded = z.decode(z.TransactionEnvelope.serialized, serialized)
+    expect(decoded.type).toBe('eip8141')
+    expect(z.encode(z.TransactionEnvelope.serialized, decoded)).toBe(serialized)
+  })
+  test('rejects invalid envelope constraints', () => {
+    expect(
+      z.safeParse(z.TxEnvelopeEip8141.Decoded, {
+        chainId: 1,
+        frames: [],
+        sender: accounts[0].address,
+        type: 'eip8141',
+      }).success,
+    ).toBe(false)
+  })
+  test('numberish encoder preserves defaults', () => {
+    expect(
+      z.encode(z.TxEnvelopeEip8141.TxEnvelopeEip8141ToRpc, {
+        chainId: '0x1',
+        frames: [{ gas: 50_000 }],
+        sender: accounts[0].address,
+        type: 'eip8141',
+      }).frames[0]!.executionGasLimit,
+    ).toBe('0xc350')
+  })
+})
+
+describe('invalid envelopes', () => {
+  const envelope = TxEnvelopeEip8141.from({
+    chainId: 1,
+    frames: [Frame.from({})],
+    sender: accounts[0].address,
+  })
+  test.each([
+    { frames: [] },
+    { frames: Array.from({ length: 65 }, () => Frame.from({})) },
+    { maxFeePerBlobGas: 1n },
+    { maxFeePerGas: 1n, maxPriorityFeePerGas: 2n },
+  ])('rejects numberish envelope %#', (fields) => {
+    const invalid = { ...envelope, ...fields }
+    expect(
+      z.safeEncode(z.TxEnvelopeEip8141.TxEnvelopeEip8141ToRpc, invalid).success,
+    ).toBe(false)
+    const rpc = TxEnvelopeEip8141.toRpc(invalid)
+    expect(
+      z.safeDecode(z.TxEnvelopeEip8141.TxEnvelopeEip8141, rpc).success,
+    ).toBe(false)
+  })
+  test('rejects malformed nested RPC signatures without throwing', () => {
+    const rpc = {
+      ...TxEnvelopeEip8141.toRpc(envelope),
+      signatures: [{ msg: '0x', scheme: 1, signature: '0x01' }],
+    } as const
+    expect(
+      z.safeDecode(z.TxEnvelopeEip8141.TxEnvelopeEip8141, rpc).success,
+    ).toBe(false)
+  })
+})

package/src/zod/internal/Frame.ts

@@ -0,0 +1,26 @@
+/* eslint-disable jsdoc-js/require-jsdoc, jsdoc-js/require-description, jsdoc-js/require-example */
+import * as Hex from '../../core/Hex.js'
+import * as Quantity from '../../core/internal/quantity.js'
+import { quantityHex, uintBigint, uintNumber } from './Integer.js'
+import * as z from 'zod/mini'
+
+export const chainId = z.codec(
+  quantityHex(),
+  z.union([uintNumber(), uintBigint()]),
+  {
+    decode(value) {
+      const id = Hex.toBigInt(value)
+      return id <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(id) : id
+    },
+    encode: (value) => Hex.fromNumber(value),
+  },
+)
+
+export const chainIdToRpc = z.codec(
+  quantityHex(),
+  z.union([quantityHex(), uintNumber(), uintBigint()]),
+  {
+    decode: (value) => z.decode(chainId, value),
+    encode: (value) => Quantity.fromNumberish(value),
+  },
+)

package/src/zod/z.ts

@@ -20,6 +20,9 @@ export * as Bytes from './Bytes.js'
 export * as Fee from './Fee.js'
 export * as Filter from './Filter.js'
 export * as Hash from './Hash.js'
+export * as Frame from './Frame.js'
+export * as FrameReceipt from './FrameReceipt.js'
+export * as FrameSignature from './FrameSignature.js'
 export * as Hex from './Hex.js'
 export * as Log from './Log.js'
 export * as RpcResponse from './RpcResponse.js'
@@ -36,6 +39,7 @@ export * as TxEnvelopeEip1559 from './TxEnvelopeEip1559.js'
 export * as TxEnvelopeEip2930 from './TxEnvelopeEip2930.js'
 export * as TxEnvelopeEip4844 from './TxEnvelopeEip4844.js'
 export * as TxEnvelopeEip7702 from './TxEnvelopeEip7702.js'
+export * as TxEnvelopeEip8141 from './TxEnvelopeEip8141.js'
 export * as TxEnvelopeLegacy from './TxEnvelopeLegacy.js'
 export * as Withdrawal from './Withdrawal.js'
 export * as tempo from './tempo/z.js'