local-exec-contract v0.0.1

Local Execution for Truffle Contracts

Ethereum Smart Contracts support -among others- the definition of pure functions, which have the property of not accessing (read / write) the contract state. Those functions have also the particularity that they don't consume gas, but still a transaction with gas has to be emitted (which is later refunded).

The purpose of this library is to give the ability to an existing truffle contract instance, to run those pure functions in a local VM environment, therefore omiting the need to emit transactions to the blockchain.

Install

npm install --save local-exec-contract

Usage

import { turnIntoLocalExecutionContract } from "local-exec-contract";
import { artifacts } from "@nomiclabs/buidler";

const MyTruffleContract = artifacts.require("MyTruffleContract")

async function runLocalContract() {
  // deployed contract reference
  const myTruffleContract = await MyTruffleContract.new()
  
  // wrap to locally-executable contract instance (address stays the same)  
  const myLocalTruffleContract = await turnIntoLocalExecutionContract(myTruffleContract)
  //=> pure functions will be available locally with 'local_' prefix 
  
  const res = await myLocalTruffleContract.pureFn() // runs in EVM
  const localRes = await myLocalTruffleContract.local_pureFn() // runs locally
  //=> the result is the same 
  // assert.deepEqual(res, localRes)
  
  // non-pure methods are still available
  const otherRes = await myLocalTruffleContract.nonPureFn() // runs in EVM
}

A more thorough standalone example can be found in examples folder.

API

turnIntoLocalExecutionContract(contract)

contract

Type: TruffleContractInstance

A deployed Truffle Contract instance to wrap.

import {turnIntoLocalExecutionContract} from "local-exec-contract";

const localContract = await turnIntoLocalExecutionContract(contract)
//=> a new contract instance pointing to the original contract address,
//   with addition of "local_"-prefixed methods for pure functions.

Development

For local development of this library, first clone the project, then install dependencies. Suggestions, issues, and PRs welcome!

Setup

npm install

Then, you can run the example with:

npm start

Test

npm run test

License

MIT