Ethereum – How to Determine Gas Usage When Calling a Contract

contract-invocationgastransactions

When I am calling (sending a transaction to) a contract how do I determine how much gas to use? Is there a way to calculate this upfront & what happens if I send too much / too few gas?

Best Answer

There are estimateGas APIs in both the JSON-RPC and Javascript.

They are estimates and for developers that want further precision, testing is required, possibly on a private chain.

If too much gas is provided, the excess gas is converted to ether and refunded. If too few gas is specified, all the specified gas is forfeited to the miner and the transaction is reverted: just like the contract was never called.

Users will generally have to trust the DApp they are using, and DApps that have good UI and UX, may indicate some estimated costs to the user, or possibly even hide such details by sending the user's account some ether, or giving a new user an account that has some ether.

This is feasible because most transactions require a very small amount of ether; 1 ether is 10^18 wei and can run many transactions. As an example, if one were simply using Ethereum to transfer wei/ether around, at the current gas price of 5 Gigawei, a user can do around 9523 transfers with 1 ether. This is because a value transfer transaction costs 21000 gas, and thus the computation is 1e18 / (21000 * 5e9) = 9523.80.

Using etherscan blockchain explorer

In etherscan, look for the TxReceipt Status which will have Fail in red, or Success in green.

Example of a failure: https://ropsten.etherscan.io/tx/0x67a5f6442f49a5da6ff8682250a8eef899d9dc0c5adf20b683709433902b5956

Using the receipt

eth.getTransactionReceipt(transactionHash) will return a status field that has a value of 0 when a transaction has failed and 1 when the transaction has succeeded.

Here's an example showing the status field:

{ blockHash: '0xb1fcff633029ee18ab6482b58ff8b6e95dd7c82a954c852157152a7a6d32785e',
  blockNumber: 4370000,
  contractAddress: null,
  cumulativeGasUsed: 21000,
  gasUsed: 21000,
  logs: [],
  logsBloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
  root: null,
  status: 1, // **** HERE IS THE STATUS FIELD *****
  transactionHash: '0x1421a887a02301ae127bf2cd4c006116053c9dc4a255e69ea403a2d77c346cf5',
  transactionIndex: 0 }

More details here.

Historical

To see if a transaction ran out of gas, you can input the transaction (hash) in https://live.ether.camp and then click on "VM Trace". (For the testnet Morden, use https://morden.ether.camp)

Or plug in the transactionHash in this url:

https://live.ether.camp/transaction/<transactionHash>/vmtrace#0

For the transaction mentioned in the question, 022f440fa96eb469363804d7b6c52321d4f409fa76578cdbdc5f04ff494b1321

here is the output https://live.ether.camp/transaction/022f440fa96eb469363804d7b6c52321d4f409fa76578cdbdc5f04ff494b1321/vmtrace#0

This transaction was out of gas immediately. Some transactions may run out of gas after doing some computations, and clicking on the Operations will show each step being performed and when the out of gas happens.

Transaction Status Detection – Handling Gas Errors and Successes

Summary

