Off-chain API: ping command

[xli]

Author: Xiao Li (@xli) Status: Idea (for discussion)

To improve the ability of off-chain service handling network problems and protocol errors, we’d like to introduce a ping command for client to:

1. detect dead connections to a remote off-chain service.
2. measure the latency to a remote off-chain service.
3. detect off-chain protocol errors to a remote off-chain service, for example: when a remote off-chain service rotates their compliance key, and client used old compliance public key to verify the response message, the ping command can be used to debug the error and verify the fix.

Specification

The PingCommand object definition:

Field	Type	Required?	Description
_ObjectType	str	Y	The fixed string PingCommand

An example CommandRequestObject JSON message with PingCommand:

{
    "_ObjectType": "CommandRequestObject",
    "command_type": "PingCommand",
    "command": {
        "_ObjectType": "PingCommand",
    },
    "cid": "12ce83f6-6d18-0d6e-08b6-c00fdbbf085a",
}

And the response of the PingCommand:

{
    "_ObjectType": "CommandResponseObject",
    “status”: “success”,
    "cid": "12ce83f6-6d18-0d6e-08b6-c00fdbbf085a"
}

Note we don’t need a random message body in PingCommand for the server to response, because the off-chain API protocol already have a cid field defined in the CommandRequestObject and CommandResponseObject to serve the purpose of distinguish different command instance.

There is no command_error for this command. Server may respond with protocol_error (with CommandResponseObject.status==“failure”) defined in DIP-1 when processing an invalid HTTP headers, JWS message or CommandRequestObject payload.

[davidiw]

You are totally the first author, aren't you?

Submit a PR for DIP-160?

[xli]

https://github.com/diem/dip/pull/163

[xli]

example implementation in Diem Python SDK mini-wallet application: https://github.com/diem/client-sdk-python/pull/267