artifact-index.md

The artifact index

This document provides an overview of what the artifact index is and how it works. The reason the artifact index was created was that we needed a way to provide different versions of a contract to the user of the uport-identity module. Truffle provides great artifacts of contracts and populates them with addresses on the networks which it has been deployed, but what if we update a contract and redeploy the new version? Then the old address would not be available this versioned index of artifacts solves this.

Structure

The artifact index consists of two structures, one on the filesystem and one javascript object.

File system structure

An example layout looks as following:

build/contracts/
├── Contract1.json
├── Contract2.json
├── Contract3.json
├── Migrations.json
├── legacy
│   ├── OldContract1.json
│   └── OldContract2.json
└── versions
    ├── v1
    │   ├── Contract1.json
    │   ├── Contract2.json
    │   └── Contract3.json
    └── v2
        ├── Contract1.json
        └── Contract3.json

Here the root folder build/contracts/ always contains the artifacts generated by truffle. When you deploy a contract to a new network only the artifacts in this root folder will be updated by truffle. The legacy folder contains old contracts that are not actively used but are kept for supportability. The versions folder contains all different versions of the contract artifacts. So if you want to use the previously deployed version of Contract1 you have to import the artifact from the v1 folder.

javascript object

A javascript object is maintained to create easy access to all different versions of the artifact. This object is exported in the file artifact-index.js and is the main entry to the uport-identity module. If generated from the example above it would get the following format:

module.exports = {
  legacy: {
    OldContract1: require('./build/contracts/legacy/OldContract1.json'),
    OldContract2: require('./build/contracts/legacy/OldContract2.json'),
  },
  Contract1: {
    latestVersion: 'v2',
    v1: require('./build/contracts/versions/v1/Contract1.json'),
    v2: require('./build/contracts/versions/v2/Contract1.json'),
  },
  Contract2: {
    latestVersion: 'v1',
    v1: require('./build/contracts/versions/v1/Contract2.json'),
  },
  Contract3: {
    latestVersion: 'v2',
    v1: require('./build/contracts/versions/v1/Contract3.json'),
    v2: require('./build/contracts/versions/v2/Contract3.json'),
  }
}

Building the index

After you have deployed a contract only the artifacts in the build/contracts/ folder will be updated by truffle. We therefore have the following command:

$ yarn build-artifact-index

This command checks if there are any changes to the artifacts created by truffle compared to the latest version of each artifact. If there are changes it makes copies of the relevant artifacts and places them in the correct version folder. It then generates and outputs the artifact-indes.js file.