Jenk-Thereum

NOTE! prod.js is configured for my thesis! Unless you dig into this library and fix this, it will not deploy to the main Ethereum network. I will update this asap, but until I defend, it will remain this way. There is a note is prod.js and monitor.js describing what to change or feel free to contact me at jon.heinekce at gmail.com to get info on how to update this for you.

The Jenk-Thereum library is designed to make building a Jenkins CI/CD pipeline easier. This library works in tandem with Jenkinsfile_Ethereum. Jenk-Thereum abstracts many complicated Ethereum functions with the help of the Ethereum-Easy library, making the process of testing and deploying smart contracts in a Jenkins pipeline much easier. If you choose to use Jenkinsfile_Ethereum, your smart contract will automatically be tested and then deployed on local, devnet, and live Ethereum blockchains.

Install

$ npm install jenk-thereum

General Usage

This library is designed to work with one smart contract at a time. In the main directory of your smart contract should contain your smart contract, a folder labeled 'test', a config file, and a package.json like so:

<your_smart_contract>.sol
test/
config.json
package.json

Because this package and the required packages for testing Ethereum smart contracts are in Javascript, you will have a package.json file and some other artifacts like node_moduels and package-lock.json. It is necessary to use .gitignore to keep your config file from getting posted to Github (as it contains sensitive information) and it is helpful to also put node_moduels and package-lock.json in there as well. Once you create this file structure, all you need to do is install the Jenk-Thereum package. The config file is described below.

The library exposes several functions and modules to make deploying smart contracts and testing them easier. The functions you have access to are:

1.  `testContractCall(toAddr, contractPath, funct)`
2.  `testContractSend(toAddr, contractPath, amount, funct, args)`
3.  `getDevLocalAddr()`
4.  `getDevLiveAddr()`
5.  `getProdAddr()`

With these functions you can easily test deployed smart contracts.

Requirements

In order to use this library, and for any smart contract testing, you will need to download the TestRPC to use the Ganache local blockchain tool. You can download this repository with:

npm install -g ethereumjs-testrpc

Also, here is a link to the TestRPC Docs - TestRPC.

Once you install this library you will need to run the TestRPC to deploy local smart contracts with testrpc -m "<your mnemonic>". If you do not have a wallet with a mnemonic yet, you can get one in the next step.

Another tool that is very handy for blockchain address management is Metamask. Metamask is a browser extension that creates and manages Ethereum account addresses. Downloading Metamask will allow you to create a new wallet and store the mnemonic needed for this library or it will allow you to load in an existing wallet from the mnemonic associated to it. However you generate a mnemonic to use in this library is fine, Metamask just makes managing the accounts associated to your mnemonic easier.

Next, you can use any api access point to communicate with the Ethereum blockchain. This can be your own node or a node hosted by a 3rd party. If you don't want to devops your own Ethereum node or have no idea what I am talking about, consider using Infura. Their easy node apis and simple sign up procedure are great for quickly getting started with the Ethereum network or not being hassled by complex node setup.

Finally, this library uses a config file to pass information to the function calls. Put this config file below in the main folder:

{
  "mnemonic": "<your mnemonic>",
  "ropsten": "<your Ropsten endpoint>",
  "rinkeby": "<your Rinkeby endpoint>",
  "kovan": "<your Kovan endpoint>",
  "ethereum": "<your Ethereum main net endpoint>",
  "network_prerference": "<your preferred testnet, ie ropsten, rinkeby, or kovan>",
  "ganacheEndpoint": "http://localhost:8545",
  "gasPriceOracle": "https://ethgasstation.info/json/ethgasAPI.json",
  "contractPath": "<the path to your smart contract on your local machine",
  "amount": <amount of ether you want to supply to the contract>,
  "args": [<'the arguments to your smart contract, separated by commas, and as an array'>]
}

Name this file config.json. If you setup an account with Infura you can put all testnet and main net enpoints in this file for easy use in the library.

Setting Started - Testing

This package does two jobs. It makes testing deployed contracts easier and it provides a Jenkins pipeline some added functionality for deploying contracts. Lets say you have a contract called foo.sol and a testing file called foo.test.js. Then your file structure will look like:

foo.sol
test/foo.test.js
config.json
package.json

There are two necessities when writing your tests in foo.test.js. The first is that you use Mocha as your testing suite (Jest throws errors that are known and unresolved). Second is that you include toAddr_dev_local = await jenkEth.getDevLocalAddr(); and toAddr_dev_live = await jenkEth.getDevLiveAddr(); in beforeEach( async () => {}); in your testing file. If you had no other testing setup in your testing file, your "before each" statement would look something like:

