ox 1.8.1 → 1.8.4

package/src/core/_test/index.test.ts

@@ -43,6 +43,7 @@ test('exports', () => {
       "Filter",
       "Frame",
       "FrameReceipt",
+      "FrameRequest",
       "FrameSignature",
       "Hash",
       "HdKey",

package/src/core/internal/frameNonce.ts

@@ -0,0 +1,61 @@
+import * as Errors from '../Errors.js'
+import * as Hex from '../Hex.js'
+import * as Quantity from './quantity.js'
+
+export function assert(keys: readonly bigint[], nonce?: bigint): void {
+  if (!Array.isArray(keys) || keys.length < 1 || keys.length > 16)
+    throw new InvalidError('Expected between 1 and 16 nonce keys.')
+  for (const [index, key] of keys.entries()) {
+    if (typeof key !== 'bigint' || key < 0n || key >= 2n ** 256n)
+      throw new InvalidError('Nonce keys must be unsigned 256-bit integers.')
+    if (index > 0 && key <= keys[index - 1]!)
+      throw new InvalidError('Nonce keys must be strictly increasing.')
+  }
+  if (keys.length > 1 && keys[0] === 0n)
+    throw new InvalidError(
+      'The zero nonce key cannot be combined with other keys.',
+    )
+  if (
+    nonce !== undefined &&
+    (typeof nonce !== 'bigint' || nonce < 0n || nonce >= 2n ** 64n - 1n)
+  )
+    throw new InvalidError('Nonce must be less than 2^64 - 1 and nonnegative.')
+}
+
+export function fromRpc(
+  keys: readonly Hex.Hex[],
+  nonce?: Hex.Hex,
+): readonly bigint[] {
+  if (!Array.isArray(keys)) throw new InvalidError('Expected a nonce key list.')
+  const integer = (value: Hex.Hex): bigint => {
+    if (
+      typeof value !== 'string' ||
+      !/^0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)$/.test(value)
+    )
+      throw new InvalidError('Expected a canonical RPC nonce quantity.')
+    return Hex.toBigInt(value)
+  }
+  const decoded = keys.map(integer)
+  assert(decoded, nonce === undefined ? undefined : integer(nonce))
+  return decoded
+}
+
+export function toRpc(
+  keys: readonly (Hex.Hex | bigint | number)[],
+  nonce?: Hex.Hex | bigint | number,
+): readonly Hex.Hex[] {
+  if (!Array.isArray(keys)) throw new InvalidError('Expected a nonce key list.')
+  const encoded = keys.map((key) => Quantity.fromNumberish(key))
+  fromRpc(
+    encoded,
+    nonce === undefined ? undefined : Quantity.fromNumberish(nonce),
+  )
+  return encoded
+}
+
+export class InvalidError extends Errors.BaseError {
+  override readonly name = 'FrameNonce.InvalidError'
+  constructor(reason: string) {
+    super(reason)
+  }
+}

package/src/core/internal/rpcSchemas/eth.ts

@@ -4,6 +4,7 @@ import type * as Block from '../../Block.js'
 import type * as BlockOverrides from '../../BlockOverrides.js'
 import type * as Fee from '../../Fee.js'
 import type * as Filter from '../../Filter.js'
+import type * as FrameReceipt from '../../FrameReceipt.js'
 import type * as Hex from '../../Hex.js'
 import type * as Log from '../../Log.js'
 import type * as RpcSchema from '../../RpcSchema.js'
@@ -11,6 +12,7 @@ import type * as StateOverrides from '../../StateOverrides.js'
 import type * as Transaction from '../../Transaction.js'
 import type * as TransactionReceipt from '../../TransactionReceipt.js'
 import type * as TransactionRequest from '../../TransactionRequest.js'
+import type * as TxEnvelope from '../../TxEnvelope.js'
 
 /**
  * Union of all JSON-RPC Methods for the `eth_` namespace.
@@ -219,12 +221,12 @@ export type Eth = RpcSchema.From<
       ReturnType: Fee.FeeHistoryRpc
     }
   /**
-   * Fills the defaults (nonce, gas, gasPrice, or 1559 fields) on a given unsigned transaction, and returns the unsigned transaction along with its raw form
+   * Fills transaction defaults and returns the unsigned transaction.
    *
    * @example
    * ```
    * request({ method: 'eth_fillTransaction', params: [{ from: '0x...', to: '0x...', value: '0x...' }] })
-   * // { raw: '0x...', tx: { ... } }
+   * // { tx: { ... } }
    * ```
    */
   | {
@@ -234,8 +236,8 @@ export type Eth = RpcSchema.From<
       }
       ReturnType: {
         capabilities?: Record<string, unknown> | undefined
-        raw: Hex.Hex
-        tx: Transaction.Rpc
+        raw?: Hex.Hex | undefined
+        tx: TxEnvelope.Rpc & { from: Address.Address }
       }
     }
   /**
@@ -769,6 +771,13 @@ export type Eth = RpcSchema.From<
                     message: string
                   }
                 | undefined
+              frameResults?:
+                | readonly (FrameReceipt.Rpc & {
+                    error?: { code: number; message: string } | undefined
+                    returnData: Hex.Hex
+                  })[]
+                | undefined
+              payer?: Address.Address | undefined
               logs?: readonly Log.Rpc[] | undefined
               gasUsed: Hex.Hex
               returnData: Hex.Hex

package/src/index.ts

@@ -1618,13 +1618,13 @@ export * as Filter from './core/Filter.js'
  * import { Frame } from 'ox'
  *
  * const frame = Frame.from({
+ *   executionGas: 50_000n,
  *   flags: 'approveExecutionAndPayment',
- *   gas: 50_000n,
  *   mode: 'verify'
  * })
  * ```
  *
- * @category Transaction Envelopes
+ * @category Frames (EIP-8141)
  */
 export * as Frame from './core/Frame.js'
 
