ox 1.0.0-beta.8 → 1.0.0

package/src/core/internal/human-readable/types/signatures.ts

@@ -0,0 +1,369 @@
+import type { AbiStateMutability } from 'abitype'
+import type { Error } from '../types.js'
+
+export type ErrorSignature<
+  name extends string = string,
+  parameters extends string = string,
+> = `error ${name}(${parameters})`
+export type IsErrorSignature<signature extends string> =
+  signature extends ErrorSignature<infer name> ? IsName<name> : false
+export type EventSignature<
+  name extends string = string,
+  parameters extends string = string,
+> = `event ${name}(${parameters})`
+export type IsEventSignature<signature extends string> =
+  signature extends EventSignature<infer name> ? IsName<name> : false
+
+export type FunctionSignature<
+  name extends string = string,
+  tail extends string = string,
+> = `function ${name}(${tail}`
+export type IsFunctionSignature<signature> =
+  signature extends FunctionSignature<infer name>
+    ? IsName<name> extends true
+      ? signature extends ValidFunctionSignatures
+        ? true
+        : // Check that `Parameters` is not absorbing other types (e.g. `returns`)
+          signature extends `function ${string}(${infer parameters})`
+          ? parameters extends InvalidFunctionParameters
+            ? false
+            : true
+          : false
+      : false
+    : false
+export type Scope = 'public' | 'external' // `internal` or `private` functions wouldn't make it to ABI so can ignore
+type Returns = `returns (${string})` | `returns(${string})`
+// Almost all valid function signatures, except `function ${string}(${infer parameters})` since `parameters` can absorb returns
+type ValidFunctionSignatures =
+  | `function ${string}()`
+  // basic
+  | `function ${string}() ${Returns}`
+  | `function ${string}() ${AbiStateMutability}`
+  | `function ${string}() ${Scope}`
+  // combinations
+  | `function ${string}() ${AbiStateMutability} ${Returns}`
+  | `function ${string}() ${Scope} ${Returns}`
+  | `function ${string}() ${Scope} ${AbiStateMutability}`
+  | `function ${string}() ${Scope} ${AbiStateMutability} ${Returns}`
+  // Parameters
+  | `function ${string}(${string}) ${Returns}`
+  | `function ${string}(${string}) ${AbiStateMutability}`
+  | `function ${string}(${string}) ${Scope}`
+  | `function ${string}(${string}) ${AbiStateMutability} ${Returns}`
+  | `function ${string}(${string}) ${Scope} ${Returns}`
+  | `function ${string}(${string}) ${Scope} ${AbiStateMutability}`
+  | `function ${string}(${string}) ${Scope} ${AbiStateMutability} ${Returns}`
+
+export type StructSignature<
+  name extends string = string,
+  properties extends string = string,
+> = `struct ${name} {${properties}}`
+export type IsStructSignature<signature extends string> =
+  signature extends StructSignature<infer name> ? IsName<name> : false
+
+type ConstructorSignature<tail extends string = string> = `constructor(${tail}`
+export type IsConstructorSignature<signature> =
+  signature extends ConstructorSignature
+    ? signature extends ValidConstructorSignatures
+      ? true
+      : false
+    : false
+type ValidConstructorSignatures =
+  | `constructor(${string})`
+  | `constructor(${string}) payable`
+
+export type FallbackSignature<
+  abiStateMutability extends '' | ' payable' = '' | ' payable',
+> = `fallback() external${abiStateMutability}`
+export type IsFallbackSignature<signature extends string> = signature extends
+  | FallbackSignature<''>
+  | FallbackSignature<' payable'>
+  ? true
+  : false
+
+export type ReceiveSignature = 'receive() external payable'
+
+// TODO: Maybe use this for signature validation one day
+// https://twitter.com/devanshj__/status/1610423724708343808
+export type IsSignature<type extends string> =
+  | (IsErrorSignature<type> extends true ? true : never)
+  | (IsEventSignature<type> extends true ? true : never)
+  | (IsFunctionSignature<type> extends true ? true : never)
+  | (IsStructSignature<type> extends true ? true : never)
+  | (IsConstructorSignature<type> extends true ? true : never)
+  | (IsFallbackSignature<type> extends true ? true : never)
+  | (type extends ReceiveSignature ? true : never) extends infer condition
+  ? [condition] extends [never]
+    ? false
+    : true
+  : false
+
+export type Signature<
+  string1 extends string,
+  string2 extends string | unknown = unknown,
+> =
+  IsSignature<string1> extends true
+    ? string1
+    : string extends string1 // if exactly `string` (not narrowed), then pass through as valid
+      ? string1
+      : Error<`Signature "${string1}" is invalid${string2 extends string
+          ? ` at position ${string2}`
+          : ''}.`>
+
+export type Signatures<signatures extends readonly string[]> = {
+  [key in keyof signatures]: Signature<signatures[key], key>
+}
+
+export type Modifier = 'calldata' | 'indexed' | 'memory' | 'payable' | 'storage'
+export type FunctionModifier = Extract<
+  Modifier,
+  'calldata' | 'memory' | 'payable' | 'storage'
+>
+export type EventModifier = Extract<Modifier, 'indexed'>
+
+export type IsName<name extends string> = name extends ''
+  ? false
+  : ValidateName<name> extends name
+    ? true
+    : false
+
+export type AssertName<name extends string> =
+  ValidateName<name> extends infer invalidName extends string[]
+    ? `[${invalidName[number]}]`
+    : name
+
+export type ValidateName<
+  name extends string,
+  checkCharacters extends boolean = false,
+> = name extends `${string}${' '}${string}`
+  ? Error<`Identifier "${name}" cannot contain whitespace.`>
+  : IsSolidityKeyword<name> extends true
+    ? Error<`"${name}" is a protected Solidity keyword.`>
+    : name extends `${number}`
+      ? Error<`Identifier "${name}" cannot be a number string.`>
+      : name extends `${number}${string}`
+        ? Error<`Identifier "${name}" cannot start with a number.`>
+        : checkCharacters extends true
+          ? IsValidCharacter<name> extends true
+            ? name
+            : Error<`"${name}" contains invalid character.`>
+          : name
+
+export type IsSolidityKeyword<type extends string> =
+  type extends SolidityKeywords ? true : false
+
+export type SolidityKeywords =
+  | 'after'
+  | 'alias'
+  | 'anonymous'
+  | 'apply'
+  | 'auto'
+  | 'byte'
+  | 'calldata'
+  | 'case'
+  | 'catch'
+  | 'constant'
+  | 'copyof'
+  | 'default'
+  | 'defined'
+  | 'error'
+  | 'event'
+  | 'external'
+  | 'false'
+  | 'final'
+  | 'function'
+  | 'immutable'
+  | 'implements'
+  | 'in'
+  | 'indexed'
+  | 'inline'
+  | 'internal'
+  | 'let'
+  | 'mapping'
+  | 'match'
+  | 'memory'
+  | 'mutable'
+  | 'null'
+  | 'of'
+  | 'override'
+  | 'partial'
+  | 'private'
+  | 'promise'
+  | 'public'
+  | 'pure'
+  | 'reference'
+  | 'relocatable'
+  | 'return'
+  | 'returns'
+  | 'sizeof'
+  | 'static'
+  | 'storage'
+  | 'struct'
+  | 'super'
+  | 'supports'
+  | 'switch'
+  | 'this'
+  | 'true'
+  | 'try'
+  | 'typedef'
+  | 'typeof'
+  | 'var'
+  | 'view'
+  | 'virtual'
+  | `address${`[${string}]` | ''}`
+  | `bool${`[${string}]` | ''}`
+  | `string${`[${string}]` | ''}`
+  | `tuple${`[${string}]` | ''}`
+  | `bytes${number | ''}${`[${string}]` | ''}`
+  | `${'u' | ''}int${number | ''}${`[${string}]` | ''}`
+
+export type IsValidCharacter<character extends string> =
+  character extends `${ValidCharacters}${infer tail}`
+    ? tail extends ''
+      ? true
+      : IsValidCharacter<tail>
+    : false
+
+// biome-ignore format: no formatting
+type ValidCharacters =
+  // uppercase letters
+  | 'A'
+  | 'B'
+  | 'C'
+  | 'D'
+  | 'E'
+  | 'F'
+  | 'G'
+  | 'H'
+  | 'I'
+  | 'J'
+  | 'K'
+  | 'L'
+  | 'M'
+  | 'N'
+  | 'O'
+  | 'P'
+  | 'Q'
+  | 'R'
+  | 'S'
+  | 'T'
+  | 'U'
+  | 'V'
+  | 'W'
+  | 'X'
+  | 'Y'
+  | 'Z'
+  // lowercase letters
+  | 'a'
+  | 'b'
+  | 'c'
+  | 'd'
+  | 'e'
+  | 'f'
+  | 'g'
+  | 'h'
+  | 'i'
+  | 'j'
+  | 'k'
+  | 'l'
+  | 'm'
+  | 'n'
+  | 'o'
+  | 'p'
+  | 'q'
+  | 'r'
+  | 's'
+  | 't'
+  | 'u'
+  | 'v'
+  | 'w'
+  | 'x'
+  | 'y'
+  | 'z'
+  // numbers
+  | '0'
+  | '1'
+  | '2'
+  | '3'
+  | '4'
+  | '5'
+  | '6'
+  | '7'
+  | '8'
+  | '9'
+  // special characters
+  | '_'
+  | '$'
+
+// Template string inference can absorb `returns`:
+// type Result = `function foo(string) return s (uint256)` extends `function ${string}(${infer Parameters})` ? Parameters : never
+// //   ^? type Result = "string ) return s (uint256"
+// So we need to validate against `returns` keyword with all combinations of whitespace
+type InvalidFunctionParameters =
+  | `${string}${MangledReturns} (${string}`
+  | `${string}) ${MangledReturns}${string}`
+  | `${string})${string}${MangledReturns}${string}(${string}`
+// r_e_t_u_r_n_s
+type MangledReturns =
+  // Single
+  | `r${string}eturns`
+  | `re${string}turns`
+  | `ret${string}urns`
+  | `retu${string}rns`
+  | `retur${string}ns`
+  | `return${string}s`
+  // Double
+  // `r_e*`
+  | `r${string}e${string}turns`
+  | `r${string}et${string}urns`
+  | `r${string}etu${string}rns`
+  | `r${string}etur${string}ns`
+  | `r${string}eturn${string}s`
+  // `re_t*`
+  | `re${string}t${string}urns`
+  | `re${string}tu${string}rns`
+  | `re${string}tur${string}ns`
+  | `re${string}turn${string}s`
+  // `ret_u*`
+  | `ret${string}u${string}rns`
+  | `ret${string}ur${string}ns`
+  | `ret${string}urn${string}s`
+  // `retu_r*`
+  | `retu${string}r${string}ns`
+  | `retu${string}rn${string}s`
+  // `retur_n*`
+  | `retur${string}n${string}s`
+  // Triple
+  // `r_e_t*`
+  | `r${string}e${string}t${string}urns`
+  | `r${string}e${string}tu${string}rns`
+  | `r${string}e${string}tur${string}ns`
+  | `r${string}e${string}turn${string}s`
+  // `re_t_u*`
+  | `re${string}t${string}u${string}rns`
+  | `re${string}t${string}ur${string}ns`
+  | `re${string}t${string}urn${string}s`
+  // `ret_u_r*`
+  | `ret${string}u${string}r${string}ns`
+  | `ret${string}u${string}rn${string}s`
+  // `retu_r_n*`
+  | `retu${string}r${string}n${string}s`
+  // Quadruple
+  // `r_e_t_u*`
+  | `r${string}e${string}t${string}u${string}rns`
+  | `r${string}e${string}t${string}ur${string}ns`
+  | `r${string}e${string}t${string}urn${string}s`
+  // `re_t_u_r*`
+  | `re${string}t${string}u${string}r${string}ns`
+  | `re${string}t${string}u${string}rn${string}s`
+  // `ret_u_r_n*`
+  | `ret${string}u${string}r${string}n${string}s`
+  // Quintuple
+  // `r_e_t_u_r*`
+  | `r${string}e${string}t${string}u${string}r${string}ns`
+  | `r${string}e${string}t${string}u${string}rn${string}s`
+  // `re_t_u_r_n*`
+  | `re${string}t${string}u${string}r${string}n${string}s`
+  // Sextuple
+  // `r_e_t_u_r_n_s`
+  | `r${string}e${string}t${string}u${string}r${string}n${string}s`

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

