diff --git a/api.json b/api.json index 69e01d0..57297b0 100644 --- a/api.json +++ b/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", diff --git a/api.yaml b/api.yaml index bc4f9de..2382df1 100644 --- a/api.yaml +++ b/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 diff --git a/models/Block.yaml b/models/Block.yaml index 5ad3ccd..8a0f6c2 100644 --- a/models/Block.yaml +++ b/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