Highlights    Breaking Changes    Fixes    New Features   Known Issues   Future Plans 

This release is the second alpha release of the new and improved Ganache v7.0.0. You'll definitely want to catch up on the previous changes, if you haven't already, before reading on!

But first, this is still an alpha release; even these 7.0.0 release notes are "alpha" and the information here is likely incomplete. There will be bugs and kinks to work out before we ship things off to beta, rc, then finally to latest. You absolutely should use this alpha release, but only to try it out and let us know where it breaks for you!

In other words: 🔥🐉 Here be dragons 🔥🐉️

To install globally run:

npm uninstall ganache-cli --global
npm install ganache@alpha --global

• Added Berlin's EIP-2930 Access List Transactions

• Added "london" hardfork support with EIP-1559 Fee Market Transactions

• Added a new provider event system

^{back to top}

The default hardfork has changed to "london"

We generally do not consider hardfork updates to be "breaking changes" in the semver sense, and they don't ever warrant a major version bump on their own. Regardless, we're listing the changes that are likely to cause your tests to fail here, instead of in the list of features, as it seems helpful to separate them out.

The London hardfork changes many things about the way Ethereum works, and many of these changes might cause your tests to break and fail. We've outlined the most common changes here:

Non-zero gas prices are not permitted

A side effect of the updating to London is that transactions can no longer be sent with a gasPrice of 0. The reason for this is that blocks automatically adjust the minimum gas price from one block to another. We'll be adding a feature flag to allow for zero-gasPrice transactions in the future. If you need zero-gasPrice transactions now you'll have to set the --hardfork flag to "berlin" or earlier.

Legacy transactions sent via eth_sendTransaction are automatically upgraded to "Type 2" (EIP-1559) transactions.

If you send a transaction with eth_sendTransaction and that transaction doesn't have a gasPrice field the transaction will be automatically "upgraded" to a type 2 transaction. Type 2 transactions will have many different fields for an identical legacy transaction sent pre-london.

// send a "legacy" transaction
const hash = await provider.request("eth_sendTransaction", [{ from }]); 
const tx = await provider.request("eth_getTransactionByHash", [hash]);
// The returned `type` field indicates it was updated to a type 2 transaction
assert.strictEqual(tx.type, "0x2");

New fields enabled by EIP-1559:

• maxPriorityFeePerGas:
  • Gas price above the block's base gas price you'll pay the miner.
  • currently defaults to 0, but we'll likely change this before v7.0.0.
• maxFeePerGas:
  • The maximum gas price you'll pay for the transaction.
  • For eth_sendTransaction, this value is defaulted to the maximum possible block base gas price over the next 3 blocks (the fee can theoretically increase by a maximum of 12.5% per block).
  • If the transaction cannot be included within the next 3 blocks it is possible it will be rejected for having a too-low maxFeePerGas value.

New fields enabled by the Berlin hardfork (EIP-2718, EIP-2930):

• type: The type, currently "0x0" (Legacy), "0x1" (EIP-2930), or "0x2" (EIP-1559)
• chainId: The chainId of the chain the transaction is intended for. If the chainId of the transaction doesn't match the chainId of the node the transaction will be rejected.
• accessList: A list of addresses and storage keys that the transaction plans to access. Accesses outside the list are possible, but may be more expensive.

Changed fields:

• hash
• v - type 1 and type 2 transactions do not encode the chain ID here (EIP-155) and do not include the addition of the number 27.
• r
• s

Transactions are now ordered relative to the "current" block's baseFeePerGas

Because the gas fee a transaction might pay now depends on the block's baseFeePerGas transactions are re-sorted in the context of each new block. Transaction ordering is still deterministic (except in rare cases) but the order now depends on previous blocks.

^{back to top}

• WebSocket connections are sometimes closed prematurely (#1097)
• Zero address transactions are now always signed with the same (fake) key (#1117)
• Signatures with r or s values containing leading 0s would result in incorrect transaction hashes

^{back to top}

This alpha release brings you Berlin and London hardfork support as well as a new ganache event system.

Berlin's Access List Transactions (EIP-2930)

Access List Transactions enable support for specifying an accessList. The access list defines a list of addresses and storage keys that the transaction plans to access. Accesses outside the list are possible, but may be more expensive.

See the EIP-2930 for details.

London and its Fee Market Transactions (EIP-1559)

EIP-1559 builds upon EIP-2930 by specifying a new transaction type: "0x2", or just "type 2".

Read about what EIP-1559 is and how it is changing Ethereum.

Event system

In addition to EIP-1193's "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, 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:

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.

With all that said, we might change this event system depending on feedback about it's API and usefulness. Follow or comment on this issue if you'd like to influence the design of this system.

^{back to top}

• transactions that aren't immediately executable can't be replaced by "better" transactions (#1219)
• replacement transactions are run twice (#1218)
• type 2 gasPrice needs to be handled better (#1213)
• eth_call needs additional eip-1559 gasPrice logic (#1214)
• It may be possible for the transaction pool to not be stable sorted (#1193)
• Forking is so very slow.
• Forking's chainId shouldn't match the remote chain. We really should use a different chainId than the remote, but still be able to contextualize past transactions with their original chainId.
• Our TypeScript types aren't properly exported.
• Our Docker container isn't published.
• We don't return a proper pending block.
• Uncles aren't fully supported when forking.
• Forking may fail in weird and unexpected ways. We need to "error better" here.

^{back to top}

• Support for enabling eligible draft EIPs before they are finalized or considered for inclusion in a hardfork.
• New hardfork support well in advance of the hardfork launch.
• Add an eth_createAccessList method.
• Add in VM events so tools like solcoverage will work.
• Track test performance metrics over time.
• Track real world Ganache usage (opt-in and anonymized) to better tune performance and drive bug fixes and feature development.
• Track test coverage.
• Document how to use Ganache in the browser, and what limits it has.
• evm_mine will return the new blocks instead of just 0x0.
• We've laid the groundwork for additional performance improvements. We expect to see an additional 2-5x speed up for typical testing work loads in the near future.
• Add new evm_setCode and evm_setStorageAt RPC methods.
• Make evm_snapshot ids globally unique (unpredictable instead of a counter).
• Support eth_getRawTransactionByHash RPC method.
• Support debug_accountAt RPC method.
• Allow "mining" to be disabled on start up.
• Set CLI options via config file, package.json, or ENV vars.
• "Flavor" Plugins: We're building support for Layer 2 plugins into Ganache so we can start up and manage other chains. e.g., The ganache filecoin command will look for the @ganache/filecoin package and start up a Filecoin and IPFS server.
• Multi-chain configurations: you'll be able to start up your project's entire blockchain "ecosystem" from a single ganache command: e.g., ganache --flavor ethereum --flavor filecoin --flavor optimism.
  • this is where defining your CLI options via JSON config will come in very handy!
• Integrate with Infura: e.g., ganache --fork mainnet to fork mainnet via your own Infura account.
• Create a CLI interactive/RELP mode.
• Enable a CLI daemon mode.

Open new issues (or join our team) to influence what we gets implemented and prioritized.

^{back to top}

💖 The Truffle Team