@uma/contracts-node
v0.4.25
Published
UMA smart contracts and unit tests
Downloads
9,940
Keywords
Readme
@uma/contracts-node
This package exports all UMA smart contract artifacts specifically meant for consumption in nodejs.
Installing the package
yarn add @uma/contracts-node
Importing artifacts directly
To import artifacts directly into your tool of choice, the index file provides convenient functions for doing so:
const { getAbi, getBytecode, getAddress } = require("@uma/contracts-node")
// Gets the abi object for the Voting contract.
// This will be needed to interact with the voting contract.
const votingAbi = getAbi("Voting")
// Gets the bytecode string for the voting contract.
// This should usually only be required if you need to deploy a voting contract (rare).
const votingBytecode = getBytecode("Voting")
// Gets the address of the voting contract for chain id 1 (eth mainnet).
// If there is no single canonical deployment of a particular contract on the network provided, this will fail.
const chainId = 1
const votingAddress = getAddress("Voting", chainId)
Typescript!
Typescript is fully supported for all of the above operations:
import { getAbi, getBytecode, getAddress } from "@uma/contracts-node";
...
In addition to artifact support, typescript types (and sometimes factories) are available for ethers and web3.
Ethers
The best support is for Ethers contract types. To construct an Ethers contract, import one of the ethers factories:
import { VotingEthers__factory, getAddress } from "@uma/contracts-node" // Factory to create ethers instance.
import type { VotingEthers } from "@uma/contracts-node" // Type for ethers instance.
const NETWORK_ID = 1
const VOTING_ADDRESS = getAddress("Voting", NETWORK_ID)
// Note: the explicit type here isn't necessary -- this is just provided to document what VotingEthers is.
const votingInstance: VotingEthers = VotingEthers__factory.connect(VOTING_ADDRESS, providerOrSigner)
Web3
Web3 factories are not provided, but web3 contract types are. They can be used as follows:
import type { VotingWeb3 } from "@uma/contracts-node"
import { getAbi, getAddress, getBytecode } from "@uma/contracts-node"
const VOTING_ABI = getAbi("Voting")
const NETWORK_ID = 1
const VOTING_ADDRESS = getAddress("Voting", NETWORK_ID)
// Create a voting instance to represent a pre-deployed voting contract.
const voting = new web3.eth.Contract(VOTING_ABI, VOTING_ADDRESS) as VotingWeb3
// Or you can create a new voting instance using the bytecode.
const VOTING_BYTECODE = getBytecode("Voting")
const newVotingInstance = (await new web3Instance.eth.Contract(VOTING_ABI, undefined)
.deploy({ data: VOTING_BYTECODE, arguments: VOTING_ARGS })
.send({ from: YOUR_ADDRESS })) as VotingWeb3
Testing
This package works well with hardhat test. If you use hardhat-deploy to set up deployments in hardhat, getAddress
should recognize them.
// Note: if running directly from node rather than inside hardhat, you will need to manually set global.hre.
// @uma/contracts-node uses the global object to detect hardhat. For hardhat tests, this step should be
// unnecessary.
global.hre = require("hardhat");
const { getAddress } = require("@uma/contracts-node");
...
// hre.deployments.deploy deploys and saves the deployment.
await hre.deployments.deploy("Voting", { args: YOUR_ARGS, from: YOUR_ADDRESS });
// To add an address deployed without .deploy
// hre.deployments.save("Voting", { address: VOTING_ADDRESS, abi: VOTING_ABI });
// Address should be pulled out as expected.
const address = getAddress("Voting", parseInt(await hre.getChainId()));
Adding contracts from external packages
To add external package contracts, the external package must be set up in a particular way. Most of it is standard hardhat, but a few exports must be added specifically.
Requirements
The external package must export:
- All hardhat artifacts that it wants this package to re-export.
- Typechain types under
/typechain
. It must include web3 and ethers typechain exports. - A special json file at the path
/build/artifacts.json
that describes the location of all hardhat artifacts. This JSON file is a simple json array of objects, each object having a field calledrelativePath
that is the path from the root to each hardhat artifact. The artifact's filename must match the contract name. - A folder at
/networks
following the same structure as/packages/core/networks
in this repository for any contract addresses that it wants to add.
Adding an external package
To add an external package:
- Add the external package name to the
EXTERNAL_PACKAGES
array in/packages/common/hardhat/tasks/artifacts.ts
. - Add the external package to this package as a
devDependency
. - Copy the
copy-across-types
package.json script in this package replacing the name and@across-protocol/contracts
with the new package. - Add your new package.json script to the
generate-ts
script in package.json similar to howcopy-across-types
is. - Add similar
include
andexclude
paths for your package's artifacts in thetsconfig.json
as exist for@across-protocol/contracts
.