You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc-site/docs/reference/types/_includes/contractlistener_description.md
+141Lines changed: 141 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,3 +4,144 @@ of the interface for that event.
4
4
5
5
Check out the [Custom Contracts Tutorial](../../tutorials/custom_contracts/index.md) for
6
6
a walk-through of how to set up listeners for the events from your smart contracts.
7
+
8
+
See below for a deep dive into the format of contract listeners and important concepts to understand when managing them.
9
+
10
+
### Event filters
11
+
12
+
#### Multiple filters
13
+
14
+
From v1.3.1 onwards, a contract listener can be created with multiple filters under a single topic, when supported by the connector. Each filter contains:
15
+
16
+
- a reference to a specific blockchain event to listen for
17
+
- (optional) a specific location/address to listen from
18
+
- a connector-specific signature (generated from the event and the location)
19
+
20
+
In addition to this list of multiple filters, the listener specifies a single `topic` to identify the stream of events.
21
+
22
+
Creating a single listener that listens for multiple events will allow for the easiest management of listeners, and for strong ordering of the events that they process.
23
+
24
+
#### Single filter
25
+
26
+
Before v1.3.1, each contract listener would only support listening to one specific event from a contract interface. Each listener would be comprised of:
27
+
28
+
- a reference to a specific blockchain event to listen for
29
+
- (optional) a specific location/address to listen from
30
+
- a connector-specific signature (generated from the event), which allows you to easily identify and search for the contact listener for an event
31
+
- a `topic` which determines the ordered stream that these events are part of
32
+
33
+
For backwards compatibility, this format is still supported by the API.
34
+
35
+
### Signature strings
36
+
37
+
#### String format
38
+
39
+
Each filter is identified by a generated `signature` that matches a single event, and each contract listener is identified by a `signature` computed from its filters.
40
+
41
+
Ethereum provides a string standard for event signatures, of the form `EventName(uint256,bytes)`. Prior to v1.3.1, the signature of each Ethereum contract listener would exactly follow this Ethereum format.
42
+
43
+
As of v1.3.1, Ethereum signature strings have been changed, because this format does not fully describe the event - particularly because each top-level parameter can in the ABI definition be marked as `indexed`. For example, while the following two Solidity events have the same signature, they are serialized differently due to the different placement of `indexed` parameters, and thus a listener must define both individually to be able to process them:
The two above are now expressed in the following manner by the Ethereum blockchain connector:
58
+
59
+
```solidity
60
+
Transfer(address,address,uint256) [i=0,1]
61
+
Transfer(address,address,uint256) [i=0,1,2]
62
+
```
63
+
64
+
The `[i=]` listing at the end of the signature indicates the position of all parameters that are marked as `indexed`.
65
+
66
+
Building on the blockchain-specific signature format for each event, FireFly will then compute the final signature for each filter and each contract listener as follows:
67
+
68
+
- Each filter signature is a combination of the location and the specific connector event signature, such as `0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]`
69
+
- Each contract listener signature is a concatenation of all the filter signatures, separated by `;`
70
+
71
+
#### Duplicate filters
72
+
73
+
FireFly restricts the creation of a contract listener containing duplicate filters.
74
+
75
+
This includes the special case where one filter is a superset of another filter, due to a wildcard location.
76
+
77
+
For example, if two filters are listening to the same event, but one has specified a location and the other hasn't, then the latter will be a superset, and already be listening to all the events matching the first filter. Creation of duplicate or superset filters within a single listener will be blocked.
78
+
79
+
#### Duplicate listeners
80
+
81
+
As noted above, each listener has a generated signature. This signature - containing all the locations and event signatures combined with the listener topic - will guarantee uniqueness of the contract listener. If you tried to create the same listener again, you would receive HTTP 409. This combination can allow a developer to assert that their listener exists, without the risk of creating duplicates.
82
+
83
+
**Note:** Prior to v1.3.1, FireFly would detect duplicates simply by requiring a unique combination of signature + topic + location for each listener. The updated behavior for the listener signature is intended to preserve similar functionality, even when dealing with listeners that contain many event filters.
84
+
85
+
### Backwards compatibility
86
+
87
+
As noted throughout this document, the behavior of listeners is changed in v1.3.1. However, the following behaviors are retained for backwards-compatibility, to ensure that code written prior to v1.3.1 should continue to function.
88
+
89
+
- The response from all query APIs of `listeners` will continue to populate top-level `event` and `location` fields
90
+
- The first entry from the `filters` array is duplicated to these fields
91
+
- On input to create a new `listener`, the `event` and `location` fields are still supported
92
+
- They function identically to supplying a `filters` array with a single entry
93
+
- The `signature` field is preserved at the listener level
94
+
- The format has been changed as described above
95
+
96
+
### Input formats
97
+
98
+
The two input formats supported when creating a contract listener are shown below.
Copy file name to clipboardExpand all lines: doc-site/docs/tutorials/custom_contracts/ethereum.md
+59-15Lines changed: 59 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -648,21 +648,25 @@ Here is an example of sending 100 wei with a transaction:
648
648
649
649
Now that we've seen how to submit transactions and preform read-only queries to the blockchain, let's look at how to receive blockchain events so we know when things are happening in realtime.
650
650
651
-
If you look at the source code for the smart contract we're working with above, you'll notice that it emits an event when the stored value of the integer is set. In order to receive these events, we first need to instruct FireFly to listen for this specific type of blockchain event. To do this, we create an **Event Listener**. The `/contracts/listeners` endpoint is RESTful so there are `POST`, `GET`, and `DELETE` methods available on it. To create a new listener, we will make a `POST` request. We are going to tell FireFly to listen to events with name `"Changed"` from the FireFly Interface we defined earlier, referenced by its ID. We will also tell FireFly which contract address we expect to emit these events, and the topic to assign these events to. Topics are a way for applications to subscribe to events they are interested in.
651
+
If you look at the source code for the smart contract we're working with above, you'll notice that it emits an event when the stored value of the integer is set. In order to receive these events, we first need to instruct FireFly to listen for this specific type of blockchain event. To do this, we create an **Event Listener**. The `/contracts/listeners` endpoint is RESTful so there are `POST`, `GET`, and `DELETE` methods available on it. To create a new listener, we will make a `POST` request. We are going to tell FireFly to listen to events with name `"Changed"` from the FireFly Interface we defined earlier, referenced by its ID. We will also tell FireFly which contract address we expect to emit these events, and the topic to assign these events to. You can specify multiple filters for a listener, in this case we only specify one for our event. Topics are a way for applications to subscribe to events they are interested in.
0 commit comments