Merge bitcoin/bitcoin#31043: rpc: getorphantxs follow-up

0ea84bc362 test: explicitly check boolean verbosity is disallowed (tdb3)
7a2e6b68cd doc: add rpc guidance for boolean verbosity avoidance (tdb3)
698f302df8 rpc: disallow boolean verbosity in getorphantxs (tdb3)
63f5e6ec79 test: add entry and expiration time checks (tdb3)
808a708107 rpc: add entry time to getorphantxs (tdb3)
56bf302714 refactor: rename rpc_getorphantxs to rpc_orphans (tdb3)
7824f6b077 test: check that getorphantxs is hidden (tdb3)
ac68fcca70 rpc: disallow undefined verbosity in getorphantxs (tdb3)

Pull request description:

  Implements follow-up suggestions from #30793.

  - Now disallows undefined verbosity levels (below and above valid values) (https://github.com/bitcoin/bitcoin/pull/30793#discussion_r1786093549)
  - Disallows boolean verbosity (https://github.com/bitcoin/bitcoin/pull/30793#discussion_r1788273274) and adds guidance to developer-notes
  - Checks that `getorphantxs` is a hidden rpc (https://github.com/bitcoin/bitcoin/pull/30793#discussion_r1786107786)
  - Adds a test for `expiration` time
  - Adds `entry` time to the returned orphan objects (verbosity >=1) to relieve the user from having to calculate it from `expiration`.  Also adds associated test. (https://github.com/bitcoin/bitcoin/pull/30793#discussion_r1743687732)
  - Minor cleanup (blank line removal and log message move) (https://github.com/bitcoin/bitcoin/pull/30793#discussion_r1786092641)

  Included a commit to rename the test to a more generic `get_orphans` to better accommodate future orphanage-related RPCs (e.g. `getorphanangeinfo`).  Can drop the refactor commit from this PR if people feel strongly about it.

ACKs for top commit:
  achow101:
    ACK 0ea84bc362
  glozow:
    utACK 0ea84bc362
  rkrux:
    tACK 0ea84bc362
  itornaza:
    tACK 0ea84bc362

Tree-SHA512: e48a088f333ebde132923072da58e970461e74362d0acebbc799c3043d5727cdf5f28e82b43cb38bbed27c603df6710695dba91ff0695e623ad168e985dce08e
This commit is contained in:
Ava Chow
2024-10-29 14:49:19 -04:00
10 changed files with 60 additions and 21 deletions

View File

@@ -1397,6 +1397,12 @@ A few guidelines for introducing and reviewing new RPC interfaces:
to a multi-value, or due to other historical reasons. **Always** have false map to 0 and
true to 1 in this case.
- For new RPC methods, if implementing a `verbosity` argument, use integer verbosity rather than boolean.
Disallow usage of boolean verbosity (see `ParseVerbosity()` in [util.h](/src/rpc/util.h)).
- *Rationale*: Integer verbosity allows for multiple values. Undocumented boolean verbosity is deprecated
and new RPC methods should prevent its use.
- Don't forget to fill in the argument names correctly in the RPC command table.
- *Rationale*: If not, the call cannot be used with name-based arguments.