Network Files

OpenZeppelin Upgrades keep track of all the contract versions you have deployed in an .openzeppelin folder in the project root, as well as the proxy admin. You will find one file per network there. It is advised that you commit to source control the files for all networks except the development ones (you may see them as .openzeppelin/unknown-*.json).

The format of the files within the .openzeppelin folder is not compatible with those of the OpenZeppelin CLI. If you want to use these plugins for an existing OpenZeppelin CLI project, you have to migrate it first. See Migrate from CLI for instructions.

`<network_name>.json`

OpenZeppelin Upgrades will generate a file for each of the networks you work on (ropsten, mainnet, etc). These files share the same structure:

// .openzeppelin/<network_name>.json
{
  "manifestVersion": "3.0",
  "impls": {
    "...": {
      "address": "...",
      "txHash": "...",
      "layout": {
        "storage": [...],
        "types": {...}
      }
    },
    "...": {
      "address": "...",
      "txHash": "...",
      "layout": {
        "storage": [...],
        "types": {...}
      }
    }
  },
  "admin": {
    "address": "...",
    "txHash": "..."
  }
}

For every logic contract, besides the deployment address, the following info is also tracked:

types keeps track of all the types used in the contract or its ancestors, from basic types like uint256 to custom struct types
storage tracks the storage layout of the linearized contract, referencing the types defined in the types section, and is used for verifying that any storage layout changes between subsequent versions are compatible

The naming of the file will be <network_name>.json, but note that <network_name> is not taken from the name of the network’s entry in the Truffle or Hardhat configuration file, but is instead inferred from the chain id associated to the entry.

There is a limited set of public chains; Chains not on the list such as Ethereum Classic will have network files named unknown-<chain_id>.json.

Configuration Files in Version Control

Public network files like mainnet.json or ropsten.json should be tracked in version control. These contain valuable information about your project’s status in the corresponding network, like the addresses of the contract versions that have been deployed. Such files should be identical for all the contributors of a project.

However, local network files like unknown-<chain_id>.json only represent a project’s deployment in a temporary local network such as ganache-cli that are only relevant to a single contributor of the project and should not be tracked in version control.

An example .gitignore file could contain the following entries:

// .gitignore
# OpenZeppelin
.openzeppelin/unknown-*.json

Temporary Files

Hardhat development networks using Hardhat version 2.12.3 or later will have network files written to an openzeppelin-upgrades folder under the operating system’s temporary directory. These files are named hardhat-<chain_id>-<instance_id>.json, where <instance_id> is a 0x-prefixed hex id that uniquely identifies an instance/run of the Hardhat network. Files in this temporary folder can be safely deleted when their corresponding Hardhat network instance is no longer active, for example after Hardhat tests have finished.

You can determine the location of a temporary network file by doing the following:

Run export DEBUG=@openzeppelin:* to enable debug logging.
Run your Hardhat test or script.
Find the log message containing the text development manifest file:.