Merge bitcoin/bitcoin#28590: assumeutxo: change getchainstates RPC to return a list of chainstates

a9ef702a877a964bac724a56e2c0b5bee4ea7586 assumeutxo: change getchainstates RPC to return a list of chainstates (Ryan Ofsky)

Pull request description:

  Current `getchainstates` RPC returns "normal" and "snapshot" fields which are not ideal because it requires new "normal" and "snapshot" terms to be defined, and the definitions are not really consistent with internal code. (In the RPC interface, the "snapshot" chainstate becomes the "normal" chainstate after it is validated, while in internal code there is no "normal chainstate" and the "snapshot chainstate" is still called that temporarily after it is validated).

  The current `getchainstates` RPC is also awkward to use if you to want information about the most-work chainstate, because you have to look at the "snapshot" field if it exists, and otherwise fall back to the "normal" field.

  Fix these issues by having `getchainstates` just return a flat list of chainstates ordered by work, and adding a new chainstate "validated" field alongside the existing "snapshot_blockhash" field so it is explicit if a chainstate was originally loaded from a snapshot, and whether the snapshot has been validated.

  This change was motivated by comment thread in https://github.com/bitcoin/bitcoin/pull/28562#discussion_r1344154808

ACKs for top commit:
  Sjors:
    re-ACK a9ef702a877a964bac724a56e2c0b5bee4ea7586
  jamesob:
    re-ACK a9ef702
  achow101:
    ACK a9ef702a877a964bac724a56e2c0b5bee4ea7586

Tree-SHA512: b364e2e96675fb7beaaee60c4dff4b69e6bc2d8a30dea1ba094265633d1cddf9dbf1c5ce20c07d6e23222cf1e92a195acf6227e4901f3962e81a1e53a43490aa

1 files changed, 22 insertions, 25 deletions

diff --git a/test/functional/feature_assumeutxo.py b/test/functional/feature_assumeutxo.py
index be0715df32..15cacc204c 100755
--- a/test/functional/feature_assumeutxo.py
+++ b/test/functional/feature_assumeutxo.py
@@ -128,10 +128,13 @@ class AssumeutxoTest(BitcoinTestFramework):
         assert_equal(loaded['coins_loaded'], SNAPSHOT_BASE_HEIGHT)
         assert_equal(loaded['base_height'], SNAPSHOT_BASE_HEIGHT)
 
-        monitor = n1.getchainstates()
-        assert_equal(monitor['normal']['blocks'], START_HEIGHT)
-        assert_equal(monitor['snapshot']['blocks'], SNAPSHOT_BASE_HEIGHT)
-        assert_equal(monitor['snapshot']['snapshot_blockhash'], dump_output['base_hash'])
+        normal, snapshot = n1.getchainstates()["chainstates"]
+        assert_equal(normal['blocks'], START_HEIGHT)
+        assert_equal(normal.get('snapshot_blockhash'), None)
+        assert_equal(normal['validated'], True)
+        assert_equal(snapshot['blocks'], SNAPSHOT_BASE_HEIGHT)
+        assert_equal(snapshot['snapshot_blockhash'], dump_output['base_hash'])
+        assert_equal(snapshot['validated'], False)
 
         assert_equal(n1.getblockchaininfo()["blocks"], SNAPSHOT_BASE_HEIGHT)
 
@@ -159,20 +162,11 @@ class AssumeutxoTest(BitcoinTestFramework):
         self.connect_nodes(0, 1)
 
         self.log.info(f"Ensuring snapshot chain syncs to tip. ({FINAL_HEIGHT})")
-
-        def check_for_final_height():
-            chainstates = n1.getchainstates()
-            # The background validation may have completed before we run our first
-            # check, so accept a final blockheight from either chainstate type.
-            cs = chainstates.get('snapshot') or chainstates.get('normal')
-            return cs['blocks'] == FINAL_HEIGHT
-
-        wait_until_helper(check_for_final_height)
+        wait_until_helper(lambda: n1.getchainstates()['chainstates'][-1]['blocks'] == FINAL_HEIGHT)
         self.sync_blocks(nodes=(n0, n1))
 
         self.log.info("Ensuring background validation completes")
-        # N.B.: the `snapshot` key disappears once the background validation is complete.
-        wait_until_helper(lambda: not n1.getchainstates().get('snapshot'))
+        wait_until_helper(lambda: len(n1.getchainstates()['chainstates']) == 1)
 
         # Ensure indexes have synced.
         completed_idx_state = {
@@ -189,8 +183,8 @@ class AssumeutxoTest(BitcoinTestFramework):
 
             assert_equal(n.getblockchaininfo()["blocks"], FINAL_HEIGHT)
 
-            assert_equal(n.getchainstates()['normal']['blocks'], FINAL_HEIGHT)
-            assert_equal(n.getchainstates().get('snapshot'), None)
+            chainstate, = n.getchainstates()['chainstates']
+            assert_equal(chainstate['blocks'], FINAL_HEIGHT)
 
             if i != 0:
                 # Ensure indexes have synced for the assumeutxo node
@@ -208,17 +202,20 @@ class AssumeutxoTest(BitcoinTestFramework):
         assert_equal(loaded['coins_loaded'], SNAPSHOT_BASE_HEIGHT)
         assert_equal(loaded['base_height'], SNAPSHOT_BASE_HEIGHT)
 
-        monitor = n2.getchainstates()
-        assert_equal(monitor['normal']['blocks'], START_HEIGHT)
-        assert_equal(monitor['snapshot']['blocks'], SNAPSHOT_BASE_HEIGHT)
-        assert_equal(monitor['snapshot']['snapshot_blockhash'], dump_output['base_hash'])
+        normal, snapshot = n2.getchainstates()['chainstates']
+        assert_equal(normal['blocks'], START_HEIGHT)
+        assert_equal(normal.get('snapshot_blockhash'), None)
+        assert_equal(normal['validated'], True)
+        assert_equal(snapshot['blocks'], SNAPSHOT_BASE_HEIGHT)
+        assert_equal(snapshot['snapshot_blockhash'], dump_output['base_hash'])
+        assert_equal(snapshot['validated'], False)
 
         self.connect_nodes(0, 2)
-        wait_until_helper(lambda: n2.getchainstates()['snapshot']['blocks'] == FINAL_HEIGHT)
+        wait_until_helper(lambda: n2.getchainstates()['chainstates'][-1]['blocks'] == FINAL_HEIGHT)
         self.sync_blocks()
 
         self.log.info("Ensuring background validation completes")
-        wait_until_helper(lambda: not n2.getchainstates().get('snapshot'))
+        wait_until_helper(lambda: len(n2.getchainstates()['chainstates']) == 1)
 
         completed_idx_state = {
             'basic block filter index': COMPLETE_IDX,
@@ -234,8 +231,8 @@ class AssumeutxoTest(BitcoinTestFramework):
 
             assert_equal(n.getblockchaininfo()["blocks"], FINAL_HEIGHT)
 
-            assert_equal(n.getchainstates()['normal']['blocks'], FINAL_HEIGHT)
-            assert_equal(n.getchainstates().get('snapshot'), None)
+            chainstate, = n.getchainstates()['chainstates']
+            assert_equal(chainstate['blocks'], FINAL_HEIGHT)
 
             if i != 0:
                 # Ensure indexes have synced for the assumeutxo node