OpenZeppelin Quick Reference for the Busy Hacker

Greetings, dear hacker! If you are reading this, you are probably about to embark on a coding marathon, and want to spend as much time as you can coding to bring your ideas to life - without losing time to complex setups, navigating through lengthy documentations, or having to reinvent the wheel. We want to do our best to help you, so we are providing you with quick pointers on how to leverage the OpenZeppelin set of open source tools & libraries, to make the most out of your time hacking!

101 Guides for the Ethereum beginner

If this is one of your first experiences building on Ethereum, our Learning guides may be of help. These will guide you through every step of the journey: from setting up a new Node project and writing Solidity smart contracts, to deploying your project on a public network.

Kickstart your DApp with Starter Kits

If you are building a DApp, you can save a lot of bootstrap time by leveraging one of our Starter Kits. The vanilla Starter Kit sports a create-react-app, includes OpenZeppelin Contracts managed by the CLI, imports Rimble UI components, and connects to testnet Infura nodes using OpenZeppelin network-js. It also includes our Solidity Hot Loader, so whenever you change a Solidity file, it will be automatically upgraded in your development environment!

You can check out a demo of the starter kit here, and quickly unpack it using the CLI:

$ npm install --global @openzeppelin/cli
$ oz unpack starter

There are additional Starter Kits, such as a Tutorial for learning how to build a DApp, a kit with GSN-powered meta-transactions already built-in, and one contributed by Provable with their Oracles ready-to-use.

Writing and Testing Contracts

If your focus is on writing Solidity contracts, then including the OpenZeppelin Contracts library is a must. You can find building blocks for easy signature checking, enumerable sets, safe math operations, ownership, and more. Contracts also includes vetted implementations for the most popular ERCs, such as ERC20 fungible tokens, ERC777 tokens, or ERC721 collectibles. The library also has first-class support for meta-transactions using the GSN.

Contracts is shipped as an npm package, so you can just npm install @openzeppelin/contracts and start using it right away:

pragma solidity ^0.5.0;

import "@openzeppelin/contracts/token/ERC721/ERC721Full.sol";

contract MyNFT is ERC721Full {
    constructor() ERC721Full("MyNFT", "MNFT") public { }

    function awardNFT(address player, uint256 id) public returns (id) {
      _mint(player, id);
      return id;

The current release of Contracts is built for Solidity 0.5. If you want to try the bleeding edge version built for Solidity 0.6, you can install @openzeppelin/contracts@beta to try the 3.0 beta!

Testing your contracts can be easily done with the OpenZeppelin Test Environment. This small library will set up a development blockchain behind the scenes, so you can run your tests on it using whatever runner you like. You can combine it with the OpenZeppelin Test Helpers for having handy assertions for your contracts!

npm install --save-dev @openzeppelin/test-environment @openzeppelin/test-helpers mocha chai

Writing contracts tests is now easy in any javascript project, with access to assertions on events or reverts, as well as available accounts and contracts:

const { accounts, contract } = require('@openzeppelin/test-environment');
const { expectEvent } = require('@openzeppelin/test-helpers');

const [ owner, player ] = accounts;
const MyNFT = contract.fromArtifact('MyNFT');

describe('MyNFT', function () {
  beforeEach(async function () {
    this.contract = await{ from: owner });

  it('awards an NFT to a player', async function () {
    const receipt = await this.contract.awardNFT(player, 42, { from: owner });
    expectEvent(receipt, 'Transfer', { to: player, tokenId: '42' });
    expect((await this.contract.ownerOf(42))).to.equal(player);

Rapid Prototyping from your Command Line

If you want to quickly interact with your contracts for rapid prototyping, the OpenZeppelin CLI is just for you. You only need to download the CLI, init your project, and spin up a local blockchain:

$ npm install --global @openzeppelin/cli ganache-cli
$ npm init -y && oz init
$ ganache-cli

With the CLI, you can easily compile & deploy your contracts, send transactions to them, and query them, all from the comfort of your command line:

$ oz create
✓ Compiled contracts with solc 0.5.9
? Pick a contract to instantiate: MyNFT
? Pick a network: development
✓ Contract MyNFT deployed

$ oz send-tx
? Pick a network: development
? Pick an instance: MyNFT at 0xCfEB869F69431e42cdB54A4F4f105C19C080A601
? Select which function: awardNFT(player: address, id: uint256)
? player (address): 0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0
? id (uint256): 10
✓ Transaction successful
Events emitted: Transfer(0x0, 0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0, 10)

$ oz call
? Pick a network: development
? Pick an instance: MyNFT at 0xCfEB869F69431e42cdB54A4F4f105C19C080A601
? Select which function: ownerOf(id: uint256)
? id (uint256): 10
✓ Method 'ownerOf()' returned: 0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0

Not only that, but you can also modify your Solidity code and upgrade your contracts, so you can make adjustments to your logic, while preserving state and the contract addresses!

$ oz upgrade
? Pick a network: development
✓ Contract MyNFT deployed
? Which instances would you like to upgrade?: All instances
Instance upgraded at 0xCfEB869F69431e42cdB54A4F4f105C19C080A601.

We hope you find the set of OpenZeppelin tools useful during the hackathon, and please share any issues or feedback you may have here on the forum. Best of luck, and happy hacking!