Ganache v7's Instamine Modes Explained

[davidmurdoch]

This is an explanation of Ganache v7's new "instamine" modes . Let us know in the comments below if you need any further clarification.

New option --miner.instamine

Ganache has historically "instamined" transactions in a way that can cause code that works with Ganache to not work when run against a real network. By default Ganache returns the transaction's hash to the caller after the transaction has been included in a block, whereas transactions sent to a real node always return the hash before the transaction has been included in a block.

The following assertion will pass in Ganache, but fail when run on a real node:

const transactionHash = provider.request({method: "eth_sendTransaction", params: [transaction]});
const receipt = provider.request({method: "eth_getTransactionReceipt", params: [transactionHash]});
assert.notStrictEqual(receipt, null);

--miner.instamine=eager (default)

The new --miner.instamine defaults to eager, which is the same default behavior Ganache has always had. While convenient for writing tests and quick prototypes, this default behavior has led many new Ethereum developers to believe that eth_sendTransaction doesn't return until the transaction is included in a block.

That said, this behavior is so convenient that while wrong, we are not getting rid of it and will be keeping it as the default instamine mode in Ganache v7. We'll work on educating users where we can, and will provide a new method for users that want the speed of instamine, but behavior closer to that of a real node.

One related change in Ganache v7 that does depart from the old defaults is that the --vmErrorsOnRPCResponse flag now defaults to false; meaning you won't get transaction revert errors as a response to an eth_sendTransaction. If you need this behavior set the --chain.vmErrorsOnRPCResponse flag.

--miner.instamine=strict

To bring Ganache more in alignment with the behavior of a real node we've introduced a new strict instamine mode.

In strict mode we now add the transaction to an internal transaction pool, return the transaction's hash to the caller, and then process the transaction for inclusion in a block.

This change causes the previous code to fail, as the receipt will be null. We currently detect when a transaction receipt for a transaction that is currently in the pool is requested and log the following message with a link to this very discussion:

Ganache `eth_getTransactionReceipt` notice: the transaction with hash `{hash}` has not yet been mined.

If you connect to Ganache with a Web3 library like web3.js or ethers.js your code probably still works, but it may be much slower! 😲 This can happen if the library doesn't listen to the newHeads event early enough, causing the provider to poll for changes.

const receipt = await web3.eth.sendTransaction(tx); // this may take a whole second!

We'll be working with library authors to make sure the libraries listen to events correctly, so if the library you are using appears to fall back to polling make sure you've updated to the latest version, and if so please let us, or them, know by opening an Issue!

Now, to enable this new mode:

• on the command line:

ganache --miner.instamine strict

• programmatically:

ganache.provider({ miner: { instamine: "strict" } });

Awaiting Transactions in Strict Mode

A robust approach to wait for a transaction to be confirmed without a helper library like web3.js or ethers.js would be:

async function sendAndWaitForTransaction(transaction) {
  // subscribe to the newHeads event so we are notified on each new transaction
  const subId = await provider.request({ method: "eth_subscribe", params: ["newHeads"] });

  try {
    // send the transaction
    const txHash = await provider.request({ method: "eth_sendTransaction", params: [transaction] });

    // wait for the receipt
    return await new Promise((resolve, reject) => {
      // listen for newHeads event
      const off = provider.on("message", async message => {
        // only respond to our own subscription
        if (subId === message.data.subscription) {
          // check if our transaction has been included in a block
          const transaction = await provider.request({
            method: "eth_getTransactionByHash",
            params: [txHash]
          });

          // if the transaction was `null` it was probably discarded by the node
          if (transaction === null) {
            off(); // stop listening to newHeads

            reject(new Error("Transaction failed or discarded")); // throw

            // If the transaction has a `blockHash` it has been included in a block
          } else if (transaction.blockHash !== null) {
            off(); // stop listening to newHeads

            // return the receipt
            resolve(provider.request({ method: "eth_getTransactionReceipt", params: [txHash] }));
          }
        }
      });
    });
  } finally {
    // always clean up our subscription
    await provider.request({ method: "eth_unsubscribe", params: [subId] });
  }
}

If your use case can safely assume that transactions will always be successful and no other "message" events will be emitted by the provider (e.g. in your tests), this more terse (albeit naive) way of waiting for a transaction with a Ganache provider could be helpful:

async function naiveSendAndWaitForTransaction(transaction) {
  // subscribe to the newHeads event so we are notified on each new transaction
  const subId = await provider.request({ method: "eth_subscribe", params: ["newHeads"] });

  try {
    // send the transaction
    const txHash = await provider.request({ method: "eth_sendTransaction", params: [transaction] });

    // assume the next `message` will be from our `newHeads` subscription
    // and the block includes our transaction
    await provider.once("message");

    // return the receipt
    return await provider.request({ method: "eth_getTransactionReceipt", params: [txHash] });
  } finally {
    // always clean up our subscription
    await provider.request({ method: "eth_unsubscribe", params: [subId] });
  }
}

Another important side effect of this change is that EVM exceptions that occur during the execution of your transaction are now discarded, and the vmErrorsOnRPCResponse option has no effect! 😬

In the future we plan on implementing EIP-758 Subscriptions and filter for completed transactions in Ganache and other nodes, but in the meantime you'll have to work around this problem by replaying your transaction with eth_call (see this).

---

Let us know below if you have any questions.

[cds-amal]

Thanks for this excellent explanation @davidmurdoch!