Event result documentation

Question

The current documentation does not go into detail about the structure of the result returned by an event. In this thread and this question, there are mentions about the fields of the result returned by an event listener but where is the documentation?

Answer 1

From JavaScript-API - web3.eth.filter:

• Object - When using manual filter options, it returns a log object as follows:

  • logIndex: Number - integer of the log index position in the block. null when its pending log.
  • transactionIndex: Number - integer of the transactions index position log was created from. null when its pending log.
  • transactionHash: String, 32 Bytes - hash of the transactions this log was created from. null when its pending log.
  • blockHash: String, 32 Bytes - hash of the block where this log was in. null when its pending. null when its pending log.
  • blockNumber: Number - the block number where this log was in. null when its pending. null when its pending log.
  • address: String, 32 Bytes - address from which this log originated.
  • data: String - contains one or more 32 Bytes non-indexed arguments of the log.
  • topics: Array of Strings - Array of 0 to 4 32 Bytes DATA of indexed log arguments. (In solidity: The first topic is the hash of the signature of the event (e.g. Deposit(address,bytes32,uint256)), except if you declared the event with the anonymous specifier.)

---

An Example Of A TheDAO.CreatedToken Event

Use the following geth commands to extract some CreatedToken events:

var theDAOABIFragment = [{"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"balanceOf","outputs":[{"name":"balance","type":"uint256"}],"type":"function"}, {"anonymous":false,"inputs":[{"indexed":true,"name":"to","type":"address"},{"indexed":false,"name":"amount","type":"uint256"}],"name":"CreatedToken","type":"event"}, {"anonymous":false,"inputs":[{"indexed":true,"name":"_from","type":"address"},{"indexed":true,"name":"_to","type":"address"},{"indexed":false,"name":"_amount","type":"uint256"}],"name":"Transfer","type":"event"}];
var theDAOAddress = "0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413";
var theDAO = web3.eth.contract(theDAOABIFragment).at(theDAOAddress);
var theDAOCreatedTokenEvent = theDAO.CreatedToken({}, {fromBlock: 1428757, toBlock: 1429757});
theDAOCreatedTokenEvent.watch(function(error, result) {
  console.log(JSON.stringify(result));
});

And here are the first two events

{"address":"0xbb9bc244d798123fde783fcc1c72d3bb8c189413","args":{"amount":"30000000000000000","to":"0xb504e60998c6f354a0794abd91d85e8bc8436211"},"blockHash":"0x031d5bac6154ca7616ac62e966da2b50a0aaa1b3bc24958ed9cb52d8c8fc1e2f","blockNumber":1429038,"event":"CreatedToken","logIndex":3,"transactionHash":"0xc96b0f95a1e7e8c07cd488a05f20f9e8d4003fe8eea0ec7f7f4bf199af3198e1","transactionIndex":9} {"address":"0xbb9bc244d798123fde783fcc1c72d3bb8c189413","args":{"amount":"500000000000000000","to":"0x53024f875bc85709af41d1c65c01fb4cc92d5c1c"},"blockHash":"0x48cf967fc94c2f808d82906c1a56e3e09abc99bb8279266fbace13963dc30a1f","blockNumber":1429053,"event":"CreatedToken","logIndex":0,"transactionHash":"0x1e9ec3974b89653961cbd996d4f6cfc2845db977a3385761b99ed459c2464740","transactionIndex":1}

And from TheDAO's source code, here is the definition of the CreatedToken event:

event CreatedToken(address indexed to, uint amount);

So looking at the first record from the results we have:

• address: "0xbb9bc244d798123fde783fcc1c72d3bb8c189413" - The DAO's address
• args - CreatedToken's arguments
  • amount: "30000000000000000"
  • to: "0xb504e60998c6f354a0794abd91d85e8bc8436211"
• blockHash: "0x031d5bac6154ca7616ac62e966da2b50a0aaa1b3bc24958ed9cb52d8c8fc1e2f" - hash of the block containing the event
• blockNumber: 1429038 - number of the block containing the event
• event: CreatedToken - Event name
• logIndex: 3
• transactionHash: "0xc96b0f95a1e7e8c07cd488a05f20f9e8d4003fe8eea0ec7f7f4bf199af3198e1"
• transactionIndex: 9

Getting the transactions getTransactionReceipt(...), you can see the same event data in the logs data structure:

> eth.getTransactionReceipt("0xc96b0f95a1e7e8c07cd488a05f20f9e8d4003fe8eea0ec7f7f4bf199af3198e1")
{
  blockHash: "0x031d5bac6154ca7616ac62e966da2b50a0aaa1b3bc24958ed9cb52d8c8fc1e2f",
  blockNumber: 1429038,
  contractAddress: null,
  cumulativeGasUsed: 284538,
  from: "0xfbb1b73c4f0bda4f67dca266ce6ef42f520fbb98",
  gasUsed: 91206,
  logs: [{
      address: "0xbb9bc244d798123fde783fcc1c72d3bb8c189413",
      blockHash: "0x031d5bac6154ca7616ac62e966da2b50a0aaa1b3bc24958ed9cb52d8c8fc1e2f",
      blockNumber: 1429038,
      data: "0x000000000000000000000000000000000000000000000000006a94d74f430000",
      logIndex: 3,
      topics: ["0xdbccb92686efceafb9bb7e0394df7f58f71b954061b81afb57109bf247d3d75a", "0x000000000000000000000000b504e60998c6f354a0794abd91d85e8bc8436211"],
      transactionHash: "0xc96b0f95a1e7e8c07cd488a05f20f9e8d4003fe8eea0ec7f7f4bf199af3198e1",
      transactionIndex: 9
  }],
  root: "e8ba75bf5d12f93c991721565270a135194887b9260b3f7d809d9a6270dcd6c5",
  to: "0xbb9bc244d798123fde783fcc1c72d3bb8c189413",
  transactionHash: "0xc96b0f95a1e7e8c07cd488a05f20f9e8d4003fe8eea0ec7f7f4bf199af3198e1",
  transactionIndex: 9
}

Getting the block's data, you can see that blockHash above is the same as hash below:

> eth.getBlock(1429038);
{
  difficulty: 32654434227321,
  extraData: "0xd783010306844765746887676f312e352e31856c696e7578",
  gasLimit: 4712388,
  gasUsed: 368538,
  hash: "0x031d5bac6154ca7616ac62e966da2b50a0aaa1b3bc24958ed9cb52d8c8fc1e2f",
  logsBloom: "0x00400000000000020000000000020000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000001002000000000000000005000000020000000000000000000000000000000000000000000000000002000000000000000000000000000040000000000000000000008000000000000000000000000000000000000000000000000000000000000000000400000000000000000",
  miner: "0x2a65aca4d5fc5b5c859090a6c34d164135398226",
  nonce: "0x1ec6b2f3920a1b75",
  number: 1429038,
  parentHash: "0xb70be7a89e89a93248498c60e0254f7212bdec42ec5f3be3e9c4687c46a8dd21",
  receiptRoot: "0x0c80b60072f41ffe060af09913c09e8760839e084b1711663b6c05e5b5b4a698",
  sha3Uncles: "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
  size: 2144,
  stateRoot: "0x1b7a7df358c82b30a2e84e10bde606af1a1e868bde1abf499518f5282b4c2caa",
  timestamp: 1461984747,
  totalDifficulty: 16452703203387523239,
  transactions: ["0x07233561a800dcd2d0b7f5b913f689d15418264f3c025959a04c6a06fc83a715", "0x7d62d8988352db1bef3d2814c80bd78c0789e0345bb5a71bb4b61595e0f2c490", "0xebf630e4bdc04eeebfac6283ca208ed49d80c4ae3340cb6f15df050fc8c1e4ef", "0xa60119d8f8078b862e8df96877f9846d68ba89798be0510b7cf8593eb2f80bc4", "0xbc9850758015bf24e115a0d019001972259b58a562f3664e03df71f709e6cff5", "0xc271d871f5becd2e00b0bd6e1460e7f77812b985ae5de79a0e0f3bfc9ee4f82d", "0xada6df7c55113ddda794ba9924245e4c2b3ff9a7a61d00477976df28910961f6", "0x222b83cac7b441eea0b769268b9534167295065b11b62ad4c3b80c17384ae4da", "0xa3c3bcdb89da86c6b7d174ccb375702c32fb9bfc662d5281436d0da7bb66630f", "0xc96b0f95a1e7e8c07cd488a05f20f9e8d4003fe8eea0ec7f7f4bf199af3198e1", "0xa8ae7985e399753bcc8fd9b92a6a2af206c1b9e813412a337a0c073d3d25ef05", "0xea513060036eb3128e1b9a0d0d434a51b63c9fa45a8048961a766231f7e6ab03", "0x81fc3f258042fc69b11970e632e7fbbb4bbaae1fa52facde2cdd8d76d46fb8e4", "0x6e806f8ecd9b511d560819219e8fb11cf47cb7d9ad643574fb121687d89d175b"],
  transactionsRoot: "0x15fb5d46063445c898589e3894c1002eecac98fdecf6d4ae6c82c78a03ce9390",
  uncles: []
}

Let's work out the data field from the getTransactionReceipt(...) result:

data: "0x000000000000000000000000000000000000000000000000006a94d74f430000"

This is the unindexed parameter to the CreatedToken event:

> web3.toBigNumber("0x000000000000000000000000000000000000000000000000006a94d74f430000")
30000000000000000

And let's work out the topics from the getTransactionReceipt(...) result:

topics: ["0xdbccb92686efceafb9bb7e0394df7f58f71b954061b81afb57109bf247d3d75a", "0x000000000000000000000000b504e60998c6f354a0794abd91d85e8bc8436211"],

The first element "0xdbccb92686efceafb9bb7e0394df7f58f71b954061b81afb57109bf247d3d75a" is the signature of the event:

> web3.sha3('CreatedToken(address,uint256)')
"0xdbccb92686efceafb9bb7e0394df7f58f71b954061b81afb57109bf247d3d75a"

The second element "0x000000000000000000000000b504e60998c6f354a0794abd91d85e8bc8436211" is the indexed to address parameter.

From github - go-ethereum/core/vm/log.go, lines 67-80:

func (r *Log) MarshalJSON() ([]byte, error) {
    fields := map[string]interface{}{
        "address":          r.Address,
        "data":             fmt.Sprintf("%#x", r.Data),
        "blockNumber":      fmt.Sprintf("%#x", r.BlockNumber),
        "logIndex":         fmt.Sprintf("%#x", r.Index),
        "blockHash":        r.BlockHash,
        "transactionHash":  r.TxHash,
        "transactionIndex": fmt.Sprintf("%#x", r.TxIndex),
        "topics":           r.Topics,
    }

    return json.Marshal(fields)
}