npm package: @platonnetwork/ganache-core
Description: [![npm Version](https://img.shields.io/npm/v/ganache-core.svg)](https://www.npmjs.com/package/ganache-core) [![npm Downloads](https://img.shields.io/npm/dm/ganache-core.svg)](https://www.npmjs.com/package/ganache-core) [![Build Status](https://travis-ci.o
Latest version: 1.0.0

[![npm Version](https://img.shields.io/npm/v/ganache-core.svg)](https://www.npmjs.com/package/ganache-core)
[![npm Downloads](https://img.shields.io/npm/dm/ganache-core.svg)](https://www.npmjs.com/package/ganache-core)
[![Build Status](https://travis-ci.org/trufflesuite/ganache-core.svg?branch=master)](https://travis-ci.org/trufflesuite/ganache-core)
[![Coverage Status](https://coveralls.io/repos/github/trufflesuite/ganache-core/badge.svg?branch=develop)](https://coveralls.io/github/trufflesuite/ganache-core?branch=develop)
# Ganache Core

This is the core code that powers the Ganache application and the Ganache command line tool.

[Usage](#usage) | [Options](#options) | [Implemented Methods](#implemented-methods) | [Custom Methods](#custom-methods) | [Unsupported Methods](#unsupported-methods) | [Testing](#testing)

## Installation

`ganache-core` is written in JavaScript and distributed as a Node.js package via `npm`. Make sure you have Node.js (>= v8.9.0) installed, and your environment is capable of installing and compiling `npm` modules.

**macOS** Make sure you have the XCode Command Line Tools installed. These are needed in general to be able to compile most C based languages on your machine, as well as many npm modules.

**Windows** See our [Windows install instructions](https://github.com/trufflesuite/ganache-cli/wiki/Installing-ganache-cli-on-Windows).

**Ubuntu/Linux** Follow the basic instructions for installing [Node.js](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions) and make sure that you have `npm` installed, as well as the `build-essential` `apt` package (it supplies `make` which you will need to compile most things). Use the official Node.js packages, *do not use the package supplied by your distribution.*

Using npm:

```Bash
npm install ganache-core
```

or, if you are using [Yarn](https://yarnpkg.com/):

```Bash
yarn add ganache-core
```


## Usage

As a [Web3](https://github.com/ethereum/web3.js/) provider:

```javascript
const ganache = require("ganache-core");
const web3 = new Web3(ganache.provider());
```
If web3 is already initialized:
```javascript
const ganache = require("ganache-core");
web3.setProvider(ganache.provider());
```
NOTE: depending on your web3 version, you may need to set a number of confirmation blocks
```javascript
const web3 = new Web3(provider, null, { transactionConfirmationBlocks: 1 });
```

As an [ethers.js](https://github.com/ethers-io/ethers.js/) provider:

```javascript
const ganache = require("ganache-core");
const provider = new ethers.providers.Web3Provider(ganache.provider());
```

As a general HTTP and WebSocket server:

```javascript
const ganache = require("ganache-core");
const server = ganache.server();
const provider = server.provider;
server.listen(port, function(err, blockchain) { ... });
```

## Options

Both `.provider()` and `.server()` take a single object which allows you to specify behavior of the Ganache instance. This parameter is optional. Available options are:

* `"accounts"`: `Array` of `Object`'s. Each object should have a `balance` key with a hexadecimal value. The key `secretKey` can also be specified, which represents the account's private key. If no `secretKey`, the address is auto-generated with the given balance. If specified, the key is used to determine the account's address.
* `"debug"`: `boolean` - Output VM opcodes for debugging
* `"blockTime"`: `number` - Specify blockTime in seconds for automatic mining. If you don't specify this flag, ganache will instantly mine a new block for every transaction. Using the `blockTime` option is discouraged unless you have tests which require a specific mining interval.
* `"logger"`: `Object` - Object, like `console`, that implements a `log()` function.
* `"mnemonic"`: Use a specific HD wallet mnemonic to generate initial addresses.
* `"port"`: `number` Port number to listen on when running as a server.
* `"seed"`: Use arbitrary data to generate the HD wallet mnemonic to be used.
* `"default_balance_ether"`: `number` - The default account balance, specified in ether.
* `"total_accounts"`: `number` - Number of accounts to generate at startup.
* `"fork"`: `string` or `object` - Fork from another currently running Ethereum client at a given block.  When a `string`, input should be the HTTP location and port of the other client, e.g. `http://localhost:8545`. You can optionally specify the block to fork from using an `@` sign: `http://localhost:8545@1599200`. Can also be a `Web3 Provider` object, optionally used in conjunction with the `fork_block_number` option below.
* `"fork_block_number"`: `string` or `number` - Block number the provider should fork from, when the `fork` option is specified. If the `fork` option is specified as a string including the `@` sign and a block number, the block number in the `fork` parameter takes precedence.
* `"network_id"`: Specify the network id ganache-core will use to identify itself (defaults to the current time or the network id of the forked blockchain if configured)
* `"time"`: `Date` - Date that the first block should start. Use this feature, along with the `evm_increaseTime` method to test time-dependent code.
* `"locked"`: `boolean` - whether or not accounts are locked by default.
* `"unlocked_accounts"`: `Array` - array of addresses or address indexes specifying which accounts should be unlocked.
* `"db_path"`: `String` - Specify a path to a directory to save the chain database. If a database already exists, `ganache-core` will initialize that chain instead of creating a new one.
* `"db"`: `Object` - Specify an alternative database instance, for instance [MemDOWN](https://github.com/level/memdown).
* `"ws"`: `boolean` Enable a websocket server. This is `true` by default.
* `"account_keys_path"`: `String` - Specifies a file to save accounts and private keys to, for testing.
* `"vmErrorsOnRPCResponse"`: `boolean` - Whether or not to transmit transaction failures as RPC errors. Set to `false` for error reporting behaviour which is compatible with other clients such as geth and Parity. This is `true` by default to replicate the error reporting behavior of previous versions of ganache.
* `"hdPath"`: The hierarchical deterministic path to use when generating accounts. Default: "m/44'/60'/0'/0/"
* `"hardfork"`: `String` Allows to specify which hardfork should be used. Supported hardforks are `byzantium`, `constantinople`, and `petersburg` (default).
* `"allowUnlimitedContractSize"`: `boolean` - Allows unlimited contract sizes while debugging (NOTE: this setting is often used in conjuction with an increased `gasLimit`). By setting this to `true`, the check within the EVM for contract size limit of 24KB (see [EIP-170](https://git.io/vxZkK)) is bypassed. Setting this to `true` **will** cause `ganache-core` to behave differently than production environments. (default: `false`; **ONLY** set to `true` during debugging).
* `"gasPrice"`: `String::hex` Sets the default gas price for transactions if not otherwise specified. Must be specified as a `hex` encoded string in `wei`. Defaults to `"0x77359400"` (2 `gwei`).
* `"gasLimit"`: `String::hex` Sets the block gas limit. Must be specified as a `hex` string. Defaults to `"0x6691b7"`.
* `"keepAliveTimeout"`:  `number` If using `.server()` - Sets the HTTP server's `keepAliveTimeout` in milliseconds. See the [NodeJS HTTP docs](https://nodejs.org/api/http.html#http_server_keepalivetimeout) for details. `5000` by default.

## Implemented Methods

The RPC methods currently implemented are:

* [platon_accounts](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_accounts)
* [platon_blockNumber](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_blockNumber)
* [platon_call](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_call)
* `platon_chainId`
* [platon_coinbase](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_coinbase)
* [platon_estimateGas](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_estimateGas)
* [platon_gasPrice](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_gasPrice)
* [platon_getBalance](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getBalance)
* [platon_getBlockByNumber](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getBlockByNumber)
* [platon_getBlockByHash](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getBlockByHash)
* [platon_getBlockTransactionCountByHash](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getBlockTransactionCountByHash)
* [platon_getBlockTransactionCountByNumber](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getBlockTransactionCountByNumber)
* [platon_getCode](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getCode)
* [platon_getCompilers](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getCompilers)
* [platon_getFilterChanges](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getFilterChanges)
* [platon_getFilterLogs](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getFilterLogs)
* [platon_getLogs](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getLogs)
* [platon_getStorageAt](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getStorageAt)
* [platon_getTransactionByHash](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getTransactionByHash)
* [platon_getTransactionByBlockHashAndIndex](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getTransactionByBlockHashAndIndex)
* [platon_getTransactionByBlockNumberAndIndex](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getTransactionByBlockNumberAndIndex)
* [platon_getTransactionCount](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getTransactionCount)
* [platon_getTransactionReceipt](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_getTransactionReceipt)
* [platon_hashrate](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_hashrate)
* [platon_mining](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_mining)
* [platon_newBlockFilter](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_newBlockFilter)
* [platon_newFilter](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_newFilter)
* [platon_protocolVersion](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_protocolVersion)
* [platon_sendTransaction](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_sendTransaction)
* [platon_sendRawTransaction](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_sendRawTransaction)
* [platon_sign](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_sign)
* `platon_signTypedData`
* [platon_subscribe](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_subscribe)
* [platon_unsubscribe](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_unsubscribe)
* [shh_version](https://github.com/ethereum/wiki/wiki/JSON-RPC#shh_version)
* [net_version](https://github.com/ethereum/wiki/wiki/JSON-RPC#net_version)
* [net_peerCount](https://github.com/ethereum/wiki/wiki/JSON-RPC#net_peerCount)
* [net_listening](https://github.com/ethereum/wiki/wiki/JSON-RPC#net_listening)
* [platon_uninstallFilter](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_uninstallFilter)
* [platon_syncing](https://github.com/ethereum/wiki/wiki/JSON-RPC#platon_syncing)
* [web3_clientVersion](https://github.com/ethereum/wiki/wiki/JSON-RPC#web3_clientVersion)
* [web3_sha3](https://github.com/ethereum/wiki/wiki/JSON-RPC#web3_sha3)
* `bzz_hive`
* `bzz_info`

#### Management API Methods

* [debug_traceTransaction](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#debug_tracetransaction)
* [miner_start](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#miner_start)
* [miner_stop](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#miner_stop)
* [personal_sendTransaction](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_sendTransaction)
* [personal_unlockAccount](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_unlockAccount)
* [personal_importRawKey](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_importRawKey)
* [personal_newAccount](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_newAccount)
* [personal_lockAccount](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_lockAccount)
* [personal_listAccounts](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_listaccounts)

## Custom Methods

Special non-standard methods that aren’t included within the original RPC specification:
* `evm_snapshot` : Snapshot the state of the blockchain at the current block. Takes no parameters. Returns the integer id of the snapshot created. A snapshot can only be used once. After a successful `evm_revert`, the same snapshot id cannot be used again. Consider creating a new snapshot after each `evm_revert` *if you need to revert to the same point multiple times*.
  ```bash
  curl -H "Content-Type: application/json" -X POST --data \
          '{"id":1337,"jsonrpc":"2.0","method":"evm_snapshot","params":[]}' \
          http://localhost:8545
  ```
  ```json
  { "id": 1337, "jsonrpc": "2.0", "result": "0x1" }
  ```
* `evm_revert` : Revert the state of the blockchain to a previous snapshot. Takes a single parameter, which is the snapshot id to revert to. This deletes the given snapshot, as well as any snapshots taken after (Ex: reverting to id `0x1` will delete snapshots with ids `0x1`, `0x2`, `etc`...  If no snapshot id is passed it will revert to the latest snapshot. Returns `true`.
  ```bash
  # Ex: ID "1" (hex encoded string)
  curl -H "Content-Type: application/json" -X POST --data \
          '{"id":1337,"jsonrpc":"2.0","method":"evm_revert","params":["0x1"]}' \
          http://localhost:8545
  ```
  ```json
  { "id": 1337, "jsonrpc": "2.0", "result": true }
  ```
* `evm_increaseTime` : Jump forward in time. Takes one parameter, which is the amount of time to increase in seconds. Returns the total time adjustment, in seconds.
  ```bash
  # Ex: 1 minute (number)
  curl -H "Content-Type: application/json" -X POST --data \
          '{"id":1337,"jsonrpc":"2.0","method":"evm_increaseTime","params":[60]}' \
          http://localhost:8545
  ```
  ```json
  { "id": 1337, "jsonrpc": "2.0", "result": "060" }
  ```
* `evm_mine` : Force a block to be mined. Takes one optional parameter, which is the timestamp a block should setup as the mining time. Mines a block independent of whether or not mining is started or stopped.
  ```bash
  # Ex: new Date("2009-01-03T18:15:05+00:00").getTime()
  curl -H "Content-Type: application/json" -X POST --data \
          '{"id":1337,"jsonrpc":"2.0","method":"evm_mine","params":[1231006505000]}' \
          http://localhost:8545
  ```

  ```json
  { "id": 1337, "jsonrpc": "2.0", "result": "0x0" }
  ```

## Unsupported Methods

* `platon_compileSolidity`: If you'd like Solidity compilation in Javascript, please see the [solc-js project](https://github.com/ethereum/solc-js).


## Testing

Run tests via:

```
$ npm test
```

## License
[MIT](https://tldrlegal.com/license/mit-license)