Summary

This DIP describes an off-chain API v2 ping command that makes it easier for clients to detect network and protocol problems.

Abstract

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: an off-chain service responds back with an unexpected compliance key due to key rotation, this can be leveraged to debug and verify the inconsistency.

Specification

The PingCommand object's 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, PingCommand does not require a random payload, as the Off-Chain Protocol already has a cid to uniquely distinguish different CommandRequestObject and CommandResponseObject.

This command introduces no new errors outside the scope of DIP-1.