Merge pull request #71 from coinbase/patrick/network-status-tip

Return `Synced` Status

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"
@@ -1171,14 +1171,11 @@
         }
       },
      "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.",
+           "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
@@ -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 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"
           }
         }
       },
@@ -1681,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": {

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,

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.
 

models/SyncStatus.yaml

@@ -14,20 +14,25 @@
 
 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.
 
-  If an implementation is immediately queryable, this model is
-  often not populated.
+  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.
+
+      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 
@@ -43,3 +48,15 @@ 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 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