1 | [![npm Version](https://img.shields.io/npm/v/ganache-core.svg)](https://www.npmjs.com/package/ganache-core)
|
2 | [![npm Downloads](https://img.shields.io/npm/dm/ganache-core.svg)](https://www.npmjs.com/package/ganache-core)
|
3 | [![Build Status](https://travis-ci.org/trufflesuite/ganache-core.svg?branch=master)](https://travis-ci.org/trufflesuite/ganache-core)
|
4 | # Ganache Core
|
5 |
|
6 | This is the core code that powers the Ganache application and the Ganache command line tool.
|
7 |
|
8 | [Usage](#usage) | [Options](#options) | [Implemented Methods](#implemented-methods) | [Custom Methods](#custom-methods) | [Unsupported Methods](#unsupported-methods) | [Testing](#testing)
|
9 |
|
10 | ## Installation
|
11 |
|
12 | `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.
|
13 |
|
14 | **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.
|
15 |
|
16 | **Windows** See our [Windows install instructions](https://github.com/trufflesuite/ganache-cli/wiki/Installing-ganache-cli-on-Windows).
|
17 |
|
18 | **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.*
|
19 |
|
20 | Using npm:
|
21 |
|
22 | ```Bash
|
23 | npm install ganache-core
|
24 | ```
|
25 |
|
26 | or, if you are using [Yarn](https://yarnpkg.com/):
|
27 |
|
28 | ```Bash
|
29 | yarn add ganache-core
|
30 | ```
|
31 |
|
32 |
|
33 | ## Usage
|
34 |
|
35 | As a [Web3](https://github.com/ethereum/web3.js/) provider:
|
36 |
|
37 | ```javascript
|
38 | const ganache = require("ganache-core");
|
39 | const web3 = new Web3(ganache.provider());
|
40 | ```
|
41 | If web3 is already initialized:
|
42 | ```javascript
|
43 | const ganache = require("ganache-core");
|
44 | web3.setProvider(ganache.provider());
|
45 | ```
|
46 | NOTE: depending on your web3 version, you may need to set a number of confirmation blocks
|
47 | ```javascript
|
48 | const web3 = new Web3(provider, null, { transactionConfirmationBlocks: 1 });
|
49 | ```
|
50 |
|
51 | As an [ethers.js](https://github.com/ethers-io/ethers.js/) provider:
|
52 |
|
53 | ```javascript
|
54 | const ganache = require("ganache-core");
|
55 | const provider = new ethers.providers.Web3Provider(ganache.provider());
|
56 | ```
|
57 |
|
58 | As a general HTTP and WebSocket server:
|
59 |
|
60 | ```javascript
|
61 | const ganache = require("ganache-core");
|
62 | const server = ganache.server();
|
63 | const provider = server.provider;
|
64 | server.listen(port, function(err, blockchain) { ... });
|
65 | ```
|
66 |
|
67 | ## Options
|
68 |
|
69 | 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:
|
70 |
|
71 | * `"accounts"`: `Array` of `Object`'s of the following shape: `{ secretKey: privateKey, balance: HexString }`.
|
72 | * If `secretKey` is specified, the key is used to determine the account's address. Otherwise, the address is auto-generated.
|
73 | * The `balance` is a hexadecimal value of the amount of Ether (in Wei) you want the account to be pre-loaded with.
|
74 | * `"debug"`: `boolean` - Output VM opcodes for debugging
|
75 | * `"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.
|
76 | * `"logger"`: `Object` - Object, like `console`, that implements a `log()` function.
|
77 | * `"mnemonic"`: Use a specific HD wallet mnemonic to generate initial addresses.
|
78 | * `"port"`: `number` Port number to listen on when running as a server.
|
79 | * `"seed"`: Use arbitrary data to generate the HD wallet mnemonic to be used.
|
80 | * `"default_balance_ether"`: `number` - The default account balance, specified in ether.
|
81 | * `"total_accounts"`: `number` - Number of accounts to generate at startup.
|
82 | * `"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.
|
83 | * `"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.
|
84 | - `"forkCacheSize"`: `number` - The maximum size, in bytes, of the in-memory cache for queries on a chain fork. Defaults to `1_073_741_824` bytes (1 gigabyte). You can set this to `0` to disable caching (not recommended), or to `-1` for unlimited (will be limited by your node/browser process).
|
85 | * `"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)
|
86 | * `"_chainId"`: **(temporary option until v3)** Specify the chain's chainId. For legacy reasons, this does NOT affect the `eth_chainId` RPC response! Defaults to `1`
|
87 | * `"_chainIdRpc"`: **(temporary option until v3)** Specify the `eth_chainId` RPC response value. For legacy reasons, this does NOT affect the chain's `chainid`! Defaults to `1337`
|
88 | * `"time"`: `Date` - Date that the first block should start. Use this feature, along with the `evm_increaseTime` method to test time-dependent code.
|
89 | * `"locked"`: `boolean` - whether or not accounts are locked by default.
|
90 | * `"unlocked_accounts"`: `Array` - array of addresses or address indexes specifying which accounts should be unlocked.
|
91 | * `"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. Note: You will not be able to modify state (accounts, balances, etc) on startup when you initialize ganache-core with a pre-existing database.
|
92 | * `"db"`: `Object` - Specify an alternative database instance, for instance [MemDOWN](https://github.com/level/memdown).
|
93 | * `"ws"`: `boolean` Enable a websocket server. This is `true` by default.
|
94 | * `"account_keys_path"`: `String` - Specifies a file to save accounts and private keys to, for testing.
|
95 | * `"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.
|
96 | * `"hdPath"`: The hierarchical deterministic path to use when generating accounts. Default: "m/44'/60'/0'/0/"
|
97 | * `"hardfork"`: `String` Allows users to specify which hardfork should be used. Supported hardforks are `byzantium`, `constantinople`, `petersburg`, `istanbul`, and `muirGlacier` (default).
|
98 | * `"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).
|
99 | * `"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`).
|
100 | * `"gasLimit"`: `String::hex | number` Sets the block gas limit. Must be specified as a `hex` string or `number`(integer). Defaults to `"0x6691b7"`.
|
101 | * `"callGasLimit"`: `number` Sets the transaction gas limit for `eth_call` and `eth_estimateGas` calls. Must be specified as a `hex` string. Defaults to `"0x1fffffffffffff"` (`Number.MAX_SAFE_INTEGER`).
|
102 | * `"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.
|
103 |
|
104 | ## Implemented Methods
|
105 |
|
106 | The RPC methods currently implemented are:
|
107 |
|
108 | * [eth_accounts](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_accounts)
|
109 | * [eth_blockNumber](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_blockNumber)
|
110 | * [eth_call](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_call)
|
111 | * `eth_chainId`
|
112 | * [eth_coinbase](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_coinbase)
|
113 | * [eth_estimateGas](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_estimateGas)
|
114 | * [eth_gasPrice](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_gasPrice)
|
115 | * [eth_getBalance](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getBalance)
|
116 | * [eth_getBlockByNumber](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getBlockByNumber)
|
117 | * [eth_getBlockByHash](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getBlockByHash)
|
118 | * [eth_getBlockTransactionCountByHash](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getBlockTransactionCountByHash)
|
119 | * [eth_getBlockTransactionCountByNumber](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getBlockTransactionCountByNumber)
|
120 | * [eth_getCode](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getCode)
|
121 | * [eth_getCompilers](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getCompilers)
|
122 | * [eth_getFilterChanges](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getFilterChanges)
|
123 | * [eth_getFilterLogs](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getFilterLogs)
|
124 | * [eth_getLogs](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getLogs)
|
125 | * [eth_getStorageAt](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getStorageAt)
|
126 | * [eth_getTransactionByHash](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getTransactionByHash)
|
127 | * [eth_getTransactionByBlockHashAndIndex](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getTransactionByBlockHashAndIndex)
|
128 | * [eth_getTransactionByBlockNumberAndIndex](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getTransactionByBlockNumberAndIndex)
|
129 | * [eth_getTransactionCount](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getTransactionCount)
|
130 | * [eth_getTransactionReceipt](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getTransactionReceipt)
|
131 | * [eth_hashrate](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_hashrate)
|
132 | * [eth_mining](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_mining)
|
133 | * [eth_newBlockFilter](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_newBlockFilter)
|
134 | * [eth_newFilter](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_newFilter)
|
135 | * [eth_protocolVersion](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_protocolVersion)
|
136 | * [eth_sendTransaction](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sendTransaction)
|
137 | * [eth_sendRawTransaction](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sendRawTransaction)
|
138 | * [eth_sign](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sign)
|
139 | * `eth_signTypedData`
|
140 | * [eth_subscribe](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_subscribe)
|
141 | * [eth_unsubscribe](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_unsubscribe)
|
142 | * [shh_version](https://github.com/ethereum/wiki/wiki/JSON-RPC#shh_version)
|
143 | * [net_version](https://github.com/ethereum/wiki/wiki/JSON-RPC#net_version)
|
144 | * [net_peerCount](https://github.com/ethereum/wiki/wiki/JSON-RPC#net_peerCount)
|
145 | * [net_listening](https://github.com/ethereum/wiki/wiki/JSON-RPC#net_listening)
|
146 | * [eth_uninstallFilter](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_uninstallFilter)
|
147 | * [eth_syncing](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_syncing)
|
148 | * [web3_clientVersion](https://github.com/ethereum/wiki/wiki/JSON-RPC#web3_clientVersion)
|
149 | * [web3_sha3](https://github.com/ethereum/wiki/wiki/JSON-RPC#web3_sha3)
|
150 | * `bzz_hive`
|
151 | * `bzz_info`
|
152 |
|
153 | #### Management API Methods
|
154 |
|
155 | * [debug_traceTransaction](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#debug_tracetransaction)
|
156 | * [miner_start](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#miner_start)
|
157 | * [miner_stop](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#miner_stop)
|
158 | * [personal_sendTransaction](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_sendTransaction)
|
159 | * [personal_unlockAccount](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_unlockAccount)
|
160 | * [personal_importRawKey](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_importRawKey)
|
161 | * [personal_newAccount](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_newAccount)
|
162 | * [personal_lockAccount](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_lockAccount)
|
163 | * [personal_listAccounts](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#personal_listaccounts)
|
164 |
|
165 | ## Custom Methods
|
166 |
|
167 | Special non-standard methods that aren’t included within the original RPC specification:
|
168 | * `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*.
|
169 | ```bash
|
170 | curl -H "Content-Type: application/json" -X POST --data \
|
171 | '{"id":1337,"jsonrpc":"2.0","method":"evm_snapshot","params":[]}' \
|
172 | http://localhost:8545
|
173 | ```
|
174 | ```json
|
175 | { "id": 1337, "jsonrpc": "2.0", "result": "0x1" }
|
176 | ```
|
177 | * `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`.
|
178 | ```bash
|
179 | # Ex: ID "1" (hex encoded string)
|
180 | curl -H "Content-Type: application/json" -X POST --data \
|
181 | '{"id":1337,"jsonrpc":"2.0","method":"evm_revert","params":["0x1"]}' \
|
182 | http://localhost:8545
|
183 | ```
|
184 | ```json
|
185 | { "id": 1337, "jsonrpc": "2.0", "result": true }
|
186 | ```
|
187 | * `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.
|
188 | ```bash
|
189 | # Ex: 1 minute (number)
|
190 | curl -H "Content-Type: application/json" -X POST --data \
|
191 | '{"id":1337,"jsonrpc":"2.0","method":"evm_increaseTime","params":[60]}' \
|
192 | http://localhost:8545
|
193 | ```
|
194 | ```json
|
195 | { "id": 1337, "jsonrpc": "2.0", "result": "060" }
|
196 | ```
|
197 | * `evm_mine` : Force a block to be mined (independent of mining status: started | stopped). Takes one **optional** parameter, which is the timestamp a block should setup as the mining time. NOTE: the timestamp parameter should be specified in `seconds`. In JavaScript you would calculate it like this: `Math.floor(Date.now() / 1000);`
|
198 | ```bash
|
199 | # Ex: new Date("2009-01-03T18:15:05+00:00").getTime()
|
200 | curl -H "Content-Type: application/json" -X POST --data \
|
201 | '{"id":1337,"jsonrpc":"2.0","method":"evm_mine","params":[1231006505000]}' \
|
202 | http://localhost:8545
|
203 | ```
|
204 |
|
205 | ```json
|
206 | { "id": 1337, "jsonrpc": "2.0", "result": "0x0" }
|
207 | ```
|
208 | * `evm_unlockUnknownAccount` : Unlocks any unknown account. Accounts known to the `personal` namespace and accounts
|
209 | returned by `eth_accounts` cannot be unlocked using this method; use `personal_lockAccount` instead.
|
210 | ```bash
|
211 | # Ex: account: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
|
212 | curl -H "Content-Type: application/json" -X POST --data \
|
213 | '{"id":1337,"jsonrpc":"2.0","method":"evm_unlockUnknownAccount","params":["0x742d35Cc6634C0532925a3b844Bc454e4438f44e"]}' \
|
214 | http://localhost:8545
|
215 | ```
|
216 |
|
217 | ```json
|
218 | { "id": 1337, "jsonrpc": "2.0", "result": true }
|
219 | ```
|
220 | * `evm_lockUnknownAccount` : Locks any unknown account. Accounts known to the `personal` namespace and accounts
|
221 | returned by `eth_accounts` cannot be locked using this method; use `personal_unlockAccount` instead.
|
222 | ```bash
|
223 | # Ex: account: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
|
224 | curl -H "Content-Type: application/json" -X POST --data \
|
225 | '{"id":1337,"jsonrpc":"2.0","method":"evm_lockUnknownAccount","params":["0x742d35Cc6634C0532925a3b844Bc454e4438f44e"]}' \
|
226 | http://localhost:8545
|
227 | ```
|
228 |
|
229 | ```json
|
230 | { "id": 1337, "jsonrpc": "2.0", "result": true }
|
231 | ```
|
232 |
|
233 | ## Unsupported Methods
|
234 |
|
235 | * `eth_compileSolidity`: If you'd like Solidity compilation in Javascript, please see the [solc-js project](https://github.com/ethereum/solc-js).
|
236 |
|
237 |
|
238 | ## Testing
|
239 |
|
240 | Run tests via:
|
241 |
|
242 | ```
|
243 | $ npm test
|
244 | ```
|
245 |
|
246 | ## License
|
247 | [MIT](https://tldrlegal.com/license/mit-license)
|
248 |
|
\ | No newline at end of file |