eth_isSyncing proposal

isSynching.md

This method should notify a dapp when the node is syncing (e.g. importing more than 10 blocks), so that dapps can stop asking nodes or process incoming blocks for performance reasons.

We might add fields in the future for state db syncing.

eth_syncing

Returns an object object with data about the sync status.

Parameters

none

Returns

Object|Boolean, An object with sync status data or FALSE, when not syncing:

• startingBlock: QUANTITY - The block at which the import started (will only be reset, after the sync reached his head)
• currentBlock: QUANTITY - The current block, same as eth_blockNumber
• highestBlock: QUANTITY - The estimated highest block

Example

// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_isSyncing","params":[],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": {
    startingBlock: '0x384',
    currentBlock: '0x386',
    highestBlock: '0x454'
  }
}
// Or when not syncing
{
  "id":1,
  "jsonrpc": "2.0",
  "result": false
}

Discussion

in web3 i would create a polling automatically under the hood and you can simple register a callback, which gets fired when a sync starts or stops and updates. We could then easily transform that later to a push API under the hood:

web3.eth.isSyncing(function(sync){
    if(sync === true) {
       // stop all activity
       web3.reset();
    } else if(sync) {
       // show sync info, stop app calls etc
       console.log(sync.highestBlock);
    } else {
       // regain app operation
    }
});

As per the discussion in skype, the proposal is ok, with the corrections:

• Rename blocksToImport to currentBlock
• Maybe rename startBlock to originBlock?
• Drop the estimate, it's more uniformely done client side.
• Add a note, that further fields may be added for fast and light syncs.

Otherwise, 👍

As per Peter's notes, also eth_isSyncing.

Otherwise, 👍

All done already

Btw, could we have the function name as syncing only? I.e. drop the Is? The check for mining already does this, so it would be more consistent API wise https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_mining

Actually we need to name it eth_syncing, so web3 can implement both, the same property call for web3.eth.syncing and the convenience function web3.eth.isSyncing with auto polling an callback.