Merge #17617: doc: unify unix epoch time descriptions

d94d34f05f4ae3efa07de409489d68bbcc216346 doc: update developer notes wrt unix epoch time (Jon Atack)
e2f32cb5c5c7f2b1d1fc7003587b6573fb59526a qa: unify unix epoch time descriptions (Jon Atack)

Pull request description:

  Closes #17613.

  Updated call sites: mocktime, getblockheader, getblock, pruneblockchain,
  getchaintxstats, getblocktemplate, setmocktime, getpeerinfo, setban,
  getnodeaddresses, getrawtransaction, importmulti, listtransactions,
  listsinceblock, gettransaction, getwalletinfo, getaddressinfo

  Commands for testing manually:
  ```
  bitcoind -help-debug | grep -A1 mocktime
  bitcoin-cli help getblockheader
  bitcoin-cli help getblock
  bitcoin-cli help pruneblockchain
  bitcoin-cli help getchaintxstats
  bitcoin-cli help getblocktemplate
  bitcoin-cli help setmocktime
  bitcoin-cli help getpeerinfo
  bitcoin-cli help setban
  bitcoin-cli help getnodeaddresses
  bitcoin-cli help getrawtransaction
  bitcoin-cli help importmulti
  bitcoin-cli help listtransactions
  bitcoin-cli help listsinceblock
  bitcoin-cli help gettransaction
  bitcoin-cli help getwalletinfo
  bitcoin-cli help getaddressinfo
  ```

ACKs for top commit:
  laanwj:
    re-ACK d94d34f05f4ae3efa07de409489d68bbcc216346

Tree-SHA512: 060713ea4e20ab72c580f06c5c7e3ef344ad9c2c9cb034987d980a54e3ed2ac0268eb3929806daa5caa7797c45f5305254fd499767db7f22862212cf77acf236

7 files changed, 23 insertions, 15 deletions

diff --git a/src/rpc/blockchain.cpp b/src/rpc/blockchain.cpp
index 946152d9aa..6f97ab8bd1 100644
--- a/src/rpc/blockchain.cpp
+++ b/src/rpc/blockchain.cpp
@@ -742,8 +742,8 @@ static UniValue getblockheader(const JSONRPCRequest& request)
             "  \"version\" : n,         (numeric) The block version\n"
             "  \"versionHex\" : \"00000000\", (string) The block version formatted in hexadecimal\n"
             "  \"merkleroot\" : \"xxxx\", (string) The merkle root\n"
-            "  \"time\" : ttt,          (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)\n"
-            "  \"mediantime\" : ttt,    (numeric) The median block time in seconds since epoch (Jan 1 1970 GMT)\n"
+            "  \"time\" : ttt,          (numeric) The block time expressed in " + UNIX_EPOCH_TIME + "\n"
+            "  \"mediantime\" : ttt,    (numeric) The median block time expressed in " + UNIX_EPOCH_TIME + "\n"
             "  \"nonce\" : n,           (numeric) The nonce\n"
             "  \"bits\" : \"1d00ffff\", (string) The bits\n"
             "  \"difficulty\" : x.xxx,  (numeric) The difficulty\n"
@@ -854,8 +854,8 @@ static UniValue getblock(const JSONRPCRequest& request)
             "     \"transactionid\"     (string) The transaction id\n"
             "     ,...\n"
             "  ],\n"
-            "  \"time\" : ttt,          (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)\n"
-            "  \"mediantime\" : ttt,    (numeric) The median block time in seconds since epoch (Jan 1 1970 GMT)\n"
+            "  \"time\" : ttt,          (numeric) The block time expressed in " + UNIX_EPOCH_TIME + "\n"
+            "  \"mediantime\" : ttt,    (numeric) The median block time expressed in " + UNIX_EPOCH_TIME + "\n"
             "  \"nonce\" : n,           (numeric) The nonce\n"
             "  \"bits\" : \"1d00ffff\", (string) The bits\n"
             "  \"difficulty\" : x.xxx,  (numeric) The difficulty\n"
