Merge branch 'develop' into chore/3.1.0.0.12_develop

Author: wileyj

.cargo/config.toml

@@ -1,7 +1,7 @@
 [alias]
 stacks-node = "run --package stacks-node --"
 fmt-stacks = "fmt -- --config group_imports=StdExternalCrate,imports_granularity=Module"
-clippy-stacks = "clippy -p libstackerdb -p stacks-signer -p pox-locking -p clarity -p libsigner -p stacks-common --no-deps --tests --all-features -- -D warnings"
+clippy-stacks = "clippy -p stx-genesis -p libstackerdb -p stacks-signer -p pox-locking -p clarity -p libsigner -p stacks-common --no-deps --tests --all-features -- -D warnings"
 
 # Uncomment to improve performance slightly, at the cost of portability
 #   * Note that native binaries may not run on CPUs that are different from the build machine

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to the versioning scheme outlined in the [README.md](README.md).
 
+## Unreleased
+
+### Added
+
+- Added a new RPC endpoint `/v3/health` to query the node's health status. The endpoint returns a 200 status code with relevant synchronization information (including the node's current Stacks tip height, the maximum Stacks tip height among its neighbors, and the difference between these two). A user can use the `difference_from_max_peer` value to decide what is a good threshold for them before considering the node out of sync. The endpoint returns a 500 status code if the query cannot retrieve viable data.
+
 ## [3.1.0.0.12]
 
 ### Added
