Skip to content

Commit b67c3de

Browse files
matthew1001matthew1001
committed
Add blockchain sub-status documentation
Signed-off-by: Matthew Whitehead <[email protected]>
1 parent 98867ac commit b67c3de

28 files changed

+490
-22
lines changed

‎docs/_i18n/en.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ pages:
1414
avalanche: Avalanche Testnet
1515
binance_smart_chain: Binance Smartchain Testnet
1616
blockchain_protocols: Blockchain Protocols
17+
blockchain_operation_status: Blockchain Operation Status
1718
broadcast_data: Broadcast data
1819
broadcast_data: Broadcast Data
1920
broadcast_shared_data: Broadcast / Shared Data

‎docs/architecture/blockchain_connector_framework.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,10 @@ A reference implementation is provided that:
145145

146146
The reference implementation is available [here](https://github.com/hyperledger/firefly-transaction-manager/blob/main/pkg/policyengines/simple/simple_policy_engine.go)
147147

148+
FireFly 1.2 introduced a specification for policy engines to record more detailed information about transaction sub-status and lower-level actions it performs
149+
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)
150+
151+
148152
## Event Streams
149153

150154
One of the largest pieces of heavy lifting code in the FFTM codebase, is the event stream

‎docs/images/blockchain-sub-status.png‎

180 KB
Loading

