README.md

utility-emissions-channel

This project implements the Utility Emissions Channel Hyperledger Fabric network in a docker-compose setup and provides a REST API to interact with the blockchain. To see how it works, check out this video.

Running the Fabric network and Express API

1. Make sure you have Git, curl, Docker, and Docker Compose installed, or follow instructions from Hyperledger Fabric Install Prerequisites
2. From utility-emissions-channel/, copy over the Amazon Web Services (AWS) configuration template file with:

$ cp ./typescript_app/src/config/aws-config.js.template ./typescript_app/src/config/aws-config.js

3. If you want to use AWS S3 service to store documents, then fill in AWS credentials in typescript_app/src/config/aws-config.js:

    exports.AWS_ACCESS_KEY_ID = 'your_access_key';
    exports.AWS_SECRET_ACCESS_KEY = 'your_secret_key';
    exports.S3_LOCAL = true;
    exports.BUCKET_NAME = "local-bucket";

Otherwise leave it unchanged, and you will be able to store your documents locally with serverless.

4. From utility-emissions-channel/, copy over the Ethereum network configuration settings template file with:

$ cp ./typescript_app/src/config/networkConfig.ts.example ./typescript_app/src/config/networkConfig.ts

5. Fill in Ethereum configuration settings in typescript_app/src/config/networkConfig.ts:

    export const PRIVATE_KEY = "private_key_of_ethereum_dealer_wallet";
    export const CONTRACT_ADDRESS = "address_of_ethereum_contract_to_connect_to_on_goerli";
    export const INFURA_PROJECT_ID = "infura_id";
    export const INFURA_PROJECT_SECRET = "infura_secret";

6. Install the right binaries. You will need the linux binaries to run inside of docker, as well as the binaries for your operating system.

$ cd docker-compose-setup

Install binaries for linux distribution.

$ ./bootstrap.sh  2.2.1 1.4.9 -d -s

If you are using a Mac, you will also need to get the Mac binaries. In a separate directory, follow the steps from Hyperledger Fabric Install Samples and Binaries to install fabric-samples with a bin/ directory. Then move that bin/ directory over to a bin_mac/ directory inside docker-compose-setup. For example, I had installed fabric-samples in a hyperledger directory, so:

$ mv ~/hyperledger/fabric-samples/bin/ ./bin_mac/

Then modify the file utility-emissions-channel/docker-compose-setup/scripts/invokeChaincode.sh and change ./bin/peer to ./bin_mac/peer

7. Install the dependencies for the server. This is a temporary fix as reported in issue #71

From utility-emissions-channel/:

$ cd typescript_app
$ npm install

8. From utilities-emissions-channel/docker-compose-setup, run the start script (includes the reset script which resets the Fabric state):

Start network, create channel, and deployCC:

sh ./scripts/reset.sh && sh start.sh

9. Follow the instructions under Steps to seed the Fabric database to initialize the Fabric network with emissions data to pull from when recording emissions.

Seeding the Fabric database

To calculate emissions, we need data on the emissions from electricity usage. We're currently using the U.S. Environmental Protection Agency eGRID data, U.S. Energy Information Administration's Utility Identifiers, and European Environment Agency's Renewable Energy Share and CO2 Emissions Intensity. The Node.js script egrid-data-loader.js in utility-emissions-channel/docker-compose-setup/ imports this data into the Fabric network.

From utility-emissions-channel/docker-compose-setup/,

1. Install the dependencies:

$ npm install

2. Download and extract the EPA data:

$ wget https://www.epa.gov/sites/production/files/2020-01/egrid2018_all_files.zip
$ unzip egrid2018_all_files.zip

3. Download the utility identifiers from Form EIA-861 and extract:

$ wget https://www.eia.gov/electricity/data/eia861/zip/f8612019.zip
$ unzip f8612019.zip

4. Download the data from the European Environment Agency and extract the zip file.

5. Load utility emissions and identifiers data from the files. NOTE: There is a known issue with loading the European co2-emissions-intensity file on Mac OS X, so if you are looking to use this for European data, it will only work on Ubuntu:

$ node egrid-data-loader.js load_utility_emissions eGRID2018_Data_v2.xlsx NRL18
$ node egrid-data-loader.js load_utility_emissions eGRID2018_Data_v2.xlsx ST18
$ node egrid-data-loader.js load_utility_identifiers Utility_Data_2019.xlsx

