Merge pull request #1665 from hyperledger/update_listener_docs

Update contract listener documentation to be clearer

Author: EnriqueL8

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

@@ -40,7 +40,7 @@ Each filter is identified by a generated `signature` that matches a single event
 
 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.
 
-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:
+As of v1.3.1, Ethereum format signature strings have been changed in FireFly, 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:
 
 - ERC-20 `Transfer`
 
@@ -54,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 are now expressed in the following manner by the Ethereum blockchain connector:
+The two above are now expressed in the following manner by the FireFly Ethereum blockchain connector:
 
 ```solidity
 Transfer(address,address,uint256) [i=0,1]
@@ -65,7 +65,7 @@ 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 is a combination of the location and the specific connector event signature, such as `0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]`
+- Each filter signature is a combination of the location and the specific connector event signature, such as `0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Transfer(address,address,uint256) [i=0,1]`
 - Each contract listener signature is a concatenation of all the filter signatures, separated by `;`
 
 #### Duplicate filters
@@ -84,7 +84,7 @@ As noted above, each listener has a generated signature. This signature - contai
 
 ### Backwards compatibility
 
-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.
+As noted throughout this document, the behavior of listeners has 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.
 
 - The response from all query APIs of `listeners` will continue to populate top-level `event` and `location` fields
   - The first entry from the `filters` array is duplicated to these fields
@@ -93,12 +93,104 @@ As noted throughout this document, the behavior of listeners is changed in v1.3.
 - The `signature` field is preserved at the listener level
   - The format has been changed as described above
 
-### Input formats
+## Input examples
 
 The two input formats supported when creating a contract listener are shown below.
 
+### With event definition
+
+In these examples, the event schema in the FireFly Interface format is provided describing the event and its parameters. See [FireFly Interface Format](../firefly_interface_format.md)
+
 **Muliple Filters**
+```json
+{
+  "filters": [
+    {
+      "event": {
+          "name": "Changed",
+          "description": "",
+          "params": [
+              {
+                  "name": "x",
+                  "schema": {
+                      "type": "integer",
+                      "details": {
+                          "type": "uint256",
+                          "internalType": "uint256"
+                      }
+                  }
+              }
+          ]
+      },
+      "location": {
+        "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+      }
+    },
+    {
+      "event": {
+          "name": "AnotherEvent",
+          "description": "",
+          "params": [
+              {
+                  "name": "my-field",
+                  "schema": {
+                      "type": "string",
+                      "details": {
+                        "type": "address",
+                        "internalType": "address",
+                        "indexed": true
+                      }
+                  }
+              }
+          ]
+      },
+      "location": {
+        "address": "0xa4ea5d0b6b2eaf194716f0cc73981939dca27da1"
+      }
+    }
+  ],
+  "options": {
+    "firstEvent": "newest"
+  },
+  "topic": "simple-storage"
+}
+```
+
+**One filter (old format)**
+
+```json
+{
+  "event": {
+      "name": "Changed",
+      "description": "",
+      "params": [
+          {
+              "name": "x",
+              "schema": {
+                  "type": "integer",
+                  "details": {
+                      "type": "uint256",
+                      "internalType": "uint256"
+                  }
+              }
+          }
+      ]
+  },
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  },
+  "options": {
+    "firstEvent": "newest"
+  },
+  "topic": "simple-storage"
+}
+```
+
+### With interface reference
 
+These examples use an `interface` reference when creating the filters, the `eventPath` field is used to reference an event defined within the interface provided. In this case, we do not need to provide the event schema as the section above shows. See an example of creating a [FireFly Interface](../../tutorials/custom_contracts/ethereum.md/#the-firefly-interface-format) for an EVM smart contract. 
+
+**Muliple Filters**
 ```json
 {
   "filters": [

doc-site/docs/reference/types/contractlistener.md

@@ -121,9 +121,9 @@ title: ContractListener
 
 | Field Name | Description | Type |
 |------------|-------------|------|
-| `event` | The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI | [`FFISerializedEvent`](#ffiserializedevent) |
+| `event` | The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI when supplied | [`FFISerializedEvent`](#ffiserializedevent) |
 | `location` | A blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel | [`JSONAny`](simpletypes.md#jsonany) |
-| `interface` | A reference to an existing FFI, containing pre-registered type information for the event | [`FFIReference`](#ffireference) |
+| `interface` | A reference to an existing FFI, containing pre-registered type information for the event, used in combination with eventPath | [`FFIReference`](#ffireference) |
 | `signature` | The stringified signature of the event and location, as computed by the blockchain plugin | `string` |