const jenkEth = require('jenk-thereum');

let toAddr_dev_local;
let toAddr_dev_live;

beforeEach( async () => {
  toAddr_dev_local = await jenkEth.getDevLocalAddr();
  toAddr_dev_live = await jenkEth.getDevLiveAddr();
});

Functions

Now you you can use the functions testContractCall and testContractSend in your testing file. The functions that Jenk-Thereum provides are:

testContractCall

The testContractCall function returns any non-state changing information stored on a smart contract on the Ethereum blockchain, similar to that of a getter method. The function call is used as follows:

testContractCall(toAddr, contractPath, funct)

• toAddr : string This is the address of where the contract is stored on the blockchain. You should use toAddr_dev_local or toAddr_dev_live to get this address, as the address is fetched for you with this library with these variable.

• contractPath : string This is the absolute path in your operating system to the smart contract you would like to deploy.

• funct : string This is the name of the function in the smart contract that you want to invoke.

Returns : String Containing the response from the method called.

Calling this function with these parameters will return any stateless smart contract information on the blockchain stored at the address toAddress accessed with the method function.

testContractSend

The testContractSend function calls any smart contract methods in your deployed contract that change the state of the smart contract. For example, if you want to update an internal value in the contract, you will use this function. The function call is used as follows:

testContractSend(toAddr, contractPath, amount, funct, args)

• toAddr : string This is the address of where the contract is stored on the blockchain. You should use toAddr_dev_local or toAddr_dev_live to get this address, as the address is fetched for you with this library with these variable.

• contractPath : string This is the absolute path in your operating system to the smart contract you would like to deploy.

• amount : int This is the amount of Ether that you would like to send to the contract. This can be 0.

• funct : string This is the name of the function in the smart contract that you want to invoke.

• args : Array(string) These are the arguments that you want to pass to your smart contract based on the method you are calling. This is an optional parameter.

Returns : Object Containing information about the state change to the contract that occurred.

Calling this function with these parameters will trigger a method on your smart contract, funct, at address toAddress on the Ethereum blockchain from the account associated to your mnemonic in the config file with the arguments needed for the method call.

getDevLocalAddr

The getDevLocalAddr will fetch the address of the last time a contract on the local environment was deployed to the blockchain. Keep in mind, this function works in tandem with the dev_local module, so it will only find the address associated to a smart contract deployed from an invocation of dev_local.js. This function call is used as follows:

getDevLocalAddr()

Returns : string That indicates the address of the deployed contract on your local machine.

getDevLiveAddr

The getDevLiveAddr will fetch the address of the last time a contract was deployed to an Ethereum testnet. Keep in mind, this function works in tandem with the dev_live module, so it will only find the address associated to a smart contract deployed from an invocation of dev_live.js. This function call is used as follows:

getDevLiveAddr()

Returns : string That indicates the address of the deployed contract on an Ethereum testnet.

getProdAddr

The getDevLiveAddr will fetch the address of the last time a contract was deployed to the live Ethereum network. Keep in mind, this function works in tandem with the prod module, so it will only find the address associated to a smart contract deployed from an invocation of prod.js. This function call is used as follows:

getProdAddr()

Returns : string That indicates the address of the deployed contract on the Ethereum live network.

Setting Started - Jenkins

Using Jenk-Thereum in your pipeline is simple as well. An example of a Jenkinsfile implementing Jenk-Thereum can be found [here]((https://github.com/le-sanglier/Jenkinsfile_Ethereum). There are three modules that you can invoke in your pipeline to aid in deployment. dev_local.js, dev_live.js, and prod.js all deploy the smart contract you have in your file system to the environment listed. The parameters needed are taken from your config file, so all you need to do is include the correct steps in your Jenkinsfile.

One step that is crucial is the Prep Env step in the repo above. If you do not npm install the library in Jenkins, it will not have access to the node_moduels to make this work. As long as this step precludes any invocation of the Jenk-Thereum modules, you can call them with sh 'node ./node_modules/jenk-thereum/.... In the repo you will find:

stage('Deploy') {
            steps {
                sh 'node ./node_modules/jenk-thereum/dev_local.js'
                sh 'node ./node_modules/jenk-thereum/dev_live.js'
            }
        }

This is an example of how to use the package modules to deploy your contracts.