Merge pull request #26 from matheusd/inalterable-blocks

Add /block idempotency requirement

api.json

@@ -139,7 +139,7 @@
    "/block": {
      "post": {
        "summary":"Get a Block",
-       "description":"Get a block by its Block Identifier. If transactions are returned in the same call to the node as fetching the block, the response should include these transactions in the Block object. If not, an array of Transaction Identifiers should be returned so /block/transaction fetches can be done to get all transaction information.",
+       "description":"Get a block by its Block Identifier. If transactions are returned in the same call to the node as fetching the block, the response should include these transactions in the Block object. If not, an array of Transaction Identifiers should be returned so /block/transaction fetches can be done to get all transaction information. When requesting a block by the hash component of the BlockIdentifier, this request MUST be idempotent: repeated invocations for the same hash-identified block must return the exact same block contents. No such restriction is imposed when requesting a block by height, given that a chain reorg event might cause the specific block at height `n` to be set to a different one.",
        "operationId":"block",
        "tags": [
          "Block"
@@ -838,7 +838,7 @@
         }
       },
      "Block": {
-       "description":"Blocks contain an array of Transactions that occurred at a particular BlockIdentifier.",
+       "description":"Blocks contain an array of Transactions that occurred at a particular BlockIdentifier. A hard requirement for blocks returned by Rosetta implementations is that they MUST be _inalterable_: once a client has requested and received a block identified by a specific BlockIndentifier, all future calls for that same BlockIdentifier must return the same block contents.",
        "type":"object",
        "required": [
          "block_identifier",

api.yaml

@@ -119,6 +119,14 @@ paths:
         include these transactions in the Block object. If not, an array of
         Transaction Identifiers should be returned so /block/transaction
         fetches can be done to get all transaction information.
+
+        When requesting a block by the hash component of the BlockIdentifier,
+        this request MUST be idempotent: repeated invocations for the same
+        hash-identified block must return the exact same block contents.
+
+        No such restriction is imposed when requesting a block by height,
+        given that a chain reorg event might cause the specific block at
+        height `n` to be set to a different one.
       operationId: block
       tags:
         - Block

models/Block.yaml

@@ -15,6 +15,13 @@
 description: |
   Blocks contain an array of Transactions that
   occurred at a particular BlockIdentifier.
+
+  A hard requirement for blocks returned by Rosetta
+  implementations is that they MUST be _inalterable_:
+  once a client has requested and received
+  a block identified by a specific BlockIndentifier,
+  all future calls for that same BlockIdentifier
+  must return the same block contents.
 type: object
 required:
   - block_identifier