Eos: unclear what the 'time' field represents in "cleos net status"

[matthewdarwin]

"cleos net status" returns a "time" field. It is not clear what this time represents.

There is no documentation about it https://developers.eos.io/eosio-cleos/reference#cleos-net-status

cleos net status 192.168.146.46:9876
{
  "peer": "192.168.146.46:9876",
  "connecting": false,
  "syncing": false,
  "last_handshake": {
    "network_version": 1206,
    "chain_id": "aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906",
    "node_id": "dd13ae5b58a1737e303fd9279a31c9314b2e2d5b04889c3d30bed8423006159f",
    "key": "EOS5vrm1RdspjKXy9Zx1Ng31oH1qcw9DpY3b3XyDJSR7gWSj8kN15",
    "time": "1574372902409323000",
    "token": "af82042161695334b9d0b47de604e53e966cb1d08fb73e168c791a13f6fd1c0c",
    "sig": "SIG_K1_K3zHxB8qFNDH63gAaGvR3iCwzdyp4cFsKQZb1fsE99yWVsQa9jXenLFuWyADiosiDZv9pYyKDAbKYoC2RYFZ7XhNvxqTU7",
    "p2p_address": "eos-dsp3:9876 - dd13ae5",
    "last_irreversible_block_num": 91095115,
    "last_irreversible_block_id": "056e004b79122f5f1ec131bc795f6715e48517c766c4a82bba96b855e6d40132",
    "head_num": 91095446,
    "head_id": "056e0196fb9c8f23fcaa6c969a7c63534a79c03ba47eac6801eac736f8c02486",
    "os": "linux",
    "agent": "\"EOS Nation\"",
    "generation": 1
  }
}

[johndebord]

We can find the underlying data structure of last_handshake in file eos/plugins/net_plugin/include/eosio/net_plugin/protocol.hpp#L24-L40:

struct handshake_message {
   uint16_t                   network_version = 0; ///< incremental value above a computed base
   chain_id_type              chain_id; ///< used to identify chain
   fc::sha256                 node_id; ///< used to identify peers and prevent self-connect     
   chain::public_key_type     key; ///< authentication key; may be a producer or peer key, or empty
   tstamp                     time;
   fc::sha256                 token; ///< digest of time to prove we own the private key of the key above
   chain::signature_type      sig; ///< signature for the digest
   string                     p2p_address;
   uint32_t                   last_irreversible_block_num = 0;
   block_id_type              last_irreversible_block_id;
   uint32_t                   head_num = 0;
   block_id_type              head_id;
   string                     os;
   string                     agent;
   int16_t                    generation;
};

In the same file, we can also see that the field time is of type tstamp which is a typedef to:

typedef std::chrono::system_clock::duration::rep tstamp;

But what is it a timestamp of?
Well, let's follow the logic in the code originating from file eos/programs/cleos/main.cpp#L3114-L3119:

auto status = net->add_subcommand("status", localized("Status of existing connection"), false);
   status->add_option("host", new_host, localized("The hostname:port to query status of connection"))->required();
   status->set_callback([&] {
   const auto& v = call(url, net_status, new_host);
   std::cout << fc::json::to_pretty_string(v) << std::endl;
});

We end up calling the function connection::get_status() in file eos/plugins/net_plugin/net_plugin.cpp#L508-L515:

connection_status connection::get_status()const {
   connection_status stat;
   stat.peer = peer_addr;
   stat.connecting = connecting;
   stat.syncing = syncing;
   std::lock_guard<std::mutex> g( conn_mtx );
   stat.last_handshake = last_handshake_recv;
   return stat;
}

Lastly, the type connection_status holds a field that is of type handshake_message; which can be found in file eos/plugins/net_plugin/include/eosio/net_plugin/net_plugin.hpp#L13-L18:

struct connection_status {
   string            peer;
   bool              connecting = false;
   bool              syncing    = false;
   handshake_message last_handshake;
};

We can now see that the field time corresponds to the last timestamp of the last handshake received; last_handshake_recv.

[lparisc]

@matthewdarwin See also a description of the handshake message in the EOSIO network protocol document.

[iamveritas]

thank you all, for reporting this and for contributing to the solution @lparisc and @johndebord .
in the light of the new documentation that explains the time field of the handshake message can we close this issue @matthewdarwin ?

[matthewdarwin]

Can the page at https://developers.eos.io/manuals/eos/latest/cleos/command-reference/net/status point to the web page with the handshake details?

[iamveritas]

Can the page at https://developers.eos.io/manuals/eos/latest/cleos/command-reference/net/status point to the web page with the handshake details?

https://github.com/EOSIO/eos/pull/8718

we have in plan to improve the whole cleos reference documentation for now this is the best I can do.

[lparisc]

docs/02_cleos/03_command-reference/net/status.md
network_peer_protocol#421-handshake-message