@@ -0,0 +1,221 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type {
+  ParseStruct,
+  ParseStructProperties,
+  ParseStructs,
+  ResolveStructs,
+  StructLookup,
+} from './structs.js'
+
+test('ParseStructs', () => {
+  type Result = ParseStructs<
+    [
+      'struct Person { Name name; }',
+      'struct Name { Foo foo; }',
+      'struct Foo { string bar; }',
+      'function addPerson(Person person)',
+    ]
+  >
+  expectTypeOf<Result>().toEqualTypeOf<{
+    Person: readonly [
+      {
+        readonly name: 'name'
+        readonly type: 'tuple'
+        readonly components: readonly [
+          {
+            readonly name: 'foo'
+            readonly type: 'tuple'
+            readonly components: readonly [
+              {
+                readonly type: 'string'
+                readonly name: 'bar'
+              },
+            ]
+          },
+        ]
+      },
+    ]
+    Foo: readonly [{ readonly type: 'string'; readonly name: 'bar' }]
+    Name: readonly [
+      {
+        readonly type: 'tuple'
+        readonly name: 'foo'
+        readonly components: readonly [
+          { readonly type: 'string'; readonly name: 'bar' },
+        ]
+      },
+    ]
+  }>()
+
+  expectTypeOf<
+    ParseStructs<['struct Foo { Bar bar; }', 'struct Bar { Foo foo; }']>
+  >().toEqualTypeOf<{
+    Foo: readonly [
+      {
+        readonly name: 'bar'
+        readonly type: 'tuple'
+        readonly components: readonly [
+          {
+            readonly name: 'foo'
+            readonly type: 'tuple'
+            readonly components: readonly [
+              [
+                'Error: Circular reference detected. Struct "Bar" is a circular reference.',
+              ],
+            ]
+          },
+        ]
+      },
+    ]
+    Bar: readonly [
+      {
+        readonly name: 'foo'
+        readonly type: 'tuple'
+        readonly components: readonly [
+          {
+            readonly name: 'bar'
+            readonly type: 'tuple'
+            readonly components: readonly [
+              [
+                'Error: Circular reference detected. Struct "Foo" is a circular reference.',
+              ],
+            ]
+          },
+        ]
+      },
+    ]
+  }>()
+
+  expectTypeOf<ParseStructs<['struct Foo { Foo foo; }']>>().toEqualTypeOf<{
+    Foo: readonly [
+      {
+        readonly name: 'foo'
+        readonly type: 'tuple'
+        readonly components: readonly [
+          [
+            'Error: Circular reference detected. Struct "Foo" is a circular reference.',
+          ],
+        ]
+      },
+    ]
+  }>()
+
+  expectTypeOf<
+    ParseStructs<['struct Person { Name name;']>
+  >().toEqualTypeOf<{}>()
+
+  expectTypeOf<ParseStructs<[]>>().toEqualTypeOf<{}>()
+  expectTypeOf<
+    ParseStructs<['function addPerson(Person person)']>
+  >().toEqualTypeOf<{}>()
+})
+
+test('ParseStruct', () => {
+  expectTypeOf<
+    ParseStruct<'struct Foo { string foo; string bar; }'>
+  >().toEqualTypeOf<{
+    readonly name: 'Foo'
+    readonly components: [
+      { readonly type: 'string'; readonly name: 'foo' },
+      { readonly type: 'string'; readonly name: 'bar' },
+    ]
+  }>()
+  expectTypeOf<ParseStruct<'struct Foo {}'>>().toEqualTypeOf<{
+    readonly name: 'Foo'
+    readonly components: []
+  }>()
+  expectTypeOf<ParseStruct<'struct Foo { Bar bar; }'>>().toEqualTypeOf<{
+    readonly name: 'Foo'
+    readonly components: [
+      {
+        readonly type: 'Bar'
+        readonly name: 'bar'
+      },
+    ]
+  }>()
+
+  expectTypeOf<ParseStruct<''>>().toEqualTypeOf<never>()
+  expectTypeOf<ParseStruct<'function foo()'>>().toEqualTypeOf<never>()
+})
+
+test('ResolveStructs', () => {
+  type Result = ResolveStructs<
+    [{ type: 'Name'; name: 'name' }],
+    {
+      Person: [{ type: 'Name'; name: 'name' }]
+      Name: [{ type: 'Foo'; name: 'foo' }]
+      Foo: [{ type: 'string'; name: 'bar' }, { type: 'uint16'; name: 'baz' }]
+    }
+  >
+  expectTypeOf<Result>().toEqualTypeOf<
+    readonly [
+      {
+        readonly name: 'name'
+        readonly type: 'tuple'
+        readonly components: readonly [
+          {
+            readonly name: 'foo'
+            readonly type: 'tuple'
+            readonly components: readonly [
+              { type: 'string'; name: 'bar' },
+              { type: 'uint16'; name: 'baz' },
+            ]
+          },
+        ]
+      },
+    ]
+  >()
+
+  expectTypeOf<ResolveStructs<[], StructLookup>>().toEqualTypeOf<readonly []>()
+  expectTypeOf<
+    ResolveStructs<
+      [{ type: 'Foo[]'; name: 'foo' }],
+      { Foo: [{ type: 'string'; name: 'bar' }] }
+    >
+  >().toEqualTypeOf<
+    readonly [
+      {
+        readonly name: 'foo'
+        readonly type: 'tuple[]'
+        readonly components: readonly [
+          {
+            type: 'string'
+            name: 'bar'
+          },
+        ]
+      },
+    ]
+  >()
+})
+
+test('ParseStructProperties', () => {
+  expectTypeOf<ParseStructProperties<'string;'>>().toEqualTypeOf<
+    [{ readonly type: 'string' }]
+  >()
+  expectTypeOf<ParseStructProperties<'string foo;'>>().toEqualTypeOf<
+    [{ readonly type: 'string'; readonly name: 'foo' }]
+  >()
+  expectTypeOf<
+    ParseStructProperties<'string; string;'> extends [
+      { readonly type: 'string' },
+      { readonly type: 'string' },
+    ]
+      ? true
+      : false
+  >().toEqualTypeOf<true>()
+  expectTypeOf<
+    ParseStructProperties<'string foo; string bar;'>
+  >().toEqualTypeOf<
+    [
+      { readonly type: 'string'; readonly name: 'foo' },
+      { readonly type: 'string'; readonly name: 'bar' },
+    ]
+  >()
+
+  expectTypeOf<ParseStructProperties<''>>().toEqualTypeOf<[]>()
+  expectTypeOf<ParseStructProperties<'string'>>().toEqualTypeOf<[]>()
+  expectTypeOf<ParseStructProperties<'string; string'>>().toEqualTypeOf<
+    [{ readonly type: 'string' }]
+  >()
+})

