Addressed greg's comments: added test comments, fixed style issues in openapi.yaml

docs/rpc/openapi.yaml

@@ -79,8 +79,9 @@ paths:
         schema:
           type: string
         description: |
-          If use_latest_tip == 1, query will be run from the latest tip (includes unconfirmed state).
-          If 0, the tip is selected as usual (first checking value of the tip parameter, otherwise taking the stacks chain tip)
+          If use_latest_tip == 1, the query will be run from the latest tip (includes unconfirmed state).
+          If use_latest_tip == 0 or is unspecified, the tip is selected as usual (first checking value of the
+          tip parameter, otherwise taking the stacks chain tip).
   /v2/map_entry/{contract_address}/{contract_name}/{map_name}:
     post:
       summary: Get specific data-map inside a contract
@@ -138,8 +139,9 @@ paths:
           schema:
             type: string
           description: |
-            If use_latest_tip == 1, query will be run from the latest tip (includes unconfirmed state).
-            If 0, the tip is selected as usual (first checking value of the tip parameter, otherwise taking the stacks chain tip)
+            If use_latest_tip == 1, the query will be run from the latest tip (includes unconfirmed state).
+            If use_latest_tip == 0 or is unspecified, the tip is selected as usual (first checking value of the
+            tip parameter, otherwise taking the stacks chain tip).
     x-codegen-request-body-name: key
       requestBody:
         description: Hex string serialization of the lookup key (which should be a Clarity value)
@@ -193,9 +195,9 @@ paths:
         in: query
         schema:
           type: string
-        description: |
-          If use_latest_tip == 1, query will be run from the latest tip (includes unconfirmed state).
-          If 0, the tip is selected as usual (first checking value of the tip parameter, otherwise taking the stacks chain tip)
+        description: If use_latest_tip == 1, the query will be run from the latest tip (includes unconfirmed state).
+          If use_latest_tip == 0 or is unspecified, the tip is selected as usual (first checking value of the
+          tip parameter, otherwise taking the stacks chain tip).
 
   /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}:
     post:
@@ -249,8 +251,9 @@ paths:
           schema:
             type: string
           description: |
-            If use_latest_tip == 1, query will be run from the latest tip (includes unconfirmed state).
-            If 0, the tip is selected as usual (first checking value of the tip parameter, otherwise taking the stacks chain tip)
+            If use_latest_tip == 1, the query will be run from the latest tip (includes unconfirmed state).
+            If use_latest_tip == 0 or is unspecified, the tip is selected as usual (first checking value of the
+            tip parameter, otherwise taking the stacks chain tip).
       requestBody:
         description: map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values.
         required: true
@@ -298,8 +301,9 @@ paths:
           schema:
             type: string
           description: |
-            If use_latest_tip == 1, query will be run from the latest tip (includes unconfirmed state).
-            If 0, the tip is selected as usual (first checking value of the tip parameter, otherwise taking the stacks chain tip)
+            If use_latest_tip == 1, the query will be run from the latest tip (includes unconfirmed state).
+            If use_latest_tip == 0 or is unspecified, the tip is selected as usual (first checking value of the
+            tip parameter, otherwise taking the stacks chain tip).
       responses:
         200:
           description: Success
@@ -371,8 +375,9 @@ paths:
           schema:
             type: string
           description: |
-            If use_latest_tip == 1, query will be run from the latest tip (includes unconfirmed state).
-            If 0, the tip is selected as usual (first checking value of the tip parameter, otherwise taking the stacks chain tip)
+            If use_latest_tip == 1, the query will be run from the latest tip (includes unconfirmed state).
+            If use_latest_tip == 0 or is unspecified, the tip is selected as usual (first checking value of the
+            tip parameter, otherwise taking the stacks chain tip).
 
   /v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_ contract_name}/{trait_name}:
     get:
@@ -431,5 +436,6 @@ paths:
           schema:
             type: string
           description: |
-            If use_latest_tip == 1, query will be run from the latest tip (includes unconfirmed state).
-            If 0, the tip is selected as usual (first checking value of the tip parameter, otherwise taking the stacks chain tip)
+            If use_latest_tip == 1, the query will be run from the latest tip (includes unconfirmed state).
+            If use_latest_tip == 0 or is unspecified, the tip is selected as usual (first checking value of the
+            tip parameter, otherwise taking the stacks chain tip).

src/net/http.rs

@@ -1660,9 +1660,8 @@ impl HttpRequestType {
         ))
     }
 
