Merge branch 'main' into bump_cli

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` |
 
 

doc-site/docs/releasenotes/index.md

@@ -2,8 +2,35 @@
 title: Release Notes
 ---
 
+# Release Notes
+
 [Full release notes](https://github.com/hyperledger/firefly/releases)
 
+## [v1.3.3 - Mar 24, 2025](https://github.com/hyperledger/firefly/releases/tag/v1.3.3)
+
+What's New:
+- Add new interface for blockchain plugins to stream receipt notifications in transactional batches
+    - For blockchain connectors that have an `ack` based reliable receipt stream (or other checkpoint system)
+    - Allows strictly ordered delivery of receipts from blockchain plugins that support it
+    - Allows resilience on receipt delivery to core, against a checkpoint maintained in the connector
+- Changes in metrics:   
+    - Added new metrics for Data Exchange for monitoring by a timeseries and alerting system.
+        - `ff_multiparty_node_identity_dx_mismatch` notify that the certificate in FireFly Core is different to the one stored in Data Exchange
+        - `ff_multiparty_node_identity_dx_expiry_epoch` emit the timestamp of the certificate of Data Exchange useful for SREs to monitor before it expires 
+    - Added a namespace label to existing metrics to separate metrics more easily 
+    - Added HTTP Response Time and Complete Gauge Support to `firefly-common`
+    - Allow the `metrics` server to host additional routes such as status endpoints 
+        - This resulted in a new configuration section of `monitoring` to be more appropriate than `metrics` which has now be deprecated. 
+- Fix to issue that resulted in retried private messages using local namespace rather than the network namespace
+- Fix to issue that could result in messages being marked `Pending` on re-delivery of a batch over the network
+- Miscellaneous bug fixes and minor improvements
+- Documentation updates, new troubleshooting section for multiparty messages
+- CVE fixes and adoption of OpenSSF scorecard on key repositories
+    
+### Migration consideration
+
+As part of the changes to the metrics to add the new `namespace` label, we changed from using a Prometheus `Counter` to a `CounterVec`. As a result there is no default value of `0` on the counter, which means when users query for a specific metric such as `ff_message_rejected_total` it will not be available until the `CounterVec` associated with that metric is incremented. This has been determined to be an easy upgrade for SRE monitoring these metrics, hence inclusion in a patch release. 
+
 ## [v1.3.2 - Oct 3, 2024](https://github.com/hyperledger/firefly/releases/tag/v1.3.2)
 
 What's New:
@@ -24,7 +51,7 @@ What's New:
     See [Contract Listeners](../reference/types/contractlistener.md) for details
 - New multiparty status API at `/status/multiparty`
 
-## [v1.3.0 - April 25, 2024](https://github.com/hyperledger/firefly/releases/tag/v1.1.0)
+## [v1.3.0 - April 25, 2024](https://github.com/hyperledger/firefly/releases/tag/v1.3.0)
 
 [Migration guide](1.3_migration_guide.md)
 
@@ -50,9 +77,6 @@ What's New:
 - Custom HTTP headers can be passed through to FireFly dependency microservices
 - Evmconnect is now the default blockchain connector for Ethereum based FireFly stacks
 
-# Release Notes
-
-[Full release notes](https://github.com/hyperledger/firefly/releases)
 
 ## [v1.1.0 - September 12, 2022](https://github.com/hyperledger/firefly/releases/tag/v1.1.0)