ox 1.0.0-beta.8 → 1.0.0

package/src/core/internal/human-readable/errors.test.ts

@@ -0,0 +1,258 @@
+import { expect, test } from 'vp/test'
+import {
+  CircularReferenceError,
+  InvalidAbiItemError,
+  InvalidAbiParameterError,
+  InvalidAbiParametersError,
+  InvalidAbiTypeParameterError,
+  InvalidFunctionModifierError,
+  InvalidModifierError,
+  InvalidParameterError,
+  InvalidParenthesisError,
+  InvalidSignatureError,
+  InvalidStructSignatureError,
+  SolidityProtectedKeywordError,
+  UnknownSignatureError,
+  UnknownSolidityTypeError,
+  UnknownTypeError,
+} from './errors.js'
+
+test('InvalidAbiItemError', () => {
+  expect(new InvalidAbiItemError({ signature: 'address' }))
+    .toMatchInlineSnapshot(`
+    [AbiItem.InvalidAbiItemError: Failed to parse ABI item.
+
+    Details: parseAbiItem("address")
+    See: https://oxlib.sh/api/AbiItem/from]
+  `)
+})
+
+test('UnknownTypeError', () => {
+  expect(new UnknownTypeError({ type: 'Foo' })).toMatchInlineSnapshot(`
+    [HumanReadableAbi.UnknownTypeError: Unknown type.
+
+    Type "Foo" is not a valid ABI type. Perhaps you forgot to include a struct signature?]
+  `)
+})
+
+test('UnknownSolidityTypeError', () => {
+  expect(new UnknownSolidityTypeError({ type: 'Foo' })).toMatchInlineSnapshot(`
+    [HumanReadableAbi.UnknownSolidityTypeError: Unknown type.
+
+    Type "Foo" is not a valid ABI type.]
+  `)
+})
+
+test('InvalidAbiParamterError', () => {
+  expect(new InvalidAbiParameterError({ param: 'address owner' }))
+    .toMatchInlineSnapshot(`
+    [AbiParameter.InvalidAbiParameterError: Failed to parse ABI parameter.
+
+    Details: parseAbiParameter("address owner")
+    See: https://oxlib.sh/api/AbiParameter/from]
+  `)
+})
+
+test('InvalidAbiParamtersError', () => {
+  expect(new InvalidAbiParametersError({ params: 'address owner' }))
+    .toMatchInlineSnapshot(`
+    [AbiParameters.InvalidAbiParametersError: Failed to parse ABI parameters.
+
+    Details: parseAbiParameters("address owner")
+    See: https://oxlib.sh/api/AbiParameters/from]
+  `)
+})
+
+test('InvalidParameterError', () => {
+  expect(
+    new InvalidParameterError({
+      param: 'address',
+    }),
+  ).toMatchInlineSnapshot(`
+    [HumanReadableAbi.InvalidParameterError: Invalid ABI parameter.
+
+    Details: address]
+  `)
+})
+
+test('SolidityProtectedKeywordError', () => {
+  expect(
+    new SolidityProtectedKeywordError({
+      param: 'address',
+      name: 'address',
+    }),
+  ).toMatchInlineSnapshot(`
+    [HumanReadableAbi.SolidityProtectedKeywordError: Invalid ABI parameter.
+
+    "address" is a protected Solidity keyword. More info: https://docs.soliditylang.org/en/latest/cheatsheet.html
+
+    Details: address]
+  `)
+})
+
+test('InvalidModifierError', () => {
+  expect(
+    new InvalidModifierError({
+      param: 'address',
+      modifier: 'calldata',
+      type: 'event',
+    }),
+  ).toMatchInlineSnapshot(`
+    [HumanReadableAbi.InvalidModifierError: Invalid ABI parameter.
+
+    Modifier "calldata" not allowed in "event" type.
+
+    Details: address]
+  `)
+
+  expect(
+    new InvalidModifierError({
+      param: 'address',
+      modifier: 'calldata',
+    }),
+  ).toMatchInlineSnapshot(`
+    [HumanReadableAbi.InvalidModifierError: Invalid ABI parameter.
+
+    Modifier "calldata" not allowed.
+
+    Details: address]
+  `)
+})
+
+test('InvalidFunctionModifierError', () => {
+  expect(
+    new InvalidFunctionModifierError({
+      param: 'address',
+      modifier: 'calldata',
+      type: 'function',
+    }),
+  ).toMatchInlineSnapshot(`
+    [HumanReadableAbi.InvalidFunctionModifierError: Invalid ABI parameter.
+
+    Modifier "calldata" not allowed in "function" type.
+    Data location can only be specified for array, struct, or mapping types, but "calldata" was given.
+
+    Details: address]
+  `)
+})
+
+test('InvalidAbiTypeParameterError', () => {
+  expect(
+    new InvalidAbiTypeParameterError({
+      abiParameter: { type: 'address' },
+    }),
+  ).toMatchInlineSnapshot(`
+    [HumanReadableAbi.InvalidAbiTypeParameterError: Invalid ABI parameter.
+
+    ABI parameter type is invalid.
+
+    Details: {
+      "type": "address"
+    }]
+  `)
+})
+
+test('InvalidSignatureError', () => {
+  expect(
+    new InvalidSignatureError({
+      signature: 'function name??()',
+      type: 'function',
+    }),
+  ).toMatchInlineSnapshot(`
+    [Abi.InvalidSignatureError: Invalid function signature.
+
+    Details: function name??()]
+  `)
+
+  expect(
+    new InvalidSignatureError({
+      signature: 'function name??()',
+      type: 'struct',
+    }),
+  ).toMatchInlineSnapshot(`
+    [Abi.InvalidSignatureError: Invalid struct signature.
+
+    Details: function name??()]
+  `)
+
+  expect(
+    new InvalidSignatureError({
+      signature: 'function name??()',
+      type: 'error',
+    }),
+  ).toMatchInlineSnapshot(`
+    [Abi.InvalidSignatureError: Invalid error signature.
+
+    Details: function name??()]
+  `)
+
+  expect(
+    new InvalidSignatureError({
+      signature: 'function name??()',
+      type: 'event',
+    }),
+  ).toMatchInlineSnapshot(`
+    [Abi.InvalidSignatureError: Invalid event signature.
+
+    Details: function name??()]
+  `)
+
+  expect(
+    new InvalidSignatureError({
+      signature: 'function name??()',
+      type: 'constructor',
+    }),
+  ).toMatchInlineSnapshot(`
+    [Abi.InvalidSignatureError: Invalid constructor signature.
+
+    Details: function name??()]
+  `)
+})
+
+test('UnknownSignatureError', () => {
+  expect(new UnknownSignatureError({ signature: 'invalid' }))
+    .toMatchInlineSnapshot(`
+    [Abi.UnknownSignatureError: Unknown signature.
+
+    Details: invalid]
+  `)
+})
+
+test('InvalidStructSignatureError', () => {
+  expect(new InvalidStructSignatureError({ signature: 'struct Foo{}' }))
+    .toMatchInlineSnapshot(`
+    [Abi.InvalidStructSignatureError: Invalid struct signature.
+
+    No properties exist.
+
+    Details: struct Foo{}]
+  `)
+})
+
+test('InvalidParenthesisError', () => {
+  expect(new InvalidParenthesisError({ current: '(Foo))', depth: -1 }))
+    .toMatchInlineSnapshot(`
+    [HumanReadableAbi.InvalidParenthesisError: Unbalanced parentheses.
+
+    "(Foo))" has too many closing parentheses.
+
+    Details: Depth "-1"]
+  `)
+
+  expect(new InvalidParenthesisError({ current: '((Foo)', depth: 1 }))
+    .toMatchInlineSnapshot(`
+    [HumanReadableAbi.InvalidParenthesisError: Unbalanced parentheses.
+
+    "((Foo)" has too many opening parentheses.
+
+    Details: Depth "1"]
+  `)
+})
+
+test('CircularReferenceError', () => {
+  expect(new CircularReferenceError({ type: 'Foo' })).toMatchInlineSnapshot(`
+    [Abi.CircularReferenceError: Circular reference detected.
+
+    Struct "Foo" is a circular reference.]
+  `)
+})