-    /// check whether the given option query string
-    ///   sets proof=0 (setting proof to false).
-    /// Defaults to _true_
+    /// Check whether the given option query string sets proof=0 (setting proof to false).
+    /// Defaults to true.
     fn get_proof_query(query: Option<&str>) -> bool {
         let no_proof = if let Some(query_string) = query {
             form_urlencoded::parse(query_string.as_bytes())
@@ -1677,18 +1676,16 @@ impl HttpRequestType {
     }
 
     /// Check whether the given option query string sets use_latest_tip=1 (setting use_latest_tip to true).
-    /// Defaults to _false_
+    /// Defaults to false.
     fn get_use_latest_chain_tip(query: Option<&str>) -> bool {
-        let use_latest_tip = if let Some(query_string) = query {
+        if let Some(query_string) = query {
             form_urlencoded::parse(query_string.as_bytes())
                 .find(|(key, _v)| key == "use_latest_tip")
                 .map(|(_k, value)| value == "1")
                 .unwrap_or(false)
         } else {
             false
-        };
-
-        use_latest_tip
+        }
     }
 
     /// get the chain tip optional query argument (`tip`)

src/net/rpc.rs

@@ -1511,11 +1511,16 @@ impl ConversationHttp {
     /// Load up the canonical Stacks chain tip.  Note that this is subject to both burn chain block
     /// Stacks block availability -- different nodes with different partial replicas of the Stacks chain state
     /// will return different values here.
-    /// tip_opt is given by the HTTP request as the optional query parameter for the chain tip
-    /// hash.  It will be None if there was no paramter given.
+    ///
+    /// # Inputs
+    /// - `tip_opt` is given by the HTTP request as the optional query parameter for the chain tip
+    /// hash.  It will be None if there was no parameter given.
+    /// - `use_latest_tip` is also an optional query parameter, and defaults to false.
+    ///
     /// The order of chain tips this method prefers is as follows:
-    /// * tip_opt, if it's Some(..),
-    /// * the unconfirmed canonical stacks chain tip, if initialized
+    /// * If `use_latest_tip` is true, the method attempts to return the unconfirmed chain tip,
+    ///     and returns the confirmed stacks chain tip if that doesn't work.
+    /// * `tip_opt`, if it's Some(..),
     /// * the confirmed canonical stacks chain tip
     fn handle_load_stacks_chain_tip<W: Write>(
         http: &mut StacksHttp,
@@ -1527,18 +1532,18 @@ impl ConversationHttp {
         use_latest_tip: bool,
     ) -> Result<Option<StacksBlockId>, net_error> {
         if use_latest_tip {
-            let (use_unconfirmed, unconfirmed_chain_tip) = match &chainstate.unconfirmed_state {
+            let unconfirmed_chain_tip_opt = match &chainstate.unconfirmed_state {
                 Some(unconfirmed_state) => {
                     if unconfirmed_state.is_readable() {
-                        (true, unconfirmed_state.unconfirmed_chain_tip.clone())
+                        Some(unconfirmed_state.unconfirmed_chain_tip.clone())
                     } else {
-                        (false, StacksBlockId([0; 32]))
+                        None
                     }
                 }
-                None => (false, StacksBlockId([0; 32])),
+                None => None,
             };
 
-            if use_unconfirmed {
+            if let Some(unconfirmed_chain_tip) = unconfirmed_chain_tip_opt {
                 Ok(Some(unconfirmed_chain_tip))
             } else {
                 let tip = chainstate.get_stacks_chain_tip(sortdb).unwrap().unwrap();
@@ -4329,6 +4334,9 @@ mod test {
         );
     }
 
+    /// In this test, the query parameter `use_latest_tip` is set to true, and so we expect the
+    /// tip used for the query to be the latest microblock.
+    /// We check that the account state matches the state in the most recent microblock.
     #[test]
     #[ignore]
     fn test_rpc_get_account_use_latest_tip() {
@@ -4370,6 +4378,10 @@ mod test {
         );
     }
 
+    /// In this test, the query parameter `use_latest_tip` is set to true, but we did not generate
+    /// microblocks in the rpc test. Thus, we expect the tip used for the query to be the previous
+    /// anchor block (which is the latest tip).
+    /// We check that the account state matches the state in the previous anchor block.
     #[test]
     #[ignore]
     fn test_rpc_get_account_use_latest_tip_no_microblocks() {