↓Skip to main content
Dev Blog Dev Blog
  1. All Posts/

ganache

Tools TypeScript




A tool for creating a local blockchain for fast Ethereum development.


Features •
Getting Started •
Documentation •
Community •
Docker •
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.

  • console.log in Solidity
  • Zero-config Mainnet Forking
  • 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, programmatically via Node.js, or in the browser.

Command line use

You must first install Node.js >= v14.0.0 and npm >= 6.12.0.
To install Ganache globally, run:

$ npm install ganache --global

In case you’re upgrading from a previous version of Ganache, we’ve also written up this handy guide on how to upgrade/install Ganache and to document all breaking changes to look out for.
Once installed globally, you can start ganache right from your command line:

ganache

Your output should look something like this:

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

NPM project use

If you want to install Ganache into an npm project, run:

$ npm install ganache

You can then add Ganache to your package.json scripts:

"scripts": {
  "ganache": "ganache --wallet.seed myCustomSeed"
}

See Documentation for additional command line options.
Then start it:

$ npm run ganache

Programmatic use

You can use Ganache programmatically from Node.js. Install Ganache into your npm package:

$ npm install ganache

Then you can use ganache as an EIP-1193 provider only, an EIP-1193 provider and JSON-RPC web server, as a Web3 provider, or an ethers provider.

As an EIP-1193 provider only: 

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: 

const ganache = require("ganache");

const options = {};
const server = ganache.server(options);
const PORT = 8545;
server.listen(PORT, async 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 provider:

To use ganache as a Web3 provider:

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: 

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:

<script src="https://cdn.jsdelivr.net/npm/ganache@{VERSION}/dist/web/ganache.min.js"></script>

NOTE: the {VERSION} in the above path needs to be replaced with a version number or tag that is listed in npm.
From there, Ganache is available in your browser for use:

const options = {};
const provider = Ganache.provider(options);

Documentation

New interactive RPC documentation coming soon!
In the meantime, check out our Ethereum JSON-RPC documentation.

Startup Options

The startup options are grouped in the chain, database, fork, logging, miner, wallet, and server namespaces, and should be used as such on startup, i.e.

ganache --namespace.option="value"

for CLI use, and

const options = { namespace: { option: "value"}};
const provider = ganache.provider(options);

for programmatic use.
The following options are listed for command line use, but can also be used when running Ganache programmatically in your project.

Chain:
  --chain.allowUnlimitedContractSize    Allows unlimited contract sizes while debugging. Setting this to true
                                        will cause ganache to behave differently than production environments.
                                                                                    [boolean] [default: false]

  --chain.asyncRequestProcessing        When set to false only one request will be processed at a time.
                                                                                     [boolean] [default: true]

  --chain.chainId                       The currently configured chain id.            [number] [default: 1337]

  -i, --chain.networkId                 The id of the network returned by the RPC method net_version.
                                        deprecated aliases: --networkId
                                                            [number] [default: System time at process start or
                                                               Network ID of forked blockchain if configured.]

  -t, --chain.time                      Date that the first block should start.
                                        deprecated aliases: --time                                    [number]

  -k, --chain.hardfork                  Set the hardfork rules for the EVM.
                                        deprecated aliases: --hardfork
          [string] [choices: "constantinople", "byzantium", "petersburg", "istanbul", "muirGlacier", "berlin",
                                         "london", "arrowGlacier", "grayGlacier", "merge"] [default: "merge"]

  --chain.vmErrorsOnRPCResponse         Whether to report runtime errors from EVM code as RPC errors.
                                                                                    [boolean] [default: false]


Database:
  --database.dbPath                     Specify a path to a directory to save the chain database.
                                        deprecated aliases: --db, --db_path                           [string]

Logging:
  --logging.debug                       Set to true to log EVM opcodes.             [boolean] [default: false]

  -q, --logging.quiet                   Set to true to disable logging.
                                        deprecated aliases: --quiet                 [boolean] [default: false]

  -v, --logging.verbose                 Set to true to log detailed RPC requests.
                                        deprecated aliases: --verbose               [boolean] [default: false]


Miner:
  -b, --miner.blockTime                 Sets the blockTime in seconds for automatic mining. A blockTime of 0
                                        enables "instamine mode", where new executable transactions will be
                                        mined instantly.
                                        deprecated aliases: --blockTime                  [number] [default: 0]

  -g, --miner.defaultGasPrice           Sets the default gas price in WEI for transactions if not otherwise
                                        specified.
                                        deprecated aliases: --gasPrice          [string] [default: 0x77359400]

  -l, --miner.blockGasLimit             Sets the block gas limit in WEI.
                                        deprecated aliases: --gasLimit            [string] [default: 0xb71b00]

  --miner.defaultTransactionGasLimit    Sets the default transaction gas limit in WEI. Set to "estimate" to
                                        use an estimate (slows down transaction execution by 40%+).
                                                                                   [string] [default: 0x15f90]

  --miner.difficulty                    Sets the block difficulty.                     [string] [default: 0x1]

  --miner.callGasLimit                  Sets the transaction gas limit in WEI for eth_call and eth_estimateGas
                                        calls.
                                                                                 [string] [default: 0x2faf080]
  --miner.instamine                     Set the...


↑