RFC: Contract Instances

[jxom]

Summary

This is a mini proposal for the concept of Contract Instances in viem.

Basic Example

The ability to define contract instances up front so that folks don't have to switch between clients & pass an address/abi around:

const contract = getContract({
  abi,
  address,
  publicClient,
  walletClient,
})

// readContract
contract.read.totalSupply({ blockNumber: 1n })

// writeContract
contract.write.mint([420], { value })

// simulateContract
contract.simulate.mint([420], { value })

// estimateContractGas
contract.estimateGas.mint([420], { value })

// createContractEventFilter
contract.createEventFilter({ fromBlock: 'latest' })
contract.createEventFilter.Transfer({ from, to }, { fromBlock: 'latest' })

// watchContractEvent
contract.watchEvent({ batch: true })
contract.watchEvent.Transfer({ from, to }, { batch: true })

The Problem

The current APIs for contract interactions are currently primitives, which means they are a bit more verbose than folks would like.

1. They need to pass an abi and address around:

If multiple contract functions are being utilized in an application, a consumer would need to pass the abi and address args around to those definitions.

import { publicClient } from './client'
import { address, abi } from './contract'

const totalSupply = await publicClient.readContract({
  address,
  abi,
  functionName: 'totalSupply'
})
const symbol = await publicClient.readContract({
  address,
  abi,
  functionName: 'symbol'
})
const balanceOf = await publicClient.readContract({
  address,
  abi,
  functionName: 'balanceOf',
  args: ['0x...']
})

2. They need to switch between publicClient and walletClient

This can get a bit more tedious when you start to deal with contract writes, as you then need to add a walletClient into the mix.

Let's take the previous example.

import { 
  publicClient 
+ walletClient
} from './client'
import { address, abi } from './contract'

const totalSupply = await publicClient.readContract({
  address,
  abi,
  functionName: 'totalSupply'
})
const symbol = await publicClient.readContract({
  address,
  abi,
  functionName: 'symbol'
})
const balanceOf = await publicClient.readContract({
  address,
  abi,
  functionName: 'balanceOf',
  args: ['0x...']
})
+ const hash = await walletClient.writeContract({
+   address,
+   abi,
+   functionName: 'mint',
+   args: [420]
+ })

The reason why it was designed this way is because we wanted to keep our APIs mostly flat as this leads to a more predictable & comprehensive implementation, however, this obviously comes with the trade-off that things get a bit more verbose.
I understand for things like calling contract functions, this can get overly verbose, and I agree that there should be an abstraction to make things a bit easier.

Detailed Design

The solution to this would be an API that looks like the one defined in Basic Example:

const contract = getContract({
  abi,
  address,
  publicClient,
  walletClient,
})

// readContract
await contract.read.totalSupply()
await contract.read.totalSupply({ blockNumber: 69420n })

await contract.read.balanceOf(['0x..'])
await contract.read.balanceOf(['0x..'], { blockNumber: 69420n })

// writeContract
await contract.write.mint([420], { value })

// simulateContract
await contract.simulate.mint([420], { value })

// estimateContractGas
await contract.estimateGas.mint([420], { value })

// createContractEventFilter
await contract.createEventFilter({ fromBlock: 'latest' })
await contract.createEventFilter.Transfer({ from, to }, { fromBlock: 'latest' })

// watchContractEvent
contract.watchEvent({ onLogs: logs => ... })
contract.watchEvent.Transfer({ from, to }, { onLogs: logs => ... })

getContract

This will create the contract instance:

const contract = getContract({
  abi,
  address,
  publicClient,
  walletClient,
})

• The abi is required,
• The publicClient is optional – if it is not passed, the contract instance will not have access to "read" methods,
• The walletClient is optional – if it is not passed, the contract instance will not have access to "write" methods,
• The address is optional, so that folks can pass in an address dynamically to a contract function,

read

Same functionality as readContract.

const totalSupply = await contract.read.totalSupply()

Contract Arguments

If the function requires arguments, this can be placed as an array in the first parameter:

const balance = await contract.read.balanceOf(['0x..'])

eth_call Arguments

If the function needs call args, this can be:

• placed as the second parameter (if contract args exist), or
• placed as the first parameter.

const balance = await contract.read.balanceOf(['0x..'], { blockNumber: 69420n })
// or
const totalSupply = await contract.read.totalSupply({ blockNumber: 69420n })

write

Same functionality as writeContract.

const hash = await contract.write.mint()

Contract Arguments

If the function requires arguments, this can be placed as an array in the first parameter:

const hash = await contract.write.mint([420])

eth_sendTransaction Arguments

If the function needs send txn args, this can be:

• placed as the second parameter (if contract args exist), or
• placed as the first parameter.

const { result } = await contract.write.mint([420], { value: parseEther('1') })
// or
const { result } = await contract.write.mint({ value: parseEther('1') })

simulate