package/src/core/internal/human-readable/types/structs.ts

@@ -0,0 +1,88 @@
+import type { AbiParameter } from 'abitype'
+import type { Error, Trim } from '../types.js'
+import type { StructSignature } from './signatures.js'
+import type { ParseAbiParameter } from './utils.js'
+
+export type StructLookup = Record<string, readonly AbiParameter[]>
+
+export type ParseStructs<signatures extends readonly string[]> =
+  // Create "shallow" version of each struct (and filter out non-structs or invalid structs)
+  {
+    [signature in signatures[number] as ParseStruct<signature> extends infer struct extends
+      {
+        name: string
+      }
+      ? struct['name']
+      : never]: ParseStruct<signature>['components']
+  } extends infer structs extends Record<
+    string,
+    readonly (AbiParameter & { type: string })[]
+  >
+    ? // Resolve nested structs inside each struct
+      {
+        [structName in keyof structs]: ResolveStructs<
+          structs[structName],
+          structs
+        >
+      }
+    : never
+
+export type ParseStruct<
+  signature extends string,
+  structs extends StructLookup | unknown = unknown,
+> =
+  signature extends StructSignature<infer name, infer properties>
+    ? {
+        readonly name: Trim<name>
+        readonly components: ParseStructProperties<properties, structs>
+      }
+    : never
+
+export type ResolveStructs<
+  abiParameters extends readonly (AbiParameter & { type: string })[],
+  structs extends Record<string, readonly (AbiParameter & { type: string })[]>,
+  keyReferences extends { [_: string]: unknown } | unknown = unknown,
+> = readonly [
+  ...{
+    [key in keyof abiParameters]: abiParameters[key]['type'] extends `${infer head extends
+      string & keyof structs}[${infer tail}]` // Struct arrays (e.g. `type: 'Struct[]'`, `type: 'Struct[10]'`, `type: 'Struct[][]'`)
+      ? head extends keyof keyReferences
+        ? Error<`Circular reference detected. Struct "${abiParameters[key]['type']}" is a circular reference.`>
+        : {
+            readonly name: abiParameters[key]['name']
+            readonly type: `tuple[${tail}]`
+            readonly components: ResolveStructs<
+              structs[head],
+              structs,
+              keyReferences & { [_ in head]: true }
+            >
+          }
+      : // Basic struct (e.g. `type: 'Struct'`)
+        abiParameters[key]['type'] extends keyof structs
+        ? abiParameters[key]['type'] extends keyof keyReferences
+          ? Error<`Circular reference detected. Struct "${abiParameters[key]['type']}" is a circular reference.`>
+          : {
+              readonly name: abiParameters[key]['name']
+              readonly type: 'tuple'
+              readonly components: ResolveStructs<
+                structs[abiParameters[key]['type']],
+                structs,
+                keyReferences & { [_ in abiParameters[key]['type']]: true }
+              >
+            }
+        : abiParameters[key]
+  },
+]
+
+export type ParseStructProperties<
+  signature extends string,
+  structs extends StructLookup | unknown = unknown,
+  result extends any[] = [],
+> =
+  Trim<signature> extends `${infer head};${infer tail}`
+    ? ParseStructProperties<
+        tail,
+        structs,
+        [...result, ParseAbiParameter<head, { structs: structs }>]
+      >
+    : result