‎docs/reference/blockchain_operation_status.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
layout: default
3+
title: pages.blockchain_operation_status
4+
parent: pages.reference
5+
nav_order: 5
6+
---
7+
8+
# Blockchain Operation Status
9+
{: .no_toc }
10+
11+
## Table of contents
12+
{: .no_toc .text-delta }
13+
14+
1. TOC
15+
{:toc}
16+
17+
---
18+
19+
20+
## Blockchain Operations
21+
22+
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.
23+
24+
## Blockchain Operation Status
25+
26+
A blockchain operation can require the connector to go through various stages of processing in order to successfully confirm the transaction on the blockchain. The orchestrator in FireFly receives updates from the connector to indicate when the operation has been completed and determine when the FireFly transaction as a whole has finished. These updates must contain enough information to correlate the operation to the FireFly transaction but it can be useful to see more detailed information about how the transaction was processed.
27+
28+
FireFly 1.2 introduced the concept of sub-status types that allow a blockchain connector to distinguish between the intermediate steps involved in progressing a transaction. It also introduced the concept of an action which a connector might carry out in order to progress between types of sub-status. This can be described as a state machine as shown in the following diagram:
29+
30+
[![Sub-status diagram](../images/blockchain-sub-status.png)](../images/blockchain-sub-status.png)
31+
32+
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.
33+
34+
### Example
35+
36+
```json
37+
{
38+
"id": "04a8b0c4-03c2-4935-85a1-87d17cddc20a",
39+
"namespace": "ns1",
40+
"tx": "99543134-769b-42a8-8be4-a5f8873f969d",
41+
"type": "blockchain_invoke",
42+
"status": "Succeeded",
43+
"plugin": "ethereum",
44+
"input": {
45+
"id": "80d89712-57f3-48fe-b085-a8cba6e0667d"
46+
},
47+
"output": {
48+
"payloadRef": "QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC"
49+
},
50+
"detail": {
51+
// Blockchain operation status included here
52+
}
53+
"created": "2022-05-16T01:23:15Z"
54+
}
55+
```
56+
57+
## Status Structure
58+
59+
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:
60+
61+
- **history** an ordered list of status changes that have taken place during processing of the transaction
62+
- **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.
63+
64+
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`.
65+
66+
### Example
67+
68+
```json
69+
{
70+
...
71+
"lastSubmit": "2023-01-27T17:11:41.222375469Z",
72+
"nonce": "14",
73+
"history": [
74+
{
75+
"subStatus": "Received",
76+
"time": "2023-01-27T17:11:41.122965803Z"
77+
"actions": [
78+
{
79+
"action": "AssignNonce",
80+
"count": 1,
81+
"lastInfo": {
82+
  "nonce": "14"
83+
},
84+
"lastOccurrence": "2023-01-27T17:11:41.122967219Z",
85+
"time": "2023-01-27T17:11:41.122967136Z"
86+
},
87+
  {
88+
"action": "RetrieveGasPrice",
89+
"count": 1,
90+
"lastInfo": {
91+
"gasPrice": "0"
92+
},
93+
"lastOccurrence": "2023-01-27T17:11:41.161213303Z",
94+
"time": "2023-01-27T17:11:41.161213094Z"
95+
},
96+
{
97+
"action": "SubmitTransaction",
98+
"count": 1,
99+
  "lastInfo": {
100+
"txHash": "0x4c37de1cf320a1d5c949082bbec8ad5fe918e6621cec3948d609ec3f7deac243"
101+
},
102+
  "lastOccurrence": "2023-01-27T17:11:41.222374636Z",
103+
  "time": "2023-01-27T17:11:41.222374553Z"
104+
  }
105+
  ],
106+
  },
107+
  {
108+
   "subStatus": "Tracking",
109+
"time": "2023-01-27T17:11:41.222400219Z"
110+
  "actions": [
111+
    {
112+
     "action": "ReceiveReceipt",
113+
     "count": 2,
114+
     "lastInfo": {
115+
      "protocolId": "000001265122/000000"
116+
     },
117+
     "lastOccurrence": "2023-01-27T17:11:57.93120838Z",
118+
     "time": "2023-01-27T17:11:47.930332625Z"
119+
    },
120+
    {
121+
     "action": "Confirm",
122+
     "count": 1,
123+
     "lastOccurrence": "2023-01-27T17:12:02.660275549Z",
124+
     "time": "2023-01-27T17:12:02.660275382Z"
125+
    }
126+
   ],
127+
  },
128+
  {
129+
   "subStatus": "Confirmed",
130+
   "time": "2023-01-27T17:12:02.660309382Z",
131+
   "actions": [],
132+
  }
133+
]
134+
...
135+
}
136+
```
137+
138+
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.
139+
140+
### Example
141+
142+
```json
143+
{
144+
...
145+
"historySummary": [
146+
{
147+
"count": 1,
148+
  "firstOccurrence": "2023-01-27T17:11:41.122966136Z",
149+
"lastOccurrence": "2023-01-27T17:11:41.122966136Z",
150+
  "subStatus": "Received"
151+
},
152+
{
153+
"count": 1,
154+
"firstOccurrence": "2023-01-27T17:11:41.122967219Z",
155+
"lastOccurrence": "2023-01-27T17:11:41.122967219Z",
156+
"action": "AssignNonce"
157+
},
158+
{
159+
"count": 1,
160+
"firstOccurrence": "2023-01-27T17:11:41.161213303Z",
161+
"lastOccurrence": "2023-01-27T17:11:41.161213303Z",
162+
"action": "RetrieveGasPrice"
163+
},
164+
{
165+
"count": 1,
166+
"firstOccurrence": "2023-01-27T17:11:41.222374636Z",
167+
"lastOccurrence": "2023-01-27T17:11:41.222374636Z",
168+
"action": "SubmitTransaction"
169+
},
170+
{
171+
  "count": 1,
172+
  "firstOccurrence": "2023-01-27T17:11:41.222400678Z",
173+
"lastOccurrence": "",
174+
  "subStatus": "Tracking"
175+
},
176+
{
177+
"count": 1,
178+
"firstOccurrence": "2023-01-27T17:11:57.93120838Z",
179+
"lastOccurrence": "2023-01-27T17:11:57.93120838Z",
180+
"action": "ReceiveReceipt"
181+
},
182+
{
183+
"count": 1,
184+
"firstOccurrence": "2023-01-27T17:12:02.660309382Z",
185+
"lastOccurrence": "2023-01-27T17:12:02.660309382Z",
186+
"action": "Confirm"
187+
},
188+
{
189+
  "count": 1,
190+
  "firstOccurrence": "2023-01-27T17:12:02.660309757Z",
191+
"lastOccurrence": "2023-01-27T17:12:02.660309757Z",
192+
  "subStatus": "Confirmed"
193+
}
194+
]
195+
}
196+
```

‎docs/reference/events.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
layout: default
33
title: Event Bus
44
parent: pages.reference
5-
nav_order: 5
5+
nav_order: 6
66
---
77

88
# Event Bus

‎docs/reference/firefly_interface_format.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
layout: default
33
title: FireFly Interface Format
44
parent: pages.reference
5-
nav_order: 7
5+
nav_order: 8
66
---
77

88
# FireFly Interface Format

‎docs/reference/identities.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
layout: default
33
title: Identities
44
parent: pages.reference
5-
nav_order: 6
5+
nav_order: 7
66
---
77

88
# Identities

‎docs/reference/microservices/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
layout: default
33
title: Microservices
44
parent: pages.reference
5-
nav_order: 9
5+
nav_order: 10
66
has_children: true
77
---

‎docs/reference/namespaces.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
layout: default
33
title: Namespaces
44
parent: pages.reference
5-
nav_order: 8
5+
nav_order: 9
66
---
77

88
# Namespaces

‎docs/reference/types/_includes/operationwithdetail_description.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Operation with detail is an extension to operations that allow additional information to be encapsulated with an operation. An operation
2+
can be supplemented by a connector and that information will be returned in a `detail` field.
3+
4+
Operation with detail is a superset of an [Operation](../_includes/operation_description.md). For information about the detail provided
5+
by blockchain connectors see [Blockchain operation status](../../blockchain_operation_status.md).

0 commit comments

Comments
 (0)