Skip to main content

Models

Call​

Represents a single call to a contract that can be included in multicall.

Fields

  • args: any[] - arguments for the function
  • contract: Contract - contract instance, see Contract
  • method: string - function name

Typechecking:

If you want a variable of type Call to be type checked you need to pass a typechain contract type as in below example

const typedCall: Call<ERC20> = { contract: ERC20Contract, method: 'name', args: [] }

If you also supply a method name in type arguments will also be type checked

const typedCall: Call<ERC20, 'name'> = { contract: ERC20Contract, method: 'name', args: [] }

CallResult​

Result of a useCall query.

It is undefined when call didn't return yet or a object { value, error } if it did.

  • value: any[] | undefined - array of results or undefined if error occurred,
  • error: Error | undefined - encountered error or undefined if call was successful.

Chain​

Represents the chain type.

Fields

  • blockExplorerUrl: string - The URL of the network's block explorer, used for adding the network to Metamask
  • chainId: number - The ID of the chain. Every chain has a unique chainId.
  • chainName: string - The name of the chain.

  • getExplorerAddressLink: (address: string) => string - A function to construct a link to a blockchain explorer, based on an ethereum address.

  • getExplorerTransactionLink: (address: string) => string - A function to construct a link to a blockchain explorer, based on a transaction hash.

  • isLocalChain: boolean - Whether the chain is a development chain running on localhost.

  • isTestChain: boolean - Whether the chain is a testnet, such as Kovan or Ropsten.
  • multicall2Address: string - An address of the Multicall2 contract on the chain.
  • multicallAddress: string - An address of the Multicall contract on the chain.
  • nativeCurrency: Object - The network's currency, used for adding the network to Metamask
  • rpcUrl: string - The URL of the network's RPC provider, used (required) for adding the network to Metamask

ContractCall​

Represents a single call to a contract that can be included in multicall.

Fields

  • abi: Interface - ABI of a contract, see Interface
  • address: string - address of a contract to call
  • args: any[] - arguments for the function
  • method: string - function name

Currency​

The Currency class is tasked with representing the individual currencies as well as handling formatting.

The base Currency class is constructed with the following parameters:

  • name - name of the currency
  • ticker - e.g. USD, EUR, BTC
  • decimals - number of decimal places (e.g. 2 for USD, 18 for ETH)
  • formattingOptions - define how the currency values are formatted The following formatting options are supported:
  • decimals - Defaults to the decimals of the currency.
  • thousandSeparator - Defaults to ','. Used for separating thousands.
  • decimalSeparator - Defaults to '.'. Used for separating the integer part from the decimal part.
  • significantDigits - Defaults to Infinity. Can limit the number of digits on the decimal part, such that either the total number of displayed digits is equal to this parameter or more digits are displayed, but the decimal part is missing.
  • useFixedPrecision - Defaults to false. Switches from using significant digits to fixed precision digits.
  • fixedPrecisionDigits - Defaults to 0. Can specify the number of digits on the decimal part.
  • prefix - Defaults to ''. Prepended to the result.
  • suffix - Defaults to ''. Appended to the result. Other variants of Currency include FiatCurrency, NativeCurrency and Token. FiatCurrency takes the same parameters as Currency but uses fixed precision digits by default. NativeCurrency additionally takes a chainId parameter. The format function is configured with the ticker prefix and 6 significant digits by default. Token additionally takes a chainId parameter as well as an address parameter. The format function is configured with the ticker prefix and 6 significant digits by default.

CurrencyValue​

