docs: ahead of v1.3.1

[EnriqueL8]

Update release notes for the v1.3.1 release.

v1.3.1 included mostly fixes and the main feature to the FireFly Core is the multiple filter per contract listeners

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (3a2d40c) to head (c5718bb).
Report is 17 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1544   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          325       325           
  Lines        24022     24049   +27     
=========================================
+ Hits         24022     24049   +27     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[peterbroadhurst]

Suggested change

	- Enable contract listeners with multiple filters, old format is persevered for backwards compatibility
	- Enable contract listeners with multiple filters
	- See XXXX for detail

While there's no need for migration, we do need documentation for this feature (not sure we'd describe that as "format" as an aside"
The PR for this is not good reference information, due to the churn inside of there - but there's lots of raw information that could be harvested.

The two main places I think need reference to it is:

• https://hyperledger.github.io/firefly/head/reference/events/
  • Think this needs a small paragraph with a pointer "As of 1.3.1 a group of event filters can be established under a single topic when supported by the connector, which has benefits for ordering. See XXX for more detail"
• https://hyperledger.github.io/firefly/head/reference/types/contractlistener/
  • The example needs to be updated to be representative, and we need a clear code block describing the two supported ways to separate things.
  • Here would be the place for the core documentation on why you might choose to have a list of multiple filters grouped under a single listener

[peterbroadhurst]

I do think it's important we fully document this feature, and the reasons you might want to make changes in the application (even though you are not forced to)

[awrichar]

I've proposed some of my own edits here: #1550

[peterbroadhurst]

Suggested change

	This format is still supported by the API. However, it may not fully guarantee accurate ordering of events coming from multiple listeners, even if they share the same `topic` (such as during cases of blockchain catch-up, or when one listener is created much later than the others).
	For backwards compatibility the `event` and `signature` fields are still supported by the API. They contain the `event` from the first `filters` entry.

I think this is the point being made here? Not sure. Overall this paragraph seems a little confusing.

[peterbroadhurst]

No, you've made that point below.

I think this paragraph just needs removing

[peterbroadhurst]

it may not fully guarantee accurate ordering of events coming from multiple listeners

This statement has nothing to do with the API input/output format. I think you've elsewhere made the point how the new flexibility of allowing len(filter) > 1 is a good thing.

[peterbroadhurst]

Suggested change

	Note: For backwards compatibility, the response from the API will populate top-level `event` and `location` fields with the contents of the first event filter in the array.
	### Signature strings
	In order to precisely differentiate between different events within an array of filters and prevent duplication, we require a `signature` that exactly matches a single event.
	Ethereum provides a string standard for this of the form `EventName(uint256,bytes)`, but this does not fully describe the event because each top-level parameter can in the ABI definition be marked as `indexed`.
	For example, the following two famous Solidity event definition have the same signature, but are serialized differently and thus a listener must define both individually to be able to process them:
	- ERC-20 `Transfer`
	```solidity
	event Transfer(address indexed _from, address indexed _to, uint256 _value)
	```
	- ERC-721`Transfer`
	```solidity
	event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);
	```
	To handle this and provide uniqueness checking of events in a `filters` array while supporting events with different `indexed` settings on the fields, FireFly in 1.3.1 now uses a modified `signature` formula.
	The two above would be expressed:
	> TODO: @EnriqueL8 or @awrichar to fill in
	### Backwards compatibility
	- The response from all query APIs of `listeners` will populate top-level `event` and `location` fields
	- The first entry from the `filters` array is duplicated to these fields
	- On input to create a new `listener` the `event` and `location` fields are supported
	- They function identically to supplying a `filters` array with a single entry
	- The `signature` field is preserved at the top level
	- The format has been changed as described above
	- When multiple filters exist the signature contains multiple signature strings, concatenated with `;`

Validated from

firefly/internal/contracts/manager.go

Line 960 in 44ab1c7

sb.WriteString(";")

As an aside, I came across a confusingly named function on my travels (which has nothing to do with functions, which don't have an indexed bool):
https://github.com/hyperledger/firefly/blob/44ab1c72ffa5e47aa06746492b6bd4e72db7288b/internal/blockchain/ethereum/ethereum.go#L1021C6-L1021C33

[awrichar]

Yes, seems like ABIMethodToIndexedSignature does double duty by helping to parse both methods and events...