Contract interface v3

[janek26]

Hey all,

I thought a lot about interfaces for v3 and after coming up with the interfaces and default implementations of Provider, Signer and the all new Account classes, I'll be on vacation for the next 3 weeks 🌴

I think the new v3 Contract interface should work a lot like the ethers.js Contract class. I wrote a little interface before I leave. As I came up with this interface without working on the default implementation maybe I've missed something/some changes are needed.

It borrows a lot from https://docs.ethers.io/v5/api/contract/contract/ and I think we should do that. It also relies a lot on the provided ABI. It is a proven interface and supports a wide combination of use cases, from very simple JS scripts to full blown TS projects using TypeChain etc.

export abstract class ContractInterface {
  abi: Abi;

  // This is the address the contract was constructed with
  address: string | null;

  // If the Contract object is the result of a ContractFactory deployment, this is the transaction which was used to deploy the contract.
  deployTransaction?: AddTransactionResponse;

  // One of the two must be set:
  // If a provider was provided to the constructor, this is that provider. If a signer was provided that had a Provider, this is that provider.
  provider?: ProviderInterface;
  // If a signer was provided to the constructor, this is that signer.
  account?: AccountInterface;

  /**
   * This can't actually be in the interface as it's the constructor, but this is what I think it should look like.
   *
   * Contract class to handle contract methods
   *
   * @param address (optional) - address to connect to
   * @param abi - Abi of the contract object
   * @param providerOrAccount - Can be a provider or an account class instance. If a provider is passed we could limit the functions to calls only.
   */
  constructor(
    address: string | null = null,
    abi: Abi,
    providerOrAccount: ProviderInterface | AccountInterface
  ): void;

  /**
   * Returns a new instance of the Contract attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them.
   *
   * @param address - Address to connect to
   * @returns new Contract instance
   */
  public abstract attach(address: string): ContractInterface;

  /**
   * Returns a new instance of the Contract, but connected to providerOrSigner.
   *
   * By passing in a Provider, this will return a downgraded Contract which only has read-only access (i.e. constant calls).
   * By passing in a Signer. this will return a Contract which will act on behalf of that signer.
   *
   * @param providerOrSigner - Provider or Signer instance
   * @returns new Contract instance
   */
  public abstract connect(
    providerOrAccount: ProviderInterface | AccountInterface
  ): ContractInterface;

  /**
   * Waits til the contract is deployed and returns a new instance of the Contract.
   * Returns immediately if contract was not created by a ContractFactory, aka if deployTransaction is not set.
   *
   * @returns new Contract instance
   */
  public abstract deployed(): Promise<ContractInterface>;

  /**
   * The rest of the methods are generated dynamically and match the Contract external functions provided onchain.
   * This can be read from the abi. Arguments to these functions should be passed as arrays of values, or objects where the key is the same as the name of the parameter in the ABI. It can also be passed as multiple arguments, which will be parsed into an array.
   * Input parameters should be processed as described by the ABI. felt, Uint256 and Arrays should be recogized and parsed.
   * All additional types should be passed as arrays of values, or objects where the key is the same as the name of the parameter in the ABI type definition.
   * It's very much inspired by ethers.js (https://docs.ethers.io/v5/api/contract/contract/#Contract--metaclass)
   */

  /**
   * EXAMPLE ERC20:
   */

  /**
   * Method to get the balance of an account
   *
   * It automatically parses the output of the contract call which is Uint256 to a single BN. This should be supported nativly.
   * This is a view and should be accessable when initialized with a Provider OR Account.
   *
   * @param account - Account to get the balance of
   * @returns balance as an instance of BN. As just one value gets returned from the contract, it's not wrapped inside an array.
   */
  public abstract balanceOf(address: string): Promise<BN>;
  public abstract balanceOf([address]: [string]): Promise<BN>;
  public abstract balanceOf({ address }: { address: string }): Promise<BN>;

  /**
   * Method to send tokens to an account
   *
   * It automatically parses the input of the function from a BN to a Uint256 as detected in the ABI. This should be supported nativly.
   * This is NOT a view and should only be accessable when initialized with a Signer.
   *
   * @param to - Address to send the tokens to
   * @param value - Amount of tokens to send
   *
   * @returns transaction response
   */
  public abstract transfer(to: string, value: BN): Promise<AddTransactionResponse>;
  public abstract transfer([to, value]: [string, BN]): Promise<AddTransactionResponse>;
  public abstract transfer({
    to,
    value,
  }: {
    to: string;
    value: BN;
  }): Promise<AddTransactionResponse>;

