Idea: Bubble up invalid ABI type errors on readContract and others alike.

[Raiden1411]

Problem

Recently on the ABIType repository, there was an issue where an invalid ABI was being used and the readContract here was not inferring the functionName correctly, but we found out the problem was a missing required property on the provided ABI. But the problem here is that the ABI was extracted from a third-party website like etherscan, and currently there is no way to let developers know that they are using invalid ABIs.

So, with this in mind, I currently see two solutions to this problem.

Solution 1

The easiest solution here is to just "throw" an invalid ABI error if the functionName cannot be inferred from the ABI.

export type GetFunctionName<
  TAbi extends Abi | readonly unknown[] = Abi,
  TFunctionName extends string = string,
  TAbiStateMutability extends AbiStateMutability = AbiStateMutability,
> = TAbi extends Abi
  ? ExtractAbiFunctionNames<
      TAbi,
      TAbiStateMutability
    > extends infer AbiFunctionNames
    ?
        | AbiFunctionNames
        | (TFunctionName extends AbiFunctionNames ? TFunctionName : never)
        | (Abi extends TAbi ? string : never)
    : never
    // We would change the value here to something like ["Error: Invalid ABI"]
  : TFunctionName

But this poses a problem... What about ABIs that folks use from JSON files or simply don't const assert?
With solution 1, those ABIs would also fail, and that is not good. Since they could indeed be using valid ABIs and would essentially be forcing folks to const assert their ABIs.

So what can we do to mitigate this?

Solution 2

Here we check for all ABIs that are either const asserted or simply aren't and check if any of them have errors in the case that they don't evaluate to valid ABIs. This would work on declared ABIs, zodParsed, and ABIs that are imported via JSON files.
I will go into more details below, but to follow along, assume that these ABIs can all be the following: constAsserted, jsonAbi, zodAbi, and notConstAsserted.

Invalid ABI

[
  {
    "name": "foo",
    "type": "error",
    "inputs": []
  },
  {
    "name": "foo",
    "stateMutability": "view",
    "inputs": [],
    "outputs": [{ "type": "string", "name": "" }]
  },
  {
    "name": "bar",
    "type": "function",
    "stateMutability": "view",
    "inputs": [{ "type": "address", "name": "" }],
    "outputs": [{ "type": "address", "name": "" }]
  },
  {
    "name": "foo",
    "type": "function",
    "inputs": [],
    "outputs": [{ "type": "string", "name": "" }],
  }
]

Valid ABI

[
  {
    "name": "foo",
    "type": "error",
    "inputs": []
  },
  {
    "name": "foo",
    "type": "function",
    "stateMutability": "view",
    "inputs": [],
    "outputs": [{ "type": "string", "name": "" }]
  },
  {
    "name": "bar",
    "type": "function",
    "stateMutability": "view",
    "inputs": [{ "type": "address", "name": "" }],
    "outputs": [{ "type": "address", "name": "" }]
  }
]

For solution two to work, we need a way to validate that the ABIs that aren't const asserted are also valid, and to do so, we will need some helper types, and luckily, ABIType will get us there pretty quickly.

type NotAssertedAbiParameter =
  | {
      type: string;
      name?: string;
      internalType?: string;
    }
  | {
      type: string;
      name?: string;
      internalType?: string;
      components: NotAssertedAbiParameter[];
    };

type NotAssertedConstructor = Pick<AbiConstructor, "payable"> & {
  type: string;
  stateMutability: string;
};
type NotAssertedFallback = Pick<AbiFallback, "payable" | "inputs"> & {
  type: string;
  stateMutability: string;
};
type NotAssertedReceive = { type: string; stateMutability: string };
type NotAssertedError = Pick<AbiError, "name"> & {
  type: string;
  inputs?: NotAssertedAbiParameter[];
};
type NotAssertedEvent = Pick<AbiEvent, "name" | "anonymous"> & {
  type: string;
  inputs?: (NotAssertedAbiParameter & { indexed?: true })[];
};
type NotAssertedFunction = Pick<
  AbiFunction,
  "name" | "constant" | "gas" | "payable"
> & {
  type: string;
  stateMutability: string;
  inputs: NotAssertedAbiParameter[];
  outputs: NotAssertedAbiParameter[];
};

Using the already-defined types for const asserted ABIs, we can pick the properties that we want and create the rest. With this setup, we can quickly get to the required ABI.

export type NotConstAssertedAbi = (
  | NotAssertedConstructor
  | NotAssertedFallback
  | NotAssertedReceive
  | NotAssertedError
  | NotAssertedEvent
  | NotAssertedFunction
)[];

Now that we have all of these types helpers, we need a way to validate to check if the abi that was passed on to the function is valid, and if it's not valid, we need to check what failed.

Using the GetFunctionName type above, we can extend it to check for NotConstAssertedAbi with something like this:

TAbi extends NotConstAssertedAbi
  ? TFunctionName
  : // Do the error checking here

So what can we do to check which member of the ABI is invalid? Using something like the isSignature and Signatures types from ABIType, we can achieve that. This will allow us to pinpoint exactly where the invalid ABI members are on the const asserted ABIs, and we can display that to the developer.

