πŸ–‡ Eth-Hooks Overview
Commonly used Ethereum hooks.
Commonly used Ethereum hooks.
Used by πŸ— scaffold-eth Used by βš™ eth-components​
Created by 🏰 BuidlGuidl.eth​

Install

yarn add eth-hooks

Authors

Peer Dependencies

  • react & general
    • react
    • react-dom
  • web3
    • @uniswap/sdk

API

Hooks & Helpers

useExchangeEthPrice β‡’
Get the Exchange price of ETH/USD (extrapolated from WETH/DAI)
useTokenList β‡’
Gets a tokenlist (see more at https://tokenlists.org/), returning the .tokens only
~ How can I use? ~ const tokenList = useTokenList(); <- default returns the Unsiwap tokens const tokenList = useTokenList("https://gateway.ipfs.io/ipns/tokens.uniswap.org");
useLookupAddress β‡’
Gets ENS name from given address and provider
useResolveEnsName β‡’
Gets the address from an ENS name and provider
useTokenBalance β‡’
Get the balance of an ERC20 token in an address
~ Features ~
  • Provide address and get balance corresponding to given address
  • Change provider to access balance on different chains (ex. mainnetProvider)
  • If no pollTime is passed, the balance will update on every new block
useEventListener β‡’
Enables you to keep track of events
~ Features ~
  • Provide readContracts by loading contracts (see more on ContractLoader.js)
  • Specify the name of the contract, in this case it is "YourContract"
  • Specify the name of the event in the contract, in this case we keep track of "SetPurpose" event
  • Specify the provider
parseProviderOrSigner β‡’
Parse TEthersProviderOrSigner to TProviderAndSigner
useBalance β‡’
Gets your balance in ETH from given address and provider
~ Features ~
  • Provide address and get balance corresponding to given address
  • Change provider to access balance on different chains (ex. mainnetProvider)
  • If no pollTime is passed, the balance will update on every new block
useBlockNumber β‡’
Get the current block number of the network
useBurnerSigner β‡’
A hook that creates a buner address and returns a Signer
useContractExistsAtAddress β‡’
Checks whether a contract exists on the blockchain, returns true if it exists, otherwise false
~ Features ~
  • Provide contractAddress to check if the contract is deployed
  • Change provider to check contract address on different chains (ex. mainnetProvider)
useContractLoader β‡’
Loads your local contracts and gives options to read values from contracts or write transactions into them
~ Features ~
  • localProvider enables reading values from contracts
  • userProvider enables writing transactions into contracts
  • Example of keeping track of "purpose" variable by loading contracts into readContracts and using ContractReader.js hook: const purpose = useContractReader(readContracts,"YourContract", "purpose")
  • Example of using setPurpose function from our contract and writing transactions by Transactor.js helper: tx( writeContracts.YourContract.setPurpose(newPurpose) )
config can include:
  • chainId - to hardcode the chainId, irrespective of the providerOrSigner chainId
  • hardhatNetworkName - to hardcode the hardhat network of interest
  • customAddresses: { contractName: 0xCustomAddress } to hardcode the address for a given named contract
  • hardhatContracts: object following the hardhat deploy export format (Json with chainIds as keys, which have hardhat network names as keys, which contain arrays of contracts for each)
  • externalContracts: object with chainIds as keys, with an array of contracts for each
useContractReader β‡’
Enables you to call functions in contracts and read their values. It helps keep track of them in the local React states
~ Features ~
  • Provide readContracts by loading contracts (see more on ContractLoader.js)
  • Specify the name of the contract, in this case it is "YourContract"
  • Specify the name of the variable in the contract, in this case we keep track of "purpose" variable
  • Pass an args array if the function requires
  • Pass pollTime - if no pollTime is specified, the function will update on every new block
useGasPrice β‡’
Gets the gas price from Eth Gas Station
useNonce β‡’
Get the current nonce of the address provided
useOnBlockuseOnRepetition
A hook will invoke a callback regularly on the "block" event. Alternatively, If a pollTime is provided, it will use that instead. The minumum polling time is 10s
  • the hook will invoke the callback when the leadTrigger changes state to true as a leading invokation
usePolleruseTimestamp β‡’
Get the current timestamp from the latest block
useUserAddress β‡’
Get the address from the current signer or provider
useUserProviderAndSigner β‡’
Gets user provider/signer from injected provider or local provider Use your injected provider from 🦊 Metamask If you don't have it then instantly generate a πŸ”₯ burner wallet from a local provider
~ Features ~
  • Specify the injected provider from Metamask
  • Specify the local provider
  • Usage examples: const tx = Transactor(userSigner, gasPrice)

useExchangeEthPrice β‡’

Get the Exchange price of ETH/USD (extrapolated from WETH/DAI)
Kind: global constant Returns: (number) :: price
Param
Description
targetNetwork
(TNetwork)
mainnetProvider
(TEthersProvider)
pollTime
(number) :: if >0 use polling, else use instead of onBlock event

useTokenList β‡’

Gets a tokenlist (see more at https://tokenlists.org/), returning the .tokens only
~ How can I use? ~ const tokenList = useTokenList(); <- default returns the Unsiwap tokens const tokenList = useTokenList("https://gateway.ipfs.io/ipns/tokens.uniswap.org");
Kind: global constant Returns: (TokenInfo[])
Param
Description
tokenListUri
(string)
chainId
(number)

useLookupAddress β‡’

Gets ENS name from given address and provider
Kind: global constant Returns: (string) ens name
Param
Description
provider
(TEthersProvider)
address
(string)

useResolveEnsName β‡’

Gets the address from an ENS name and provider
Kind: global constant Returns: (string) :: address
Param
Description
provider
(TEthersProvider)
ensName
(string)

useTokenBalance β‡’

Get the balance of an ERC20 token in an address
~ Features ~
  • Provide address and get balance corresponding to given address
  • Change provider to access balance on different chains (ex. mainnetProvider)
  • If no pollTime is passed, the balance will update on every new block
Kind: global constant Returns: (BigNumber) :: balance
Param
Description
contract
(ethers->Contract) contract object for the ERC20 token
address
(string)
pollTime
(number) :: if >0 use polling, else use instead of onBlock event

useEventListener β‡’

Enables you to keep track of events
~ Features ~
  • Provide readContracts by loading contracts (see more on ContractLoader.js)
  • Specify the name of the contract, in this case it is "YourContract"
  • Specify the name of the event in the contract, in this case we keep track of "SetPurpose" event
  • Specify the provider
Kind: global constant Returns: (ethers->Event)
Param
Description
contracts
(Record<string, Contract>) :: record of current contractname/contract
contractName
(string) :: name of the contract you are interested in
eventName
(string) :: name of the event
provider
(TEthersProvider)
startBlock
(number) string block of events

parseProviderOrSigner β‡’

Parse TEthersProviderOrSigner to TProviderAndSigner
Kind: global constant Returns: TProviderAndSigner
Param
Description
providerOrSigner
TEthersProviderOrSigner

useBalance β‡’

Gets your balance in ETH from given address and provider
~ Features ~
  • Provide address and get balance corresponding to given address
  • Change provider to access balance on different chains (ex. mainnetProvider)
  • If no pollTime is passed, the balance will update on every new block
Kind: global constant Returns: (Bignumber) :: current balance
Param
Description
provider
(ethers->Provider)
address
(string)
pollTime
(number) :: if >0 use polling, else use instead of onBlock event

useBlockNumber β‡’

Get the current block number of the network
Kind: global constant Returns: (number) :: block number
Param
Description
provider
(TEthersProvider)
pollTime
(number) :: if >0 use polling, else use instead of onBlock event

useBurnerSigner β‡’

A hook that creates a buner address and returns a Signer
Kind: global constant Returns: (ethers.signer) :: signer of the wallet
Param
Description
provider
(TEthersProvider)

useContractExistsAtAddress β‡’

Checks whether a contract exists on the blockchain, returns true if it exists, otherwise false
~ Features ~
  • Provide contractAddress to check if the contract is deployed
  • Change provider to check contract address on different chains (ex. mainnetProvider)
Kind: global constant Returns: (boolean)
Param
Description
provider
(TEthersProvider)
contractAddress
(string)

useContractLoader β‡’

Loads your local contracts and gives options to read values from contracts or write transactions into them
~ Features ~
  • localProvider enables reading values from contracts
  • userProvider enables writing transactions into contracts
  • Example of keeping track of "purpose" variable by loading contracts into readContracts and using ContractReader.js hook: const purpose = useContractReader(readContracts,"YourContract", "purpose")
  • Example of using setPurpose function from our contract and writing transactions by Transactor.js helper: tx( writeContracts.YourContract.setPurpose(newPurpose) )
config can include:
  • chainId - to hardcode the chainId, irrespective of the providerOrSigner chainId
  • hardhatNetworkName - to hardcode the hardhat network of interest
  • customAddresses: { contractName: 0xCustomAddress } to hardcode the address for a given named contract
  • hardhatContracts: object following the hardhat deploy export format (Json with chainIds as keys, which have hardhat network names as keys, which contain arrays of contracts for each)
  • externalContracts: object with chainIds as keys, with an array of contracts for each
Kind: global constant Returns: (Record<string, Contract>) :: a record of contractName:contract
Param
Description
providerOrSigner
(TEthersProviderOrSigner)
config
(TContractConfig) :: configuration for loader

useContractReader β‡’

Enables you to call functions in contracts and read their values. It helps keep track of them in the local React states
~ Features ~
  • Provide readContracts by loading contracts (see more on ContractLoader.js)
  • Specify the name of the contract, in this case it is "YourContract"
  • Specify the name of the variable in the contract, in this case we keep track of "purpose" variable
  • Pass an args array if the function requires
  • Pass pollTime - if no pollTime is specified, the function will update on every new block
Kind: global constant Returns: () :: generic return type
Param
Description
contracts
(Record<string, Contract>) :: a record of contractName/contract
contractName
(string) :: The contract name
functionName
(string) :: The function name in the contract
functionArgs
(any[]) :: arguments to functions
pollTime
(number) :: optional :: if >0 use polling, else use instead of onBlock event
formatter
((_value: T) => T) :: optional :: function to format the result
onChange
(string) :: optional :: callback to call with the function

useGasPrice β‡’

Gets the gas price from Eth Gas Station
Kind: global constant Returns: (number) gas price in gwei
Param
Description
targetNetwork
(TNetwork)
speed
(TGasStationSpeed) 'fast', 'fastest', 'safeLow', 'average'
pollTime
(number) :: if > 0 use polling, else use instead of onBlock event

useNonce β‡’

Get the current nonce of the address provided
Kind: global constant Returns: (number) nonce
Param
Description
provider
(TEthersProvider)
address
(string)
pollTime
(number) :: if >0 use polling, else use instead of onBlock event

useOnBlock

Kind: global constant See: useOnRepetition for a newer implementation helper hook to call a function regularly at time intervals when the block changes.
Param
Description
provider
ethers/web3 provider
callbackFn
any function
args
function parameters

useOnRepetition

A hook will invoke a callback regularly on the "block" event. Alternatively, If a pollTime is provided, it will use that instead. The minumum polling time is 10s
  • the hook will invoke the callback when the leadTrigger changes state to true as a leading invokation
Kind: global constant
Param
Description
callback
(func) :: callback funciton, can have variable args
options
(TOptions)
args
varargs callback function arguments

usePoller

Kind: global constant See: useOnRepetition for a newer implementation helper hook to call a function regularly in time intervals
Param
callbackFn
delay
extraWatch

useTimestamp β‡’

Get the current timestamp from the latest block
Kind: global constant Returns: (number) :: timestamp
Param
Description
provider
(TEthersProvider)
pollTime
(number) :: if >0 use polling, else use instead of onBlock event

useUserAddress β‡’

Get the address from the current signer or provider
Kind: global constant Returns: (string) :: address
Param
Description
providerOrSigner
(TEthersProviderOrSigner)

useUserProviderAndSigner β‡’

Gets user provider/signer from injected provider or local provider Use your injected provider from 🦊 Metamask If you don't have it then instantly generate a πŸ”₯ burner wallet from a local provider
~ Features ~
  • Specify the injected provider from Metamask
  • Specify the local provider
  • Usage examples: const tx = Transactor(userSigner, gasPrice)
Kind: global constant Returns: (TProviderAndSigner)
Param
Description
injectedProviderOrSigner
(TEthersProviderOrSigner) :: injected provider/signer from metamask etc..
localProvider
(TEthersProvider) local provider to generate a burner wallet from
Last modified 11mo ago
Copy link
On this page
Install
Authors
Peer Dependencies
API
Hooks & Helpers
useExchangeEthPrice β‡’
useTokenList β‡’
useLookupAddress β‡’
useResolveEnsName β‡’
useTokenBalance β‡’
useEventListener β‡’
parseProviderOrSigner β‡’
useBalance β‡’
useBlockNumber β‡’
useBurnerSigner β‡’
useContractExistsAtAddress β‡’
useContractLoader β‡’
useContractReader β‡’
useGasPrice β‡’
useNonce β‡’
useOnBlock
useOnRepetition
usePoller
useTimestamp β‡’
useUserAddress β‡’
useUserProviderAndSigner β‡’