Standardize debug namespace

[lightclient]

Clients currently support an assortment of debug-like RPCs and commands. In an effort to simplify debugging chain disagreements and have more reusable debugging tooling across clients, I propose we standardize five basic JSON-RPC methods.

• debug_getRawHeader(hashOrNumber) -> bytes -- gets header RLP.
• debug_getRawBlock(hashOrNumber) -> bytes -- gets block RLP.
• debug_getRawTransaction(hash) -> bytes -- gets EIP-2718 encoded tx.
• debug_getRawReceipts(hashOrNumber) -> []bytes -- gets array of EIP-2718 encoded receipts.
• debug_getBadBlocks -> []BadBlock -- gets recent invalid blocks seen by the client.
• debug_setHead(number) -> null -- overrides the client and resets the head to a certain block number.

edit: seems like the general consensus is to not expose setHead under debug.

Geth currently supports all of these (although the interfaces are slightly different at the moment). I see other clients support some of the methods.

I'd like to know:

1. Is this is a good minimal set of debug methods to standardize (open to add/removing methods as needed)?
2. How long would it take for clients to implement each of these if there were integration tests for them in hive?

[lightclient]

It seems like the odd-method-out is debug_setHead. So I'd also like to know how useful client teams feel it is to standardize around and how difficult it would be to implement, if it isn't already exposed. Additionally, it's not clear if it makes sense to expose methods that orchestrate the chain in the debug namespace. Before it was standardized, debug was the wild west where anything goes. Now, it's possible that API providers would want to also provide it to customers. In which case, they'd have to manually disable debug_setHead.

[daniellehrner]

I like the idea, but I think debug_setHead should not be part of it. If somebody exposes their RPC by accident, a malicious actor could mess with the node.

A setHead endpoint would be great to have to fix problems on a node. But I would create a separate and protected namespace for it. Maybe similar to the engine namespace.

[matkt]

Is It not the goal of admin namespace ?

[lightclient]

@daniellehrner @matkt okay seems reasonable enough to just forget about setHead for the debug namespace. I like the idea of exposing it on admin though and the promise will be that the admin namespace should never be exposed publicly whereas it might make sense for debug to.

[LukaszRozmej]

Need to specify what is the format of binary receipts. I would propose for it to be RLP of receipts already used when syncing. So instead of an array of bytes, it would be just bytes.

[axic]

Can some of this be revived too ethereum/interfaces#4 (in the future and not as part of this PR)? 😅

It is mostly concerned by methods used by development frameworks.

[lightclient]

@LukaszRozmej I've updated to clarify receipts are EIP-2718 binary-encoded. I'm not sure if using the EIP-2976 encoding of txs makes sense here (although can be convinced otherwise). The original motivation of the endpoint was to be something that could be used to quickly recalculate a block's receipt root. I'm going to leave the result as-is, unless there is convincing reason we should encode it using EIP-2976.

[zemse]

Would addition of debug_getTransactionRaw be helpful? Recently, I was debugging a library and wanted to see what the raw transaction was sent, and then realized there seemed to be no way to get raw transaction RLP encoded form from a node given a tx hash.

[lightclient]

@zemse I'm not sure how useful it is to get a tx by hash for client-level debugging, but I see the merit in it generally. It should be extremely easy to implement regardless, so I've added it to the spec.

[fjl]

Regarding the receipts, I side with @lightclient. The individual receipt objects should be encoded as they are handled by consensus. However, it's not very useful to get an RLP-list of all receipts. If you want to find a specific one, you need to decode the RLP.

[lightclient]

I've added bad.rlp which is an RLP encoded block with a valid seal, but lists the gas used incorrectly in the header. If a client were to ingest it, it would be considered a bad block and should be returned by debug_badBlock. It isn't easy to write a test for this in the standard format, so I have written a special test case in hive for this method.

With that, each new method has a corresponding test and this PR has been stable for well over a month now -- I'm going to go ahead and merge it.

[Apdlrcjafg19]

V.V