I have sent a test transaction (#1) to firstly find out how much gas a successful smart contract transaction uses. From the results of this transaction, the gas required for a successful transaction is 26747.

I then used this 26747 gas amount in my going-to-be-successful transaction (#2). And gasUsed == gas.

I then use this same 26747 gas amount in my going-to-be-UNSUCCESSFUL transaction (#3). And gasUsed == gas.

The only reliable way I have found so far to easily check if a smart contract transaction is successful is to use debug.traceTransaction and check the last error message. If this is "" then no error occurred. If this is "Out of gas" or "invalid jump destination (PUSH1) 2", then an error occurred.

And here's a short bit of code to determine the status of your transaction.

> var status = debug.traceTransaction("0xd23219e2ea10528b245deb9e47993cae2ffd3ffe9fc27aeb808e94fc4e75d37b")
undefined
> if (status.structLogs.length > 0) {
  console.log(status.structLogs[status.structLogs.length-1].error)
}
"invalid jump destination (PUSH1) 2"

The return value above will be "" if there are no errors, or "Out of gas" if you run out of gas.

UPDATE 29/07/2016 - the geth --fast blockchain download does not contain the information for debug.traceTransaction(...) to display.

Details

I'm using the following example for a smart contract that throws an exception if _value < 12345:

contract TestStatus {
    uint public value;
    function setValue(uint256 _value) {
        value = _value;
        if (_value < 12345) {
            throw;
        }
    }
}

I flattened the source to:

var testStatusSource='contract TestStatus { uint public value; function setValue(uint256 _value) { value = _value; if (_value < 12345) { throw; } }}'

I compiled and inserted the contract into the blockchain:

var testStatusCompiled = web3.eth.compile.solidity(testStatusSource);

var testStatusContract = web3.eth.contract(testStatusCompiled.TestStatus.info.abiDefinition);
var testStatus = testStatusContract.new({
  from:web3.eth.accounts[0], 
  data: testStatusCompiled.TestStatus.code, gas: 1000000}, 
  function(e, contract) {
    if (!e) {
      if (!contract.address) {
        console.log("Contract transaction send: TransactionHash: " + contract.transactionHash + 
          " waiting to be mined...");
      } else {
        console.log("Contract mined! Address: " + contract.address);
        console.log(contract);
      }
  }
})
Contract transaction send: TransactionHash: 0x4de11cc54484333036f45a2441563d6badae43d2e2789e0b113b6703a582a879 waiting to be mined...
undefined
...
Contract mined! Address: 0x87847eb0f944fbb6d5c5a4891e3b103a63cee45c
[object Object]

I sent a transaction that won't cause an error to determine the gas required:

# Not an error
testStatus.setValue(123456, eth.accounts[0], {
  from:web3.eth.accounts[0], 
  data: testStatusCompiled.TestStatus.code,
  gas: 41747
});
...
> eth.getTransactionReceipt("0x727cb3c6846bbb05c8437e97aa32db39a252426b09ed837a76bb364748ce73c4")
{
  blockHash: "0x293b4d357d72615c409ba37a6430253d64b4646e0366ac987d1364a258cf81fa",
  blockNumber: 2465,
  contractAddress: null,
  cumulativeGasUsed: 26747,
  from: "0xa7857047907d53a2e494d5f311b4b586dc6a96d2",
  gasUsed: 26747,
  logs: [],
  root: "fbb29f9eff2340aa8d7df7feec74671c2b693fb9e7b6ec3b710ca6d64813da0e",
  to: "0x87847eb0f944fbb6d5c5a4891e3b103a63cee45c",
  transactionHash: "0x727cb3c6846bbb05c8437e97aa32db39a252426b09ed837a76bb364748ce73c4",
  transactionIndex: 0
}

The gas required is 26747.

I sent a transaction with value=123456 that will NOT fail, and gas==gasUsed:

testStatus.setValue(123456, eth.accounts[0], {
  from:web3.eth.accounts[0], 
  data: testStatusCompiled.TestStatus.code,
  gas: 26747
});
0xc0ab94adfe473811d055f98528a625dbebf66026b7ec5ad8eab939de862bc2d1

I'm using debug.traceTransaction to confirm that this transaction has not encountered an error.

> var status = debug.traceTransaction("0xc0ab94adfe473811d055f98528a625dbebf66026b7ec5ad8eab939de862bc2d1")
undefined
> status.structLogs[status.structLogs.length-1].error
""

And in this situation gas(26747) == gasUsed(26747)

eth.getTransaction("0xc0ab94adfe473811d055f98528a625dbebf66026b7ec5ad8eab939de862bc2d1")
{
  blockHash: "0x961277e2bebfe8332a23d240672b2658eced493b70fd145c99991c3c8651adcc",
  blockNumber: 2475,
  from: "0xa7857047907d53a2e494d5f311b4b586dc6a96d2",
  gas: 26747,
  gasPrice: 20000000000,
  hash: "0xc0ab94adfe473811d055f98528a625dbebf66026b7ec5ad8eab939de862bc2d1",
  input: "0x55241077000000000000000000000000000000000000000000000000000000000001e240",
  nonce: 66,
  to: "0x87847eb0f944fbb6d5c5a4891e3b103a63cee45c",
  transactionIndex: 0,
  value: 0
}
eth.getTransactionReceipt("0xc0ab94adfe473811d055f98528a625dbebf66026b7ec5ad8eab939de862bc2d1")
{
  blockHash: "0x961277e2bebfe8332a23d240672b2658eced493b70fd145c99991c3c8651adcc",
  blockNumber: 2475,
  contractAddress: null,
  cumulativeGasUsed: 26747,
  from: "0xa7857047907d53a2e494d5f311b4b586dc6a96d2",
  gasUsed: 26747,
  logs: [],
  root: "f850e1e5c99352f47e3409e4e9f966a49c13152e63aaa7bb3765f0b37bfe09e5",
  to: "0x87847eb0f944fbb6d5c5a4891e3b103a63cee45c",
  transactionHash: "0xc0ab94adfe473811d055f98528a625dbebf66026b7ec5ad8eab939de862bc2d1",
  transactionIndex: 0
}

I then sent a transaction with value=123 that failed, and gas==gasUsed:

testStatus.setValue(123, eth.accounts[0], {
  from:web3.eth.accounts[0], 
  data: testStatusCompiled.TestStatus.code,
  gas: 26747
});

0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a
> var status = debug.traceTransaction("0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a")
undefined
> status.structLogs[status.structLogs.length-1].error
"invalid jump destination (PUSH1) 2"

> eth.getTransaction("0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a")
{
  blockHash: "0x22fb5fcaef27dd017efcde8c3f78df7f5168c505210f5d08872a9c2877146044",
  blockNumber: 2484,
  from: "0xa7857047907d53a2e494d5f311b4b586dc6a96d2",
  gas: 26747,
  gasPrice: 20000000000,
  hash: "0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a",
  input: "0x55241077000000000000000000000000000000000000000000000000000000000000007b",
  nonce: 67,
  to: "0x87847eb0f944fbb6d5c5a4891e3b103a63cee45c",
  transactionIndex: 0,
  value: 0
}
> eth.getTransactionReceipt("0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a")
{
  blockHash: "0x22fb5fcaef27dd017efcde8c3f78df7f5168c505210f5d08872a9c2877146044",
  blockNumber: 2484,
  contractAddress: null,
  cumulativeGasUsed: 26747,
  from: "0xa7857047907d53a2e494d5f311b4b586dc6a96d2",
  gasUsed: 26747,
  logs: [],
  root: "ab51ab81c19eb8da7f8d0216d6c2f1d8946e88842b758ff0af13c28ff7e181b4",
  to: "0x87847eb0f944fbb6d5c5a4891e3b103a63cee45c",
  transactionHash: "0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a",
  transactionIndex: 0
}

So the only easy reliable way I've found to determine if a smart contract transaction has succeeded or failed is to use debug.traceTransaction.

Here's the output of debug.traceTransaction for the last transaction that failed.

debug.traceTransaction("0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a")
{
  gas: 26747,
  returnValue: "",
  structLogs: [{
      depth: 1,
      error: "",
      gas: 5280,
      gasCost: 3,
      memory: null,
      op: "PUSH1",
      pc: 0,
      stack: [],
      storage: {}
  }, {
      depth: 1,
      error: "",
      gas: 5277,
      gasCost: 3,
      memory: null,
      op: "PUSH1",
      pc: 2,
      stack: ["0000000000000000000000000000000000000000000000000000000000000060"],
      storage: {}
  }, {
  ...
  }, {
      depth: 1,
      error: "invalid jump destination (PUSH1) 2",
      gas: 129,
      gasCost: 8,
      memory: ["0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"],
      op: "JUMP",
      pc: 66,
      stack: ["0000000000000000000000000000000000000000000000000000000055241077", "0000000000000000000000000000000000000000000000000000000000000022", "000000000000000000000000000000000000000000000000000000000000007b"],
      storage: {
        0000000000000000000000000000000000000000000000000000000000000000: "000000000000000000000000000000000000000000000000000000000000007b"
      }
  }]
}

And here's a short script to check if the transaction passed or failed:

> var status = debug.traceTransaction("0x9ee86a200528de32a695f1e2dd0d94a3871fefc7e49c5fd24a4a37eab1b99f7a")
undefined
> status.structLogs[status.structLogs.length-1].error
"invalid jump destination (PUSH1) 2"