The CurrencyValue class represents a value tied to a currency. The methods include:

  • static fromString(currency, value) - creates a new CurrencyValue from string.
  • static zero(currency) - creates a new CurrencyValue equal to 0.
  • toString() - returns the value of the CurrencyValue as a decimal string with no formatting.
  • format(overrideOptions?) - formats the value according to the currency. The caller can override the formatting options.
  • map(fn) - returns a new CurrencyValue with value transformed by the callback.
  • add(other) - returns a new CurrencyValue with value being the sum of this value and other value. The argument must be a CurrencyValue with the same Currency.
  • sub(other) - returns a new CurrencyValue with value being the difference of this value and other value. The argument must be a CurrencyValue with the same Currency.
  • mul(value) - returns a new CurrencyValue with value multiplied by the argument.
  • div(value) - returns a new CurrencyValue with value divided by the argument.
  • mod(value) - returns a new CurrencyValue with value modulo the argument.
  • equals(other) - performs an equality check on the currencies and the values of both objects.
  • lt(other) - checks if this value is less than the other value. The argument must be a CurrencyValue with the same Currency.
  • lte(other) - checks if this value is less than or equal to the other value. The argument must be a CurrencyValue with the same Currency.
  • gt(other) - checks if this value is greater than the other value. The argument must be a CurrencyValue with the same Currency.
  • gte(other) - checks if this value is greater than or equal to the other value. The argument must be a CurrencyValue with the same Currency.
  • isZero() - returns true if the value is zero.

Config​

useDApp configuration.

Fields

  • autoConnect: boolean - Enables reconnecting to last used provider when user revisits the page.

    Default value

    true

  • bufferGasLimitPercentage: number Flags:

    note

    The flag is deprecated and it is not recommended to use it.

  • connectors: Object - Specify configuration of the wallets that can be used in the app

    Default value

    {
     metamask: new MetamaskConnector(),
    }

  • fastMulticallEncoding: boolean - When set to true, improves performance by using optimized encoders and decoders for multicall data.

    Flags:

    note

    The flag is experimental and is not fully tested yet.

    Default value

    false

  • gasLimitBufferPercentage: number - If set, adds an additional buffer to estimated gas limit before sending a transaction. Useful if a gas limit of a transaction can be different depending on the state of the blockchain. Gas estimation can be not accurate because the state of the blockchain can change between the time of estimation and the time of transaction mining.

  • localStorage: Object - Paths to locations in local storage.

    Default value

    {
      transactionPath: 'transactions'
    }

  • localStorageOverride: Storage - Optional Local storage override for use in environments like React Native

  • multicallAddresses: MulticallAddresses - Mapping of ChainId's to multicall contract addresses on the chain.
  • multicallVersion: 1 | 2 - Version of multicall contract on the chain.

  • networks: Chain[] - List of intended supported chain configs. If a user tries to connect to an unsupported chain an error value will be returned by useEthers. Check the full list in chain

    Default value

    DEFAULT_SUPPORTED_CHAINS // [Localhost, Hardhat, Mainnet, Ropsten, Rinkeby, Goerli, Kovan, ...]

  • noMetamaskDeactivate: boolean - Don't listen on disconnect event from Metamask. Might be useful in dealing with this Metamask bug.

    Flags:

    note

    The flag is experimental and is not fully tested yet.

    Default value

    false

  • notifications: Object - Notifications options.

    Default value

    {
      checkInterval: 500,
      expirationPeriod: 5000,
    }

  • pollingInterval: number - Default polling interval [ms] for a new block.

    Default value

    15000

  • pollingIntervals: PollingIntervals - Polling intervals for new blocks on specific chains.

  • readOnlyChainId: number - ChainId of a chain you want to connect to by default in a read-only mode

  • readOnlyUrls: NodeUrls - Mapping of ChainId's to node URLs to use in read-only mode.

    Example

    {
      ...
      readOnlyUrls: {
        [Mainnet.chainId]: 'https://mainnet.infura.io/v3/xxx',
        [Goerli.chainId]: getDefaultProvider('goerli')
      }
    }

  • refresh: number | "never" | "everyBlock" - Refresh standard calls each time the n-th block is mined.

  • supportedChains: number[] - List of intended supported chains. If a user tries to connect to an unsupported chain an error value will be returned by useEthers.

    Flags:

    note

    The flag is deprecated and it is not recommended to use it.

    Default value

    [ChainId.Mainnet, ChainId.Goerli, ChainId.Kovan, ChainId.Rinkeby, ChainId.Ropsten, ChainId.xDai]

LogsResult​

Result of a useLogs query.

It is undefined when the query didn't return yet or one of the following objects:

  • { value: DetailedEventRecord[], error: undefined }, if the query succeeded,
  • { value: undefined, error: Error }, if the query failed.

