eth_blockNumber

json-rpc/eth_blockNumber.md

@@ -0,0 +1,51 @@
+# `eth_blockNumber`
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC-2119](https://www.ietf.org/rfc/rfc2119.txt).
+Specification | Description 
+---|---
+ 1 |  Returns the number of the block that is the current chain head (the latest best processed and verified block on the chain) |
+ 2 |  The number of the chain head is returned if the node has ability of serving the header, body, and the full state starting from the state root of the block having the number in a finite time  |
+ 3 | The node may know a higher block number but still return a lower one if the lower number block has higher total difficulty or if the higher number block has not been fully processed yet |
+ 4 | Provides no promise on for how long the node will keep the block details so if you request the block data for the given block number any time after receiving the block number itself, you may get a null response |
+ 5 | Returns an error if the node has not yet processed or failed to process the genesis block. Some nodes MAY decide not to enable JSON RPC if the genesis block calculation has not been done yet |
+
+# Tests
+
+[...]
+
+# Security Considerations
+`eth_blockNumber` is considered safe
+
+# Notes About Usage
+
+### Description
+`eth_blockNumber` is the most commonly called JSON RPC endpoint, yet it has some undefined edge cases. The goal is to assert its behavior for all current and future Ethereum 1.x client implementations.
+
+### Parameters
+
+_(none)_
+
+### Returns
+
+{[`Quantity`](./types/Quantity.md)} - number of the latest block
+
+### Example
+
+```sh
+# Request
+curl -X POST --data '{
+    "id": 1337,
+    "jsonrpc": "2.0",
+    "method": "eth_blockNumber",
+    "params": []
+}' <url>
+
+# Response
+{
+    "id": 1337,
+    "jsonrpc": "2.0",
+    "result": "0xc94"
+}
+```
+
+# Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

json-rpc/types/Quantity.md

@@ -0,0 +1,27 @@
+
+# `Quantity`
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC-2119](https://www.ietf.org/rfc/rfc2119.txt).
+| Requirement | Description  |
+| ----------- | ------------ |
+| 1   | A `Quantity` value **MUST** be hex-encoded |
+| 2   | A `Quantity` value **MUST** be "0x"-prefixed |
+| 3   | A `Quantity` value **MUST** be expressed using the fewest possible hex digits per byte |
+| 4   | A `Quantity` value **MUST** express zero as "0x0" |
+| 5   | A `Quantity` value **MUST** represent an unsigned integer value |
+| 6   | A `Quantity` value **MUST** represent a 32 byte hex encoded decimal with the leading `0`s stripped |
+
+# Notes About Usage
+### Description
+`Quantity` is the 32 byte hex-encoded representation of a decimal value
+
+### Examples 
+
+|Value|Valid|Reason|
+|-|-|-|
+|0x|`invalid`|empty not a valid quantity|
+|0x0|`valid`|interpreted as a quantity of zero|
+|0x00|`invalid`|leading zeroes not allowed|
+|0x41|`valid`|interpreted as a quantity of 65|
+|0x400|`valid`|interpreted as a quantity of 1024|
+|0x0400|`invalid`|leading zeroes not allowed|
+|ff|`invalid`|values must be prefixed|