Open Primary Tabs Configuration Options
The previous posts in this series have given an introduction to Ethereum blockchain contracts and different types of interactions with them via their methods. Contract state over time can be determined via calling methods at different points in the blockchain, but iterating large parts of the blockchain to do so isn't efficient. Luckily, Ethereum provides an alternate method for understanding the state changes of a contract in a generic way, known as events.
An event allows a contract to log a change of state to the blockchain in a specific format to allow the Ethereum VM to easily retrieve and filter them, and an event can carry with it data about the state change.
Defining Events
The simple example contract introduced in the first post included the following event:
event Given(address indexed _from, address indexed _to);
The event signature syntax is essentially the same as a function, but it has no body itself, but it can take parameters which will be saved in the event data.
Firing Events
The event may be fired from other functions in the contract; in this case, when the owned item is given from one account to another via the give method:
function give(address _to) public onlyOwner {
Given(owner, _to);
owner = _to;
}
When the transaction is processed for a call to the give method, the logged event will also be included in the mined block, along with the parameter data it's called with.
Indexed Parameters
The above example shows two address type parameters, but notably also denotes them as indexed. The indexed keyword tells the Ethereum VM to place the argument in the topics section of the event data, which allows them to be easily searched and filtered based on that data.
Note that the event signature hash is the first topic by default (unless it is declared as anonymous), and each event is limited to a total of three indexed topics. An event can accept as many parameters as necessary, and they don't have to be indexed. Unindexed parameters appear encoded in the event data.
Loading Events
Based on the contract and transactions used in the earlier posts, a Given event can be seen by loading the transaction of the call that generated it:
> eth.getTransactionReceipt("0xed08a57547c40bad3bd6c3a318c9a0a1efd24e4bda241bc21765b21701b639fe");
{
...
logs: [{
address: "0x78561813fb0cfad61da69c3ca0ba6938637ca993",
blockHash: "0x40a0d5fa545f34b33bf11e89acae3fd3350ddeeb94b60bb7c86c2abc269d272f",
blockNumber: 92,
data: "0x",
logIndex: 0,
removed: false,
topics: ["0x320eced36ecfb55be328aacf4e2813ac7c426ee41f4ae29fd40781f9138d14e8", "0x000000000000000000000000498f0c603cf19cb5bef5461d7d9cf0acaa2f65b0", "0x00000000000000000000000002b831775e3d48b2bc107c8431d15aa4e0f8fd41"],
transactionHash: "0xed08a57547c40bad3bd6c3a318c9a0a1efd24e4bda241bc21765b21701b639fe",
transactionIndex: 0
}],
...
}
In this case, the event topics include the signature of the Given event and the addresses of the accounts involved in the transfer. This event has nothing in the additional data section because all of its parameters are indexed.
Event Filters
The real power of events is the ability to find and be notified about them based on the topics of the event. The Ethereum API for doing so differs slightly depending on how the client is communicating with it.
The web3 Ethereum js API can register a callback function along with a new filter request, which will be called with the resulting log messages (or newly-generated log messages asynchronously). If you’re using the JSON RPC, the client registers the filter instead and can check it periodically for new results. In either case, the syntax for doing so is largely the same.
A filter can specify one or more values for each of the three topics on log records, and can further be optionally restricted to a certain block range on the chain, or to one or more specific originating contract addresses.
Filtered events—combined with appropriate use of events in contracts—allow applications interacting with Ethereum blockchain contracts to easily determine and track changes in state for display to users.