$ node egrid-data-loader.js load_utility_emissions 2019-RES_proxies_EEA.csv Sheet1
$ node egrid-data-loader.js load_utility_emissions co2-emission-intensity-6.csv Sheet1

Viewing the seed data

Check the CouchDB interface at http://localhost:5984/_utils/ and look in the utilityemissionchannel_emissionscontract for the data stored in your ledger. The default CouchDB username and password are admin and adminpw.

More complex queries can be run with Mango at http://localhost:5984/_utils/#database/utilityemissionchannel_emissionscontract/_find. See tutorial on running Mango queries.

For example, to search for utility emissions factors, run the Mango query:

{
   "selector": {
      "class": {
         "$eq": "org.hyperledger.blockchain-carbon-accounting.utilityemissionsfactoritem"
      }
   }
}

To search for utility identifiers, run the Mango query:

{
   "selector": {
      "class": {
         "$eq": "org.hyperledger.blockchain-carbon-accounting.utilitylookupitem"
      }
   }
}

Recording emissions with chain code

From the utility-emissions-channel/docker-compose-setup directory, you can run a script to record and get the emissions:

# Record emission to utilityemissionchannel
$ sudo bash ./scripts/invokeChaincode.sh '{"function":"'recordEmissions'","Args":["USA_EIA_11208","MyCompany","2018-06-01T10:10:09Z","2018-06-30T10:10:09Z","150","KWH","url","md5"]}' 1 2

# Query emission data
$ sudo bash ./scripts/invokeChaincode.sh '{"function":"'getEmissionsData'","Args":["1"]}' 1

You should also be able to see your emissions records in Couchdb with a Mango query:

{
   "selector": {
      "class": {
         "$eq": "org.hyperledger.blockchain-carbon-accounting.emissionsrecord"
      }
   }
}

Starting the Express server (REST API)

This is normally done for you in the start.sh script, but you can also start it manually. From the utility-emissions-channel/ directory:

$ cd typescript_app
$ npm i
$ cd ..
$ ./scripts/startApi.sh

4. Go to http://localhost:9000/api-docs/ to use the API.

Working with the Express Server API

First register an organization using /registerEnroll/admin:

{
  "orgName": "auditor1"
}

Next register a user under this organization with /registerEnroll/user:

{
  "userId": "testuser1",
  "orgName": "auditor1",
  "affiliation": "auditor1.department1"
}

Now you can record emissions with different energyUseAmount over different dates with /emissionscontract/recordEmissions. Be sure that your dates do not overlap. For testing, you may use utilityId 11208 for Los Angeles Department of Water and Power.

You can verify that that your emissions can be successfully retrieved using /emissionscontract/getAllEmissionsDataByDateRange.

Shutting Down

From the docker-compose-setup/ directory:

$ ./network.sh down

To shut down and then reset everything:

$ sh ./scripts/reset.sh

Integrating with the Net Emissions Token Network integration

Through an endpoint in the REST API, you can retrieve a series of emissions records by date range and issue an Audited Emissions Token based on this data. This currently works with public Ethereum networks, such as the Goerli testnet.

To set it up, Edit typescript_app/src/config/networkConfig.ts:

• Set IS_GOERLI to true.
• Set the contract address on Goerli, your Infura keys, and the private key of your audited emissions dealer wallet.

Reset and restart the API if it is running.

After some emissions are recorded via calls to recordEmissions, call recordAuditedEmissionsToken to issue audited tokens to the contract on Goerli.

Then you can see them on goerli.etherscan.io by searching for the contract address, or on emissionstokens.opentaps.org/ by logging in with your Goerli wallet.

Other Useful Things

Updating the Chaincode

From the docker-compose-setup/ directory:

2. Update Chaincode: Run ./network.sh deployCC -ccv 'VERSION' -ccs 'SEQUENCE' e.g. update chaincode emissionscontract to version 2: ./network.sh deployCC -ccv 2.0 -ccs 2
3. Check help, if further infomation is needed. Run: ./network.sh -h

Hyperledger explorer

You can start Hyperledger Explorer by running this from docker-compose-setup/

$ ./network.sh startBlockchainExplorer

You can access it at http://localhost:8080 with username exploreradmin and password exploreradminpw

To stop it:

$ ./network.sh stopBlockchainExplorer`

Automated Tests

When the network/API has fully started, you can run the automated tests by navigating to the typescript_app directory and executing the tests into the docker container:

$ sh runTests.sh

The automated tests are currently not working. An issue has been created for this.