package/src/core/internal/human-readable/errors.ts

@@ -0,0 +1,205 @@
+import type { AbiItemType, AbiParameter } from 'abitype'
+import { BaseError } from '../../Errors.js'
+import type { Modifier } from './types/signatures.js'
+
+export class InvalidAbiItemError extends BaseError {
+  override name = 'AbiItem.InvalidAbiItemError'
+
+  constructor({ signature }: { signature: string | object }) {
+    super('Failed to parse ABI item.', {
+      details: `parseAbiItem(${JSON.stringify(signature, null, 2)})`,
+      docsPath: '/api/AbiItem/from',
+    })
+  }
+}
+
+export class UnknownTypeError extends BaseError {
+  override name = 'HumanReadableAbi.UnknownTypeError'
+
+  constructor({ type }: { type: string }) {
+    super('Unknown type.', {
+      metaMessages: [
+        `Type "${type}" is not a valid ABI type. Perhaps you forgot to include a struct signature?`,
+      ],
+    })
+  }
+}
+
+export class UnknownSolidityTypeError extends BaseError {
+  override name = 'HumanReadableAbi.UnknownSolidityTypeError'
+
+  constructor({ type }: { type: string }) {
+    super('Unknown type.', {
+      metaMessages: [`Type "${type}" is not a valid ABI type.`],
+    })
+  }
+}
+
+export class InvalidAbiParameterError extends BaseError {
+  override name = 'AbiParameter.InvalidAbiParameterError'
+
+  constructor({ param }: { param: string | object }) {
+    super('Failed to parse ABI parameter.', {
+      details: `parseAbiParameter(${JSON.stringify(param, null, 2)})`,
+      docsPath: '/api/AbiParameter/from',
+    })
+  }
+}
+
+export class InvalidAbiParametersError extends BaseError {
+  override name = 'AbiParameters.InvalidAbiParametersError'
+
+  constructor({ params }: { params: string | object }) {
+    super('Failed to parse ABI parameters.', {
+      details: `parseAbiParameters(${JSON.stringify(params, null, 2)})`,
+      docsPath: '/api/AbiParameters/from',
+    })
+  }
+}
+
+export class InvalidParameterError extends BaseError {
+  override name = 'HumanReadableAbi.InvalidParameterError'
+
+  constructor({ param }: { param: string }) {
+    super('Invalid ABI parameter.', {
+      details: param,
+    })
+  }
+}
+
+export class SolidityProtectedKeywordError extends BaseError {
+  override name = 'HumanReadableAbi.SolidityProtectedKeywordError'
+
+  constructor({ param, name }: { param: string; name: string }) {
+    super('Invalid ABI parameter.', {
+      details: param,
+      metaMessages: [
+        `"${name}" is a protected Solidity keyword. More info: https://docs.soliditylang.org/en/latest/cheatsheet.html`,
+      ],
+    })
+  }
+}
+
+export class InvalidModifierError extends BaseError {
+  override name = 'HumanReadableAbi.InvalidModifierError'
+
+  constructor({
+    param,
+    type,
+    modifier,
+  }: {
+    param: string
+    type?: AbiItemType | 'struct' | undefined
+    modifier: Modifier
+  }) {
+    super('Invalid ABI parameter.', {
+      details: param,
+      metaMessages: [
+        `Modifier "${modifier}" not allowed${
+          type ? ` in "${type}" type` : ''
+        }.`,
+      ],
+    })
+  }
+}
+
+export class InvalidFunctionModifierError extends BaseError {
+  override name = 'HumanReadableAbi.InvalidFunctionModifierError'
+
+  constructor({
+    param,
+    type,
+    modifier,
+  }: {
+    param: string
+    type?: AbiItemType | 'struct' | undefined
+    modifier: Modifier
+  }) {
+    super('Invalid ABI parameter.', {
+      details: param,
+      metaMessages: [
+        `Modifier "${modifier}" not allowed${
+          type ? ` in "${type}" type` : ''
+        }.`,
+        `Data location can only be specified for array, struct, or mapping types, but "${modifier}" was given.`,
+      ],
+    })
+  }
+}
+
+export class InvalidAbiTypeParameterError extends BaseError {
+  override name = 'HumanReadableAbi.InvalidAbiTypeParameterError'
+
+  constructor({
+    abiParameter,
+  }: {
+    abiParameter: AbiParameter & { indexed?: boolean | undefined }
+  }) {
+    super('Invalid ABI parameter.', {
+      details: JSON.stringify(abiParameter, null, 2),
+      metaMessages: ['ABI parameter type is invalid.'],
+    })
+  }
+}
+
+export class InvalidSignatureError extends BaseError {
+  override name = 'Abi.InvalidSignatureError'
+
+  constructor({
+    signature,
+    type,
+  }: {
+    signature: string
+    type: AbiItemType | 'struct'
+  }) {
+    super(`Invalid ${type} signature.`, {
+      details: signature,
+    })
+  }
+}
+
+export class UnknownSignatureError extends BaseError {
+  override name = 'Abi.UnknownSignatureError'
+
+  constructor({ signature }: { signature: string }) {
+    super('Unknown signature.', {
+      details: signature,
+    })
+  }
+}
+
+export class InvalidStructSignatureError extends BaseError {
+  override name = 'Abi.InvalidStructSignatureError'
+
+  constructor({ signature }: { signature: string }) {
+    super('Invalid struct signature.', {
+      details: signature,
+      metaMessages: ['No properties exist.'],
+    })
+  }
+}
+
+export class InvalidParenthesisError extends BaseError {
+  override name = 'HumanReadableAbi.InvalidParenthesisError'
+
+  constructor({ current, depth }: { current: string; depth: number }) {
+    super('Unbalanced parentheses.', {
+      metaMessages: [
+        `"${current.trim()}" has too many ${
+          depth > 0 ? 'opening' : 'closing'
+        } parentheses.`,
+      ],
+      details: `Depth "${depth}"`,
+    })
+  }
+}
+
+export class CircularReferenceError extends BaseError {
+  override name = 'Abi.CircularReferenceError'
+
+  constructor({ type }: { type: string }) {
+    super('Circular reference detected.', {
+      metaMessages: [`Struct "${type}" is a circular reference.`],
+    })
+  }
+}

