diff --git a/doc-site/docs/reference/types/_includes/contractlistener_description.md b/doc-site/docs/reference/types/_includes/contractlistener_description.md index 5027b71ade..d9071511eb 100644 --- a/doc-site/docs/reference/types/_includes/contractlistener_description.md +++ b/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": [ diff --git a/doc-site/docs/reference/types/contractlistener.md b/doc-site/docs/reference/types/contractlistener.md index 9b5b13415a..f46e78186e 100644 --- a/doc-site/docs/reference/types/contractlistener.md +++ b/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` | diff --git a/doc-site/docs/swagger/swagger.yaml b/doc-site/docs/swagger/swagger.yaml index e56fed9a17..cfac89b6bb 100644 --- a/doc-site/docs/swagger/swagger.yaml +++ b/doc-site/docs/swagger/swagger.yaml @@ -1443,7 +1443,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -1487,7 +1487,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used + in combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -1725,7 +1726,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -1767,7 +1768,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used in + combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -5885,7 +5887,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -5929,7 +5931,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used + in combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -6082,7 +6085,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from the - referenced FFI + referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -6127,7 +6130,8 @@ paths: type: string interface: description: A reference to an existing FFI, containing pre-registered - type information for the event + type information for the event, used in combination with + eventPath properties: id: description: The UUID of the FireFly interface @@ -6251,7 +6255,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -6293,7 +6297,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used in + combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -6489,7 +6494,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -6531,7 +6536,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used in + combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -6683,7 +6689,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from the - referenced FFI + referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -6728,7 +6734,8 @@ paths: type: string interface: description: A reference to an existing FFI, containing pre-registered - type information for the event + type information for the event, used in combination with + eventPath properties: id: description: The UUID of the FireFly interface @@ -14132,7 +14139,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -14176,7 +14183,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used + in combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -14345,7 +14353,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from the - referenced FFI + referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -14385,7 +14393,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing pre-registered - type information for the event + type information for the event, used in combination with + eventPath properties: id: description: The UUID of the FireFly interface @@ -14509,7 +14518,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -14551,7 +14560,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used in + combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -19041,7 +19051,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -19085,7 +19095,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used + in combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -19245,7 +19256,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from the - referenced FFI + referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -19290,7 +19301,8 @@ paths: type: string interface: description: A reference to an existing FFI, containing pre-registered - type information for the event + type information for the event, used in combination with + eventPath properties: id: description: The UUID of the FireFly interface @@ -19414,7 +19426,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -19456,7 +19468,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used in + combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -19666,7 +19679,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from - the referenced FFI + the referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -19708,7 +19721,8 @@ paths: type: object interface: description: A reference to an existing FFI, containing - pre-registered type information for the event + pre-registered type information for the event, used in + combination with eventPath properties: id: description: The UUID of the FireFly interface @@ -19867,7 +19881,7 @@ paths: event: description: The definition of the event, either provided in-line when creating the listener, or extracted from the - referenced FFI + referenced FFI when supplied properties: description: description: A description of the smart contract event @@ -19912,7 +19926,8 @@ paths: type: string interface: description: A reference to an existing FFI, containing pre-registered - type information for the event + type information for the event, used in combination with + eventPath properties: id: description: The UUID of the FireFly interface diff --git a/internal/coremsgs/en_struct_descriptions.go b/internal/coremsgs/en_struct_descriptions.go index 208df0d3b5..98c2235a1c 100644 --- a/internal/coremsgs/en_struct_descriptions.go +++ b/internal/coremsgs/en_struct_descriptions.go @@ -319,8 +319,8 @@ var ( // ContractListenerOptions field descriptions ContractListenerOptionsFirstEvent = ffm("ContractListenerOptions.firstEvent", "A blockchain specific string, such as a block number, to start listening from. The special strings 'oldest' and 'newest' are supported by all blockchain connectors. Default is 'newest'") - ListenerFilterInterface = ffm("ListenerFilter.interface", "A reference to an existing FFI, containing pre-registered type information for the event") - ListenerFilterEvent = ffm("ListenerFilter.event", "The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI") + ListenerFilterInterface = ffm("ListenerFilter.interface", "A reference to an existing FFI, containing pre-registered type information for the event, used in combination with eventPath") + ListenerFilterEvent = ffm("ListenerFilter.event", "The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI when supplied") ListenerFilterEventPath = ffm("ListenerFilter.eventPath", "When creating a listener from an existing FFI, this is the pathname of the event on that FFI to be detected by this listener") ListenerFilterLocation = ffm("ListenerFilter.location", "A blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel") ListenerFilterSignature = ffm("ListenerFilter.signature", "The stringified signature of the event and location, as computed by the blockchain plugin")