Type DetailedEventRecord represents a single event (log) on a typed contract:

type DetailedEventRecord<T extends TypedContract, EN extends ContractEventNames<T>> = {
  data: EventRecord<T, EN>
  blockNumber: number
  blockHash: string
  transactionIndex: number
  transactionHash: string
  removed: boolean
}

Additional resources related to events can be found here.

QueryParams​

Optional overrides for hooks querying the state of the blockchain.

Fields

  • chainId: ChainId - ChainId of the chain you want to perform the query on. Defaults to the chainId of the connected wallet. See ChainId
  • isStatic: boolean - Whether the query is static (not expected to change between calls). Used for optimizations.
  • refresh: number | "never" | "everyBlock" - Refresh call each time the n-th block is mined.

RawCall​

Represents a single call on the blockchain that can be included in multicall.

Fields

  • address: string - address of a contract to call
  • chainId: ChainId - chain id of the chain to perform the call on
  • data: string - calldata of the call that encodes function call
  • isStatic: boolean - Whether the call is static (not expected to change between calls). Used for optimizations.
  • lastUpdatedBlockNumber: number - number of last updated block
  • refreshPerBlocks: number - number of blocks to wait before updating the call

RawCallResult​

Result of a useRawCall query.

It is undefined when call didn't return yet or object { success: boolean, value: string } if it did.

  • success - boolean indicating whether call was successful or not,
  • value - encoded result when success is true or encoded error message when success is false.

TransactionOptions​

Represents a options for sending transactions. All fields are optional.

Fields:

  • signer?: Signer - specifies signer for a transaction.
  • transactionName?: string - specifies a transaction name. Used by notifications and history hooks.
  • gasLimitBufferPercentage?: number - If set, adds an additional buffer to estimated gas limit before sending a transaction. Useful if a gas limit of a transaction can be different depending on the state of the blockchain. Gas estimation can be not accurate because the state of the blockchain can change between the time of estimation and the time of transaction mining. This will add additional 10% of gasLimit to estimates:
gasLimitBufferPercentage: 10

TransactionState​

Represents current state of a transaction.

Can be one of the following:

  • None - before a transaction is created.
  • Pending signature - when a transaction has been initiated, but requires signature.
  • Mining - when a transaction is sent to the network, but not yet mined. In this state transaction: TransactionResponse is available.
  • Success - when a transaction has been mined successfully. In this state transaction: TransactionResponse and receipt: TransactionReceipt are available.
  • Fail - when a transaction has been mined, but ended up reverted. Again transaction: TransactionResponse and receipt: TransactionReceipt are available.
  • Exception - when a transaction hasn't started, due to the exception that was thrown before the transaction was propagated to the network. The exception can come from application/library code (e.g. unexpected exception like malformed arguments) or externally (e.g user discarded transaction in Metamask). In this state the errorMessage: string is available (as well as exception object).
  • CollectingSignaturePool - when user is sending transaction by Multisig wallet (Gnosis Safe) and is waiting for other owners to sign the transaction.

TransactionStatus​

Represents a state of a single transaction.

Fields

  • chainId: number - optional field. See ChainId. Available when status is not None.
  • errorCode: number - string that can contain one of None PendingSignature Mining Success Fail Exception CollectingSignaturePool
  • errorHash: string - string that can contain one of None PendingSignature Mining Success Fail Exception CollectingSignaturePool
  • errorMessage: string - optional field that contains error message when transaction fails or throws.
  • originalTransaction: TransactionResponse - string that can contain one of None PendingSignature Mining Success Fail Exception CollectingSignaturePool
  • status: TransactionState - Current state of the transaction. See TransactionState.
  • transactionName: string

Change in state will update the component so you can use it in useEffect.

TypedFilter​

Represents a filter of logs emitted on a typed contract. To be used with the useLogs hook.

Fields

  • args: any[]

  • contract: Contract

  • event: string

Example

const filter: TypedFilter = {
  contract: token,
  event: 'Transfer',
  args: [null, deployer.address],
}