ox 1.0.0-beta.8 → 1.0.0

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

@@ -0,0 +1,183 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type { Abi } from 'abitype'
+import type { ParseAbiItem } from './parseAbiItem.js'
+import { parseAbiItem } from './parseAbiItem.js'
+
+test('ParseAbiItem', () => {
+  expectTypeOf<ParseAbiItem<''>>().toEqualTypeOf<never>()
+  expectTypeOf<ParseAbiItem<['']>>().toEqualTypeOf<never>()
+  expectTypeOf<
+    ParseAbiItem<['struct Foo { string name; }']>
+  >().toEqualTypeOf<never>()
+
+  // string
+  expectTypeOf<ParseAbiItem<'function foo()'>>().toEqualTypeOf<{
+    readonly name: 'foo'
+    readonly type: 'function'
+    readonly stateMutability: 'nonpayable'
+    readonly inputs: readonly []
+    readonly outputs: readonly []
+  }>()
+
+  // Array
+  expectTypeOf<
+    ParseAbiItem<['function bar(Foo, bytes32)', 'struct Foo { string name; }']>
+  >().toEqualTypeOf<{
+    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 []
+  }>()
+
+  expectTypeOf<
+    ParseAbiItem<
+      [
+        'event Transfer(address indexed from, address indexed to, uint256 amount)',
+      ]
+    >
+  >().toEqualTypeOf<{
+    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'
+      },
+    ]
+  }>()
+
+  const abiItem = ['function bar(Foo, bytes32)', 'struct Foo { string name; }']
+  expectTypeOf<ParseAbiItem<typeof abiItem>>().toEqualTypeOf<Abi[number]>()
+
+  expectTypeOf<ParseAbiItem<['function foo ()']>>().toEqualTypeOf<never>()
+})
+
+test('parseAbiItem', () => {
+  // @ts-expect-error empty array not allowed
+  expectTypeOf(parseAbiItem([])).toEqualTypeOf<never>()
+  expectTypeOf(
+    parseAbiItem(['struct Foo { string name; }']),
+  ).toEqualTypeOf<never>()
+
+  // string
+  expectTypeOf(parseAbiItem('function foo()')).toEqualTypeOf<{
+    readonly name: 'foo'
+    readonly type: 'function'
+    readonly stateMutability: 'nonpayable'
+    readonly inputs: readonly []
+    readonly outputs: readonly []
+  }>()
+  expectTypeOf(parseAbiItem('function foo((string), address)')).toEqualTypeOf<{
+    readonly name: 'foo'
+    readonly type: 'function'
+    readonly stateMutability: 'nonpayable'
+    readonly inputs: readonly [
+      {
+        readonly type: 'tuple'
+        readonly components: readonly [
+          {
+            readonly type: 'string'
+          },
+        ]
+      },
+      {
+        readonly type: 'address'
+      },
+    ]
+    readonly outputs: readonly []
+  }>()
+
+  expectTypeOf(
+    // @ts-expect-error invalid signature
+    parseAbiItem(''),
+  ).toEqualTypeOf<never>()
+
+  // Array
+  const res2 = parseAbiItem([
+    'function bar(Foo, bytes32)',
+    'struct Foo { string name; }',
+  ])
+  expectTypeOf<typeof res2>().toEqualTypeOf<{
+    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 []
+  }>()
+
+  const abi2 = [
+    'function foo()',
+    'function bar(Foo, bytes32)',
+    'struct Foo { string name; }',
+  ]
+  expectTypeOf(parseAbiItem(abi2)).toEqualTypeOf<Abi[number]>()
+
+  // @ts-expect-error invalid signature
+  expectTypeOf(parseAbiItem(['function foo ()'])).toEqualTypeOf<never>()
+
+  const signature: string = 'function foo()'
+  expectTypeOf(parseAbiItem(signature)).toEqualTypeOf<Abi[number]>()
+
+  // fallback
+  expectTypeOf(parseAbiItem('fallback() external')).toEqualTypeOf<{
+    readonly type: 'fallback'
+    readonly stateMutability: 'nonpayable'
+  }>()
+  expectTypeOf(parseAbiItem('fallback() external payable')).toEqualTypeOf<{
+    readonly type: 'fallback'
+    readonly stateMutability: 'payable'
+  }>()
+
+  // receive
+  expectTypeOf(parseAbiItem('receive() external payable')).toEqualTypeOf<{
+    readonly type: 'receive'
+    readonly stateMutability: 'payable'
+  }>()
+})
+
+test('nested tuples', () => {
+  const formattedAbiItem =
+    'function stepChanges((uint256 characterID, uint64 newPosition, uint24 xp, uint24 epoch, uint8 hp, (int32 x, int32 y, uint8 hp, uint8 kind)[5] monsters, (uint8 monsterIndexPlus1, uint8 attackCardsUsed1, uint8 attackCardsUsed2, uint8 defenseCardsUsed1, uint8 defenseCardsUsed2) battle) stateChanges, uint256 action, bool revetOnInvalidMoves) pure returns ((uint256 characterID, uint64 newPosition, uint24 xp, uint24 epoch, uint8 hp, (int32 x, int32 y, uint8 hp, uint8 kind)[5] monsters, (uint8 monsterIndexPlus1, uint8 attackCardsUsed1, uint8 attackCardsUsed2, uint8 defenseCardsUsed1, uint8 defenseCardsUsed2) battle))'
+
+  const abiItem = parseAbiItem(formattedAbiItem)
+  expectTypeOf(abiItem.stateMutability).toEqualTypeOf<'pure'>()
+  expectTypeOf(abiItem.inputs.length).toEqualTypeOf<3>()
+})

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