  /**
   * Method that expects some custom struct, like `Uint512` which is not supported natively.
   * Multiplys two inputs together.
   *
   * ABI looks like this:
   * ```
   * [
   *   {
   *     members: [
   *       {
   *         name: 'low',
   *         offset: 0,
   *         type: 'felt',
   *       },
   *       {
   *         name: 'middle',
   *         offset: 1,
   *         type: 'felt',
   *       },
   *       {
   *         name: 'high',
   *         offset: 2,
   *         type: 'felt',
   *       },
   *     ],
   *     name: 'Uint512',
   *     size: 3,
   *     type: 'struct',
   *   },
   *   {
   *     inputs: [
   *       {
   *         name: 'mult_one',
   *         type: 'Uint512',
   *       },
   *       {
   *         name: 'mult_two',
   *         type: 'Uint512',
   *       }
   *     ],
   *     name: 'multiply',
   *     outputs: [
   *       {
   *         name: 'result',
   *         type: 'Uint512',
   *       },
   *     ],
   *     stateMutability: 'view',
   *     type: 'function',
   *   },
   * ]
   * ```
   *
   * @param multOne - expects a struct of type `Uint512` which is not natively supported, therefore it expects an array of felts or an object with the same keys as the struct.
   * @param multTwo - expects a struct of type `Uint512` which is not natively supported, therefore it expects an array of felts or an object with the same keys as the struct.
   * @return result - returns a struct of type `Uint512` which is not natively supported, therefore it expects an array of felts or an object with the same keys as the struct. As just one value gets returned from the contract, it's not wrapped inside an array. Results should be accessable as arrays and objects.
   */
  public abstract multiply(
    multOne: [BigNumberish, BigNumberish, BigNumberish],
    multTwo: [BigNumberish, BigNumberish, BigNumberish]
  ): Promise<
    [BN, BN, BN] & {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    }
  >;
  public abstract multiply([
    [BigNumberish, BigNumberish, BigNumberish],
    [BigNumberish, BigNumberish, BigNumberish],
  ]): Promise<
    [BN, BN, BN] & {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    }
  >;
  public abstract multiply([{ low, middle, high }, { low, middle, high }]: [
    {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    },
    {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    }
  ]): Promise<
    [BN, BN, BN] & {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    }
  >;
  public abstract multiply(
    multOne: {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    },
    multTwo: {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    }
  ): Promise<
    [BN, BN, BN] & {
      low: BigNumberish;
      middle: BigNumberish;
      high: BigNumberish;
    }
  >;

  /**
   * If there are multiple return values, as with ie `divideWithRemainder`, the return value is an array of the return values.
   * If there is only one return value, it's unwrapped and returned as a single value, as seen before.
   *
   * @param divisor - Uint256
   * @param dividend - Uint256
   * @return [result, remainder] - returns the result as an Uint256 and the remainder as an Uint256
   */
  public abstract divideWithRemainder(
    divisor: BigNumberish,
    dividend: BigNumberish
  ): Promise<
    [BN, BN] & {
      result: BN;
      remainder: BN;
    }
  >;
  public abstract divideWithRemainder([BigNumberish, BigNumberish]): Promise<
    [BN, BN] & {
      result: BN;
      remainder: BN;
    }
  >;
  public abstract divideWithRemainder({
    divisor,
    dividend,
  }: {
    divisor: BigNumberish;
    dividend: BigNumberish;
  }): Promise<
    [BN, BN] & {
      result: BN;
      remainder: BN;
    }
  >;
}

I think additionally there should be a class called ContractFactory which can deploy Contracts, just as in ethers https://docs.ethers.io/v5/api/contract/contract-factory/

Thanks for the read and let me know what you think about this interface!

Best,
Janek

[fracek]

The interface looks reasonable, quick question: should the contract interface also provide the contract.METHOD_NAME(...args) methods like ethers.js does? From the comments it looks like that's the case, but should the interface also include the estimateGas, populateTransaction versions of the methods?

[janek26]

Yes right, the idea was to have that pattern. As you can see in the snippet I just added some of such methods to display how type transformation would work

[MilGard91]

With this interface the contract will be more intuitive and easier to use since we will have the direct call for the methods like @fracek mentioned and I agree also on ContractFactory, it can support type transformation on deployment for more complex args, because it will have access to the abi.

[dhruvkelawala]

This will be a really great interface to implement. Excited! :)