Merge pull request #1555 from kaleido-io/docs_v1.3.1_awr

More listener docs

doc-site/docs/reference/types/_includes/contractlistener_description.md

@@ -7,17 +7,23 @@ a walk-through of how to set up listeners for the events from your smart contrac
 
 See below for a deep dive into the format of contract listeners and important concepts to understand when managing them.
 
-### Multiple filters
+### Event filters
 
-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:
+#### Multiple filters
+
+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:
 
 - a reference to a specific blockchain event to listen for
 - (optional) a specific location/address to listen from
 - a connector-specific signature (generated from the event and the location)
 
-In addition to this list of multiple filters, the listener specifies a single `topic` to identify the stream of events. This new feature will allow better management of contract listeners, and strong ordering of events matching multiple filters.
+In addition to this list of multiple filters, the listener specifies a single `topic` to identify the stream of events.
+
+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.
+
+#### Single filter
 
-Before this change, each contract listener would only support listening to one specific event from an interface previously defined. Each listener would be comprised of:
+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:
 
 - a reference to a specific blockchain event to listen for
 - (optional) a specific location/address to listen from
@@ -28,6 +34,8 @@ For backwards compatibility, this format is still supported by the API.
 
 ### Signature strings
 
+#### String format
+
 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.
 
 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.
@@ -46,7 +54,7 @@ As of v1.3.1, Ethereum signature strings have been changed, because this format
   event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);
   ```
 
-The two above will now be expressed in the following manner by the Ethereum blockchain connector:
+The two above are now expressed in the following manner by the Ethereum blockchain connector:
 
 ```solidity
 Transfer(address,address,uint256) [i=0,1]
@@ -57,14 +65,18 @@ The `[i=]` listing at the end of the signature indicates the position of all par
 
 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:
 
-- Each filter signature will be a combination of the location and the specific connector event signature, such as `0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]`
-- Each contract listener signature will be a concatenation of all the filter signatures, separated by `;`
+- Each filter signature is a combination of the location and the specific connector event signature, such as `0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]`
+- Each contract listener signature is a concatenation of all the filter signatures, separated by `;`
+
+#### Duplicate filters
+
+FireFly restricts the creation of a contract listener containing duplicate filters.
 
-### Duplicate filters
+This includes the special case where one filter is a superset of another filter, due to a wildcard location.
 
-FireFly will restrict the creation of a contract listener containing duplicate filters or superset filters. 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.
+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.
 
-### Duplicate listeners
+#### Duplicate listeners
 
 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.