Moved finality listeners to FSC

docs/core-token.md

@@ -28,7 +28,53 @@ token:
     # leaseCleanupTickPeriod defines how often the eviction algorithm must be executed
     # if leaseCleanupTickPeriod is zero, the eviction algorithm is never executed
     leaseCleanupTickPeriod: 90s
-
+  # when we are interested to know when a tx reaches finality, we subscribe to the Finality Listener Manager for the finality event of that tx
+  # this configuration specifies the way the manager is instantiated, i.e. how it gets notified about the finality events, how often it checks
+  finality:
+    # the implementation of the finality manager. The finality manager keeps track of all subscribers that are interested to a transaction.
+    # These are the possible values:
+    # delivery: The manager subscribes to the delivery service and receives all final transactions.
+    # This manager keeps two structures: an LRU cache of recently finalized transactions, and a list of listeners that are waiting for future transactions.
+    # When a new block comes from the delivery service, we store all new transactions in the cache and notify all interested listeners
+    # When a client subscribes to the manager for a specific transaction, we go through the following steps, that correspond to all possible scenarios with decreasing probability:
+    # a) The transaction reached finality recently, so we perform a lookup. If not found, we go to step b.
+    # b) The transaction will reach finality shortly, so we append a listener and wait for a timeout. If the listener reaches timeout, we go to step c.
+    # c) The transaction reached finality long ago, so we query the whole ledger for this specific transaction. If the query returns no result, we go to step d.
+    # d) The transaction will reach finality at some point beyond the timeout or never, so we return Unknown. Then it is up to the client to either append another listener or accept that the transaction will never reach finality.  
+    # committer: The manager subscribes to the commit pipeline and receives all finalized transactions.
+    # If we subscribe for a transaction that hasn't been finalized yet, we will get notified once it reaches the commit pipeline.
+    # For listeners that haven been invoked yet, either the transaction hasn't been finalized or it was finalized before we subscribed.
+    # For this reason, there is a periodic polling period (1s) that queries all txIDs for which there is a pending listener and invokes the listeners for the ones found.
+    # Once we get notified about finality, we try (repeatedly) to fetch the additional tx information needed from the vault (e.g. transactionRequest)
+    # If we work without replicas, there is no need to try more than once to fetch the additional tx information, because the finality notification and vault update happen in sync.
+    # It is only needed in case we have replicas, where another replica may have updated the vault shortly before.
+    type: delivery
+    # Only applicable when type = 'committer'
+    committer:
+      # how many times should we try to fetch the additional tx information from the vault
+      maxRetries: 3
+      # how long should we wait before retrying
+      retryWaitDuration: 5s
+    # Only applicable when type = 'delivery'
+    delivery:
+      # how many goroutines should process incoming transactions in parallel. Defaults to 1
+      mapperParallelism: 10
+      # how many blocks can we process in parallel when they arrive from the delivery service
+      # if the value is <= 1, then blocks are processed sequentially.
+      # This is the suggested configuration if we are not sure about the dependencies between blocks.
+      # The total go routines processing transactions will be blockProcessParallelism * mapperParallelism
+      blockProcessParallelism: 1
+      # how many transactions should we guarantee that we keep in our recent cache
+      # if the transaction is not among these elements we proceed to the step b, as described above.
+      # if lruSize and lruBuffer are not set, then we will never evict past transactions (the cache will grow infinitely)
+      lruSize: 30
+      # eviction will happen when the cache size exceeds lruSize + lruBuffer
+      lruBuffer: 15
+      # when we can't find a transaction in the cache most probably it is about to become final
+      # we will listen for this amount of time and then we will query the whole ledger, as described in step c.
+      # if the timeout is not set, then the listener will never be evicted and we will never proceed to step c.
+      # We will wait forever for the transaction to return (as is done for the 'committer' type)
+      listenerTimeout: 10s
   tms:
     mytms: # unique name of this token management system
       network: default # the name of the network this TMS refers to (Fabric, Orion, etc)

