From af0e5c1a0d7beffdb07ca82e0eec1cd1d8b5ba1e Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Fri, 4 Dec 2020 14:15:03 -0600 Subject: [PATCH 1/6] first pass --- models/SyncStatus.yaml | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/models/SyncStatus.yaml b/models/SyncStatus.yaml index 30e66dc..73209b0 100644 --- a/models/SyncStatus.yaml +++ b/models/SyncStatus.yaml @@ -17,12 +17,7 @@ description: | implementation's sync status. It is often used to indicate that an implementation is healthy when it cannot be queried until some sync phase occurs. - - If an implementation is immediately queryable, this model is - often not populated. type: object -required: - - current_index properties: current_index: description: | @@ -43,3 +38,16 @@ properties: Stage is the phase of the sync process. type: string example: "header sync" + synced: + description: | + sycned is a boolean that indicates if an implementation has reached + the most recent block. + + If set to true, the caller will assume that the implementation + is considered healthy and is at the tip of the network. + + This field is particularly useful for quiescent blockchans where + the most recent block could have been produced at some variable + time in the past where a traditional time comparison with tip + may not make sense. + type: boolean From e5b2a9ab0124ad7b2a43ab4adeb6062e142eb65e Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Fri, 4 Dec 2020 14:21:56 -0600 Subject: [PATCH 2/6] add synced field --- models/SyncStatus.yaml | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/models/SyncStatus.yaml b/models/SyncStatus.yaml index 73209b0..2fffcf9 100644 --- a/models/SyncStatus.yaml +++ b/models/SyncStatus.yaml @@ -14,9 +14,12 @@ description: | SyncStatus is used to provide additional context about an - implementation's sync status. It is often used to indicate - that an implementation is healthy when it cannot be queried - until some sync phase occurs. + implementation's sync status. + + This object is often used by implementations to indicate healthiness + when block data cannot be queried until some sync phase completes or + cannot be determined by comparing the timestamp of the most recent + block with the current time. type: object properties: current_index: @@ -40,14 +43,14 @@ properties: example: "header sync" synced: description: | - sycned is a boolean that indicates if an implementation has reached - the most recent block. - - If set to true, the caller will assume that the implementation - is considered healthy and is at the tip of the network. + sycned is a boolean that indicates if an implementation has synced up + to the most recent block. If set to true, the caller will assume that + the implementation is considered healthy and is at the tip of the network. + If this field is not populated, the caller should rely on a traditional + tip timestamp comparison to determine if an implementation is synced. - This field is particularly useful for quiescent blockchans where - the most recent block could have been produced at some variable - time in the past where a traditional time comparison with tip - may not make sense. + This field is particularly useful for quiescent blockchains (blocks + only produced when there are pending transactions). In these blockchains, + the most recent block could have a timestamp far behind the current + time but the node could be at tip. type: boolean From 6b48db0cb08ef1a2fe8b31e51dc7d0a235989703 Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Fri, 4 Dec 2020 14:22:32 -0600 Subject: [PATCH 3/6] make gen --- api.json | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/api.json b/api.json index f92e843..5c02b12 100644 --- a/api.json +++ b/api.json @@ -1171,11 +1171,8 @@ } }, "SyncStatus": { - "description":"SyncStatus is used to provide additional context about an implementation's sync status. It is often used to indicate that an implementation is healthy when it cannot be queried until some sync phase occurs. If an implementation is immediately queryable, this model is often not populated.", + "description":"SyncStatus is used to provide additional context about an implementation's sync status. This object is often used by implementations to indicate healthiness when block data cannot be queried until some sync phase completes or cannot be determined by comparing the timestamp of the most recent block with the current time.", "type":"object", - "required": [ - "current_index" - ], "properties": { "current_index": { "description":"CurrentIndex is the index of the last synced block in the current stage.", @@ -1193,6 +1190,10 @@ "description":"Stage is the phase of the sync process.", "type":"string", "example":"header sync" + }, + "synced": { + "description":"sycned is a boolean that indicates if an implementation has synced up to the most recent block. If set to true, the caller will assume that the implementation is considered healthy and is at the tip of the network. If this field is not populated, the caller should rely on a traditional tip timestamp comparison to determine if an implementation is synced. This field is particularly useful for quiescent blockchains (blocks only produced when there are pending transactions). In these blockchains, the most recent block could have a timestamp far behind the current time but the node could be at tip.", + "type":"boolean" } } }, From 9e9daabf3e2a1da7b13c797de1b1041fe284f4d3 Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Fri, 4 Dec 2020 14:26:01 -0600 Subject: [PATCH 4/6] nits --- api.json | 2 +- models/SyncStatus.yaml | 9 ++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/api.json b/api.json index 5c02b12..ba604dd 100644 --- a/api.json +++ b/api.json @@ -1192,7 +1192,7 @@ "example":"header sync" }, "synced": { - "description":"sycned is a boolean that indicates if an implementation has synced up to the most recent block. If set to true, the caller will assume that the implementation is considered healthy and is at the tip of the network. If this field is not populated, the caller should rely on a traditional tip timestamp comparison to determine if an implementation is synced. This field is particularly useful for quiescent blockchains (blocks only produced when there are pending transactions). In these blockchains, the most recent block could have a timestamp far behind the current time but the node could be at tip.", + "description":"sycned is a boolean that indicates if an implementation has synced up to the most recent block. If this field is not populated, the caller should rely on a traditional tip timestamp comparison to determine if an implementation is synced. This field is particularly useful for quiescent blockchains (blocks only produced when there are pending transactions). In these blockchains, the most recent block could have a timestamp far behind the current time but the node could be healthy and at tip.", "type":"boolean" } } diff --git a/models/SyncStatus.yaml b/models/SyncStatus.yaml index 2fffcf9..501bc11 100644 --- a/models/SyncStatus.yaml +++ b/models/SyncStatus.yaml @@ -44,13 +44,12 @@ properties: synced: description: | sycned is a boolean that indicates if an implementation has synced up - to the most recent block. If set to true, the caller will assume that - the implementation is considered healthy and is at the tip of the network. - If this field is not populated, the caller should rely on a traditional - tip timestamp comparison to determine if an implementation is synced. + to the most recent block. If this field is not populated, the caller + should rely on a traditional tip timestamp comparison to determine if + an implementation is synced. This field is particularly useful for quiescent blockchains (blocks only produced when there are pending transactions). In these blockchains, the most recent block could have a timestamp far behind the current - time but the node could be at tip. + time but the node could be healthy and at tip. type: boolean From ca1215d9cb1cdfe82c9813212c69ef28238e4616 Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Fri, 4 Dec 2020 14:36:35 -0600 Subject: [PATCH 5/6] add more details about why current_index exists --- api.json | 2 +- models/SyncStatus.yaml | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/api.json b/api.json index ba604dd..b15dee2 100644 --- a/api.json +++ b/api.json @@ -1175,7 +1175,7 @@ "type":"object", "properties": { "current_index": { - "description":"CurrentIndex is the index of the last synced block in the current stage.", + "description":"CurrentIndex is the index of the last synced block in the current stage. This is a separate field from current_block_identifier in NetworkStatusResponse because blocks with indexes up to and including the current_index may not yet be queryable by the caller. To reiterate, all indexes up to and including current_block_identifier in NetworkStatusResponse must be queryable via the /block endpoint (excluding indexes less than oldest_block_identifier).", "type":"integer", "format":"int64", "example": 100 diff --git a/models/SyncStatus.yaml b/models/SyncStatus.yaml index 501bc11..8b349ee 100644 --- a/models/SyncStatus.yaml +++ b/models/SyncStatus.yaml @@ -26,6 +26,13 @@ properties: description: | CurrentIndex is the index of the last synced block in the current stage. + + This is a separate field from current_block_identifier in + NetworkStatusResponse because blocks with indexes up to and including + the current_index may not yet be queryable by the caller. To reiterate, + all indexes up to and including current_block_identifier in + NetworkStatusResponse must be queryable via the /block endpoint (excluding + indexes less than oldest_block_identifier). type: integer format: int64 example: 100 From cf4f140227a999ab05cc4550f1a7395036bab383 Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Fri, 4 Dec 2020 15:14:09 -0600 Subject: [PATCH 6/6] nits --- api.json | 6 +++--- api.yaml | 4 ++-- models/Operation.yaml | 2 +- models/SyncStatus.yaml | 6 +++--- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/api.json b/api.json index b15dee2..22b55a5 100644 --- a/api.json +++ b/api.json @@ -1078,7 +1078,7 @@ "$ref":"#/components/schemas/OperationIdentifier" }, "related_operations": { - "description":"Restrict referenced related_operations to identifier indexes < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree.", + "description":"Restrict referenced related_operations to identifier indices < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree.", "type":"array", "items": { "$ref":"#/components/schemas/OperationIdentifier" @@ -1175,7 +1175,7 @@ "type":"object", "properties": { "current_index": { - "description":"CurrentIndex is the index of the last synced block in the current stage. This is a separate field from current_block_identifier in NetworkStatusResponse because blocks with indexes up to and including the current_index may not yet be queryable by the caller. To reiterate, all indexes up to and including current_block_identifier in NetworkStatusResponse must be queryable via the /block endpoint (excluding indexes less than oldest_block_identifier).", + "description":"CurrentIndex is the index of the last synced block in the current stage. This is a separate field from current_block_identifier in NetworkStatusResponse because blocks with indices up to and including the current_index may not yet be queryable by the caller. To reiterate, all indices up to and including current_block_identifier in NetworkStatusResponse must be queryable via the /block endpoint (excluding indices less than oldest_block_identifier).", "type":"integer", "format":"int64", "example": 100 @@ -1682,7 +1682,7 @@ } }, "BlockResponse": { - "description":"A BlockResponse includes a fully-populated block or a partially-populated block with a list of other transactions to fetch (other_transactions). As a result of the consensus algorithm of some blockchains, blocks can be omitted (i.e. certain block indexes can be skipped). If a query for one of these omitted indexes is made, the response should not include a `Block` object. It is VERY important to note that blocks MUST still form a canonical, connected chain of blocks where each block has a unique index. In other words, the `PartialBlockIdentifier` of a block after an omitted block should reference the last non-omitted block.", + "description":"A BlockResponse includes a fully-populated block or a partially-populated block with a list of other transactions to fetch (other_transactions). As a result of the consensus algorithm of some blockchains, blocks can be omitted (i.e. certain block indices can be skipped). If a query for one of these omitted indices is made, the response should not include a `Block` object. It is VERY important to note that blocks MUST still form a canonical, connected chain of blocks where each block has a unique index. In other words, the `PartialBlockIdentifier` of a block after an omitted block should reference the last non-omitted block.", "type":"object", "properties": { "block": { diff --git a/api.yaml b/api.yaml index ab99b54..46e3bab 100644 --- a/api.yaml +++ b/api.yaml @@ -935,8 +935,8 @@ components: block with a list of other transactions to fetch (other_transactions). As a result of the consensus algorithm of some blockchains, blocks - can be omitted (i.e. certain block indexes can be skipped). If a query - for one of these omitted indexes is made, the response should not include + can be omitted (i.e. certain block indices can be skipped). If a query + for one of these omitted indices is made, the response should not include a `Block` object. It is VERY important to note that blocks MUST still form a canonical, diff --git a/models/Operation.yaml b/models/Operation.yaml index e7b1428..7c5a7bf 100644 --- a/models/Operation.yaml +++ b/models/Operation.yaml @@ -29,7 +29,7 @@ properties: $ref: 'OperationIdentifier.yaml' related_operations: description: | - Restrict referenced related_operations to identifier indexes + Restrict referenced related_operations to identifier indices < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. diff --git a/models/SyncStatus.yaml b/models/SyncStatus.yaml index 8b349ee..2fec1bd 100644 --- a/models/SyncStatus.yaml +++ b/models/SyncStatus.yaml @@ -28,11 +28,11 @@ properties: current stage. This is a separate field from current_block_identifier in - NetworkStatusResponse because blocks with indexes up to and including + NetworkStatusResponse because blocks with indices up to and including the current_index may not yet be queryable by the caller. To reiterate, - all indexes up to and including current_block_identifier in + all indices up to and including current_block_identifier in NetworkStatusResponse must be queryable via the /block endpoint (excluding - indexes less than oldest_block_identifier). + indices less than oldest_block_identifier). type: integer format: int64 example: 100