@@ -1633,10 +1633,27 @@ export * as Frame from './core/Frame.js'
  *
  * Frame receipts include execution gas, state gas, logs, and execution status.
  *
- * @category Execution Spec
+ * @category Frames (EIP-8141)
  */
 export * as FrameReceipt from './core/FrameReceipt.js'
 
+/**
+ * Convert EIP-8141 frame requests while preserving omitted gas limits for node estimation.
+ *
+ * @example
+ * ```ts twoslash
+ * import { FrameRequest } from 'ox'
+ *
+ * const frame = FrameRequest.toRpc({
+ *   mode: 'sender',
+ *   stateGas: 0n
+ * })
+ * ```
+ *
+ * @category Frames (EIP-8141)
+ */
+export * as FrameRequest from './core/FrameRequest.js'
+
 /**
  * Utilities for constructing, validating, and encoding [EIP-8141](https://eips.ethereum.org/EIPS/eip-8141) signature entries.
  *
@@ -1656,7 +1673,7 @@ export * as FrameReceipt from './core/FrameReceipt.js'
  * // @log: { payload: '0x', scheme: 'arbitrary', signature: '0xaabb' }
  * ```
  *
- * @category Transaction Envelopes
+ * @category Frames (EIP-8141)
  */
 export * as FrameSignature from './core/FrameSignature.js'
 