go.mod

@@ -9,7 +9,7 @@ require (
 	github.com/gin-gonic/gin v1.10.0
 	github.com/gobuffalo/packr/v2 v2.7.1
 	github.com/hashicorp/go-uuid v1.0.3
-	github.com/hyperledger-labs/fabric-smart-client v0.3.1-0.20241225184208-74446d73506d
+	github.com/hyperledger-labs/fabric-smart-client v0.3.1-0.20250106134255-d16c2938ac4f
 	github.com/hyperledger-labs/orion-sdk-go v0.2.10
 	github.com/hyperledger-labs/orion-server v0.2.10
 	github.com/hyperledger/fabric v1.4.0-rc1.0.20230405174026-695dd57e01c2
@@ -38,7 +38,6 @@ require (
 	go.uber.org/dig v1.18.0
 	go.uber.org/zap v1.27.0
 	golang.org/x/exp v0.0.0-20241009180824-f66d83c29e7c
-	golang.org/x/sync v0.10.0
 	google.golang.org/protobuf v1.35.1
 	gopkg.in/yaml.v2 v2.4.0
 	modernc.org/sqlite v1.33.1
@@ -275,6 +274,7 @@ require (
 	golang.org/x/mod v0.21.0 // indirect
 	golang.org/x/net v0.31.0 // indirect
 	golang.org/x/oauth2 v0.23.0 // indirect
+	golang.org/x/sync v0.10.0 // indirect
 	golang.org/x/sys v0.28.0 // indirect
 	golang.org/x/text v0.21.0 // indirect
 	golang.org/x/time v0.5.0 // indirect

go.sum

@@ -1070,8 +1070,8 @@ github.com/hidal-go/hidalgo v0.0.0-20201109092204-05749a6d73df/go.mod h1:bPkrxDl
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
 github.com/huin/goupnp v1.3.0 h1:UvLUlWDNpoUdYzb2TCn+MuTWtcjXKSza2n6CBdQ0xXc=
 github.com/huin/goupnp v1.3.0/go.mod h1:gnGPsThkYa7bFi/KWmEysQRf48l2dvR5bxr2OFckNX8=
-github.com/hyperledger-labs/fabric-smart-client v0.3.1-0.20241225184208-74446d73506d h1:8PpO3OG7v/uH7FLnfCGtAuiQ5YUE9xvgUy66Rd1aod8=
-github.com/hyperledger-labs/fabric-smart-client v0.3.1-0.20241225184208-74446d73506d/go.mod h1:Fcz6IOEmwXihzi/Hn8fxuyAbyJxhe706+TJsQwLHRME=
+github.com/hyperledger-labs/fabric-smart-client v0.3.1-0.20250106134255-d16c2938ac4f h1:sCwxAxLasNlrwfkIszj1f8gP1Th9wj9DykKh3el0weE=
+github.com/hyperledger-labs/fabric-smart-client v0.3.1-0.20250106134255-d16c2938ac4f/go.mod h1:Fcz6IOEmwXihzi/Hn8fxuyAbyJxhe706+TJsQwLHRME=
 github.com/hyperledger-labs/orion-sdk-go v0.2.10 h1:lFgWgxyvngIhWnIqymYGBmtmq9D6uC5d0uLG9cbyh5s=
 github.com/hyperledger-labs/orion-sdk-go v0.2.10/go.mod h1:iN2xZB964AqwVJwL+EnwPOs8z1EkMEbbIg/qYeC7gDY=
 github.com/hyperledger-labs/orion-server v0.2.10 h1:G4zbQEL5Egk0Oj+TwHCZWdTOLDBHOjaAEvYOT4G7ozw=

integration/nwo/token/template.go

@@ -12,4 +12,11 @@ token:
   enabled: true
   selector:
     driver: {{ TokenSelector }}
+  finality:
+    type: delivery
+    delivery:
+      mapperParallelism: 10
+      lruSize: 100
+      lruBuffer: 50
+      listenerTimeout: 30s
 `