From 883e52f8a5f413e5837768540874b1047e67fa0c Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Sat, 25 Jul 2020 17:05:42 -0700 Subject: [PATCH 1/3] Add sync status --- api.yaml | 13 +++++++++++- models/SyncStatus.yaml | 45 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 models/SyncStatus.yaml diff --git a/api.yaml b/api.yaml index 051c8b0..4b16f89 100644 --- a/api.yaml +++ b/api.yaml @@ -590,6 +590,8 @@ components: $ref: 'models/Amount.yaml' Currency: $ref: 'models/Currency.yaml' + SyncStatus: + $ref: 'models/SyncStatus.yaml' Peer: $ref: 'models/Peer.yaml' Version: @@ -807,13 +809,20 @@ components: NetworkStatusResponse: description: | NetworkStatusResponse contains basic information about the node's - view of a blockchain network. + view of a blockchain network. It is assumed that any BlockIdentifier.Index + less than or equal to CurrentBlockIdentifier.Index can be queried. If a Rosetta implementation prunes historical state, it should populate the optional `oldest_block_identifier` field with the oldest block available to query. If this is not populated, it is assumed that the `genesis_block_identifier` is the oldest queryable block. + + If a Rosetta implementation performs some pre-sync before it is + possible to query blocks, sync_status should be populated so that + clients can still monitor healthiness. Without this field, it may + appear that the implementation is stuck syncing and needs to be + terminated. type: object required: - current_block_identifier @@ -829,6 +838,8 @@ components: $ref: '#/components/schemas/BlockIdentifier' oldest_block_identifier: $ref: '#/components/schemas/BlockIdentifier' + sync_status: + $ref: '#/components/schemas/SyncStatus' peers: type: array items: diff --git a/models/SyncStatus.yaml b/models/SyncStatus.yaml new file mode 100644 index 0000000..866d134 --- /dev/null +++ b/models/SyncStatus.yaml @@ -0,0 +1,45 @@ +# Copyright 2020 Coinbase, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +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 pre-sync occurs. + + If an implementation is immediately queryable and no pre-sync + is required, this model is often not populated. +type: object +required: + - current_index +properties: + current_index: + description: | + CurrentIndex is the index of the last synced block in the + current stage. + type: integer + format: int64 + example: 100 + target_index: + description: | + TargetIndex is the index of the block that the implementation + is attempting to sync to in the current stage. + type: integer + format: int64 + example: 150 + stage: + description: | + Stage is the phase of the sync process. + type: string + example: "header sync" From ea04d7664b1b272169403bccb000e9331b0212dc Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Sat, 25 Jul 2020 17:07:41 -0700 Subject: [PATCH 2/3] Make build --- api.json | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/api.json b/api.json index 8ad3824..9cd3417 100644 --- a/api.json +++ b/api.json @@ -1003,6 +1003,32 @@ } } }, + "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 pre-sync occurs. If an implementation is immediately queryable and no pre-sync is required, this model is often not populated.", + "type":"object", + "required": [ + "current_index" + ], + "properties": { + "current_index": { + "description":"CurrentIndex is the index of the last synced block in the current stage.", + "type":"integer", + "format":"int64", + "example": 100 + }, + "target_index": { + "description":"TargetIndex is the index of the block that the implementation is attempting to sync to in the current stage.", + "type":"integer", + "format":"int64", + "example": 150 + }, + "stage": { + "description":"Stage is the phase of the sync process.", + "type":"string", + "example":"header sync" + } + } + }, "Peer": { "description":"A Peer is a representation of a node's peer.", "type":"object", @@ -1457,7 +1483,7 @@ } }, "NetworkStatusResponse": { - "description":"NetworkStatusResponse contains basic information about the node's view of a blockchain network. If a Rosetta implementation prunes historical state, it should populate the optional `oldest_block_identifier` field with the oldest block available to query. If this is not populated, it is assumed that the `genesis_block_identifier` is the oldest queryable block.", + "description":"NetworkStatusResponse contains basic information about the node's view of a blockchain network. It is assumed that any BlockIdentifier.Index less than or equal to CurrentBlockIdentifier.Index can be queried. If a Rosetta implementation prunes historical state, it should populate the optional `oldest_block_identifier` field with the oldest block available to query. If this is not populated, it is assumed that the `genesis_block_identifier` is the oldest queryable block. If a Rosetta implementation performs some pre-sync before it is possible to query blocks, sync_status should be populated so that clients can still monitor healthiness. Without this field, it may appear that the implementation is stuck syncing and needs to be terminated.", "type":"object", "required": [ "current_block_identifier", @@ -1478,6 +1504,9 @@ "oldest_block_identifier": { "$ref":"#/components/schemas/BlockIdentifier" }, + "sync_status": { + "$ref":"#/components/schemas/SyncStatus" + }, "peers": { "type":"array", "items": { From eb7206c6fca380fb33541288fa204c5d26d04649 Mon Sep 17 00:00:00 2001 From: Patrick O'Grady Date: Sat, 25 Jul 2020 17:12:32 -0700 Subject: [PATCH 3/3] nits --- api.json | 2 +- models/SyncStatus.yaml | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api.json b/api.json index 9cd3417..948d3d8 100644 --- a/api.json +++ b/api.json @@ -1004,7 +1004,7 @@ } }, "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 pre-sync occurs. If an implementation is immediately queryable and no pre-sync is required, this model is often not populated.", + "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.", "type":"object", "required": [ "current_index" diff --git a/models/SyncStatus.yaml b/models/SyncStatus.yaml index 866d134..30e66dc 100644 --- a/models/SyncStatus.yaml +++ b/models/SyncStatus.yaml @@ -16,10 +16,10 @@ 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 pre-sync occurs. + until some sync phase occurs. - If an implementation is immediately queryable and no pre-sync - is required, this model is often not populated. + If an implementation is immediately queryable, this model is + often not populated. type: object required: - current_index