Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update EIP-1898: Move to draft #5980

Merged
merged 6 commits into from
Nov 20, 2022
Merged

Update EIP-1898: Move to draft #5980

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f01fcff
draft and add besu version
macfarla Nov 16, 2022
cabe871
minor edits - add description and other headings
macfarla Nov 16, 2022
61dad50
blank lines around lists
macfarla Nov 16, 2022
354c1ba
discussions-to
macfarla Nov 16, 2022
c2d4bb1
review status
macfarla Nov 16, 2022
46b55b6
draft
macfarla Nov 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions EIPS/eip-1898.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,42 @@
---
eip: 1898
title: Add `blockHash` to JSON-RPC methods which accept a default block parameter.
title: Add `blockHash` to defaultBlock methods
description: Add `blockHash` option to JSON-RPC methods that currently support defaultBlock parameter.
author: Charles Cooper (@charles-cooper)
discussions-to: https://ethereum-magicians.org/t/eip-1898-add-blockhash-option-to-json-rpc-methods-that-currently-support-defaultblock-parameter/11757
status: Draft
type: Standards Track
category: Interface
status: Stagnant
created: 2019-04-01
requires: 234, 1474
macfarla marked this conversation as resolved.
Show resolved Hide resolved
---

## Simple Summary
## Abstract

For JSON-RPC methods which currently accept a default block parameter, additionally allow the parameter to be a block hash.

## Abstract

This EIP can be considered a generalization of [EIP-234](./eip-234.md). It would enable clients to unambiguously specify the block they want to query for certain JSON-RPC methods, even if the block is not in the canonical chain. This allows clients to maintain a coherent picture of blockchain state that they are interested in, even in the presence of reorgs, without requiring that the node maintain a persistent connection with the client or store any client-specific state.

## Specification

The following JSON-RPC methods are affected:

- `eth_getBalance`
- `eth_getStorageAt`
- `eth_getTransactionCount`
- `eth_getCode`
- `eth_call`
- `eth_getProof`

The following options, quoted from the [JSON-RPC spec](https://github.com/ethereum/wiki/wiki/JSON-RPC#the-default-block-parameter), are currently possible for the defaultBlock parameter:
The following options, quoted from the Ethereum JSON-RPC spec, are currently possible for the defaultBlock parameter:

> - HEX String - an integer block number
> - String "earliest" for the earliest/genesis block
> - String "latest" - for the latest mined block
> - String "pending" - for the pending state/transactions

Since there is no way to clearly distinguish between a DATA parameter and a QUANTITY parameter, this EIP proposes a new scheme for the block parameter. The following option is additionally allowed:

- OBJECT
- `blockNumber`: QUANTITY - a block number
- `blockHash`: DATA - a block hash
Expand All @@ -43,6 +46,7 @@ If the block is not found, the callee SHOULD raise a JSON-RPC error (the recomme
If the tag is `blockHash`, an additional boolean field may be supplied to the block parameter, `requireCanonical`, which defaults to `false` and defines whether the block must be a canonical block according to the callee. If `requireCanonical` is `false`, the callee should raise a JSON-RPC error only if the block is not found (as described above). If `requireCanonical` is `true`, the callee SHOULD additionally raise a JSON-RPC error if the block is not in the canonical chain (the recommended error code is `-32000: Invalid input` and in any case should be different than the error code for the block not found case so that the caller can distinguish the cases). The block-not-found check SHOULD take precedence over the block-is-canonical check, so that if the block is not found the callee raises block-not-found rather than block-not-canonical.

To maintain backwards compatibility, the block number MAY be specified either as a hex string or using the new block parameter scheme. In other words, the following are equivalent for the default block parameter:

- `"earliest"`
- `"0x0"`
- `{ "blockNumber": "0x0" }`
Expand All @@ -55,6 +59,7 @@ To maintain backwards compatibility, the block number MAY be specified either as
Currently, the state-querying JSON-RPC methods specified above have no option to unambiguously specify which block to query the state for. This can cause issues for applications which need to make multiple calls to the RPC. For instance, a wallet which just executed a transfer may want to display the balances of both the sender and recipient. If there is a re-org in between when the balance of the sender is queried via `eth_getBalance` and when the balance of the recipient is queried, the balances may not reconcile. As a slightly more complicated example, the UI for a decentralized exchange (which hosts orders on-chain) may walk a list of orders by calling `eth_call` for each of them to get the order data. Another type of use case is where an application needs to make a decision based on multiple pieces of state, e.g. a payout predicated on simultaneous ownership of two NFTs.

In order to ensure that the state is coherent (i.e., `eth_call` was called with exactly the same block for every call), the application may currently use one of several strategies:

- Decide on a block number to use (e.g., the latest block number known to the application). After each `eth_call` using that block number, call `eth_getBlockByNumber`, also with that block number. If the block hash does not match the known hash for that block number, rollback the current activity and retry from the beginning. This adds `O(n)` invocations as baseline overhead and another `O(n)` invocations for every retry needed. Moreover, there is no way to detect the (unlikely but possible) case that the relevant block was reorged out before `eth_call`, and then reorged back in before `eth_getBlockByNumber`.
- Rely on logs, which *can* be queried unambiguously thanks to the `blockHash` parameter. However, this requires semantic support from the smart contract; if the smart contract does not emit appropriate events, the client will not be able to reconstruct the specific state it is interested in.
- Rely on non-standard extensions like `parity_subscribe`. This requires a persistent connection between the client and node (via IPC or websockets), increases coupling between the client and the node, and cannot handle use cases where there are dependencies between invocations of `eth_call`, for example, walking a linked list.
Expand All @@ -78,9 +83,10 @@ Backwards compatible.
- `eth_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>", "requireCanonical": false }` -> return storage at given address in specified block
- `eth_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>", "requireCanonical": true }` -> raise block-not-canonical error

## Implementation
## Security Considerations

None

It is supported by Geth 1.9.6 ([PR](https://github.com/ethereum/go-ethereum/pull/19491)).

## Copyright

Expand Down