@@ -0,0 +1,264 @@
+import { expect, test } from 'vp/test'
+
+import { parseAbiItem } from './parseAbiItem.js'
+
+test('parseAbiItem', () => {
+  // @ts-expect-error invalid signature type
+  expect(() => parseAbiItem('')).toThrowErrorMatchingInlineSnapshot(
+    `[Abi.UnknownSignatureError: Unknown signature.]`,
+  )
+  // @ts-expect-error invalid signature type
+  expect(() => parseAbiItem([])).toThrowErrorMatchingInlineSnapshot(
+    `
+    [AbiItem.InvalidAbiItemError: Failed to parse ABI item.
+
+    Details: parseAbiItem([])
+    See: https://oxlib.sh/api/AbiItem/from]
+  `,
+  )
+  expect(() =>
+    parseAbiItem(['struct Foo { string name; }']),
+  ).toThrowErrorMatchingInlineSnapshot(
+    `
+    [AbiItem.InvalidAbiItemError: Failed to parse ABI item.
+
+    Details: parseAbiItem([
+      "struct Foo { string name; }"
+    ])
+    See: https://oxlib.sh/api/AbiItem/from]
+  `,
+  )
+})
+
+test.each([
+  {
+    signature: ['function foo(string)'],
+    expected: {
+      type: 'function',
+      name: 'foo',
+      inputs: [{ type: 'string' }],
+      outputs: [],
+      stateMutability: 'nonpayable',
+    },
+  },
+  {
+    signature: [
+      'event Foo(address indexed from, address indexed to, uint256 amount)',
+    ],
+    expected: {
+      type: 'event',
+      name: 'Foo',
+      inputs: [
+        { type: 'address', name: 'from', indexed: true },
+        { type: 'address', name: 'to', indexed: true },
+        { type: 'uint256', name: 'amount' },
+      ],
+    },
+  },
+  {
+    signature: ['fallback() external'],
+    expected: {
+      type: 'fallback',
+      stateMutability: 'nonpayable',
+    },
+  },
+  {
+    signature: ['fallback() external payable'],
+    expected: {
+      type: 'fallback',
+      stateMutability: 'payable',
+    },
+  },
+])('parseAbiItem($signature)', ({ signature, expected }) => {
+  expect(parseAbiItem(signature)).toEqual(expected)
+})
+
+test.each([
+  {
+    signature: ['struct Foo { string bar; }', 'function foo(Foo)'],
+    expected: {
+      type: 'function',
+      name: 'foo',
+      inputs: [
+        { type: 'tuple', components: [{ name: 'bar', type: 'string' }] },
+      ],
+      outputs: [],
+      stateMutability: 'nonpayable',
+    },
+  },
+])('parseAbiItem($signature)', ({ signature, expected }) => {
+  expect(parseAbiItem(signature)).toEqual(expected)
+})
+
+test('nested tuples', () => {
+  const formattedAbiItem =
+    'function stepChanges((uint256 characterID, uint64 newPosition, uint24 xp, uint24 epoch, uint8 hp, (int32 x, int32 y, uint8 hp, uint8 kind)[5] monsters, (uint8 monsterIndexPlus1, uint8 attackCardsUsed1, uint8 attackCardsUsed2, uint8 defenseCardsUsed1, uint8 defenseCardsUsed2) battle) stateChanges, uint256 action, bool revetOnInvalidMoves) pure returns ((uint256 characterID, uint64 newPosition, uint24 xp, uint24 epoch, uint8 hp, (int32 x, int32 y, uint8 hp, uint8 kind)[5] monsters, (uint8 monsterIndexPlus1, uint8 attackCardsUsed1, uint8 attackCardsUsed2, uint8 defenseCardsUsed1, uint8 defenseCardsUsed2) battle))'
+  expect(parseAbiItem(formattedAbiItem)).toMatchInlineSnapshot(
+    `
+    {
+      "inputs": [
+        {
+          "components": [
+            {
+              "name": "characterID",
+              "type": "uint256",
+            },
+            {
+              "name": "newPosition",
+              "type": "uint64",
+            },
+            {
+              "name": "xp",
+              "type": "uint24",
+            },
+            {
+              "name": "epoch",
+              "type": "uint24",
+            },
+            {
+              "name": "hp",
+              "type": "uint8",
+            },
+            {
+              "components": [
+                {
+                  "name": "x",
+                  "type": "int32",
+                },
+                {
+                  "name": "y",
+                  "type": "int32",
+                },
+                {
+                  "name": "hp",
+                  "type": "uint8",
+                },
+                {
+                  "name": "kind",
+                  "type": "uint8",
+                },
+              ],
+              "name": "monsters",
+              "type": "tuple[5]",
+            },
+            {
+              "components": [
+                {
+                  "name": "monsterIndexPlus1",
+                  "type": "uint8",
+                },
+                {
+                  "name": "attackCardsUsed1",
+                  "type": "uint8",
+                },
+                {
+                  "name": "attackCardsUsed2",
+                  "type": "uint8",
+                },
+                {
+                  "name": "defenseCardsUsed1",
+                  "type": "uint8",
+                },
+                {
+                  "name": "defenseCardsUsed2",
+                  "type": "uint8",
+                },
+              ],
+              "name": "battle",
+              "type": "tuple",
+            },
+          ],
+          "name": "stateChanges",
+          "type": "tuple",
+        },
+        {
+          "name": "action",
+          "type": "uint256",
+        },
+        {
+          "name": "revetOnInvalidMoves",
+          "type": "bool",
+        },
+      ],
+      "name": "stepChanges",
+      "outputs": [
+        {
+          "components": [
+            {
+              "name": "characterID",
+              "type": "uint256",
+            },
+            {
+              "name": "newPosition",
+              "type": "uint64",
+            },
+            {
+              "name": "xp",
+              "type": "uint24",
+            },
+            {
+              "name": "epoch",
+              "type": "uint24",
+            },
+            {
+              "name": "hp",
+              "type": "uint8",
+            },
+            {
+              "components": [
+                {
+                  "name": "x",
+                  "type": "int32",
+                },
+                {
+                  "name": "y",
+                  "type": "int32",
+                },
+                {
+                  "name": "hp",
+                  "type": "uint8",
+                },
+                {
+                  "name": "kind",
+                  "type": "uint8",
+                },
+              ],
+              "name": "monsters",
+              "type": "tuple[5]",
+            },
+            {
+              "components": [
+                {
+                  "name": "monsterIndexPlus1",
+                  "type": "uint8",
+                },
+                {
+                  "name": "attackCardsUsed1",
+                  "type": "uint8",
+                },
+                {
+                  "name": "attackCardsUsed2",
+                  "type": "uint8",
+                },
+                {
+                  "name": "defenseCardsUsed1",
+                  "type": "uint8",
+                },
+                {
+                  "name": "defenseCardsUsed2",
+                  "type": "uint8",
+                },
+              ],
+              "name": "battle",
+              "type": "tuple",
+            },
+          ],
+          "type": "tuple",
+        },
+      ],
+      "stateMutability": "pure",
+      "type": "function",
+    }
+  `,
+  )
+})

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

