Ethereum-easy NPM

Ethereum-Easy

The Ethereum-Easy library makes operating on the Ethereum blockchain easier by abstracting the challenges of the Web3 library to 5 simple function calls. Transact, deploy contracts, interact with blockchain elements, and listen for general events on the Ethereum network.

Install

$ npm install ethereum-easy

General Usage

This library is designed to greatly simplify the functions for interacting with the Ethereum blockchain. Chiroptera provides 8 functions:

sendTx(toAddress, transactionAmount)
deployContract(contractPath, transactionAmount, arguments)
contractCall(toAddress, contractPath, function)
contractSend(toAddress, contractPath, transactionAmount, function, arguments)
listen(matchVar)

With these functions, you can deploy, call, transact, and watch the Ethereum blockchain with ease.

To instantiate this library, use the following lines of code:

const easyEth = require('ethereum-easy');

easyEth.sendTx(toAddress, transactionAmount);
...

Finally, you will need to set your development environment variables to tell the library where you would like to deploy your contract. On a Mac, export NODE_ENV=<environment will do the trick. Your options for your environment are: dev_local, dev_live, and production. dev_local will deploy to the local testRPC (Ganache) blockchain. dev_live will deploy to the testnet blockchain set as your network_prerference in your config file (more on that later). And production will deploy to the main Ethereum blockchain.

Requirements

In order to use this library, 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>",
  "ganacheEndpoint": "http://localhost:8545",
  "gasPriceOracle": "https://ethgasstation.info/json/ethgasAPI.json"
}

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.

Function Descriptions

sendTx

The sendTx function allows you to send Ether over the blockchain. The function call is used as follows:

sendTx(toAddress, transactionAmount)

toAddress : string This is the address that you are sending Ether.
transactionAmount : int This is the amount you would like to send the toAddress.

Returns : Object Containing information about the transaction that occurred.

Calling this function with these parameters will send Ether from the account mnemonic in the config file to the account listed in the toAddress.

deployContract

The deployContract function allows you to deploy a smart contract to the Ethereum blockchain. The function call is used as follows:

deployContract(contractPath, transactionAmount, arguments)

contractPath : string This is the absolute path in your operating system to the smart contract you would like to deploy.
transactionAmount : int This is the amount of Ether that you would like to send to the contract. This can be 0.
arguments : Array(string) These are the arguments that you want to initialize your smart contract with. This is an optional parameter.

Returns : Object Containing information about the transaction that occurred. This is an object with many other nested objects. It may be useful to use the code console.log(util.inspect(result, false, null) to view this object.

Calling this function with these parameters will deploy a smart contract from the absolute path location on your computer listed in contractPath to the Ethereum blockchain with the arguments provided in arguments from the account listed in the config file with the value of transactionAmount.

contractCall

The contractCall 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:

contractCall(toAddress, contractPath, function)

toAddress : string This is the address where the contract is stored on the blockchain.
contractPath : string This is the absolute path in your operating system to the smart contract you would like to deploy.
function : 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.

contractSend

The contractSend 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:

contractSend(toAddress, contractPath, transactionAmount, function, arguments)

toAddress : string This is the address where the contract is stored on the blockchain.
contractPath : string This is the absolute path in your operating system to the smart contract you would like to deploy.
transactionAmount : int This is the amount of Ether that you would like to send to the contract. This can be 0.
function : string This is the name of the function in the smart contract that you want to invoke.
arguments : 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, funciton, 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.

listen

The listen function allows a user to define custom blockchain content and scan incoming blocks in the Ethereum blockchain for matches to this content. For example, you can search through new blocks for particular addresses, values, or any information that may be stored in the objects posted to the blockchain. Running this function will return the transaction within the current block whenever a content match is found. The function call is used as follows:

listen(matchVar)

matchVar : string | int This is the content that you would like to search for in new blocks posted to the blockchain.

Returns : Object Containing the transaction in the current block that matches your matchVar.

Calling this function with these parameters allows you to search for content defined in matchVar on any new block posted to the Ethereum blockchain.