export type isAbiSpec<T extends unknown> =
  | (T extends AbiConstructor | NotAssertedConstructor ? true : never)
  | (T extends AbiFallback | NotAssertedFallback ? true : never)
  | (T extends AbiReceive | NotAssertedReceive ? true : never)
  | (T extends AbiError | NotAssertedError ? true : never)
  | (T extends AbiEvent | NotAssertedEvent ? true : never)
  | (T extends AbiFunction | NotAssertedFunction
      ? true
      : never) extends infer Condition
  ? [Condition] extends [never]
    ? false
    : true
  : false;

export type AbiSpec<
  T extends unknown,
  K extends string | unknown = unknown
> = isAbiSpec<T> extends true
  ? never
  : `Invalid abi spec${K extends string ? ` at position ${K}` : ""}.`;

export type ValidAbi<T extends readonly unknown[]> = {
  [K in keyof T]: AbiSpec<T[K], K>;
};

Using the ValidAbi type helper, we will get the ABI with the error messages, and we can extract them and show them.

Extract<ValidAbi<TAbi>[number], string>

Using the invalid ABI above as const, here is an example of how it would show up.

It correctly grabs the spec with missing properties. In this example, position 1 is missing the type property, and position 3 is missing the stateMutability property.

What about the NotConstAsserted?

Well, in cases of error, we won't have the same level of details, but we can also give a general idea of what the problem is with this type helper.

export type CheckInvalidAbiSpec<T> = T extends
  | NotAssertedConstructor
  | NotAssertedFallback
  | NotAssertedReceive
  | NotAssertedError
  | NotAssertedEvent
  | NotAssertedFunction
  ? never
  : T;

And then we can check if there are any error messages from the previous ValidAbi type, and in case there aren't, we use this type to grab the invalid ABI spec. Where is what the final GetFunctionName type would look like:

export type GetFunctionName<
  TAbi extends Abi | readonly unknown[] = Abi,
  TFunctionName extends string = string,
  TAbiStateMutability extends AbiStateMutability = AbiStateMutability
> = TAbi extends Abi
  ? ExtractAbiFunctionNames<
      TAbi,
      TAbiStateMutability
    > extends infer AbiFunctionNames
    ?
        | AbiFunctionNames
        | (TFunctionName extends AbiFunctionNames ? TFunctionName : never)
        | (Abi extends TAbi ? string : never)
    : never
  : TAbi extends NotConstAssertedAbi
  ? TFunctionName
  : Extract<ValidAbi<TAbi>[number], string> extends infer Result
  ? [Result] extends [never]
    ? Error<{
        result: "error";
        type: "Invalid Abi spec found";
        message: CheckInvalidAbiSpec<TAbi[number]>;
      }>
    : Error<{ result: "error"; type: "Invalid Abi"; message: Result }>
  : never;

And here is an example of the error in NotConstAssertedAbis

As you can see, you won't have the same level of details, and it will only catch one invalid member at a time. Here the problem is that the type property is marked as undefined. This error checking will also work for imported JSON ABIs.

Final thoughts

With Solution 2, we would increase the DX by having developers know exactly what to expect when using ABIs in these functions.

• If they are using valid const asserted ABIs, the typescript LSP will correctly display all the possible valid names.

const resultValid = readContract({
  address: "0x",
  abi: wagmiMintExampleAbi,
  functionName: "",
  // ^? (property) functionName: "symbol" | "name" | "balanceOf" | "getApproved" | ...
});

• If they are using ABIs that weren't const asserted but are valid. The typescript LSP won't suggest any names, but it won't show any error messages either.

const resultNotConstAsserted = readContract({
  address: "0x",
  abi: validNotConstAsserted,
  functionName: "",
  // ^? (property) functionName: ""
});

const resultNotConstAsserted = readContract({
  address: "0x",
  abi: zodParsedAbi,
  functionName: "",
  // ^? (property) functionName: ""
});

const resultNotConstAsserted = readContract({
  address: "0x",
  abi: jsonImportedAbi,
  functionName: "",
  // ^? (property) functionName: ""
});

• If the typescript LSP shows you any "error" messages, then you will know that the ABI is invalid and will have a general idea of what the problem is, and in the case of const asserted ABIs, you will know exactly where the problem lies.

• And finally, if the LSP suggests never as a type, you know something bad has happened.

All the code shown here, in this example, can be found here. I recommend copying and opening it in your editor of choice, in case you want to try it out, since there are some problems with this codesandbox as its not getting all the correct types from ABIType.

TL:DR

Check for invalid ABIs at the type level. Good idea? Bad idea?

Looking forward to hearing your thoughts! Keep in mind that I'm not proposing to use the types as they are, as they were created for the purpose of this discussion.

[Raiden1411]

@jxom and @tmm, any thoughts regarding this? I can work on a PR if you think that makes sense.

[tmm]

My initial thought is providing users with feedback at the type-level is usually better than finding out at runtime something doesn't work. I wonder if it's better to move TAbi to use const parameter types, drop internal usage of Narrow<...>, and lock down the abi property (event, etc.) and show errors there instead of functionName.

[Raiden1411]

I feel like that would be a better approach than showing the errors on functionName and since viem is now on 5.0 and wagmi v1 is out (congrats btw 🖤) we can start to leverage these new features.

I also think that adding a type for not const asserted abis like json imported ones would be useful for checking the validity of the abis used in those functions. It would probably make sense in having this on abitype and then importing that here.

What do you think?