@@ -0,0 +1,91 @@
+import type { Abi } from 'abitype'
+import type { Narrow } from 'abitype'
+import type { Error, Filter } from './types.js'
+import { InvalidAbiItemError } from './errors.js'
+import { isStructSignature } from './runtime/signatures.js'
+import { parseStructs } from './runtime/structs.js'
+import { parseSignature } from './runtime/utils.js'
+import type { Signature, Signatures } from './types/signatures.js'
+import type { ParseStructs } from './types/structs.js'
+import type { ParseSignature } from './types/utils.js'
+
+/**
+ * Parses human-readable ABI item (e.g. error, event, function) into `Abi` item.
+ *
+ * @param signature - Human-readable ABI item
+ * @returns Parsed `Abi` item.
+ */
+export type ParseAbiItem<
+  signature extends string | readonly string[] | readonly unknown[],
+> =
+  | (signature extends string
+      ? string extends signature
+        ? Abi[number]
+        : signature extends Signature<signature> // Validate signature
+          ? ParseSignature<signature>
+          : never
+      : never)
+  | (signature extends readonly string[]
+      ? string[] extends signature
+        ? Abi[number] // Return generic Abi item since type was no inferrable
+        : signature extends Signatures<signature> // Validate signature
+          ? ParseStructs<signature> extends infer structs
+            ? {
+                [key in keyof signature]: ParseSignature<
+                  signature[key] extends string ? signature[key] : never,
+                  structs
+                >
+              } extends infer mapped extends readonly unknown[]
+              ? // Filter out `never` since those are structs
+                Filter<mapped, never>[0] extends infer result
+                ? result extends undefined // convert `undefined` to `never` (e.g. `ParseAbiItem<['struct Foo { string name; }']>`)
+                  ? never
+                  : result
+                : never
+              : never
+            : never
+          : never
+      : never)
+
+/**
+ * Parses human-readable ABI item (e.g. error, event, function) into `Abi` item.
+ *
+ * @param signature - Human-readable ABI item
+ * @returns Parsed `Abi` item.
+ */
+export function parseAbiItem<
+  signature extends string | readonly string[] | readonly unknown[],
+>(
+  signature: Narrow<signature> &
+    (
+      | (signature extends string
+          ? string extends signature
+            ? unknown
+            : Signature<signature>
+          : never)
+      | (signature extends readonly string[]
+          ? signature extends readonly [] // empty array
+            ? Error<'At least one signature required.'>
+            : string[] extends signature
+              ? unknown
+              : Signatures<signature>
+          : never)
+    ),
+): ParseAbiItem<signature> {
+  let abiItem: ParseAbiItem<signature> | undefined
+  if (typeof signature === 'string')
+    abiItem = parseSignature(signature) as ParseAbiItem<signature>
+  else {
+    const structs = parseStructs(signature as readonly string[])
+    const length = signature.length as number
+    for (let i = 0; i < length; i++) {
+      const signature_ = (signature as readonly string[])[i]!
+      if (isStructSignature(signature_)) continue
+      abiItem = parseSignature(signature_, structs) as ParseAbiItem<signature>
+      break
+    }
+  }
+
+  if (!abiItem) throw new InvalidAbiItemError({ signature })
+  return abiItem as ParseAbiItem<signature>
+}

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