Same functionality as simulateContract.

const { result } = await contract.simulate.mint()

Contract Arguments

If the function requires arguments, this can be placed as an array in the first parameter:

const { result } = await contract.simulate.mint([420])

eth_call Arguments

If the function needs call arguments, this can be:

• placed as the second parameter (if contract args exist), or
• placed as the first parameter.

const { result } = await contract.simulate.mint([420], { value: parseEther('1') })
// or
const { result } = await contract.simulate.mint({ value: parseEther('1') })

estimateGas

Same functionality as estimateContractGas.

const gas = await contract.estimateGas.mint()

Contract Arguments

If the function requires arguments, this can be placed as an array in the first parameter:

const gas = await contract.estimateGas.mint([420])

eth_estimateGas Arguments

If the function needs estimate gas arguments, this can be:

• placed as the second parameter (if contract args exist), or
• placed as the first parameter.

const gas = await contract.estimateGas.mint([420], { value: parseEther('1') })
// or
const gas = await contract.estimateGas.mint({ value: parseEther('1') })

createEventFilter

Same functionality as createContractEventFilter.

If no contract event is provided, it will create a filter against all events on the contract:

const filter = await contract.createEventFilter()

Scope to an Event

However, you can also scope to an event:

const filter = await contract.createEventFilter.Transfer()

Event Arguments

If the event requires indexed arguments, this can be placed as the first parameter:

const filter = await contract.createEventFilter.Transfer({ from, to })

eth_newFilter Arguments

If the function needs filter arguments, this can be:

• placed as the second parameter (if contract args exist), or
• placed as the first parameter.

const filter = await contract.createEventFilter.Transfer({ from, to }, { fromBlock: 'latest' })
// or
const filter = await contract.createEventFilter.Transfer({ fromBlock: 'latest' })

watchEvent

Same functionality as watchContractEvent.

If no contract event is provided, it will create a watcher against all events on the contract:

const unwatch = contract.watchEvent({ onLogs: logs => ... })

Scope to an Event

However, you can also scope to an event:

const unwatch = contract.watchEvent.Transfer({ onLogs: logs => ... })

Event Arguments

If the event requires indexed arguments, this can be placed as the first parameter:

const unwatch = contract.createEventFilter.Transfer({ from, to }, { onLogs: logs => ... })

eth_newFilter Arguments

If the function needs filter arguments, this can be:

• placed as the second parameter (if contract args exist), or
• placed as the first parameter.

const unwatch = contract.watchEvent.Transfer({ from, to }, { onLogs: logs => ... })
// or
const unwatch = contract.watchEvent.Transfer({ onLogs: logs => ... })

[glitch-txs]

Awesome! You were fast 😂 nice work!

[alcuadrado]

If the function needs call args, this can be:

• placed as the second parameter (if contract args exist), or
• placed as the first parameter.

const balance = await contract.read.balanceOf(['0x..'], { blockNumber: 69420n })
// or
const totalSupply = await contract.read.totalSupply({ blockNumber: 69420n })

Another alternative is to always expect the array, so the second example would be

const totalSupply = await contract.read.totalSupply([], { blockNumber: 69420n })

This is trading a bit of verbosity for api consistency and clarity. It's always clear in that case that the object are call args.

I don't have a strong opinion for either.

• The publicClient is optional – if it is not passed, the contract instance will not have access to "read" methods,
• The walletClient is optional – if it is not passed, the contract instance will not have access to "write" methods,

Maybe keeping those methods, without including them in the types, and just throwing an error in them could be useful for people using js and not ts.

I think this can be done with something like without having to cast to any

Object.defineProperty(contract.write, 'mint', {
  value: () => { throw new Error("You need a walletClient to be able to call mint"); },
  writable: false,
  enumerable: false,
  configurable: false
});

[tmm]

Agree! We'll go with the compile-time approach instead of runtime. It's less astonishing and catches errors further upstream.

[alcuadrado]

To clarify: I meant both. Type-level checks for ts users, runtime for js users.

[roninjin10]

Even js users may be able to benifit from the types. But js users need to switch to ts :)

[alcuadrado]

Agreed! It can't happen soon enough

[greenlucid]

i would appreciate having to pass empty list for methods without args, it's less surprising

[roninjin10]

I personally am a fan of minimal apis. I would prefer to simply have objects I can pass around

const myErc20 = { abi, address }

const res = client.readContract({...myErc20, 'balanceOf'})

I don't think this rfc adds any value except for a small ergonomic boost for those of us who love typing . and seeing that smooth autocomplete. I think it's fine though and I'd expect most users to appreciate this api especially since it's familiar from ethers

[jackmellis]

For me, contract reads are perfectly fine, but contract writes are now a lot more verbose than the ethers.js equivalent. I'd like the account / simulate / write to be abstracted away.

We're playing with making such an abstraction in our app, but a lot of the clever type inference tricks that viem uses aren't exported and tbh an out-the-box abstraction would be much nicer...

