Features • Getting Started • Documentation • Community • Contributing • Related
--- ## Features Ganache is an Ethereum simulator that makes developing Ethereum applications faster, easier, and safer. It includes all popular RPC functions and features (like events) and can be run deterministically to make development a breeze. - Fork any Ethereum network without waiting to sync - Ethereum json-rpc support - Snapshot/revert state - Mine blocks instantly, on demand, or at an interval - Fast-forward time - Impersonate any account (no private keys required!) - Listens for JSON-RPC 2.0 requests over HTTP/WebSockets - Programmatic use in Node.js - Pending Transactions ## Getting Started Ganache can be used from the [command line](#command-line-use), [programmatically](#programmatic-use) via Node.js, or [in the browser](#browser-use). ### Command line use You must first install [Node.js](https://nodejs.org/) >= v10.13.0 and npm >= 6.4.1. To install Ganache _beta_ globally, run: ```console $ npm install ganache@beta --global ``` For the latest stable release of ganache-cli, run: ```console $ npm install ganache-cli@latest --global ``` Once installed globally, you can start ganache right from your command line: ```console $ ganache-cli Ganache CLI v6.12.1 (ganache-core: 2.13.1) Available Accounts ================== (0) 0xe261e26aECcE52b3788Fac9625896FFbc6bb4424 (100 ETH) (1) 0xcE16e8eb8F4BF2E65BA9536C07E305b912BAFaCF (100 ETH) (2) 0x02f1c4C93AFEd946Cce5Ad7D34354A150bEfCFcF (100 ETH) (3) 0x0B75F0b70076Fab3F18F94700Ecaf3B00fE528E7 (100 ETH) (4) 0x7194d1F1d43c2c58302BB61a224D41B649e65C93 (100 ETH) (5) 0xC9A2d92c5913eDEAd9a7C936C96631F0F2241063 (100 ETH) (6) 0xD79BcDE5Cb11cECD1dfC6685B65690bE5b6a611e (100 ETH) (7) 0xb6D080353f40dEcA2E67108087c356d3A1AfcD64 (100 ETH) (8) 0x31A064DeeaD74DE7B9453beB4F780416D8859d3b (100 ETH) (9) 0x37524a360a40C682F201Fb011DB7bbC8c8A247c6 (100 ETH) Private Keys ================== (0) 0x7f109a9e3b0d8ecfba9cc23a3614433ce0fa7ddcc80f2a8f10b222179a5a80d6 (1) 0x6ec1f2e7d126a74a1d2ff9e1c5d90b92378c725e506651ff8bb8616a5c724628 (2) 0xb4d7f7e82f61d81c95985771b8abf518f9328d019c36849d4214b5f995d13814 (3) 0x941536648ac10d5734973e94df413c17809d6cc5e24cd11e947e685acfbd12ae (4) 0x5829cf333ef66b6bdd34950f096cb24e06ef041c5f63e577b4f3362309125863 (5) 0x8fc4bffe2b40b2b7db7fd937736c4575a0925511d7a0a2dfc3274e8c17b41d20 (6) 0xb6c10e2baaeba1fa4a8b73644db4f28f4bf0912cceb6e8959f73bb423c33bd84 (7) 0xfe8875acb38f684b2025d5472445b8e4745705a9e7adc9b0485a05df790df700 (8) 0xbdc6e0a69f2921a78e9af930111334a41d3fab44653c8de0775572c526feea2d (9) 0x3e215c3d2a59626a669ed04ec1700f36c05c9b216e592f58bbfd3d8aa6ea25f9 HD Wallet ================== Mnemonic: candy maple velvet cake sugar cream honey rich smooth crumble sweet treat Base HD Path: m/44'/60'/0'/0/{account_index} Default Gas Price ================== 20000000000 Gas Limit ================== 6721975 Call Gas Limit ================== 9007199254740991 Listening on 127.0.0.1:8545 ``` To install Ganache beta into an npm project, run: ```console $ npm install ganache ``` You can then add Ganache to your package.json scripts: ```json "scripts": { "ganache": "ganache --wallet.seed myCustomSeed" } ``` _See [Documentation](#documentation) for additional command line options._ Then start it: ```console $ npm run ganache ``` ### Programmatic use You can use Ganache programmatically from Node.js. Install Ganache into your npm package: ```console $ npm install ganache ``` Then you can use ganache as an [EIP-1193 provider only](#as-an-eip-1193-provider-only), an [EIP-1193 provider and JSON-RPC web server](#as-an-eip-1193-provider-and-json-rpc-web-server), as a [Web3 provider](#as-a-web3js-provider), or an [ethers provider](#as-an-ethersjs-provider). #### As an EIP-1193 provider only: ```javascript const ganache = require("ganache"); const options = {}; const provider = ganache.provider(options); const accounts = await provider.request({ method: "eth_accounts", params: [] }); ``` #### As an EIP-1193 provider and JSON-RPC web server: ```javascript const ganache = require("ganache"); const options = {}; const server = ganache.server(options); const PORT = 8545; server.listen(PORT, err => { if (err) throw err; console.log(`ganache listening on port ${PORT}...`); const provider = server.provider; const accounts = await provider.request({ method: "eth_accounts", params:[] }); }); ``` #### As a [web3.js](https://www.npmjs.com/package/web3) provider: To use ganache as a Web3 provider: ```javascript const Web3 = require("web3"); const ganache = require("ganache"); const web3 = new Web3(ganache.provider()); ``` NOTE: depending on your web3 version, you may need to set a number of confirmation blocks ``` const web3 = new Web3(ganache.provider(), null, { transactionConfirmationBlocks: 1 }); ``` #### As an [ethers.js]() provider: ```javascript const ganache = require("ganache"); const provider = new ethers.providers.Web3Provider(ganache.provider()); ``` ### Browser Use You can also use Ganache in the browser by adding the following script to your HTML: ```html ``` NOTE: the `{VERSION}` in the above path needs to be replaced with a version number or tag that is listed in [npm](https://www.npmjs.com/package/ganache?activeTab=versions). From there, Ganache is available in your browser for use: ```javascript const options = {}; const provider = Ganache.provider(options); ``` ## Documentation New RPC documentation coming soon! See https://github.com/trufflesuite/ganache/tree/master#options for Ganache v2 documentation. ### Ganache Provider Events In addition to [EIP-1193's](https://eips.ethereum.org/EIPS/eip-1193) `"message"` event and the legacy `"data"` event, Ganache emits 3 additional events: `"ganache:vm:tx:before"`, `"ganache:vm:tx:step"`, and `"ganache:vm:tx:after"`. These events can be used to observe the lifecycle of any transaction executed via `*sendTransaction`, `eth_call`, `debug_traceTransaction`, or `debug_storageRangeAt`. These share the [event paradigm that Truffle uses](https://www.trufflesuite.com/docs/truffle/advanced/event-system#how-to-define-your-event-handlers), but without any of the wildcard handling, i.e., no `"vm:*"` support (for now). Each of these events will emit a `context` object which is a unique object that can be used to identify a transaction over the course of its lifecycle. For example: ```typescript interface StepEvent { account: { nonce: bigint; balance: bigint; stateRoot: Buffer; codeHash: Buffer; }; address: Buffer; codeAddress: Buffer; depth: number; gasLeft: bigint; gasRefund: bigint; memory: Buffer; memoryWordCount: bigint; opcode: { name: string; fee: number; }; pc: number; returnStack: Buffer[]; stack: Buffer[]; } const contexts = new Map(); provider.on("ganache:vm:tx:before", (event: { context: {} }) => { contexts.set(event.context, []); }); provider.on("ganache:vm:tx:step", (event: StepEvent) => { contexts.get(event.context).push(event.data); }); provider.on("ganache:vm:tx:after", (event: { context: {} }) => { doAThingWithThisTransactionsSteps(contexts.get(event.context)); contexts.delete(event.context); }); ``` The reason this `context` is necessary is that Ganache may run multiple transactions simultaneously, so `"ganache:vm:tx:step"` events from different transactions could be intermingled. The above events will be emitted for `eth_call`, `*sendTransaction`, `debug_traceTransaction`, and `debug_storageRangeAt`. Currently, we do not await the event listener's return value, however, we'll likely enable this in the future. ## Community - [Discord](https://trfl.io/community) - [Reddit](https://www.reddit.com/r/Truffle/) ## Contributing See [CONTRIBUTING.md](https://github.com/trufflesuite/ganache/blob/develop/CONTRIBUTING.md) for our guide to contributing to Ganache. ## Related - [Truffle](https://www.github.com/trufflesuite/truffle) - [Drizzle](https://www.github.com/trufflesuite/drizzle)