ox 1.0.0-beta.8 → 1.0.0

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

@@ -0,0 +1,115 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type {
+  Abi,
+  AbiConstructor,
+  AbiError,
+  AbiEvent,
+  AbiFallback,
+  AbiFunction,
+  AbiReceive,
+} from 'abitype'
+import type { FormatAbiItem } from './formatAbiItem.js'
+import { formatAbiItem } from './formatAbiItem.js'
+
+test('FormatAbiItem', () => {
+  expectTypeOf<FormatAbiItem<Abi[number]>>().toEqualTypeOf<string>()
+  expectTypeOf<FormatAbiItem<AbiFunction>>().toEqualTypeOf<string>()
+  expectTypeOf<FormatAbiItem<AbiEvent>>().toEqualTypeOf<string>()
+  expectTypeOf<FormatAbiItem<AbiError>>().toEqualTypeOf<string>()
+  expectTypeOf<FormatAbiItem<AbiConstructor>>().toEqualTypeOf<string>()
+  expectTypeOf<FormatAbiItem<AbiFallback>>().toEqualTypeOf<string>()
+  expectTypeOf<FormatAbiItem<AbiReceive>>().toEqualTypeOf<string>()
+
+  expectTypeOf<
+    FormatAbiItem<{
+      readonly name: 'foo'
+      readonly type: 'function'
+      readonly stateMutability: 'nonpayable'
+      readonly inputs: readonly []
+      readonly outputs: readonly []
+    }>
+  >().toEqualTypeOf<'function foo()'>()
+
+  expectTypeOf<
+    FormatAbiItem<{
+      readonly name: 'address'
+      readonly type: 'function'
+      readonly stateMutability: 'nonpayable'
+      readonly inputs: readonly []
+      readonly outputs: readonly []
+    }>
+  >().toEqualTypeOf<'function [Error: "address" is a protected Solidity keyword.]()'>()
+
+  expectTypeOf<
+    FormatAbiItem<{
+      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<'event Transfer(address indexed from, address indexed to, uint256 amount)'>()
+})
+
+test('formatAbiItem', () => {
+  expectTypeOf(
+    formatAbiItem({
+      name: 'foo',
+      type: 'function',
+      stateMutability: 'nonpayable',
+      inputs: [],
+      outputs: [],
+    }),
+  ).toEqualTypeOf<'function foo()'>()
+  expectTypeOf(
+    formatAbiItem({
+      name: 'foo',
+      type: 'function',
+      stateMutability: 'nonpayable',
+      inputs: [
+        {
+          type: 'tuple',
+          components: [
+            {
+              type: 'string',
+            },
+          ],
+        },
+        {
+          type: 'address',
+        },
+      ],
+      outputs: [],
+    }),
+  ).toEqualTypeOf<'function foo((string), address)'>()
+
+  const abiItem: Abi[number] = {
+    type: 'function',
+    name: 'foo',
+    inputs: [],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  }
+  expectTypeOf(formatAbiItem(abiItem)).toEqualTypeOf<string>()
+
+  expectTypeOf(
+    formatAbiItem({ type: 'fallback', stateMutability: 'nonpayable' }),
+  ).toEqualTypeOf<'fallback() external'>()
+  expectTypeOf(
+    formatAbiItem({ type: 'fallback', stateMutability: 'payable' }),
+  ).toEqualTypeOf<'fallback() external payable'>()
+})

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

@@ -0,0 +1,102 @@
+import { expect, test } from 'vp/test'
+
+import { seaportAbi } from '../../../../test/abis/json.js'
+import { formatAbiItem } from './formatAbiItem.js'
+
+test('default', () => {
+  const result = formatAbiItem(seaportAbi[1])
+  expect(result).toMatchInlineSnapshot(
+    '"function cancel((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)[] orders) returns (bool cancelled)"',
+  )
+})
+
+test.each([
+  {
+    abiItem: {
+      type: 'function',
+      name: 'foo',
+      inputs: [{ type: 'string' }],
+      outputs: [],
+      stateMutability: 'nonpayable',
+    } as const,
+    expected: 'function foo(string)',
+  },
+  {
+    abiItem: {
+      type: 'event',
+      name: 'Foo',
+      inputs: [
+        { type: 'address', name: 'from', indexed: true },
+        { type: 'address', name: 'to', indexed: true },
+        { type: 'uint256', name: 'amount' },
+      ],
+    } as const,
+    expected:
+      'event Foo(address indexed from, address indexed to, uint256 amount)',
+  },
+  {
+    abiItem: {
+      type: 'constructor',
+      stateMutability: 'nonpayable',
+      inputs: [{ type: 'string' }],
+    } as const,
+    expected: 'constructor(string)',
+  },
+  {
+    abiItem: {
+      type: 'constructor',
+      stateMutability: 'payable',
+      inputs: [{ type: 'string' }],
+    } as const,
+    expected: 'constructor(string) payable',
+  },
+  {
+    abiItem: {
+      type: 'fallback',
+      stateMutability: 'nonpayable',
+    } as const,
+    expected: 'fallback() external',
+  },
+  {
+    abiItem: {
+      type: 'fallback',
+      stateMutability: 'payable',
+    } as const,
+    expected: 'fallback() external payable',
+  },
+  {
+    abiItem: {
+      type: 'receive',
+      stateMutability: 'payable',
+    } as const,
+    expected: 'receive() external payable',
+  },
+  {
+    abiItem: {
+      type: 'function',
+      name: 'initWormhole',
+      inputs: [
+        {
+          type: 'tuple[]',
+          name: 'configs',
+          components: [
+            {
+              type: 'uint256',
+              name: 'chainId',
+            },
+            {
+              type: 'uint16',
+              name: 'wormholeChainId',
+            },
+          ],
+        },
+      ],
+      outputs: [],
+      stateMutability: 'nonpayable',
+    } as const,
+    expected:
+      'function initWormhole((uint256 chainId, uint16 wormholeChainId)[] configs)',
+  },
+])('formatAbiItem($expected)', ({ abiItem, expected }) => {
+  expect(formatAbiItem(abiItem)).toEqual(expected)
+})

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

@@ -0,0 +1,136 @@
+import type {
+  Abi,
+  AbiConstructor,
+  AbiError,
+  AbiEvent,
+  AbiEventParameter,
+  AbiFallback,
+  AbiFunction,
+  AbiParameter,
+  AbiReceive,
+  AbiStateMutability,
+} from 'abitype'
+import {
+  type FormatAbiParameters as FormatAbiParameters_,
+  formatAbiParameters,
+} from './formatAbiParameters.js'
+import type { AssertName } from './types/signatures.js'
+
+/**
+ * Formats ABI item (e.g. error, event, function) into human-readable ABI item
+ *
+ * @param abiItem - ABI item
+ * @returns Human-readable ABI item
+ */
+export type FormatAbiItem<abiItem extends Abi[number]> =
+  Abi[number] extends abiItem
+    ? string
+    :
+        | (abiItem extends AbiFunction
+            ? AbiFunction extends abiItem
+              ? string
+              : `function ${AssertName<abiItem['name']>}(${FormatAbiParameters<
+                  abiItem['inputs']
+                >})${abiItem['stateMutability'] extends Exclude<
+                  AbiStateMutability,
+                  'nonpayable'
+                >
+                  ? ` ${abiItem['stateMutability']}`
+                  : ''}${abiItem['outputs']['length'] extends 0
+                  ? ''
+                  : ` returns (${FormatAbiParameters<abiItem['outputs']>})`}`
+            : never)
+        | (abiItem extends AbiEvent
+            ? AbiEvent extends abiItem
+              ? string
+              : `event ${AssertName<abiItem['name']>}(${FormatAbiParameters<
+                  abiItem['inputs']
+                >})`
+            : never)
+        | (abiItem extends AbiError
+            ? AbiError extends abiItem
+              ? string
+              : `error ${AssertName<abiItem['name']>}(${FormatAbiParameters<
+                  abiItem['inputs']
+                >})`
+            : never)
+        | (abiItem extends AbiConstructor
+            ? AbiConstructor extends abiItem
+              ? string
+              : `constructor(${FormatAbiParameters<
+                  abiItem['inputs']
+                >})${abiItem['stateMutability'] extends 'payable'
+                  ? ' payable'
+                  : ''}`
+            : never)
+        | (abiItem extends AbiFallback
+            ? AbiFallback extends abiItem
+              ? string
+              : `fallback() external${abiItem['stateMutability'] extends 'payable'
+                  ? ' payable'
+                  : ''}`
+            : never)
+        | (abiItem extends AbiReceive
+            ? AbiReceive extends abiItem
+              ? string
+              : 'receive() external payable'
+            : never)
+
+type FormatAbiParameters<
+  abiParameters extends readonly (AbiParameter | AbiEventParameter)[],
+> = abiParameters['length'] extends 0
+  ? ''
+  : FormatAbiParameters_<
+      abiParameters extends readonly [
+        AbiParameter | AbiEventParameter,
+        ...(readonly (AbiParameter | AbiEventParameter)[]),
+      ]
+        ? abiParameters
+        : never
+    >
+
+/**
+ * Formats ABI item (e.g. error, event, function) into human-readable ABI item
+ *
+ * @param abiItem - ABI item
+ * @returns Human-readable ABI item
+ */
+export function formatAbiItem<const abiItem extends Abi[number]>(
+  abiItem: abiItem,
+): FormatAbiItem<abiItem> {
+  type Result = FormatAbiItem<abiItem>
+  type Params = readonly [
+    AbiParameter | AbiEventParameter,
+    ...(readonly (AbiParameter | AbiEventParameter)[]),
+  ]
+
+  if (abiItem.type === 'function')
+    return `function ${abiItem.name}(${formatAbiParameters(
+      abiItem.inputs as Params,
+    )})${
+      abiItem.stateMutability && abiItem.stateMutability !== 'nonpayable'
+        ? ` ${abiItem.stateMutability}`
+        : ''
+    }${
+      abiItem.outputs?.length
+        ? ` returns (${formatAbiParameters(abiItem.outputs as Params)})`
+        : ''
+    }`
+  if (abiItem.type === 'event')
+    return `event ${abiItem.name}(${formatAbiParameters(
+      abiItem.inputs as Params,
+    )})`
+  if (abiItem.type === 'error')
+    return `error ${abiItem.name}(${formatAbiParameters(
+      abiItem.inputs as Params,
+    )})`
+  if (abiItem.type === 'constructor')
+    return `constructor(${formatAbiParameters(abiItem.inputs as Params)})${
+      abiItem.stateMutability === 'payable' ? ' payable' : ''
+    }`
+  if (abiItem.type === 'fallback')
+    return `fallback() external${
+      abiItem.stateMutability === 'payable' ? ' payable' : ''
+    }` as Result
+  return 'receive() external payable' as Result
+}

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

@@ -0,0 +1,125 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type { AbiParameter } from 'abitype'
+import type { FormatAbiParameter } from './formatAbiParameter.js'
+import { formatAbiParameter } from './formatAbiParameter.js'
+
+test('FormatAbiParameter', () => {
+  // string
+  expectTypeOf<
+    FormatAbiParameter<{
+      readonly type: 'address'
+      readonly name: 'from'
+    }>
+  >().toEqualTypeOf<'address from'>()
+  expectTypeOf<
+    FormatAbiParameter<{
+      readonly type: 'address'
+      readonly name: 'from'
+      readonly indexed: true
+    }>
+  >().toEqualTypeOf<'address indexed from'>()
+  expectTypeOf<
+    FormatAbiParameter<{
+      readonly type: 'address'
+      readonly name: ''
+    }>
+  >().toEqualTypeOf<'address'>()
+
+  expectTypeOf<
+    FormatAbiParameter<{
+      type: 'address'
+      name: 'address'
+    }>
+  >().toEqualTypeOf<'address [Error: "address" is a protected Solidity keyword.]'>()
+
+  expectTypeOf<
+    FormatAbiParameter<{
+      type: 'address'
+      name: '123'
+    }>
+  >().toEqualTypeOf<'address [Error: Identifier "123" cannot be a number string.]'>()
+
+  // Array
+  expectTypeOf<
+    FormatAbiParameter<{
+      readonly type: 'tuple'
+      readonly components: readonly [
+        {
+          readonly name: 'name'
+          readonly type: 'string'
+        },
+      ]
+    }>
+  >().toEqualTypeOf<'(string name)'>()
+
+  expectTypeOf<
+    FormatAbiParameter<{
+      readonly type: 'tuple'
+      readonly components: readonly [
+        {
+          readonly type: 'string'
+          readonly name: 'bar'
+        },
+      ]
+      readonly name: 'foo'
+    }>
+  >().toEqualTypeOf<'(string bar) foo'>()
+
+  expectTypeOf<
+    FormatAbiParameter<{
+      readonly components: [
+        {
+          readonly components: [
+            {
+              readonly type: 'string'
+              readonly name: 'foo'
+            },
+          ]
+          readonly type: 'tuple'
+        },
+      ]
+      readonly type: 'tuple'
+    }>
+  >().toEqualTypeOf<'((string foo))'>()
+
+  expectTypeOf<
+    FormatAbiParameter<{
+      readonly components: [
+        {
+          readonly components: [
+            {
+              readonly components: [
+                {
+                  readonly components: [
+                    {
+                      readonly type: 'string'
+                    },
+                  ]
+                  readonly type: 'tuple'
+                },
+              ]
+              readonly type: 'tuple'
+            },
+          ]
+          readonly type: 'tuple'
+        },
+      ]
+      readonly type: 'tuple'
+    }>
+  >().toEqualTypeOf<'((((string))))'>()
+})
+
+test('formatAbiParameter', () => {
+  expectTypeOf(
+    formatAbiParameter({
+      type: 'tuple',
+      components: [{ type: 'string' }],
+    }),
+  ).toEqualTypeOf<'(string)'>()
+
+  const param = { type: 'address' }
+  const param2: AbiParameter = param
+  expectTypeOf(formatAbiParameter(param)).toEqualTypeOf<string>()
+  expectTypeOf(formatAbiParameter(param2)).toEqualTypeOf<string>()
+})

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

@@ -0,0 +1,126 @@
+import { assertType, expect, expectTypeOf, test } from 'vp/test'
+
+import { formatAbiParameter } from './formatAbiParameter.js'
+
+test('default', () => {
+  const result = formatAbiParameter({ type: 'address', name: 'foo' })
+  expect(result).toEqual('address foo')
+  expectTypeOf(result).toEqualTypeOf<'address foo'>()
+})
+
+test('tuple', () => {
+  const result = formatAbiParameter({
+    type: 'tuple',
+    components: [
+      { type: 'string', name: 'bar' },
+      { type: 'string', name: 'baz' },
+    ],
+    name: 'foo',
+  })
+  expect(result).toMatchInlineSnapshot('"(string bar, string baz) foo"')
+  expectTypeOf(result).toEqualTypeOf<'(string bar, string baz) foo'>()
+})
+
+test('tuple[][]', () => {
+  const result = formatAbiParameter({
+    type: 'tuple[123][]',
+    components: [
+      { type: 'string', name: 'bar' },
+      { type: 'string', name: 'baz' },
+    ],
+    name: 'foo',
+  })
+  expect(result).toMatchInlineSnapshot('"(string bar, string baz)[123][] foo"')
+  expectTypeOf(result).toEqualTypeOf<'(string bar, string baz)[123][] foo'>()
+})
+
+test.each([
+  {
+    abiParameter: { type: 'string' },
+    expected: 'string',
+  },
+  {
+    abiParameter: { name: 'foo', type: 'string' },
+    expected: 'string foo',
+  },
+  {
+    abiParameter: { name: 'foo', type: 'string', indexed: true },
+    expected: 'string indexed foo',
+  },
+  {
+    abiParameter: { type: 'tuple', components: [{ type: 'string' }] },
+    expected: '(string)',
+  },
+  {
+    abiParameter: {
+      type: 'tuple',
+      components: [{ name: 'foo', type: 'string' }],
+    },
+    expected: '(string foo)',
+  },
+  {
+    abiParameter: {
+      type: 'tuple',
+      name: 'foo',
+      components: [{ name: 'bar', type: 'string' }],
+    },
+    expected: '(string bar) foo',
+  },
+  {
+    abiParameter: {
+      type: 'tuple',
+      name: 'foo',
+      components: [
+        { name: 'bar', type: 'string' },
+        { name: 'baz', type: 'string' },
+      ],
+    },
+    expected: '(string bar, string baz) foo',
+  },
+  {
+    abiParameter: { type: 'string', indexed: false },
+    expected: 'string',
+  },
+  {
+    abiParameter: { type: 'string', indexed: true },
+    expected: 'string indexed',
+  },
+  {
+    abiParameter: { type: 'string', indexed: true, name: 'foo' },
+    expected: 'string indexed foo',
+  },
+])('formatAbiParameter($abiParameter)', ({ abiParameter, expected }) => {
+  expect(formatAbiParameter(abiParameter)).toEqual(expected)
+})
+
+test('nested tuple', () => {
+  const result = formatAbiParameter({
+    components: [
+      {
+        components: [
+          {
+            components: [
+              {
+                components: [
+                  {
+                    name: 'baz',
+                    type: 'string',
+                  },
+                ],
+                name: 'bar',
+                type: 'tuple',
+              },
+            ],
+            name: 'foo',
+            type: 'tuple[1]',
+          },
+        ],
+        name: 'boo',
+        type: 'tuple',
+      },
+    ],
+    type: 'tuple',
+  })
+  expect(result).toMatchInlineSnapshot('"((((string baz) bar)[1] foo) boo)"')
+  assertType<'((((string baz) bar)[1] foo) boo)'>(result)
+})

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

@@ -0,0 +1,86 @@
+import type { AbiEventParameter, AbiParameter } from 'abitype'
+import { execTyped } from './regex.js'
+import type { IsNarrowable, Join } from './types.js'
+import type { AssertName } from './types/signatures.js'
+
+/**
+ * Formats `AbiParameter` to human-readable ABI parameter.
+ *
+ * @param abiParameter - ABI parameter
+ * @returns Human-readable ABI parameter
+ */
+export type FormatAbiParameter<
+  abiParameter extends AbiParameter | AbiEventParameter,
+> = abiParameter extends {
+  name?: infer name extends string
+  type: `tuple${infer array}`
+  components: infer components extends readonly AbiParameter[]
+  indexed?: infer indexed extends boolean
+}
+  ? FormatAbiParameter<
+      {
+        type: `(${Join<
+          {
+            [key in keyof components]: FormatAbiParameter<
+              {
+                type: components[key]['type']
+              } & (IsNarrowable<components[key]['name'], string> extends true
+                ? { name: components[key]['name'] }
+                : unknown) &
+                (components[key] extends { components: readonly AbiParameter[] }
+                  ? { components: components[key]['components'] }
+                  : unknown)
+            >
+          },
+          ', '
+        >})${array}`
+      } & (IsNarrowable<name, string> extends true ? { name: name } : unknown) &
+        (IsNarrowable<indexed, boolean> extends true
+          ? { indexed: indexed }
+          : unknown)
+    >
+  : `${abiParameter['type']}${abiParameter extends { indexed: true }
+      ? ' indexed'
+      : ''}${abiParameter['name'] extends infer name extends string
+      ? name extends ''
+        ? ''
+        : ` ${AssertName<name>}`
+      : ''}`
+
+// https://regexr.com/7f7rv
+const tupleRegex = /^tuple(?<array>(\[(\d*)\])*)$/
+
+/**
+ * Formats `AbiParameter` to human-readable ABI parameter.
+ *
+ * @param abiParameter - ABI parameter
+ * @returns Human-readable ABI parameter
+ */
+export function formatAbiParameter<
+  const abiParameter extends AbiParameter | AbiEventParameter,
+>(abiParameter: abiParameter): FormatAbiParameter<abiParameter> {
+  type Result = FormatAbiParameter<abiParameter>
+
+  let type = abiParameter.type
+  if (tupleRegex.test(abiParameter.type) && 'components' in abiParameter) {
+    type = '('
+    const length = abiParameter.components.length as number
+    for (let i = 0; i < length; i++) {
+      const component = abiParameter.components[i]!
+      type += formatAbiParameter(component)
+      if (i < length - 1) type += ', '
+    }
+    const result = execTyped<{ array?: string }>(tupleRegex, abiParameter.type)
+    type += `)${result?.array || ''}`
+    return formatAbiParameter({
+      ...abiParameter,
+      type,
+    }) as Result
+  }
+  // Add `indexed` to type if in `abiParameter`
+  if ('indexed' in abiParameter && abiParameter.indexed)
+    type = `${type} indexed`
+  // Return human-readable ABI parameter
+  if (abiParameter.name) return `${type} ${abiParameter.name}` as Result
+  return type as Result
+}