[tmm]

@jackmellis Hopefully this reduces some of the verbosity for wallet client account-based actions: #211

Agree that it is often nice to have only one way of doing things when it comes to libraries. In this case, a higher-level contract API definitely seems useful for folks that are migrating over from ethers as well as the points mentioned around slight developer experience bump.

[jackmellis]

To be honest I would be quite happy at this point to just have some of the internal types exposed so we can extract more meta from an ABI.
abitype provides some useful utils but I'm still lost trying to calculate the args and return type of a contract method. ExtractArgsFromAbi and ExtractResultFromAbi both exist in viem, but they aren't exported.

[jxom]

Can expose them!

[alcuadrado]

+1 to exposing the type "utilities" necessary to do these kind of abstractions.

Agree that it is often nice to have only one way of doing things when it comes to libraries. In this case, a higher-level contract API definitely seems useful for folks that are migrating over from ethers as well as the points mentioned around slight developer experience bump.

Agreed

[greenlucid]

i was initially skeptical since i would rather have a single choice per action. i don't want to have to keep track of many things, and I don't want contributors to be able to surprise me.

i think it would be a net gain, however. it's still pretty simple, it can cut down a lot of verbosity. if devs are expected to be going to inventing their own wheel in practice, then it should be supported.

also, there's a very simple editorial choice to make when having to decide between client methods or using a contract instance:

• am i interacting with the same contract multiple times? ==> contract instance
• is this going to be a single interaction with the contract, and i don't expect to ever need to add more? ==> client methods

[tmm]

also, there's a very simple editorial choice to make when having to decide between client methods or using a contract instance:

good point. another thing to consider is if you can use multicall.

[jackmellis]

Thanks for exporting those additional types (super fast turnaround 😄 ). I've fudged together a simple Contract implementation. It's only rudimentary.

https://gist.github.com/jackmellis/dd7e7360e3d3783dc8a1f662927e9b6c

However I'm now also thinking that combining several interactions into a single "write" action might be too opinionated for what should be considered a low level library...

[fubhy]

For simple, linear scripts contract instances can be great (it's still a matter of taste of course). But specifically for writes in the context of user interfaces where you have to react to wallet and parameter changes dynamically, handing around preinitalized objects like these can easily become a footgun. In our app state machines, we always just pass around the raw parameters until the very last moment. Initializing the contract instance there isn't necessary and doesn't add much value imho. But yeah, primarily for read operations (mostly in the context of linear scripts), and for more fluently readable documentation / examples I can see the benefit of this abstraction.

Even with the excellent types & utilities provided by standalone viem, I still see protocols shipping their own abstractions and sdks around their contracts in the future. I wouldn't want to expose every third party users of our protocol to the full width of our low level contract apis. What's viem's story going to be for those use-cases?

I'd like to be able to pass around typed output objects from encodeFunctionData and decodeFunctionResult and use them directly in writeContract / readContract calls on the client instances so my hypothetical protocol-flavoured SDK can expose some utility functions to simplify parameterization, encoding & decoding for some of the more complicated functions of our contracts whilst still leaving the signing, sending, error handling, etc. to the downstream consumer.

Is there already an idiomatic approach to that in viem that I'm missing? Providing flavours of .writeContract, .simualteContract, etc. that retain the same type coverage of the full-arg .writeContract version based on a typed, pre-encoded transaction payload would be great for that.

[fubhy]

I see two workarounds that would already be possible today ...

1. Build these sdk utils in a way that exposes the viem implementation details to the consuming user:

So, instead of building this utils in such a way that they'd return a encoded transaction payload, let them return a partial const object that the user could then spread into .writeContract / .simulateContract. This would work with the existing viem abstractions and provide the same type coverage but would leak viem implementation details from the SDK which may not be desirable.

2. Provide a serialization wrapper & formatter for these utility functions that can be stringified into a plain transaction payload or translated / formatted into typed viem .xxxContract args.

This would be very versatile and would allow the SDK consumer to translate this output also into a format that's compatible with ethers.js or web3.js. This would also work without losing any type coverage but would come with a bit of a syntactical overhead.

I'll be going with 1. for now for simplicity but find 2. quite appealing.

[fubhy]

What I like about this approach is that it doesn't break the stance that viem seems to follow (which I like) to keep abstractions flat as much as possible.

It's also very similar to the { request, result } output of .simulateContract but basically starts one step earlier.

1. Encode transaction payload via SDK abstraction
2. Pass output of 1. into .simulateContract
3. Pass output of 2. into .writeContract
4. Get fully typed output from 3. but without having to craft all the inputs manually each time.

[fubhy]

I like this also because it encourages users to follow this pattern of encode => simulate => write and also encourage the use of stuff like accessList through convenience which rarely anyone does atm.

[tmm]

Contract instances are now out as part of [email protected]!