Fix blockchain sub-status hyperlinks, add more extensive Polygon example

matthew1001 · matthew1001 · commit f816b2115421 · 2023-02-01T11:31:35.000Z
Signed-off-by: Matthew Whitehead &lt;matthew1001@gmail.com&gt;
diff --git a/docs/architecture/blockchain_connector_framework.md b/docs/architecture/blockchain_connector_framework.md
@@ -146,7 +146,7 @@ A reference implementation is provided that:
 The reference implementation is available [here](https://github.com/hyperledger/firefly-transaction-manager/blob/main/pkg/policyengines/simple/simple_policy_engine.go)
 
 FireFly 1.2 introduced a specification for policy engines to record more detailed information about transaction sub-status and lower-level actions it performs
-as part of progressing a transaction onto the chain. A policy engine might for example have a sub-status of `Received` and another sub-status of `Tracking`. For more information see [Blockchain Operation Status](../reference/blockchain_operations.html)
+as part of progressing a transaction onto the chain. A policy engine might for example have a sub-status of `Received` and another sub-status of `Tracking`. For more information see [Blockchain Operation Status](../reference/blockchain_operation_status.html)
 
 
 ## Event Streams
diff --git a/docs/reference/blockchain_operation_status.md b/docs/reference/blockchain_operation_status.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: pages.blockchain_operation_status
+title: Blockchain Operation Status
 parent: pages.reference
 nav_order: 5
 ---
@@ -19,7 +19,7 @@ nav_order: 5
 
 ## Blockchain Operations
 
-Every FireFly [Transaction](./types/_includes/transaction_description.html) can involve zero or more [Operations](./types/_includes/operation_description.html). Blockchain operations are handled by the blockchain connector configured for the namespace and represent a blockchain transaction being handled by that connector.
+Every FireFly [Transaction](./types/transaction.html) can involve zero or more [Operations](./types/operation.html). Blockchain operations are handled by the blockchain connector configured for the namespace and represent a blockchain transaction being handled by that connector.
 
 ## Blockchain Operation Status
 
@@ -29,41 +29,43 @@ FireFly 1.2 introduced the concept of sub-status types that allow a blockchain c
 
 [![Sub-status diagram](../images/blockchain-sub-status.png)](../images/blockchain-sub-status.png)
 
-To access detailed information about a blockchain operation FireFly 1.2 introduced a new query parameter, `fetchStatus`, to the `/transaction/{txid}/operation/{opid}` API. When FireFly receives an API request that includes the fetchStatus query parameter it makes a synchronous call directly to the blockchain connector, requesting all of blockchain transaction detail it has. This payload is then included in the FireFly transaction response under a new `detail` field.
+To access detailed information about a blockchain operation FireFly 1.2 introduced a new query parameter, `fetchStatus`, to the `/transaction/{txid}/operation/{opid}` API. When FireFly receives an API request that includes the fetchStatus query parameter it makes a synchronous call directly to the blockchain connector, requesting all of blockchain transaction detail it has. This payload is then included in the FireFly operation response under a new `detail` field.
 
-### Example
+### Blockchain Operation Example
 
 ```json
 {
     "id": "04a8b0c4-03c2-4935-85a1-87d17cddc20a",
+    "created": "2022-05-16T01:23:15Z",
     "namespace": "ns1",
     "tx": "99543134-769b-42a8-8be4-a5f8873f969d",
     "type": "blockchain_invoke",
     "status": "Succeeded",
     "plugin": "ethereum",
     "input": {
-        "id": "80d89712-57f3-48fe-b085-a8cba6e0667d"
+        // Input used to initiate the blockchain operation
     },
     "output": {
-        "payloadRef": "QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC"
+        // Minimal blockchain operation data necessary
+        // to resolve the FF transaction
     },
     "detail": {
-        // Blockchain operation status included here
+        // Full blockchain operation information, including sub-status
+        // transitions that took place for the operation to succeed.
     }
-    "created": "2022-05-16T01:23:15Z"
 }
 ```
 
-## Status Structure
+## Detail Status Structure
 
-The structure of a blockchain operation follows the structure described in [Operations](./types/_includes/operation_description.html). In FireFly 1.2, 2 new attributes were added to that structure to allow more detailed status information to be recorded:
+The structure of a blockchain operation follows the structure described in [Operations](./types/operation.html). In FireFly 1.2, 2 new attributes were added to that structure to allow more detailed status information to be recorded:
 
 - **history** an ordered list of status changes that have taken place during processing of the transaction
 - **historySummary** an un-ordered list any sub-status type that the blockchain connector uses, and any action type that the blockchain connector carries out as part of processing the transaction.
 
 The `history` field is designed to record an ordered list of sub-status changes that the transaction has gone through. Within each sub-status change are the actions that have been carried out to try and move the transaction on to a new sub-status. Some transactions might spend a long time going looping between different sub-status types so this field records the N most recent sub-status changes (where the size of N is determined by blockchain connector and its configuration). The follow example shows a transaction going starting at `Received`, moving to `Tracking`, and finally ending up as `Confirmed`. In order to move from `Received` to `Tracking` several actions were performed: `AssignNonce`, `RetrieveGasPrice`, and `SubmitTransaction`.
 
-### Example
+### History Example
 
 ```json
 {
@@ -73,7 +75,7 @@ The `history` field is designed to record an ordered list of sub-status changes
     "history": [
         {
             "subStatus": "Received",
-            "time": "2023-01-27T17:11:41.122965803Z"
+            "time": "2023-01-27T17:11:41.122965803Z",
             "actions": [
                 {
                     "action": "AssignNonce",
@@ -106,7 +108,7 @@ The `history` field is designed to record an ordered list of sub-status changes
         },
         {
             "subStatus": "Tracking",
-            "time": "2023-01-27T17:11:41.222400219Z"
+            "time": "2023-01-27T17:11:41.222400219Z",
             "actions": [
                 {
                     "action": "ReceiveReceipt",
@@ -137,7 +139,7 @@ The `history` field is designed to record an ordered list of sub-status changes
 
 Because the `history` field is a FIFO structure describing the N most recent sub-status changes, some early sub-status changes or actions may be lost over time. For example an action of `assignNonce` might only happen once when the transaction is first processed by the connector. The `historySummary` field ensures that a minimal set of information is kept about every single subStatus type and action that has been recorded.
 
-### Example
+### History Summary Example
 
 ```json
 {
@@ -194,3 +196,139 @@ Because the `history` field is a FIFO structure describing the N most recent sub
     ]
 }
 ```
+
+## Public Chain Operations
+
+Blockchain transactions submitted to a public chain, for example to Polygon PoS, might take longer and involve more sub-status transitions before being confirmed. One reason for this could be because of gas price fluctuations of the chain. In this case the `history` for a public blockchain operation might include a large number of `subStatus` entries. Using the example sub-status values above, a blockchain operation might move from `Tracking` to `Stale`, back to `Tracking`, back to `Stale` and so on.
+
+Below is an example of the `history` for a public blockchain operation.
+
+### Polygon Example
+
+```json
+{
+    ...
+    "lastSubmit": "2023-01-27T17:11:41.222375469Z",
+    "nonce": "14",
+    "history": [
+        {
+            "subStatus": "Received",
+            "time": "2023-01-27T17:11:41.122965803Z",
+            "actions": [
+                {
+                    "action": "AssignNonce",
+                    "count": 1,
+                    "lastInfo": {
+                        "nonce": "1"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.122967219Z",
+                    "time": "2023-01-27T17:11:41.122967136Z"
+                },
+                {
+                    "action": "RetrieveGasPrice",
+                    "count": 1,
+                    "lastInfo": {
+                        "gasPrice": "34422243"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.161213303Z",
+                    "time": "2023-01-27T17:11:41.161213094Z"
+                },
+                {
+                    "action": "SubmitTransaction",
+                    "count": 1,
+                    "lastInfo": {
+                        "txHash": "0x83ba5e1cf320a1d5c949082bbec8ae7fe918e6621cec39478609ec3f7deacbdb"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.222374636Z",
+                    "time": "2023-01-27T17:11:41.222374553Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Tracking",
+            "time": "2023-01-27T17:11:41.222400219Z",
+            "actions": [],
+        },
+        {
+            "subStatus": "Stale",
+            "time": "2023-01-27T17:13:21.222100434Z",
+            "actions": [
+                {
+                    "action": "RetrieveGasPrice",
+                    "count": 1,
+                    "lastInfo": {
+                        "gasPrice": "44436243"
+                    },
+                    "lastOccurrence": "2023-01-27T17:13:22.93120838Z",
+                    "time": "2023-01-27T17:13:22.93120838Z"
+                },
+                {
+                    "action": "SubmitTransaction",
+                    "count": 1,
+                    "lastInfo": {
+                        "txHash": "0x7b3a5e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7aea6103d5"
+                    },
+                    "lastOccurrence": "2023-01-27T17:13:32.656374637Z",
+                    "time": "2023-01-27T17:13:32.656374637Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Tracking",
+            "time": "2023-01-27T17:13:33.434400219Z",
+            "actions": [],
+        },
+        {
+            "subStatus": "Stale",
+            "time": "2023-01-27T17:15:21.222100434Z",
+            "actions": [
+                {
+                    "action": "RetrieveGasPrice",
+                    "count": 1,
+                    "lastInfo": {
+                        "gasPrice": "52129243"
+                    },
+                    "lastOccurrence": "2023-01-27T17:15:22.93120838Z",
+                    "time": "2023-01-27T17:15:22.93120838Z"
+                },
+                {
+                    "action": "SubmitTransaction",
+                    "count": 1,
+                    "lastInfo": {
+                        "txHash": "0x89995e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7a8c64abc"
+                    },
+                    "lastOccurrence": "2023-01-27T17:15:32.656374637Z",
+                    "time": "2023-01-27T17:15:32.656374637Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Tracking",
+            "time": "2023-01-27T17:15:33.434400219Z",
+            "actions": [
+                {
+                    "action": "ReceiveReceipt",
+                    "count": 1,
+                    "lastInfo": {
+                        "protocolId": "000004897621/000000"
+                    },
+                    "lastOccurrence": "2023-01-27T17:15:33.94120833Z",
+                    "time": "2023-01-27T17:15:33.94120833Z"
+                },
+                {
+                    "action": "Confirm",
+                    "count": 1,
+                    "lastOccurrence": "2023-01-27T17:16:02.780275549Z",
+                    "time": "2023-01-27T17:16:02.780275382Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Confirmed",
+            "time": "2023-01-27T17:16:03.990309381Z",
+            "actions": [],
+        }
+    ]
+    ...
+}
+```
diff --git a/docs/reference/types/_includes/operationwithdetail_description.md b/docs/reference/types/_includes/operationwithdetail_description.md
@@ -1,5 +1,2 @@
 Operation with detail is an extension to operations that allow additional information to be encapsulated with an operation. An operation
-can be supplemented by a connector and that information will be returned in a `detail` field.
-
-Operation with detail is a superset of an [Operation](../_includes/operation_description.md). For information about the detail provided
-by blockchain connectors see [Blockchain operation status](../../blockchain_operation_status.md).
+can be supplemented by a connector and that information will be returned in the `detail` field.
diff --git a/docs/reference/types/operationwithdetail.md b/docs/reference/types/operationwithdetail.md
@@ -148,5 +148,5 @@ nav_order: 8
 | `created` | The time the operation was created | [`FFTime`](simpletypes#fftime) |
 | `updated` | The last update time of the operation | [`FFTime`](simpletypes#fftime) |
 | `retry` | If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried | [`UUID`](simpletypes#uuid) |
-| `detail` | OperationWithDetail.detail | `` |
+| `detail` | Additional detailed information about an operation provided by the connector | `` |
 
diff --git a/docs/swagger/swagger.yaml b/docs/swagger/swagger.yaml
diff --git a/internal/coremsgs/en_struct_descriptions.go b/internal/coremsgs/en_struct_descriptions.go
