2022-06-14 08:37:03 +00:00
|
|
|
.. index:: ! event, ! event; anonymous, ! event; indexed, ! event; topic
|
2019-01-07 13:50:21 +00:00
|
|
|
|
|
|
|
.. _events:
|
|
|
|
|
|
|
|
******
|
|
|
|
Events
|
|
|
|
******
|
|
|
|
|
|
|
|
Solidity events give an abstraction on top of the EVM's logging functionality.
|
|
|
|
Applications can subscribe and listen to these events through the RPC interface of an Ethereum client.
|
|
|
|
|
|
|
|
Events are inheritable members of contracts. When you call them, they cause the
|
|
|
|
arguments to be stored in the transaction's log - a special data structure
|
|
|
|
in the blockchain. These logs are associated with the address of the contract,
|
|
|
|
are incorporated into the blockchain, and stay there as long as a block is
|
2019-12-05 14:23:02 +00:00
|
|
|
accessible (forever as of now, but this might
|
2019-01-07 13:50:21 +00:00
|
|
|
change with Serenity). The Log and its event data is not accessible from within
|
|
|
|
contracts (not even from the contract that created them).
|
|
|
|
|
2019-12-05 14:23:02 +00:00
|
|
|
It is possible to request a Merkle proof for logs, so if
|
|
|
|
an external entity supplies a contract with such a proof, it can check
|
2019-01-07 13:50:21 +00:00
|
|
|
that the log actually exists inside the blockchain. You have to supply block headers
|
|
|
|
because the contract can only see the last 256 block hashes.
|
|
|
|
|
|
|
|
You can add the attribute ``indexed`` to up to three parameters which adds them
|
|
|
|
to a special data structure known as :ref:`"topics" <abi_events>` instead of
|
2021-05-25 16:05:45 +00:00
|
|
|
the data part of the log.
|
|
|
|
A topic can only hold a single word (32 bytes) so if you use a :ref:`reference type
|
|
|
|
<reference-types>` for an indexed argument, the Keccak-256 hash of the value is stored
|
|
|
|
as a topic instead.
|
2019-01-07 13:50:21 +00:00
|
|
|
|
|
|
|
All parameters without the ``indexed`` attribute are :ref:`ABI-encoded <ABI>`
|
|
|
|
into the data part of the log.
|
|
|
|
|
|
|
|
Topics allow you to search for events, for example when filtering a sequence of
|
|
|
|
blocks for certain events. You can also filter events by the address of the
|
|
|
|
contract that emitted the event.
|
|
|
|
|
|
|
|
For example, the code below uses the web3.js ``subscribe("logs")``
|
|
|
|
`method <https://web3js.readthedocs.io/en/1.0/web3-eth-subscribe.html#subscribe-logs>`_ to filter
|
|
|
|
logs that match a topic with a certain address value:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
|
|
|
var options = {
|
|
|
|
fromBlock: 0,
|
|
|
|
address: web3.eth.defaultAccount,
|
|
|
|
topics: ["0x0000000000000000000000000000000000000000000000000000000000000000", null, null]
|
|
|
|
};
|
|
|
|
web3.eth.subscribe('logs', options, function (error, result) {
|
|
|
|
if (!error)
|
|
|
|
console.log(result);
|
|
|
|
})
|
|
|
|
.on("data", function (log) {
|
|
|
|
console.log(log);
|
|
|
|
})
|
|
|
|
.on("changed", function (log) {
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
|
|
The hash of the signature of the event is one of the topics, except if you
|
|
|
|
declared the event with the ``anonymous`` specifier. This means that it is
|
2019-05-20 13:06:41 +00:00
|
|
|
not possible to filter for specific anonymous events by name, you can
|
|
|
|
only filter by the contract address. The advantage of anonymous events
|
2021-05-25 16:05:45 +00:00
|
|
|
is that they are cheaper to deploy and call. It also allows you to declare
|
|
|
|
four indexed arguments rather than three.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
Since the transaction log only stores the event data and not the type,
|
|
|
|
you have to know the type of the event, including which parameter is
|
|
|
|
indexed and if the event is anonymous in order to correctly interpret
|
|
|
|
the data.
|
|
|
|
In particular, it is possible to "fake" the signature of another event
|
|
|
|
using an anonymous event.
|
2019-01-07 13:50:21 +00:00
|
|
|
|
2022-06-14 08:37:03 +00:00
|
|
|
.. index:: ! selector; of an event
|
|
|
|
|
2022-04-11 07:20:20 +00:00
|
|
|
Members of Events
|
|
|
|
=================
|
|
|
|
|
|
|
|
- ``event.selector``: For non-anonymous events, this is a ``bytes32`` value
|
|
|
|
containing the ``keccak256`` hash of the event signature, as used in the default topic.
|
|
|
|
|
|
|
|
|
|
|
|
Example
|
|
|
|
=======
|
|
|
|
|
2021-07-01 13:17:42 +00:00
|
|
|
.. code-block:: solidity
|
2019-01-07 13:50:21 +00:00
|
|
|
|
2020-05-13 15:45:58 +00:00
|
|
|
// SPDX-License-Identifier: GPL-3.0
|
2020-09-08 08:48:04 +00:00
|
|
|
pragma solidity >=0.4.21 <0.9.0;
|
2019-01-07 13:50:21 +00:00
|
|
|
|
|
|
|
contract ClientReceipt {
|
|
|
|
event Deposit(
|
2022-02-16 02:59:49 +00:00
|
|
|
address indexed from,
|
|
|
|
bytes32 indexed id,
|
|
|
|
uint value
|
2019-01-07 13:50:21 +00:00
|
|
|
);
|
|
|
|
|
2022-02-16 02:59:49 +00:00
|
|
|
function deposit(bytes32 id) public payable {
|
2019-01-07 13:50:21 +00:00
|
|
|
// Events are emitted using `emit`, followed by
|
|
|
|
// the name of the event and the arguments
|
|
|
|
// (if any) in parentheses. Any such invocation
|
|
|
|
// (even deeply nested) can be detected from
|
|
|
|
// the JavaScript API by filtering for `Deposit`.
|
2022-02-16 02:59:49 +00:00
|
|
|
emit Deposit(msg.sender, id, msg.value);
|
2019-01-07 13:50:21 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
The use in the JavaScript API is as follows:
|
|
|
|
|
2021-07-14 16:52:39 +00:00
|
|
|
.. code-block:: javascript
|
2019-01-07 13:50:21 +00:00
|
|
|
|
|
|
|
var abi = /* abi as generated by the compiler */;
|
|
|
|
var ClientReceipt = web3.eth.contract(abi);
|
|
|
|
var clientReceipt = ClientReceipt.at("0x1234...ab67" /* address */);
|
|
|
|
|
2021-01-15 16:12:52 +00:00
|
|
|
var depositEvent = clientReceipt.Deposit();
|
2019-01-07 13:50:21 +00:00
|
|
|
|
|
|
|
// watch for changes
|
2021-01-15 16:12:52 +00:00
|
|
|
depositEvent.watch(function(error, result){
|
2019-01-07 13:50:21 +00:00
|
|
|
// result contains non-indexed arguments and topics
|
|
|
|
// given to the `Deposit` call.
|
|
|
|
if (!error)
|
|
|
|
console.log(result);
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
|
|
// Or pass a callback to start watching immediately
|
2021-01-15 16:12:52 +00:00
|
|
|
var depositEvent = clientReceipt.Deposit(function(error, result) {
|
2019-01-07 13:50:21 +00:00
|
|
|
if (!error)
|
|
|
|
console.log(result);
|
|
|
|
});
|
|
|
|
|
|
|
|
The output of the above looks like the following (trimmed):
|
|
|
|
|
|
|
|
.. code-block:: json
|
|
|
|
|
2021-07-14 16:56:55 +00:00
|
|
|
{
|
|
|
|
"returnValues": {
|
2022-02-16 02:59:49 +00:00
|
|
|
"from": "0x1111…FFFFCCCC",
|
|
|
|
"id": "0x50…sd5adb20",
|
|
|
|
"value": "0x420042"
|
2021-07-14 16:56:55 +00:00
|
|
|
},
|
|
|
|
"raw": {
|
|
|
|
"data": "0x7f…91385",
|
|
|
|
"topics": ["0xfd4…b4ead7", "0x7f…1a91385"]
|
|
|
|
}
|
|
|
|
}
|
2019-01-07 13:50:21 +00:00
|
|
|
|
|
|
|
Additional Resources for Understanding Events
|
2022-06-14 08:37:03 +00:00
|
|
|
=============================================
|
2019-01-07 13:50:21 +00:00
|
|
|
|
2023-03-28 13:59:48 +00:00
|
|
|
- `JavaScript documentation <https://github.com/web3/web3.js/blob/1.x/docs/web3-eth-contract.rst#events>`_
|
2020-08-06 12:37:22 +00:00
|
|
|
- `Example usage of events <https://github.com/ethchange/smart-exchange/blob/master/lib/contracts/SmartExchange.sol>`_
|
|
|
|
- `How to access them in js <https://github.com/ethchange/smart-exchange/blob/master/lib/exchange_transactions.js>`_
|