Improved contract hook typings

[kevinhalliday]

I was thinking it would be great to get accurate types on contract method names, args, and return values. I gave it a shot on the useContractRead hook and liked the result, so figured I'd start a discussion. Here's the behavior for an IERC20 contract:

Usage:

typed data:

typed function names for read methods only. So here we're trying to use approve, which is an IERC20 method, but not allowed for this hook:

typed args:

Could also be nice to require args via the Config param if the read func does in fact take arguments, though I didn't try that out.

Here's one way to get these typings. Feedback appreciated.

type Awaited<T> = T extends PromiseLike<infer U> ? U : T
type GenericWrite = (...args: any) => Promise<ethers.ContractTransaction>

type WriteMethodNames<
  Contract extends ethers.Contract,
  Methods extends Contract['functions'] = Contract['functions'],
> = {
  [M in keyof Methods]: Methods[M] extends GenericWrite ? M : never
}[keyof Methods]

type ReadMethodNames<
  Contract extends ethers.Contract,
  Methods extends Contract['functions'] = Contract['functions'],
> = Exclude<keyof Methods, WriteMethodNames<Contract>>

type Writes<Contract extends ethers.Contract> = Pick<
  Contract['functions'],
  WriteMethodNames<Contract>
>

type Reads<Contract extends ethers.Contract> = Pick<
  Contract['functions'],
  ReadMethodNames<Contract>
>

type Config<
  Contract extends ethers.Contract,
  MethodName extends ReadMethodNames<Contract>,
> = {
  args?: Parameters<Reads<Contract>[MethodName]>
  overrides?: Overrides
  skip?: boolean
  watch?: boolean
}

type State<
  Contract extends ethers.Contract,
  MethodName extends ReadMethodNames<Contract>,
> = {
  response?: Awaited<ReturnType<Reads<Contract>[MethodName]>>
  error?: Error
  loading?: boolean
}

export const useContractRead = <
  Contract extends ethers.Contract = ethers.Contract,
  MethodName extends ReadMethodNames<Contract> = ReadMethodNames<Contract>,
>(
  contractConfig: UseContractConfig,
  functionName: MethodName,
  { args, overrides, skip, watch }: Config<Contract, MethodName> = {},
) => {
  const provider = useProvider()
  const contract = useContract<Contract>({
    signerOrProvider: provider,
    ...contractConfig,
  })
  const [{ data: blockNumber }] = useBlockNumber({ skip: true, watch })
  const [state, setState] = React.useState<State<Contract, MethodName>>({
    loading: false,
  })

  const read = React.useCallback(
    async (config?: {
      args?: Config<Contract, MethodName>['args']
      overrides?: Config<Contract, MethodName>['overrides']
    }) => {
   ...

The Writes type is unused but I left it in there for symmetry. And to show we could do something similar for the useContractWrite hook.

[tmm]

Awesome! Will take a deeper look soon. ethers.js v6 should be coming out soon with better TypeScript support for contacts too.

[kevinhalliday]

Great - thanks! Happy to hear ethers is improving their TypeScript support in v6. Hopefully their upgrades will make it easier to derive dependent types from Contract generics. Having untyped data (typed as Result from ethers/lib/utils, which is just interface Result extends ReadonlyArray<any> { readonly [key: string]: any; }) has been a little frustrating.

Happy to help if needed! Don't want to step on any toes - just looking to get a bit more involved in the community, and wagmi is my favorite of the web3 libraries I've tried.

[tmm]

Sounds great! I can loop you back in re: contract typing once we see what ethers v6 has in store.

[ericzakariasson]

This looks great! If there's any other typings that can be improved I'm happy to help

[tmm]

Could be good to put together a PR for improving contract typing (useContract, useContractReadt, useContractWrite, etc.).

Not sure how long we'll need to wait for the ethers v6 release so might as well make things better in the meantime.

cc @kevinhalliday could be good to coordinate efforts - happy to chat async or live

[kevinhalliday]

@tmm agreed. I've got a busy week or so ahead of my so async might be best. thanks for giving this the go-ahead.

I'll defer to you on workflow - but maybe we open a PR with types for a single contract hook to start, so we can start discussion around preferred pattern? then extend that pattern to the rest. would leave room for more eager contributors like myself

and thanks for the bump @ericzakariasson. would definitely appreciate your help / feedback

[tmm]

Sounds good!

[ericzakariasson]

This sounds good to me as well! Let me know if you have a PR or just want to discuss some things directly, I'm happy with both sync and async. Great work so far!

[kevinhalliday]

@tmm @ericzakariasson got to work on this today. sorry it took me a bit. basically did the same thing in the snippets above, with one change that I'd like your thoughts on. also, tried to push a branch to start a discussion on a PR but didn't have the permissions. Not sure what the right process is there. So figured I'd ask here first.

In the initially proposed typings, users wouldn't be able to use the useContractRead method without providing a generic. They'd get the following error

When no generic is given, we infer read and write method names from the base ethers.Contract, which is defined as:

export class BaseContract {
   ...
    readonly functions: { [ name: string ]: ContractFunction };
   ...
  }
  
 type ContractFunction<T = any> = (...args: Array<any>) => Promise<T>;

Because the ContractFunction returns Promise<any>, all methods extend GenericWrite so

WriteMethodNames<ethers.Contract> // string
ReadMethodNames<ethers.Contract> // number

because

keyof { [name: string] ContractFunction } // string | number

Didn't think that was a great ux for users who didn't have contract types available to provide generics. The fix changes the ReadMethodNames to just do the opposite of WriteMethodNames, rather than using Omit. And adds another utility type to handle the never edge case.

type IfNeverThen<T, Then> = [T] extends [never] ? Then : T
export type ReadMethodNames<
  Contract extends ethers.Contract,
  Methods extends Contract['functions'] = Contract['functions'],
> = IfNeverThen<
  {
    [M in keyof Methods]: Methods[M] extends GenericWrite ? never : M
  }[keyof Methods],
  keyof Methods
>

Sorry, that was a lot. All in all, it works, but adds a bit more complexity to some typings that are already somewhat opaque. Maybe it's better to not try to differentiate between read and write methods. It wouldn't be as fancy of a ux, but it would simplify the typings.

[tmm]

Good points!

Would love to test out the PR and give more feedback. You should be able to fork the repo and add one.

[ericzakariasson]

Great job! Like you're saying, it's hard to settle on a good balance between complexity and DX. If we could get a feel for it and try it out in a PR, that'd be nice. Looking forward to it @kevinhalliday! 🙌