ox 1.0.0-beta.8 → 1.0.0

package/src/core/AbiParameters.ts

@@ -3,6 +3,8 @@ import * as Address from './Address.js'
 import * as Bytes from './Bytes.js'
 import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
+import * as formatAbiParameters from './internal/human-readable/formatAbiParameters.js'
+import * as parseAbiParameters from './internal/human-readable/parseAbiParameters.js'
 import * as internal from './internal/abiParameters.js'
 import * as Cursor from './internal/cursor.js'
 import * as Solidity from './Solidity.js'
@@ -13,6 +15,16 @@ export type AbiParameters = readonly abitype.AbiParameter[]
 /** A parameter on an {@link ox#AbiParameters.AbiParameters}. */
 export type Parameter = abitype.AbiParameter
 
+export {
+  InvalidAbiParametersError,
+  InvalidAbiTypeParameterError,
+  InvalidFunctionModifierError,
+  InvalidModifierError,
+  InvalidParameterError,
+  SolidityProtectedKeywordError,
+} from './internal/human-readable/errors.js'
+export { InvalidParenthesisError } from './internal/human-readable/errors.js'
+
 /** A packed ABI type. */
 export type PackedAbiType =
   | abitype.SolidityAddress
@@ -97,7 +109,9 @@ export function decode(
   for (let i = 0; i < parameters.length; ++i) {
     const param = parameters[i] as Parameter
     try {
-      cursor.setPosition(consumed)
+      // Zero-width types (e.g. `uint256[0]`, empty tuples) at the end of the
+      // data consume no bytes, so the cursor may already be exhausted.
+      if (consumed < bytes.length) cursor.setPosition(consumed)
       const [data_, consumed_] = internal.decodeParameter(cursor, param, {
         checksumAddress,
         staticPosition: 0,
@@ -386,11 +400,18 @@ export function format<
         Parameter | abitype.AbiEventParameter,
         ...(readonly (Parameter | abitype.AbiEventParameter)[]),
       ],
-): abitype.FormatAbiParameters<parameters> {
-  return abitype.formatAbiParameters(parameters)
+): format.ReturnType<parameters> {
+  return formatAbiParameters.formatAbiParameters(parameters)
 }
 
 export declare namespace format {
+  type ReturnType<
+    parameters extends readonly [
+      Parameter | abitype.AbiEventParameter,
+      ...(readonly (Parameter | abitype.AbiEventParameter)[]),
+    ] = readonly [Parameter, ...(readonly Parameter[])],
+  > = formatAbiParameters.FormatAbiParameters<parameters>
+
   type ErrorType = Errors.GlobalErrorType
 }
 
@@ -416,6 +437,22 @@ export declare namespace format {
  *
  * parameters
  * //^?
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
  * ```
  *
  * @example
@@ -432,6 +469,22 @@ export declare namespace format {
  *
  * parameters
  * //^?
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
  * ```
  *
  * @example
@@ -447,6 +500,22 @@ export declare namespace format {
  *
  * parameters
  * //^?
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
+ * //
  * ```
  *
  *
@@ -460,9 +529,9 @@ export function from<
   parameters: parameters | AbiParameters | string | readonly string[],
 ): from.ReturnType<parameters> {
   if (Array.isArray(parameters) && typeof parameters[0] === 'string')
-    return abitype.parseAbiParameters(parameters) as never
+    return parseAbiParameters.parseAbiParameters(parameters) as never
   if (typeof parameters === 'string')
-    return abitype.parseAbiParameters(parameters) as never
+    return parseAbiParameters.parseAbiParameters(parameters) as never
   return parameters as never
 }
 
@@ -470,9 +539,9 @@ export declare namespace from {
   type ReturnType<
     parameters extends AbiParameters | string | readonly string[],
   > = parameters extends string
-    ? abitype.ParseAbiParameters<parameters>
+    ? parseAbiParameters.ParseAbiParameters<parameters>
     : parameters extends readonly string[]
-      ? abitype.ParseAbiParameters<parameters>
+      ? parseAbiParameters.ParseAbiParameters<parameters>
       : parameters
 
   type ErrorType = Errors.GlobalErrorType
@@ -519,7 +588,7 @@ export class DataSizeTooSmallError extends Errors.BaseError {
   }) {
     super(`Data size of ${size} bytes is too small for given parameters.`, {
       metaMessages: [
-        `Params: (${abitype.formatAbiParameters(parameters as readonly [Parameter])})`,
+        `Params: (${formatAbiParameters.formatAbiParameters(parameters as readonly [Parameter])})`,
         `Data:   ${data} (${size} bytes)`,
       ],
     })

package/src/core/Rlp.ts

@@ -5,6 +5,9 @@ import * as internal_bytes from './internal/bytes.js'
 import * as Cursor from './internal/cursor.js'
 import type { ExactPartial, RecursiveArray } from './internal/types.js'
 
+/** Maximum nesting depth permitted when decoding an RLP value. */
+const depthLimit = 1_024
+
 /**
  * Decodes a Recursive-Length Prefix (RLP) value into a {@link ox#Bytes.Bytes} value.
  *
@@ -68,6 +71,12 @@ export function to<
   })
   const result = decodeRlpCursor(cursor, to_)
 
+  // RLP payloads encode exactly one item (Yellow Paper, Appendix B).
+  if (cursor.position < cursor.bytes.length)
+    throw new TrailingBytesError({
+      count: cursor.bytes.length - cursor.position,
+    })
+
   return result as to.ReturnType<to>
 }
 
@@ -82,6 +91,7 @@ export declare namespace to {
     | decodeRlpCursor.ErrorType
     | Cursor.create.ErrorType
     | Hex.InvalidLengthError
+    | TrailingBytesError
     | Errors.GlobalErrorType
 }
 
@@ -91,7 +101,11 @@ export declare namespace to {
 export function decodeRlpCursor<to extends 'Hex' | 'Bytes' = 'Hex'>(
   cursor: Cursor.Cursor,
   to: to | 'Hex' | 'Bytes' | undefined = 'Hex',
+  depth = 0,
 ): decodeRlpCursor.ReturnType<to> {
+  if (depth >= depthLimit)
+    throw new DepthLimitExceededError({ limit: depthLimit })
+
   if (cursor.bytes.length === 0)
     return (
       to === 'Hex' ? Hex.fromBytes(cursor.bytes) : cursor.bytes
@@ -111,7 +125,12 @@ export function decodeRlpCursor<to extends 'Hex' | 'Bytes' = 'Hex'>(
 
   // list
   const length = readLength(cursor, prefix, 0xc0)
-  return readList(cursor, length, to) as {} as decodeRlpCursor.ReturnType<to>
+  return readList(
+    cursor,
+    length,
+    to,
+    depth + 1,
+  ) as {} as decodeRlpCursor.ReturnType<to>
 }
 
 /** @internal */
@@ -121,6 +140,7 @@ export declare namespace decodeRlpCursor {
     | Hex.fromBytes.ErrorType
     | readLength.ErrorType
     | readList.ErrorType
+    | DepthLimitExceededError
     | Errors.GlobalErrorType
 }
 
@@ -149,17 +169,27 @@ export function readList<to extends 'Hex' | 'Bytes'>(
   cursor: Cursor.Cursor,
   length: number,
   to: to | 'Hex' | 'Bytes',
+  depth = 0,
 ) {
   const position = cursor.position
   const value: decodeRlpCursor.ReturnType<to>[] = []
   while (cursor.position - position < length)
-    value.push(decodeRlpCursor(cursor, to))
+    value.push(decodeRlpCursor(cursor, to, depth))
+  // Items must consume exactly the declared list length.
+  if (cursor.position - position !== length)
+    throw new ListBoundaryExceededError({
+      consumed: cursor.position - position,
+      declared: length,
+    })
   return value
 }
 
 /** @internal */
 export declare namespace readList {
-  type ErrorType = Errors.GlobalErrorType
+  type ErrorType =
+    | DepthLimitExceededError
+    | ListBoundaryExceededError
+    | Errors.GlobalErrorType
 }
 
 /**
@@ -643,3 +673,36 @@ function writeBigEndian(
 function invalidNibble(hex: Hex.Hex): Errors.BaseError {
   return new Errors.BaseError(`Invalid hex string \`${hex}\`.`)
 }
+
+/** Thrown when an RLP value nests deeper than the decode depth limit. */
+export class DepthLimitExceededError extends Errors.BaseError {
+  override readonly name = 'Rlp.DepthLimitExceededError'
+
+  constructor({ limit }: { limit: number }) {
+    super(`RLP depth limit of \`${limit}\` exceeded.`)
+  }
+}
+
+/** Thrown when RLP list items overrun the list's declared length. */
+export class ListBoundaryExceededError extends Errors.BaseError {
+  override readonly name = 'Rlp.ListBoundaryExceededError'
+
+  constructor({ consumed, declared }: { consumed: number; declared: number }) {
+    super(
+      `RLP list items consumed \`${consumed}\` bytes but the list declared a length of \`${declared}\`.`,
+    )
+  }
+}
+
+/** Thrown when an RLP payload contains bytes after the decoded item. */
+export class TrailingBytesError extends Errors.BaseError {
+  override readonly name = 'Rlp.TrailingBytesError'
+
+  constructor({ count }: { count: number }) {
+    super(
+      `RLP payload encodes a single item, but \`${count}\` trailing ${
+        count === 1 ? 'byte remains' : 'bytes remain'
+      }.`,
+    )
+  }
+}

package/src/core/RpcSchema.ts

@@ -289,7 +289,7 @@ export type FromViem<schema extends readonly ViemSchemaItem[]> = {
  * Each method's name comes from its key. Both `params` and `ReturnType` are
  * derived from the Zod schema's input (wire) type, since raw JSON-RPC clients
  * send and receive wire values. Decode wire results to their native
- * representation explicitly via {@link ox#zod/RpcSchema.decodeReturns}.
+ * representation explicitly via `zod.RpcSchema.decodeReturns`.
  *
  * @example
  * ```ts twoslash
@@ -331,7 +331,7 @@ export type Schema = Generic | FromZod.Namespace
 
 /**
  * Resolves a {@link ox#RpcSchema.Schema} input to an Ox {@link ox#RpcSchema.Generic}.
- * A Zod namespace is converted via {@link ox#RpcSchema.FromZod}; a `Generic` is
+ * A Zod namespace is converted via {@link ox#RpcSchema.(FromZod:type)}; a `Generic` is
  * passed through; otherwise falls back to {@link ox#RpcSchema.Default}.
  */
 export type ToGeneric<schema extends Schema | undefined> =

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

@@ -117,6 +117,10 @@ describe('from', () => {
 test('exports', () => {
   expect(Object.keys(Abi)).toMatchInlineSnapshot(`
     [
+      "InvalidSignatureError",
+      "InvalidStructSignatureError",
+      "UnknownSignatureError",
+      "CircularReferenceError",
       "format",
       "from",
     ]

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

@@ -2107,6 +2107,9 @@ describe('getSignatureHash', () => {
 test('exports', () => {
   expect(Object.keys(AbiItem)).toMatchInlineSnapshot(`
     [
+      "InvalidAbiItemError",
+      "UnknownSolidityTypeError",
+      "UnknownTypeError",
       "format",
       "from",
       "fromAbi",

package/src/core/_test/AbiParameter.test-d.ts

@@ -0,0 +1,41 @@
+import { AbiParameter } from 'ox'
+import { describe, expectTypeOf, test } from 'vp/test'
+
+describe('AbiParameter.format', () => {
+  test('infers parameter', () => {
+    const formatted = AbiParameter.format(value)
+    expectTypeOf(formatted).toEqualTypeOf<'address spender'>()
+  })
+
+  test('not narrowable', () => {
+    const formatted = AbiParameter.format({} as AbiParameter.AbiParameter)
+    expectTypeOf(formatted).toEqualTypeOf<string>()
+  })
+
+  const value = {
+    name: 'spender',
+    type: 'address',
+  } as const
+})
+
+describe('AbiParameter.from', () => {
+  test('infers parameter', () => {
+    const parameter = AbiParameter.from(value)
+    expectTypeOf(parameter).toEqualTypeOf(value)
+  })
+
+  test('from signature', () => {
+    const parameter = AbiParameter.from('address spender')
+    expectTypeOf(parameter).toEqualTypeOf(value)
+  })
+
+  test('not narrowable', () => {
+    const parameter = AbiParameter.from({} as AbiParameter.AbiParameter)
+    expectTypeOf(parameter).toEqualTypeOf<AbiParameter.AbiParameter>()
+  })
+
+  const value = {
+    name: 'spender',
+    type: 'address',
+  } as const
+})

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

@@ -0,0 +1,84 @@
+import { AbiParameter } from 'ox'
+import { describe, expect, test } from 'vp/test'
+
+describe('from', () => {
+  test('json parameter', () => {
+    expect(AbiParameter.from({ name: 'spender', type: 'address' }))
+      .toMatchInlineSnapshot(`
+      {
+        "name": "spender",
+        "type": "address",
+      }
+    `)
+  })
+
+  test('human-readable parameter', () => {
+    expect(AbiParameter.from('address spender')).toMatchInlineSnapshot(`
+      {
+        "name": "spender",
+        "type": "address",
+      }
+    `)
+  })
+
+  test('human-readable parameter with structs', () => {
+    expect(
+      AbiParameter.from([
+        'struct Foo { address spender; uint256 amount; }',
+        'Foo foo',
+      ]),
+    ).toMatchInlineSnapshot(`
+      {
+        "components": [
+          {
+            "name": "spender",
+            "type": "address",
+          },
+          {
+            "name": "amount",
+            "type": "uint256",
+          },
+        ],
+        "name": "foo",
+        "type": "tuple",
+      }
+    `)
+  })
+})
+
+describe('format', () => {
+  test('parameter', () => {
+    expect(
+      AbiParameter.format({ name: 'spender', type: 'address' }),
+    ).toMatchInlineSnapshot(`"address spender"`)
+  })
+
+  test('tuple parameter', () => {
+    expect(
+      AbiParameter.format({
+        components: [
+          { name: 'spender', type: 'address' },
+          { name: 'amount', type: 'uint256' },
+        ],
+        name: 'foo',
+        type: 'tuple',
+      }),
+    ).toMatchInlineSnapshot(`"(address spender, uint256 amount) foo"`)
+  })
+})
+
+test('exports', () => {
+  expect(Object.keys(AbiParameter)).toMatchInlineSnapshot(`
+    [
+      "InvalidAbiParameterError",
+      "InvalidAbiTypeParameterError",
+      "InvalidFunctionModifierError",
+      "InvalidModifierError",
+      "InvalidParameterError",
+      "SolidityProtectedKeywordError",
+      "InvalidParenthesisError",
+      "format",
+      "from",
+    ]
+  `)
+})

package/src/core/_test/AbiParameters.decode.test.ts

@@ -1601,22 +1601,12 @@ test('zst', () => {
   expect(() =>
     AbiParameters.decode([{ type: 'uint256[0][4294967295]' }], payload),
   ).toThrowErrorMatchingInlineSnapshot(
-    `
-    [AbiParameters.DataSizeTooSmallError: Data size of 64 bytes is too small for given parameters.
-
-    Params: (uint256[0][4294967295])
-    Data:   0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000FFFFFFFF (64 bytes)]
-  `,
+    '[Cursor.RecursiveReadLimitExceededError: Recursive read limit of `8192` exceeded (recursive read count: `8193`).]',
   )
   expect(() =>
     AbiParameters.decode([{ type: 'uint32[0][4294967295]' }], payload),
   ).toThrowErrorMatchingInlineSnapshot(
-    `
-    [AbiParameters.DataSizeTooSmallError: Data size of 64 bytes is too small for given parameters.
-
-    Params: (uint32[0][4294967295])
-    Data:   0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000FFFFFFFF (64 bytes)]
-  `,
+    '[Cursor.RecursiveReadLimitExceededError: Recursive read limit of `8192` exceeded (recursive read count: `8193`).]',
   )
   expect(() =>
     AbiParameters.decode(
@@ -1798,3 +1788,89 @@ test('recursive 2', () => {
     '[Cursor.RecursiveReadLimitExceededError: Recursive read limit of `8192` exceeded (recursive read count: `8193`).]',
   )
 })
+
+describe('zero-width types', () => {
+  test('zero-length fixed array', () => {
+    expect(
+      AbiParameters.decode(
+        [{ type: 'uint256[0]' }, { type: 'uint256' }],
+        '0x0000000000000000000000000000000000000000000000000000000000000003',
+      ),
+    ).toEqual([[], 3n])
+  })
+
+  test('trailing empty tuple', () => {
+    expect(
+      AbiParameters.decode(
+        [{ type: 'uint256' }, { type: 'tuple', components: [] }],
+        '0x0000000000000000000000000000000000000000000000000000000000000005',
+      ),
+    ).toEqual([5n, []])
+  })
+
+  test('zero-length fixed array of dynamic type', () => {
+    expect(
+      AbiParameters.decode(
+        [{ type: 'string[0]' }, { type: 'uint256' }],
+        '0x00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000003',
+      ),
+    ).toEqual([[], 3n])
+  })
+
+  test('standalone zero-length fixed array of dynamic type', () => {
+    // The head is a single offset word pointing at an empty tail.
+    expect(
+      AbiParameters.decode(
+        [{ type: 'string[0]' }],
+        '0x0000000000000000000000000000000000000000000000000000000000000020',
+      ),
+    ).toEqual([[]])
+    expect(
+      AbiParameters.decode(
+        [{ type: 'bytes[0]' }],
+        '0x0000000000000000000000000000000000000000000000000000000000000020',
+      ),
+    ).toEqual([[]])
+  })
+
+  test('round-trip', () => {
+    const cases = [
+      {
+        parameters: [{ type: 'uint256[0]' }, { type: 'uint256' }],
+        values: [[], 3n],
+      },
+      {
+        parameters: [{ type: 'uint256' }, { type: 'tuple', components: [] }],
+        values: [5n, []],
+      },
+      {
+        parameters: [{ type: 'string[0]' }, { type: 'uint256' }],
+        values: [[], 3n],
+      },
+      {
+        parameters: [{ type: 'uint256[0]' }, { type: 'string' }],
+        values: [[], 'hello'],
+      },
+      {
+        parameters: [{ type: 'uint256[0][2]' }, { type: 'uint256' }],
+        values: [[[], []], 9n],
+      },
+      {
+        parameters: [{ type: 'string[0]' }],
+        values: [[]],
+      },
+      {
+        parameters: [{ type: 'tuple', components: [{ type: 'string[0]' }] }],
+        values: [[[]]],
+      },
+    ] as const
+    for (const { parameters, values } of cases) {
+      expect(
+        AbiParameters.decode(
+          parameters,
+          AbiParameters.encode(parameters, values as never),
+        ),
+      ).toEqual(values)
+    }
+  })
+})

package/src/core/_test/AbiParameters.encode.test.ts

@@ -1963,3 +1963,71 @@ test('https://github.com/wevm/viem/issues/1960', () => {
     `[BaseError: Invalid boolean value: "true" (type: string). Expected: \`true\` or \`false\`.]`,
   )
 })
+
+describe('zero-width types', () => {
+  // Per the ABI spec, `enc(T[0])` and `enc(())` are zero-length: a zero-length
+  // fixed array or empty tuple contributes no bytes. Expected values verified
+  // against ethers `AbiCoder.defaultAbiCoder()`.
+  test('zero-length fixed array', () => {
+    expect(
+      AbiParameters.encode(
+        [{ type: 'uint256[0]' }, { type: 'uint256' }],
+        [[], 3n],
+      ),
+    ).toBe('0x0000000000000000000000000000000000000000000000000000000000000003')
+  })
+
+  test('empty tuple', () => {
+    expect(
+      AbiParameters.encode(
+        [{ type: 'uint256' }, { type: 'tuple', components: [] }],
+        [5n, []],
+      ),
+    ).toBe('0x0000000000000000000000000000000000000000000000000000000000000005')
+  })
+
+  test('empty tuple only', () => {
+    expect(
+      AbiParameters.encode([{ type: 'tuple', components: [] }], [[]]),
+    ).toBe('0x')
+  })
+
+  test('nested zero-length fixed arrays', () => {
+    expect(
+      AbiParameters.encode(
+        [{ type: 'uint256[0][2]' }, { type: 'uint256' }],
+        [[[], []], 9n],
+      ),
+    ).toBe('0x0000000000000000000000000000000000000000000000000000000000000009')
+    expect(
+      AbiParameters.encode(
+        [{ type: 'uint256[2][0]' }, { type: 'uint256' }],
+        [[], 9n],
+      ),
+    ).toBe('0x0000000000000000000000000000000000000000000000000000000000000009')
+  })
+
+  test('offsets skip zero-width parameters', () => {
+    expect(
+      AbiParameters.encode(
+        [{ type: 'uint256[0]' }, { type: 'string' }],
+        [[], 'hello'],
+      ),
+    ).toBe(
+      '0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000568656c6c6f000000000000000000000000000000000000000000000000000000',
+    )
+  })
+
+  // `T[0]` of a dynamic `T` is dynamic per the ABI spec: 32-byte offset
+  // pointing at a zero-length tail.
+  test('zero-length fixed array of dynamic type', () => {
+    expect(
+      AbiParameters.encode(
+        [{ type: 'string[0]' }, { type: 'uint256' }],
+        [[], 3n],
+      ),
+    ).toBe(
+      '0x00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000003',
+    )
+  })
+})

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

@@ -360,6 +360,13 @@ describe('format', () => {
 test('exports', () => {
   expect(Object.keys(AbiParameters)).toMatchInlineSnapshot(`
     [
+      "InvalidAbiParametersError",
+      "InvalidAbiTypeParameterError",
+      "InvalidFunctionModifierError",
+      "InvalidModifierError",
+      "InvalidParameterError",
+      "SolidityProtectedKeywordError",
+      "InvalidParenthesisError",
       "decode",
       "encode",
       "encodePacked",