@@ -3580,7 +3597,7 @@ export * as TxEnvelopeEip7702 from './core/TxEnvelopeEip7702.js'
  *
  * const envelope = TxEnvelopeEip8141.from({
  *   chainId: 1,
- *   frames: [{ gas: 50_000n, mode: 'sender' }],
+ *   frames: [{ executionGas: 50_000n, mode: 'sender' }],
  *   sender: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
  * })
  * ```

package/src/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '1.8.1'
+export const version = '1.8.4'

package/src/zod/Frame.ts

@@ -25,10 +25,10 @@ export const Decoded: z.ZodMiniType<core_Frame.Frame, core_Frame.Frame> = z
 export const Rpc = z
   .object({
     data: z_Hex.Hex,
-    executionGasLimit: z_Hex.Hex,
-    flags: z.number(),
-    mode: z.number(),
-    stateGasLimit: z_Hex.Hex,
+    executionGas: z_Hex.Hex,
+    flags: z_Hex.Hex,
+    mode: z_Hex.Hex,
+    stateGas: z_Hex.Hex,
     target: z.optional(z.nullable(z_Address.Address)),
     value: z_Hex.Hex,
   })
@@ -72,8 +72,8 @@ export const FrameToRpc = z.codec(Rpc, DecodedToRpc, {
 function fields<uint extends z.ZodMiniType>(uint: uint) {
   return {
     data: z.optional(z_Hex.Hex),
+    executionGas: z.optional(uint),
     flags: z.optional(Flags),
-    gas: z.optional(uint),
     mode: z.optional(Mode),
     stateGas: z.optional(uint),
     to: z.optional(z_Address.Address),

package/src/zod/FrameReceipt.ts

@@ -11,17 +11,26 @@ import * as z from 'zod/mini'
 
 const frameLog = z.object({
   address: z_Address.Address,
+  blockHash: z.optional(z_Hex.Hex),
+  blockNumber: z.optional(quantityHex()),
+  blockTimestamp: z.optional(quantityHex()),
   data: z_Hex.Hex,
+  logIndex: z.optional(quantityHex()),
+  removed: z.optional(z.boolean()),
   topics: z.array(z_Hex.Hex),
+  transactionHash: z.optional(z_Hex.Hex),
+  transactionIndex: z.optional(quantityHex()),
 })
 
 const frameReceiptRpc = z.object({
   executionGasUsed: quantityHex(),
+  gasUsed: quantityHex(),
   logs: z.readonly(z.array(frameLog)),
   stateGasUsed: quantityHex(),
-  status: z.union([z.literal(0), z.literal(1), z.literal(2)]),
+  status: z.enum(['0x0', '0x1', '0x2']),
 })
 const frameReceiptDecoded = z.object({
+  executionGasUsed: uintBigint(),
   gasUsed: uintBigint(),
   logs: z.readonly(z.array(frameLog)),
   stateGasUsed: uintBigint(),
@@ -38,6 +47,7 @@ export const FrameReceipt = z.codec(frameReceiptRpc, frameReceiptDecoded, {
 export const FrameReceiptToRpc = z.codec(
   frameReceiptRpc,
   z.extend(frameReceiptDecoded, {
+    executionGasUsed: uintBigintNumberish(),
     gasUsed: uintBigintNumberish(),
     stateGasUsed: uintBigintNumberish(),
   }),

package/src/zod/FrameRequest.ts

@@ -0,0 +1,46 @@
+/* eslint-disable jsdoc-js/require-jsdoc, jsdoc-js/require-description, jsdoc-js/require-example */
+import * as core_FrameRequest from '../core/FrameRequest.js'
+import * as z_Address from './Address.js'
+import * as z_Frame from './Frame.js'
+import * as z_Hex from './Hex.js'
+import * as z from 'zod/mini'
+
+const quantity = z_Hex.Hex.check(
+  z.refine(
+    (value) => /^0x(0|[1-9a-f][0-9a-f]*)$/.test(value),
+    'Invalid RPC quantity',
+  ),
+)
+
+const rpc = z
+  .object({
+    data: z.optional(z_Hex.Hex),
+    executionGas: z.optional(quantity),
+    flags: z.optional(z_Hex.Hex),
+    mode: z_Hex.Hex,
+    stateGas: z.optional(quantity),
+    target: z.optional(z.nullable(z_Address.Address)),
+    value: z.optional(quantity),
+  })
+  .check(
+    z.refine((value) => {
+      try {
+        core_FrameRequest.fromRpc(value)
+        return true
+      } catch {
+        return false
+      }
+    }, 'Invalid frame request'),
+  )
+
+/** Codec between RPC and decoded frame requests, preserving omitted gas limits. */
+export const FrameRequest = z.codec(rpc, z_Frame.Decoded, {
+  decode: core_FrameRequest.fromRpc,
+  encode: core_FrameRequest.toRpc,
+})
+
+/** Encode-only frame request codec accepting numberish gas and value. */
+export const FrameRequestToRpc = z.codec(rpc, z_Frame.DecodedToRpc, {
+  decode: core_FrameRequest.fromRpc,
+  encode: core_FrameRequest.toRpc,
+})

package/src/zod/FrameSignature.ts

@@ -24,7 +24,10 @@ export const Secp256k1 = z.object({
   payload: z.optional(z_Hex.Hex),
   scheme: z.union([z.literal(1), z.literal('secp256k1')]),
   signature: z.optional(
-    z.object({ r: z_Hex.Hex, s: z_Hex.Hex, yParity: z.number() }),
+    z.union([
+      z_Hex.Hex,
+      z.object({ r: z_Hex.Hex, s: z_Hex.Hex, yParity: z.number() }),
+    ]),
   ),
   signer: z.optional(z_Address.Address),
 })
@@ -36,11 +39,11 @@ const p256 = {
 }
 /** P-256 frame signature schema, including unsigned placeholders. */
 export const P256 = z.union([
-  z.object({ ...p256, publicKey, signature }),
+  z.object({ ...p256, publicKey, signature: z.union([z_Hex.Hex, signature]) }),
   z.object({
     ...p256,
     publicKey: z.optional(publicKey),
-    signature: z.optional(z.undefined()),
+    signature: z.optional(z.literal('0x')),
   }),
 ])
 
@@ -55,10 +58,10 @@ export const Decoded: z.ZodMiniType<
 /** RPC frame signature schema. */
 export const Rpc = z
   .object({
-    msg: z_Hex.Hex,
-    scheme: z.union([z.literal(0), z.literal(1), z.literal(2)]),
-    signature: z_Hex.Hex,
-    signer: z.optional(z.nullable(z_Address.Address)),
+    msg: z.optional(z_Hex.Hex),
+    scheme: z.enum(['0x0', '0x1', '0x2']),
+    signature: z.optional(z_Hex.Hex),
+    signer: z.optional(z.union([z.literal('0x'), z_Address.Address])),
   })
   .check(
     z.refine((value) => {

package/src/zod/Transaction.ts

@@ -4,7 +4,13 @@ import * as z_Address from './Address.js'
 import * as z_Authorization from './Authorization.js'
 import * as z_Frame from './Frame.js'
 import * as z_FrameSignature from './FrameSignature.js'
-import { chainId, chainIdToRpc } from './internal/Frame.js'
+import {
+  chainId,
+  chainIdToRpc,
+  nonceKeys,
+  nonceKeysToRpc,
+  validNonce,
+} from './internal/Frame.js'
 import * as z_Hex from './Hex.js'
 import * as z_Number from './Number.js'
 import * as z_Uint from './Uint.js'
@@ -142,55 +148,68 @@ export const PendingEip7702 = z.object(
 const Eip8141Type = type('0x6', 'eip8141')
 
 /** EIP-8141 transaction schema. */
-export const Eip8141 = z.object({
-  ...eip8141Fields(z_Uint.Uint, chainId, z_Frame.Frame),
-  blockHash: z_Hex.Hex,
-  blockNumber: z_Uint.Uint,
-  blockTimestamp: z.optional(z_Uint.Uint),
-  transactionIndex: z_Number.Number,
-})
+export const Eip8141 = z
+  .object({
+    ...eip8141Fields(z_Uint.Uint, chainId, z_Frame.Frame, nonceKeys),
+    blockHash: z_Hex.Hex,
+    blockNumber: z_Uint.Uint,
+    blockTimestamp: z.optional(z_Uint.Uint),
+    transactionIndex: z_Number.Number,
+  })
+  .check(z.refine(validNonce, 'Invalid keyed nonce'))
 
 /** Encode-only EIP-8141 transaction schema accepting numberish values. */
-export const Eip8141ToRpc = z.object({
-  ...eip8141Fields(z_Uint.UintToRpc, chainIdToRpc, z_Frame.FrameToRpc),
-  blockHash: z_Hex.Hex,
-  blockNumber: z_Uint.UintToRpc,
-  blockTimestamp: z.optional(z_Uint.UintToRpc),
-  transactionIndex: z_Number.NumberToRpc,
-})
+export const Eip8141ToRpc = z
+  .object({
+    ...eip8141Fields(
+      z_Uint.UintToRpc,
+      chainIdToRpc,
+      z_Frame.FrameToRpc,
+      nonceKeysToRpc,
+    ),
+    blockHash: z_Hex.Hex,
+    blockNumber: z_Uint.UintToRpc,
+    blockTimestamp: z.optional(z_Uint.UintToRpc),
+    transactionIndex: z_Number.NumberToRpc,
+  })
+  .check(z.refine(validNonce, 'Invalid keyed nonce'))
 
 /** Pending EIP-8141 transaction schema. */
-export const PendingEip8141 = z.object({
-  ...eip8141Fields(z_Uint.Uint, chainId, z_Frame.Frame),
-  blockHash: z.null(),
-  blockNumber: z.null(),
-  blockTimestamp: z.optional(z.null()),
-  transactionIndex: z.null(),
-})
+export const PendingEip8141 = z
+  .object({
+    ...eip8141Fields(z_Uint.Uint, chainId, z_Frame.Frame, nonceKeys),
+    blockHash: z.null(),
+    blockNumber: z.null(),
+    blockTimestamp: z.optional(z.null()),
+    transactionIndex: z.null(),
+  })
+  .check(z.refine(validNonce, 'Invalid keyed nonce'))
 
 function eip8141Fields<
   uint extends z.ZodMiniType,
   num extends z.ZodMiniType,
   frame extends z.ZodMiniType,
->(uint: uint, num: num, frame: frame) {
+  keys extends z.ZodMiniType,
+>(uint: uint, num: num, frame: frame, keys: keys) {
   return {
     blobVersionedHashes: z.readonly(z.array(z_Hex.Hex)),
     chainId: num,
     data: z.optional(z_Hex.Hex),
     frames: z.readonly(z.array(frame)),
     from: z_Address.Address,
-    gas: uint,
+    gas: z.optional(uint),
     gasPrice: z.optional(uint),
     hash: z_Hex.Hex,
-    input: z_Hex.Hex,
+    input: z.optional(z_Hex.Hex),
     maxFeePerBlobGas: uint,
     maxFeePerGas: uint,
     maxPriorityFeePerGas: uint,
     nonce: uint,
+    nonceKeys: z.optional(keys),
     signatures: z.readonly(z.array(z_FrameSignature.FrameSignature)),
-    to: z.nullable(z_Address.Address),
+    to: z.optional(z.nullable(z_Address.Address)),
     type: Eip8141Type,
-    value: uint,
+    value: z.optional(uint),
   }
 }
 

package/src/zod/TransactionRequest.ts

@@ -2,9 +2,10 @@
 import * as z_AccessList from './AccessList.js'
 import * as z_Address from './Address.js'
 import * as z_Authorization from './Authorization.js'
-import * as z_Frame from './Frame.js'
+import * as z_FrameRequest from './FrameRequest.js'
 import * as z_FrameSignature from './FrameSignature.js'
 import * as z_Hex from './Hex.js'
+import { nonceKeys, nonceKeysToRpc, validNonce } from './internal/Frame.js'
 import * as z_Number from './Number.js'
 import * as z_Uint from './Uint.js'
 import * as z from 'zod/mini'
@@ -33,31 +34,44 @@ const type = z.codec(z.string(), z.string(), {
 })
 
 /** Transaction request schema. */
-export const TransactionRequest = z.object(
-  fields(
-    z_Uint.Uint,
-    z_Number.Number,
-    z_Authorization.ListSigned,
-    z_Frame.Frame,
-  ),
-)
+export const TransactionRequest = z
+  .object(
+    fields(
+      z_Uint.Uint,
+      z_Number.Number,
+      z_Authorization.ListSigned,
+      z_FrameRequest.FrameRequest,
+      nonceKeys,
+    ),
+  )
+  .check(z.refine(validNonce, 'Invalid keyed nonce'))
 
 /** Encode-only transaction request schema accepting numberish `toRpc` inputs. */
-export const TransactionRequestToRpc = z.object(
-  fields(
-    z_Uint.UintToRpc,
-    z_Number.NumberToRpc,
-    z_Authorization.ListSignedToRpc,
-    z_Frame.FrameToRpc,
-  ),
-)
+export const TransactionRequestToRpc = z
+  .object(
+    fields(
+      z_Uint.UintToRpc,
+      z_Number.NumberToRpc,
+      z_Authorization.ListSignedToRpc,
+      z_FrameRequest.FrameRequestToRpc,
+      nonceKeysToRpc,
+    ),
+  )
+  .check(z.refine(validNonce, 'Invalid keyed nonce'))
 
 function fields<
   uint extends z.ZodMiniType,
   num extends z.ZodMiniType,
   authorizationList extends z.ZodMiniType,
   frame extends z.ZodMiniType,
->(uint: uint, num: num, authorizationList: authorizationList, frame: frame) {
+  keys extends z.ZodMiniType,
+>(
+  uint: uint,
+  num: num,
+  authorizationList: authorizationList,
+  frame: frame,
+  keys: keys,
+) {
   return {
     accessList: z.optional(z_AccessList.AccessList),
     authorizationList: z.optional(authorizationList),
@@ -74,6 +88,7 @@ function fields<
     maxFeePerGas: z.optional(uint),
     maxPriorityFeePerGas: z.optional(uint),
     nonce: z.optional(uint),
+    nonceKeys: z.optional(keys),
     signatures: z.optional(
       z.readonly(z.array(z_FrameSignature.FrameSignature)),
     ),

package/src/zod/TxEnvelopeEip8141.ts

@@ -25,6 +25,7 @@ export const Rpc = z
     maxFeePerGas: z_Hex.Hex,
     maxPriorityFeePerGas: z_Hex.Hex,
     nonce: z_Hex.Hex,
+    nonceKeys: z.optional(z.readonly(z.array(z_Hex.Hex))),
     signatures: z.readonly(z.array(z_FrameSignature.Rpc)),
     type: z.literal('0x6'),
   })
@@ -94,6 +95,7 @@ function fields<
     maxFeePerGas: z.optional(uint),
     maxPriorityFeePerGas: z.optional(uint),
     nonce: z.optional(uint),
+    nonceKeys: z.optional(z.readonly(z.array(uint))),
     sender: z_Address.Address,
     sidecars: z.optional(z_TxEnvelopeEip4844.Sidecars),
     signatures: z.optional(z.readonly(z.array(z_FrameSignature.Decoded))),

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

@@ -5,25 +5,25 @@ import { describe, expect, test } from 'vp/test'
 describe('Frame', () => {
   test('decodes RPC budgets and encodes named flags', () => {
     const frame = Frame.from({
+      executionGas: 50_000n,
       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',
+      executionGas: '0xc350',
+      flags: '0x3',
+      mode: '0x1',
+      stateGas: '0x0',
       target: '0x1111111111111111111111111111111111111111',
       value: '0x0',
     })
     expect(z.decode(z.Frame.Frame, rpc)).toEqual({
       data: '0x',
+      executionGas: 50_000n,
       flags: 3,
-      gas: 50_000n,
       mode: 1,
       stateGas: 0n,
       to: '0x1111111111111111111111111111111111111111',
@@ -32,12 +32,14 @@ describe('Frame', () => {
   })
   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)
+    expect(z.safeParse(z.Frame.Decoded, { executionGas: -1n }).success).toBe(
+      false,
+    )
   })
   test('encodes numberish values', () => {
     expect(
-      z.encode(z.Frame.FrameToRpc, { gas: '0xc350', stateGas: 0 })
-        .executionGasLimit,
+      z.encode(z.Frame.FrameToRpc, { executionGas: '0xc350', stateGas: 0 })
+        .executionGas,
     ).toBe('0xc350')
   })
 })
@@ -46,9 +48,9 @@ describe('FrameToRpc validation', () => {
   test.each([
     { mode: 3 },
     { flags: 8 },
-    { gas: 2n ** 64n },
+    { executionGas: 2n ** 64n },
     { stateGas: -1 },
-    { gas: '0x10000000000000000' },
+    { executionGas: '0x10000000000000000' },
   ])('rejects invalid frame %#', (frame) => {
     expect(
       z.safeEncode(z.Frame.FrameToRpc, frame as Frame.toRpc.Input).success,