package/src/core/internal/human-readable/formatAbi.test-d.ts

@@ -0,0 +1,144 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type { Abi } from 'abitype'
+import { seaportAbi } from '../../../../test/abis/json.js'
+import type { FormatAbi } from './formatAbi.js'
+import { formatAbi } from './formatAbi.js'
+
+test('FormatAbi', () => {
+  expectTypeOf<FormatAbi<[]>>().toEqualTypeOf<never>()
+
+  expectTypeOf<
+    FormatAbi<
+      readonly [
+        {
+          readonly name: 'foo'
+          readonly type: 'function'
+          readonly stateMutability: 'nonpayable'
+          readonly inputs: readonly []
+          readonly outputs: readonly []
+        },
+        {
+          readonly name: 'bar'
+          readonly type: 'function'
+          readonly stateMutability: 'nonpayable'
+          readonly inputs: readonly [
+            {
+              readonly type: 'tuple'
+              readonly components: readonly [
+                {
+                  readonly name: 'name'
+                  readonly type: 'string'
+                },
+              ]
+            },
+            {
+              readonly type: 'bytes32'
+            },
+          ]
+          readonly outputs: readonly []
+        },
+      ]
+    >
+  >().toEqualTypeOf<
+    readonly ['function foo()', 'function bar((string name), bytes32)']
+  >()
+
+  expectTypeOf<
+    FormatAbi<
+      readonly [
+        {
+          readonly name: 'balanceOf'
+          readonly type: 'function'
+          readonly stateMutability: 'view'
+          readonly inputs: readonly [
+            {
+              readonly name: 'owner'
+              readonly type: 'address'
+            },
+          ]
+          readonly outputs: readonly [
+            {
+              readonly type: 'uint256'
+            },
+          ]
+        },
+        {
+          readonly name: 'Transfer'
+          readonly type: 'event'
+          readonly inputs: readonly [
+            {
+              readonly name: 'from'
+              readonly type: 'address'
+              readonly indexed: true
+            },
+            {
+              readonly name: 'to'
+              readonly type: 'address'
+              readonly indexed: true
+            },
+            {
+              readonly name: 'amount'
+              readonly type: 'uint256'
+            },
+          ]
+        },
+      ]
+    >
+  >().toEqualTypeOf<
+    readonly [
+      'function balanceOf(address owner) view returns (uint256)',
+      'event Transfer(address indexed from, address indexed to, uint256 amount)',
+    ]
+  >()
+})
+
+test('formatAbi', () => {
+  expectTypeOf(formatAbi([])).toEqualTypeOf<never>()
+
+  // Array
+  const res = formatAbi([
+    {
+      name: 'bar',
+      type: 'function',
+      stateMutability: 'nonpayable',
+      inputs: [
+        {
+          type: 'tuple',
+          components: [
+            {
+              name: 'name',
+              type: 'string',
+            },
+          ],
+        },
+        {
+          type: 'bytes32',
+        },
+      ],
+      outputs: [],
+    },
+  ])
+  expectTypeOf<typeof res>().toEqualTypeOf<
+    readonly ['function bar((string name), bytes32)']
+  >()
+
+  const abi2 = [
+    {
+      type: 'function',
+      name: 'foo',
+      inputs: [],
+      outputs: [],
+      stateMutability: 'view',
+    },
+  ]
+  expectTypeOf(formatAbi(abi2)).toEqualTypeOf<readonly string[]>()
+
+  const param = abi2 as Abi
+  expectTypeOf(formatAbi(param)).toEqualTypeOf<readonly string[]>()
+
+  const getOrderType = formatAbi(seaportAbi)[10]
+  expectTypeOf<
+    typeof getOrderType
+  >().toEqualTypeOf<'function getOrderHash((address offerer, address zone, (uint8 itemType, address token, uint256 identifierOrCriteria, uint256 startAmount, uint256 endAmount)[] offer, (uint8 itemType, address token, uint256 identifierOrCriteria, uint256 startAmount, uint256 endAmount, address recipient)[] consideration, uint8 orderType, uint256 startTime, uint256 endTime, bytes32 zoneHash, uint256 salt, bytes32 conduitKey, uint256 counter) order) view returns (bytes32 orderHash)'>()
+})

