Oz-console 2.0 released (Ethers based console)

oz-console has been significantly updated, and now is able to use the OZ network configuration for simplicity.

Previous, the network configuration was a pain. Now it more deeply integrates with OZ CLI to pull from the OZ network config.

For example:

$ oz-console -n mainnet

And it will launch a console populated with Ethers.js instance of interfaces, contracts, etc. A signer will be provided that corresponds to the OZ ‘from’ address, or one can be passed in.

1 Like

Hi @asselstine,

Thanks for sharing :pray:

Is there an example of how to use it? e.g. how to interact with a deployed contract.

Yes! I’ve updated the readme with some examples. I’ll add it here as well:

OpenZeppelin Ethers Console

Provides an Ethers.js based console to interact with your contracts.


$ yarn add oz-console


oz-console can be used from the command line or programmatically.

For example: let’s assume you have an ERC20 called MyToken that is deployed to mainnet.

Let’s interact with the contract:

# Contracts should be deployed and compiled
$ oz-console -n mainnet

Now we’re in oz-console:

// contracts contains Ethers.js Contract instance of all deployed contracts
mainnet> await contracts.MyToken.totalSupply()
// await here is redundant, but demonstrates that the syntax is supported

Or get the ether balance:

// provider and contracts are available in the environment
mainnet> provider.getBalance(contracts.MyToken.address)

Create contracts on-the-fly:

// ethers, signers, and artifacts are available in the enviroment
mainnet> let MyToken2 = new ethers.Contract('0x1234...', artifacts.MyToken.abi, signer)

For a complete reference of what variables are available in the global context see below.

CLI Help

Usage: oz-console [options]

Provides an Ethers.js based console to interact with your OpenZeppelin SDK project.  Supports await syntax.  Includes global variables:
  artifacts: Every project contract discovered, including ProxyAdmin
  interfaces: An Ethers interface for each artifact discovered
  contracts: An Ethers contract for each *deployed* artifact.  Includes ProxyAdmin.
  provider: an ethers provider
  signer: a signer for the configured OZ 'from' address
  ethers: the ethers lib

  -n, --network <network name>                  selects the openzeppelin network to use (default: "mainnet")
  -p, --projectConfig <oz project config path>  sets the project config path (default: ".openzeppelin/project.json")
  -v, --verbose                                 enable verbose logging.  useful for diagnosing errors
  -e, --exec <js file path>                     executes a javascript file instead of running a REPL
  -a, --address <from address>                  use the address as the signer
  -h, --help                                    shows this help

Programmatic Usage

Use buildContext to setup the environment programmatically

const { buildContext } = require('oz-console')

const context = buildContext({
  network: 'mainnet'

// Ethers
// OpenZeppelin CLI ProjectFile object
// Artifact JSON blobs
// Ethers Interfaces for each artifact
// Ethers Contract for each deployed contract
// Ethers provider
// Ethers signer for the OZ 'from' address
// OpenZeppelin CLI NetworkFile object
// OpenZeppelin CLi NetworkConfig object
1 Like

Hi @asselstine,

This is really awesome. :pray:

Using my favourite Box contract (https://docs.openzeppelin.com/learn/developing-smart-contracts#setting-up-a-solidity-project)


// contracts/Box.sol
pragma solidity ^0.5.0;

contract Box {
    uint256 private value;

    // Emitted when the stored value changes
    event ValueChanged(uint256 newValue);

    // Stores a new value in the contract
    function store(uint256 newValue) public {
        value = newValue;
        emit ValueChanged(newValue);

    // Reads the last stored value
    function retrieve() public view returns (uint256) {
        return value;

Deploy using the CLI

$ npx oz deploy
✓ Compiled contracts with solc 0.5.17 (commit.d19bba13)
? Choose the kind of deployment regular
? Pick a network development
? Pick a contract to deploy Box
✓ Deployed instance of Box

Interact using oz-console

Store and retrieve a value

$ npx oz-console -n development
development> await contracts.Box.store(42)
{ hash:
  blockNumber: 2,
  transactionIndex: 0,
  confirmations: 1,
  from: '0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1',
  gasPrice: BigNumber { _hex: '0x4a817c800' },
  gasLimit: BigNumber { _hex: '0xa611' },
  to: '0xe78A0F7E598Cc8b0Bb87894B0F60dD2a88d6a8Ab',
  value: BigNumber { _hex: '0x0' },
  nonce: 1,
  v: 38,
  creates: null,
  networkId: 1,
  chainId: 1,
  wait: [Function] }
development> (await contracts.Box.retrieve()).toString()
1 Like

Easy peasy! I’m glad you like it. I find it to be an essential tool.

1 Like

Hi @asselstine,

I wanted to check the network ID of a ganache-cli quickly, so I installed and used oz-console.

$ npx oz-console -n development
development> provider.getNetwork()
{ chainId: 1588737945659, name: 'unknown' }

It is a great addition to my tool box. Thank you. :pray:
It looks like I was the first stargazer: https://github.com/pooltogether/oz-console/stargazers :star:

1 Like