@@ -33,6 +39,7 @@ and this project adheres to the versioning scheme outlined in the [README.md](RE
 ## [3.1.0.0.10]
 
 ### Added
+
 - Persisted tracking of StackerDB slot versions for mining. This improves miner p2p performance.
 
 ## [3.1.0.0.9]

docs/rpc-endpoints.md

@@ -129,7 +129,7 @@ non-canonical headers will be returned instead.
 ### GET /v2/accounts/[Principal]
 
 Get the account data for the provided principal.
-The principal string is either a Stacks address or a Contract identifier (e.g., 
+The principal string is either a Stacks address or a Contract identifier (e.g.,
 `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`
 
 Returns JSON data in the form:
@@ -157,7 +157,7 @@ JSON object _without_ the `balance_proof` or `nonce_proof` fields.
 
 Attempt to vetch a data var from a contract. The contract is identified with [Stacks Address] and
  [Contract Name] in the URL path. The variable is identified with [Var Name].
- 
+
 Returns JSON data in the form:
 
 ```json
@@ -202,7 +202,7 @@ Returns JSON data in the form:
 Where data is the metadata formatted as a JSON string.
 
 ### GET /v2/constant_val/[Stacks Address]/[Contract Name]/[Constant Name]
-Attempt to fetch a constant from a contract. The contract is identified with [Stacks Address] and 
+Attempt to fetch a constant from a contract. The contract is identified with [Stacks Address] and
  [Contract Name] in the URL path. The constant is identified with [Constant Name].
 
 Returns JSON data in the form:
@@ -219,7 +219,7 @@ Where data is the hex serialization of the constant value.
 
 Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and
  [Contract Name] in the URL path. The map is identified with [Map Name].
- 
+
 The _key_ to lookup in the map is supplied via the POST body. This should be supplied as the hex string
 serialization of the key (which should be a Clarity value). Note, this is a _JSON_ string atom.
 
@@ -539,8 +539,8 @@ data.
 
 This will return 404 if the block does not exist.
 
-This endpoint also accepts a querystring parameter `?tip=` which when supplied 
-will return the block relative to the specified tip allowing the querying of 
+This endpoint also accepts a querystring parameter `?tip=` which when supplied
+will return the block relative to the specified tip allowing the querying of
 sibling blocks (same height, different tip) too.
 
 ### GET /v3/tenures/[Block ID]
@@ -595,3 +595,13 @@ This feature requires enabling of transaction indexing by setting the `txindex`
 
 This will return 404 if the transaction does not exist and 501 (Not Implemented) if
 transaction indexing is not enabled.
+
+
+### GET /v3/health
+
+Determine node's synchronization health, comparing the node's current Stacks tip height
+with the maximum Stacks tip height observed among its connected peers.
+If there are no valid initial peers or data for the node to determine this information, this endpoint returns an error. The endpoint returns the node's current Stacks tip height, the maximum Stacks tip height observed among its connected peers, and the difference between these two heights.
+A user can utilize the `difference_from_max_peer` to establish their own criteria for determining if a node is out of sync.
+
+See OpenAPI [spec](./rpc/openapi.yaml) for details.

docs/rpc/api/core-node/get-health-error.example.json

@@ -0,0 +1,3 @@
+{
+  "error": "No viable bootstrap peers found, unable to determine health"
+}

docs/rpc/api/core-node/get-health-error.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Error response when GET request to query node health fails",
+  "title": "ServerError",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "error"
+  ],
+  "properties": {
+    "error": {
+      "type": "string"
+    }
+  }
+}

docs/rpc/api/core-node/get-health.example.json

@@ -0,0 +1,5 @@
+{
+  "difference_from_max_peer": 0,
+  "max_stacks_height_of_neighbors": 12345,
+  "node_stacks_tip_height": 12345
+}

docs/rpc/api/core-node/get-health.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "GET request to query node health",
+  "title": "GetHealthResponse",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "difference_from_max_peer",
+    "max_stacks_height_of_neighbors",
+    "node_stacks_tip_height"
+  ],
+  "properties": {
+    "difference_from_max_peer": {
+      "type": "integer",
+      "description": "The difference in height between the node and its most advanced neighbor."
+    },
+    "max_stacks_height_of_neighbors": {
+      "type": "integer",
+      "description": "The max Stacks height of the node's most advanced neighbor."
+    },
+    "node_stacks_tip_height": {
+      "type": "integer",
+      "description": "The Stacks height of this node."
+    }
+  }
+}

docs/rpc/openapi.yaml

@@ -895,3 +895,36 @@ paths:
           description: Transaction indexing not enabled
           content:
             application/text-plain: {}
+
+  /v3/health:
+    get:
+      summary: Query the health of the node.
+      description: |
+        Get node health information.
+        A node is considered healthy if its Stacks tip height matches the maximum Stacks tip height observed among its connected peers.
+        This endpoint returns:
+        - `difference_from_max_peer`: The difference in Stacks height between this node and its most advanced peer.
+        - `max_stacks_height_of_neighbors`: The maximum Stacks height observed among the node's connected peers.
+        - `node_stacks_tip_height`: The current Stacks tip height of this node.
+      tags:
+        - Info
+      operationId: get_health
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: ./api/core-node/get-health.schema.json
+              example:
+                $ref: ./api/core-node/get-health.example.json
+        500:
+          description: |
+            Failed to query for health (e.g., no data or no valid peers to query from).
+            Only the `error` field will be set in this case, providing a message about the failure.
+          content:
+            application/json:
+              schema:
+                $ref: ./api/core-node/get-health-error.schema.json
+              example:
+                $ref: ./api/core-node/get-health-error.example.json

libsigner/src/events.rs

@@ -45,8 +45,8 @@ pub use stacks_common::consts::SIGNER_SLOTS_PER_USER;
 use stacks_common::types::chainstate::{
     BlockHeaderHash, BurnchainHeaderHash, ConsensusHash, SortitionId, StacksPublicKey,
 };
-use stacks_common::util::hash::{Hash160, Sha512Trunc256Sum};
-use stacks_common::util::serde_serializers::{prefix_hex, prefix_opt_hex};
+use stacks_common::util::hash::{hex_bytes, Hash160, Sha512Trunc256Sum};
+use stacks_common::util::serde_serializers::{prefix_hex, prefix_opt_hex, prefix_string_0x};
 use stacks_common::util::HexError;
 use stacks_common::versions::STACKS_NODE_VERSION;
 use tiny_http::{
@@ -229,6 +229,8 @@ pub enum SignerEvent<T: SignerEventTrait> {
         signer_sighash: Option<Sha512Trunc256Sum>,
         /// The block height for the newly processed stacks block
         block_height: u64,
+        /// The transactions included in the block
+        transactions: Vec<StacksTransaction>,
     },
 }
 
@@ -577,18 +579,26 @@ impl<T: SignerEventTrait> TryFrom<BlockValidateResponse> for SignerEvent<T> {
     }
 }
 
-#[derive(Debug, Deserialize)]
-struct BurnBlockEvent {
+/// Burn block JSON payload from the event receiver
+#[derive(Debug, Deserialize, Clone)]
+pub struct BurnBlockEvent {
+    /// The hash of the burn block
     #[serde(with = "prefix_hex")]
-    burn_block_hash: BurnchainHeaderHash,
-    burn_block_height: u64,
-    reward_recipients: Vec<serde_json::Value>,
-    reward_slot_holders: Vec<String>,
-    burn_amount: u64,
+    pub burn_block_hash: BurnchainHeaderHash,
+    /// The height of the burn block
+    pub burn_block_height: u64,
+    /// The reward recipients
+    pub reward_recipients: Vec<serde_json::Value>,
+    /// The reward slot holders
+    pub reward_slot_holders: Vec<String>,
+    /// The amount of burn
+    pub burn_amount: u64,
+    /// The consensus hash of the burn block
     #[serde(with = "prefix_hex")]
-    consensus_hash: ConsensusHash,
+    pub consensus_hash: ConsensusHash,
+    /// The parent burn block hash
     #[serde(with = "prefix_hex")]
-    parent_burn_block_hash: BurnchainHeaderHash,
+    pub parent_burn_block_hash: BurnchainHeaderHash,
 }
 
 impl<T: SignerEventTrait> TryFrom<BurnBlockEvent> for SignerEvent<T> {
@@ -605,6 +615,45 @@ impl<T: SignerEventTrait> TryFrom<BurnBlockEvent> for SignerEvent<T> {
     }
 }
 
+/// A subset of `TransactionEventPayload`, received from the event
+/// dispatcher.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct NewBlockTransaction {
+    /// The raw transaction bytes. If this is a burn operation,
+    /// this will be "00".
+    #[serde(with = "prefix_string_0x")]
+    raw_tx: String,
+}
+
+impl NewBlockTransaction {
+    pub fn get_stacks_transaction(&self) -> Result<Option<StacksTransaction>, CodecError> {
+        if self.raw_tx == "00" {
+            Ok(None)
+        } else {
+            let tx_bytes = hex_bytes(&self.raw_tx).map_err(|e| {
+                CodecError::DeserializeError(format!("Failed to deserialize raw tx: {}", e))
+            })?;
+            let tx = StacksTransaction::consensus_deserialize(&mut &tx_bytes[..])?;
+            Ok(Some(tx))
+        }
+    }
+}
+
+/// "Special" deserializer to turn `{ tx_raw: "0x..." }` into `StacksTransaction`.
+fn deserialize_raw_tx_hex<'de, D: serde::Deserializer<'de>>(
+    d: D,
+) -> Result<Vec<StacksTransaction>, D::Error> {
+    let tx_objs: Vec<NewBlockTransaction> = serde::Deserialize::deserialize(d)?;
+    Ok(tx_objs
+        .iter()
+        .map(|tx| tx.get_stacks_transaction())
+        .collect::<Result<Vec<_>, _>>()
+        .map_err(serde::de::Error::custom)?
+        .into_iter()
+        .flatten()
+        .collect::<Vec<_>>())
+}
+
 #[derive(Debug, Deserialize)]
 struct BlockEvent {
     #[serde(with = "prefix_hex")]
@@ -617,6 +666,8 @@ struct BlockEvent {
     #[serde(with = "prefix_hex")]
     block_hash: BlockHeaderHash,
     block_height: u64,
+    #[serde(deserialize_with = "deserialize_raw_tx_hex")]
+    transactions: Vec<StacksTransaction>,
 }
 
 impl<T: SignerEventTrait> TryFrom<BlockEvent> for SignerEvent<T> {
@@ -628,6 +679,7 @@ impl<T: SignerEventTrait> TryFrom<BlockEvent> for SignerEvent<T> {
             block_id: block_event.index_block_hash,
             consensus_hash: block_event.consensus_hash,
             block_height: block_event.block_height,
+            transactions: block_event.transactions,
         })
     }
 }

libsigner/src/libsigner.rs

@@ -57,8 +57,8 @@ use stacks_common::versions::STACKS_SIGNER_VERSION;
 
 pub use crate::error::{EventError, RPCError};
 pub use crate::events::{
-    BlockProposal, BlockProposalData, EventReceiver, EventStopSignaler, SignerEvent,
-    SignerEventReceiver, SignerEventTrait, SignerStopSignaler,
+    BlockProposal, BlockProposalData, BurnBlockEvent, EventReceiver, EventStopSignaler,
+    SignerEvent, SignerEventReceiver, SignerEventTrait, SignerStopSignaler,
 };
 pub use crate::runloop::{RunningSigner, Signer, SignerRunLoop};
 pub use crate::session::{SignerSession, StackerDBSession};