package/src/core/internal/human-readable/formatAbi.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from 'vp/test'
+
+import { seaportAbi } from '../../../../test/abis/json.js'
+import { formatAbi } from './formatAbi.js'
+
+const customSolidityErrorsAbi = [
+  { inputs: [], stateMutability: 'nonpayable', type: 'constructor' },
+  { inputs: [], name: 'ApprovalCallerNotOwnerNorApproved', type: 'error' },
+  { inputs: [], name: 'ApprovalQueryForNonexistentToken', type: 'error' },
+] as const
+
+test('formatAbi', () => {
+  const result = formatAbi(seaportAbi)
+  expect(result).toMatchSnapshot()
+
+  expect(formatAbi(customSolidityErrorsAbi)).toMatchInlineSnapshot(`
+    [
+      "constructor()",
+      "error ApprovalCallerNotOwnerNorApproved()",
+      "error ApprovalQueryForNonexistentToken()",
+    ]
+  `)
+})

package/src/core/internal/human-readable/formatAbi.ts

@@ -0,0 +1,37 @@
+import type { Abi } from 'abitype'
+import { type FormatAbiItem, formatAbiItem } from './formatAbiItem.js'
+
+/**
+ * Parses JSON ABI into human-readable ABI
+ *
+ * @param abi - ABI
+ * @returns Human-readable ABI
+ */
+export type FormatAbi<abi extends Abi | readonly unknown[]> = Abi extends abi
+  ? readonly string[]
+  : abi extends readonly []
+    ? never
+    : abi extends Abi
+      ? {
+          [key in keyof abi]: FormatAbiItem<abi[key]>
+        }
+      : readonly string[]
+
+/**
+ * Parses JSON ABI into human-readable ABI
+ *
+ * @param abi - ABI
+ * @returns Human-readable ABI
+ */
+export function formatAbi<const abi extends Abi | readonly unknown[]>(
+  abi: abi,
+): FormatAbi<abi> {
+  const signatures = []
+  const length = abi.length
+  for (let i = 0; i < length; i++) {
+    const abiItem = abi[i]!
+    const signature = formatAbiItem(abiItem as Abi[number])
+    signatures.push(signature)
+  }
+  return signatures as unknown as FormatAbi<abi>
+}