@@ -921,7 +921,7 @@ static UniValue pruneblockchain(const JSONRPCRequest& request)
 {
             RPCHelpMan{"pruneblockchain", "",
                 {
-                    {"height", RPCArg::Type::NUM, RPCArg::Optional::NO, "The block height to prune up to. May be set to a discrete height, or a unix timestamp\n"
+                    {"height", RPCArg::Type::NUM, RPCArg::Optional::NO, "The block height to prune up to. May be set to a discrete height, or to a " + UNIX_EPOCH_TIME + "\n"
             "                  to prune blocks whose block time is at least 2 hours older than the provided timestamp."},
                 },
                 RPCResult{
@@ -1573,7 +1573,7 @@ static UniValue getchaintxstats(const JSONRPCRequest& request)
                 },
                 RPCResult{
             "{\n"
-            "  \"time\": xxxxx,                         (numeric) The timestamp for the final block in the window in UNIX format.\n"
+            "  \"time\": xxxxx,                         (numeric) The timestamp for the final block in the window, expressed in " + UNIX_EPOCH_TIME + ".\n"
             "  \"txcount\": xxxxx,                      (numeric) The total number of transactions in the chain up to that point.\n"
             "  \"window_final_block_hash\": \"...\",      (string) The hash of the final block in the window.\n"
             "  \"window_final_block_height\": xxxxx,    (numeric) The height of the final block in the window.\n"
diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp
index 85f9f1e8b7..fc16a31423 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -379,7 +379,7 @@ static UniValue getblocktemplate(const JSONRPCRequest& request)
             "  \"coinbasevalue\" : n,              (numeric) maximum allowable input to coinbase transaction, including the generation award and transaction fees (in satoshis)\n"
             "  \"coinbasetxn\" : { ... },          (json object) information for coinbase transaction\n"
             "  \"target\" : \"xxxx\",                (string) The hash target\n"
-            "  \"mintime\" : xxx,                  (numeric) The minimum timestamp appropriate for next block time in seconds since epoch (Jan 1 1970 GMT)\n"
+            "  \"mintime\" : xxx,                  (numeric) The minimum timestamp appropriate for the next block time, expressed in " + UNIX_EPOCH_TIME + "\n"
             "  \"mutable\" : [                     (array of string) list of ways the block template may be changed \n"
             "     \"value\"                          (string) A way the block template may be changed, e.g. 'time', 'transactions', 'prevblock'\n"
             "     ,...\n"
@@ -388,7 +388,7 @@ static UniValue getblocktemplate(const JSONRPCRequest& request)
             "  \"sigoplimit\" : n,                 (numeric) limit of sigops in blocks\n"
             "  \"sizelimit\" : n,                  (numeric) limit of block size\n"
             "  \"weightlimit\" : n,                (numeric) limit of block weight\n"
-            "  \"curtime\" : ttt,                  (numeric) current timestamp in seconds since epoch (Jan 1 1970 GMT)\n"
+            "  \"curtime\" : ttt,                  (numeric) current timestamp in " + UNIX_EPOCH_TIME + "\n"
             "  \"bits\" : \"xxxxxxxx\",              (string) compressed target of next block\n"
             "  \"height\" : n                      (numeric) The height of the next block\n"
             "}\n"
diff --git a/src/rpc/misc.cpp b/src/rpc/misc.cpp
index d73dd6e52d..d967d2bcca 100644
--- a/src/rpc/misc.cpp
+++ b/src/rpc/misc.cpp
@@ -343,7 +343,7 @@ static UniValue setmocktime(const JSONRPCRequest& request)
             RPCHelpMan{"setmocktime",
                 "\nSet the local time to given timestamp (-regtest only)\n",
                 {
-                    {"timestamp", RPCArg::Type::NUM, RPCArg::Optional::NO, "Unix seconds-since-epoch timestamp\n"
+                    {"timestamp", RPCArg::Type::NUM, RPCArg::Optional::NO, UNIX_EPOCH_TIME + "\n"
             "   Pass 0 to go back to using the system time."},
                 },
                 RPCResults{},
diff --git a/src/rpc/net.cpp b/src/rpc/net.cpp
index f1dcc9b607..6ee91f139d 100644
--- a/src/rpc/net.cpp
+++ b/src/rpc/net.cpp
@@ -89,11 +89,11 @@ static UniValue getpeerinfo(const JSONRPCRequest& request)
             "         ...\n"
             "     ],\n"
             "    \"relaytxes\":true|false,    (boolean) Whether peer has asked us to relay transactions to it\n"
-            "    \"lastsend\": ttt,           (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last send\n"
-            "    \"lastrecv\": ttt,           (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last receive\n"
+            "    \"lastsend\": ttt,           (numeric) The " + UNIX_EPOCH_TIME + " of the last send\n"
+            "    \"lastrecv\": ttt,           (numeric) The " + UNIX_EPOCH_TIME + " of the last receive\n"
             "    \"bytessent\": n,            (numeric) The total bytes sent\n"
             "    \"bytesrecv\": n,            (numeric) The total bytes received\n"
-            "    \"conntime\": ttt,           (numeric) The connection time in seconds since epoch (Jan 1 1970 GMT)\n"
+            "    \"conntime\": ttt,           (numeric) The " + UNIX_EPOCH_TIME + " of the connection\n"
             "    \"timeoffset\": ttt,         (numeric) The time offset in seconds\n"
             "    \"pingtime\": n,             (numeric) ping time (if available)\n"
             "    \"minping\": n,              (numeric) minimum observed ping time (if any at all)\n"
@@ -534,7 +534,7 @@ static UniValue setban(const JSONRPCRequest& request)
                     {"subnet", RPCArg::Type::STR, RPCArg::Optional::NO, "The IP/Subnet (see getpeerinfo for nodes IP) with an optional netmask (default is /32 = single IP)"},
                     {"command", RPCArg::Type::STR, RPCArg::Optional::NO, "'add' to add an IP/Subnet to the list, 'remove' to remove an IP/Subnet from the list"},
                     {"bantime", RPCArg::Type::NUM, /* default */ "0", "time in seconds how long (or until when if [absolute] is set) the IP is banned (0 or empty means using the default time of 24h which can also be overwritten by the -bantime startup argument)"},
-                    {"absolute", RPCArg::Type::BOOL, /* default */ "false", "If set, the bantime must be an absolute timestamp in seconds since epoch (Jan 1 1970 GMT)"},
+                    {"absolute", RPCArg::Type::BOOL, /* default */ "false", "If set, the bantime must be an absolute timestamp expressed in " + UNIX_EPOCH_TIME},
                 },
                 RPCResults{},
                 RPCExamples{
@@ -691,7 +691,7 @@ static UniValue getnodeaddresses(const JSONRPCRequest& request)
                 RPCResult{
             "[\n"
             "  {\n"
-            "    \"time\": ttt,                (numeric) Timestamp in seconds since epoch (Jan 1 1970 GMT) keeping track of when the node was last seen\n"
+            "    \"time\": ttt,                (numeric) The " + UNIX_EPOCH_TIME + " of when the node was last seen\n"
             "    \"services\": n,              (numeric) The services offered\n"
             "    \"address\": \"host\",          (string) The address of the node\n"
             "    \"port\": n                   (numeric) The port of the node\n"
diff --git a/src/rpc/rawtransaction.cpp b/src/rpc/rawtransaction.cpp
index 3ffeee73de..b816a54d2f 100644
--- a/src/rpc/rawtransaction.cpp
+++ b/src/rpc/rawtransaction.cpp
@@ -139,7 +139,7 @@ static UniValue getrawtransaction(const JSONRPCRequest& request)
             "  ],\n"
             "  \"blockhash\" : \"hash\",   (string) the block hash\n"
             "  \"confirmations\" : n,      (numeric) The confirmations\n"
-            "  \"blocktime\" : ttt         (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)\n"
+            "  \"blocktime\" : ttt         (numeric) The block time expressed in " + UNIX_EPOCH_TIME + "\n"
             "  \"time\" : ttt,             (numeric) Same as \"blocktime\"\n"
             "}\n"
                     },
diff --git a/src/rpc/util.cpp b/src/rpc/util.cpp
index 0791a365fe..78586c22f9 100644
--- a/src/rpc/util.cpp
+++ b/src/rpc/util.cpp
@@ -13,6 +13,8 @@
 
 #include <tuple>
 
+const std::string UNIX_EPOCH_TIME = "UNIX epoch time";
+
 void RPCTypeCheck(const UniValue& params,
                   const std::list<UniValueType>& typesExpected,
                   bool fAllowNull)
diff --git a/src/rpc/util.h b/src/rpc/util.h
index 9304e1fefb..065a992a88 100644
--- a/src/rpc/util.h
+++ b/src/rpc/util.h
@@ -22,6 +22,12 @@
 
 #include <boost/variant.hpp>
 
+/**
+ * String used to describe UNIX epoch time in documentation, factored out to a
+ * constant for consistency.
+ */
+extern const std::string UNIX_EPOCH_TIME;
+
 class FillableSigningProvider;
 class CPubKey;
 class CScript;