@@ -0,0 +1,68 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type { AbiParameter } from 'abitype'
+import type { ParseAbiParameter } from './parseAbiParameter.js'
+import { parseAbiParameter } from './parseAbiParameter.js'
+
+test('ParseAbiParameter', () => {
+  expectTypeOf<ParseAbiParameter<''>>().toEqualTypeOf<never>()
+  expectTypeOf<ParseAbiParameter<[]>>().toEqualTypeOf<never>()
+  expectTypeOf<
+    ParseAbiParameter<['struct Foo { string name; }']>
+  >().toEqualTypeOf<never>()
+
+  // string
+  expectTypeOf<ParseAbiParameter<'address from'>>().toEqualTypeOf<{
+    readonly type: 'address'
+    readonly name: 'from'
+  }>()
+  expectTypeOf<ParseAbiParameter<'address indexed from'>>().toEqualTypeOf<{
+    readonly type: 'address'
+    readonly name: 'from'
+    readonly indexed: true
+  }>()
+  expectTypeOf<ParseAbiParameter<'address calldata foo'>>().toEqualTypeOf<{
+    readonly type: 'address'
+    readonly name: 'foo'
+  }>()
+
+  // Array
+  expectTypeOf<
+    ParseAbiParameter<['Foo', 'struct Foo { string name; }']>
+  >().toEqualTypeOf<{
+    readonly type: 'tuple'
+    readonly components: readonly [
+      {
+        readonly name: 'name'
+        readonly type: 'string'
+      },
+    ]
+  }>()
+
+  expectTypeOf<ParseAbiParameter<'(string bar) foo'>>().toEqualTypeOf<{
+    readonly type: 'tuple'
+    readonly components: readonly [
+      {
+        readonly type: 'string'
+        readonly name: 'bar'
+      },
+    ]
+    readonly name: 'foo'
+  }>()
+})
+
+test('parseAbiParameter', () => {
+  // @ts-expect-error empty array not allowed
+  expectTypeOf(parseAbiParameter([])).toEqualTypeOf<never>()
+  expectTypeOf(
+    parseAbiParameter(['struct Foo { string name; }']),
+  ).toEqualTypeOf<never>()
+
+  expectTypeOf(parseAbiParameter('(string)')).toEqualTypeOf<{
+    readonly type: 'tuple'
+    readonly components: readonly [{ readonly type: 'string' }]
+  }>()
+
+  const param: string = 'address'
+  expectTypeOf(parseAbiParameter(param)).toEqualTypeOf<AbiParameter>()
+})