feat(rpc)!: Expose the end of support height (#11097)

Author: mergify[bot]

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+### Breaking Changes
+
+- New `getdeprecationinfo` RPC returning the block height and estimated time at which this
+  release will halt for end of support, in zcashd's `end_of_service` format. The `end_of_service`
+  object is only present on Mainnet, where end of support is enforced
+  ([#11097](https://github.com/ZcashFoundation/zebra/pull/11097)).
+
 ### Added
 
 - Added `seeder.zec.rocks` and `seeder.testnet.zec.rocks` as default DNS seeders

zebra-rpc/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Breaking Changes
+
+- The `Rpc` trait has a new required `get_deprecation_info` method. Downstream implementers of
+  the trait must add it; callers of `RpcImpl` are unaffected
+  ([#11097](https://github.com/ZcashFoundation/zebra/pull/11097)).
+
+### Added
+
+- New `getdeprecationinfo` RPC method and `GetDeprecationInfoResponse` type. The reported end of
+  support height is set with `RpcImpl::with_end_of_support_height`; without it the response omits
+  the `end_of_service` object ([#11097](https://github.com/ZcashFoundation/zebra/pull/11097)).
+
 ### Changed
 
 - The indexer gRPC server now bounds concurrent HTTP/2 streams per connection (20)

zebra-rpc/src/client.rs

@@ -37,12 +37,12 @@ pub use crate::methods::{
         validate_address::ValidateAddressResponse,
         z_validate_address::{ZValidateAddressResponse, ZValidateAddressType},
     },
-    AddressStrings, BlockHeaderObject, BlockObject, GetAddressBalanceRequest,
+    AddressStrings, BlockHeaderObject, BlockObject, EndOfService, GetAddressBalanceRequest,
     GetAddressBalanceResponse, GetAddressTxIdsRequest, GetAddressUtxosResponse,
     GetAddressUtxosResponseObject, GetBlockHashResponse, GetBlockHeaderResponse,
     GetBlockHeightAndHashResponse, GetBlockResponse, GetBlockTransaction, GetBlockTrees,
-    GetBlockchainInfoResponse, GetInfoResponse, GetRawTransactionResponse, Hash,
-    SendRawTransactionResponse, Utxo,
+    GetBlockchainInfoResponse, GetDeprecationInfoResponse, GetInfoResponse,
+    GetRawTransactionResponse, Hash, SendRawTransactionResponse, Utxo,
 };
 
 /// Constants needed by clients of Zebra's RPC server

zebra-rpc/src/methods.rs

@@ -194,6 +194,28 @@ pub trait Rpc {
     #[method(name = "getinfo")]
     async fn get_info(&self) -> Result<GetInfoResponse>;
 
+    /// Returns end of support information for this node release, as a
+    /// [`GetDeprecationInfoResponse`] JSON struct.
+    ///
+    /// zcashd reference: [`getdeprecationinfo`](https://zcash.github.io/rpc/getdeprecationinfo.html)
+    /// method: post
+    /// tags: network
+    ///
+    /// # Notes
+    ///
+    /// As in zcashd, the `end_of_service` object is only present on Mainnet, where end of
+    /// support is enforced. Zebra reports the estimated last height this release supports in
+    /// `end_of_service.block_height`; the node halts when the tip goes past it.
+    ///
+    /// Some fields from the zcashd reference are missing from Zebra's response: `version` and
+    /// `subversion` are available from `getinfo`, `deprecationheight` is deprecated in zcashd,
+    /// and Zebra does not have zcashd's feature deprecation framework.
+    ///
+    /// The estimate assumes the node is synced to the network tip; during initial sync it is
+    /// significantly overestimated.
+    #[method(name = "getdeprecationinfo")]
+    async fn get_deprecation_info(&self) -> Result<GetDeprecationInfoResponse>;
+
     /// Returns blockchain state information, as a [`GetBlockchainInfoResponse`] JSON struct.
     ///
     /// zcashd reference: [`getblockchaininfo`](https://zcash.github.io/rpc/getblockchaininfo.html)
@@ -836,6 +858,10 @@ where
     /// no matter what the estimated height or local clock is.
     debug_force_finished_sync: bool,
 
+    /// The estimated last height this node release supports before its end of support halt,
+    /// if end of support is enforced on `network`. Reported by the `getdeprecationinfo` RPC.
+    end_of_support_height: Option<Height>,
+
     // Services
     //
     /// A handle to the mempool service.
@@ -950,6 +976,7 @@ where
             user_agent,
             network: network.clone(),
             debug_force_finished_sync,
+            end_of_support_height: None,
             mempool: mempool.clone(),
             state: state.clone(),
             read_state: read_state.clone(),
@@ -974,6 +1001,14 @@ where
     pub fn network(&self) -> &Network {
         &self.network
     }
+
+    /// Sets the estimated end of support height reported by the `getdeprecationinfo` RPC.
+    ///
+    /// When unset, or set to `None`, `getdeprecationinfo` omits the `end_of_service` object.
+    pub fn with_end_of_support_height(mut self, end_of_support_height: Option<Height>) -> Self {
+        self.end_of_support_height = end_of_support_height;
+        self
+    }
 }
 
 #[async_trait]
@@ -1039,6 +1074,44 @@ where
         Ok(response)
     }
 
+    async fn get_deprecation_info(&self) -> Result<GetDeprecationInfoResponse> {
+        let end_of_service = self
+            .end_of_support_height
+            // End of support is only enforced on Mainnet, and the zcashd-compatible response
+            // omits `end_of_service` on other networks, even if a height was configured.
+            .filter(|_| self.network == Network::Mainnet)
+            .map(|end_of_support_height| {
+                // Estimate the halt time from the current tip and target block spacing. If the
+                // tip is not available yet, fall back to the highest compiled-in checkpoint,
+                // which is close to the network tip at release time.
+                let tip_height = self
+                    .latest_chain_tip
+                    .best_tip_height()
+                    .unwrap_or_else(|| self.network.checkpoint_list().max_height());
+                // Use the spacing at the end of support height: it is always post-Blossom, so
+                // this stays correct even when the tip is missing or before Blossom.
+                let target_block_spacing =
+                    NetworkUpgrade::target_spacing_for_height(&self.network, end_of_support_height);
+                // If the tip is already past the end of support height, the estimate is in the
+                // past, but never negative.
+                let remaining_blocks = i64::from(end_of_support_height.0) - i64::from(tip_height.0);
+                let estimated_time = Utc::now()
+                    .timestamp()
+                    .saturating_add(
+                        remaining_blocks.saturating_mul(target_block_spacing.num_seconds()),
+                    )
+                    .saturating_sub(END_OF_SERVICE_ESTIMATE_SAFETY_MARGIN)
+                    .max(0);
+
+                EndOfService {
+                    block_height: end_of_support_height.0,
+                    estimated_time,
+                }
+            });
+
+        Ok(GetDeprecationInfoResponse { end_of_service })
+    }
+
     #[allow(clippy::unwrap_in_result)]
     async fn get_blockchain_info(&self) -> Result<GetBlockchainInfoResponse> {
         let debug_force_finished_sync = self.debug_force_finished_sync;
@@ -3508,6 +3581,41 @@ impl GetInfoResponse {
     }
 }
 
+/// The number of seconds subtracted from the `end_of_service.estimated_time` reported by
+/// `getdeprecationinfo`.
+///
+/// Block times vary, so the halt can happen earlier than a spacing-based estimate. Reporting the
+/// estimate a day early gives consumers time to act before the actual halt.
+const END_OF_SERVICE_ESTIMATE_SAFETY_MARGIN: i64 = 24 * 60 * 60;
+
+/// Response to a `getdeprecationinfo` RPC request.
+///
+/// See the notes for the [`Rpc::get_deprecation_info` method].
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize, Getters, new)]
+pub struct GetDeprecationInfoResponse {
+    /// End of service information for this node release. Only present on Mainnet, where end of
+    /// support is enforced.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    end_of_service: Option<EndOfService>,
+}
+
+/// The `end_of_service` object in a [`GetDeprecationInfoResponse`].
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize, Getters, new)]
+pub struct EndOfService {
+    /// The estimated last height this server version supports, matching zcashd's threshold
+    /// semantics. The node halts when the chain tip goes past this height.
+    #[getter(copy)]
+    block_height: u32,
+
+    /// The approximate time of the end of support halt, in seconds since epoch, estimated from
+    /// the current chain tip height and the target block spacing.
+    ///
+    /// Reported 24 hours earlier than the spacing-based estimate, so consumers are warned early
+    /// rather than late when block times vary.
+    #[getter(copy)]
+    estimated_time: i64,
+}
+
 /// Type alias for the array of `GetBlockchainInfoBalance` objects
 pub type BlockchainValuePoolBalances = [GetBlockchainInfoBalance; 6];
 

zebra-rpc/src/methods/tests/vectors.rs

@@ -116,6 +116,189 @@ async fn rpc_getinfo() {
     assert!(rpc_tx_queue_task_result.is_none());
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn rpc_getdeprecationinfo() {
+    let _init_guard = zebra_test::init();
+
+    let mempool: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let read_state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+
+    let (_tx, rx) = tokio::sync::watch::channel(None);
+    let (rpc, _rpc_tx_queue) = RpcImpl::new(
+        Mainnet,
+        Default::default(),
+        Default::default(),
+        "0.0.1",
+        "RPC test",
+        Buffer::new(mempool.clone(), 1),
+        Buffer::new(state.clone(), 1),
+        Buffer::new(read_state.clone(), 1),
+        MockService::build().for_unit_tests(),
+        MockSyncStatus::default(),
+        NoChainTip,
+        MockAddressBookPeers::default(),
+        rx,
+        None,
+    );
+
+    // Without a configured end of support height, `end_of_service` is not present.
+    let deprecation_info = rpc
+        .get_deprecation_info()
+        .await
+        .expect("getdeprecationinfo should succeed");
+    assert_eq!(deprecation_info.end_of_service, None);
+
+    let end_of_support_height = 3_546_440;
+    let rpc = rpc.with_end_of_support_height(Some(Height(end_of_support_height)));
+    let end_of_service = rpc
+        .get_deprecation_info()
+        .await
+        .expect("getdeprecationinfo should succeed")
+        .end_of_service
+        .expect("end_of_service should be present when an end of support height is set");
+
+    assert_eq!(end_of_service.block_height, end_of_support_height);
+    // This node has no tip, so the estimate counts the blocks remaining after the highest
+    // compiled-in checkpoint, not after genesis.
+    let checkpoint_height = Mainnet.checkpoint_list().max_height();
+    let remaining_blocks = i64::from(end_of_support_height - checkpoint_height.0);
+    let expected_offset = remaining_blocks * 75 - 24 * 60 * 60;
+    assert!(end_of_service.estimated_time > Utc::now().timestamp());
+    assert!(end_of_service.estimated_time <= Utc::now().timestamp() + expected_offset);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn rpc_getdeprecationinfo_estimates_time_from_tip_with_safety_margin() {
+    let _init_guard = zebra_test::init();
+
+    let mempool: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let read_state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+
+    let (latest_chain_tip, latest_chain_tip_sender) = MockChainTip::new();
+    let tip_height = Height(3_000_000);
+    latest_chain_tip_sender.send_best_tip_height(tip_height);
+
+    let (_tx, rx) = tokio::sync::watch::channel(None);
+    let (rpc, _rpc_tx_queue) = RpcImpl::new(
+        Mainnet,
+        Default::default(),
+        Default::default(),
+        "0.0.1",
+        "RPC test",
+        Buffer::new(mempool.clone(), 1),
+        Buffer::new(state.clone(), 1),
+        Buffer::new(read_state.clone(), 1),
+        MockService::build().for_unit_tests(),
+        MockSyncStatus::default(),
+        latest_chain_tip,
+        MockAddressBookPeers::default(),
+        rx,
+        None,
+    );
+
+    let end_of_support_height = Height(3_546_440);
+    let rpc = rpc.with_end_of_support_height(Some(end_of_support_height));
+
+    // Both heights are after Blossom, so every remaining block is expected to take 75 seconds,
+    // and the estimate is reported 24 hours early.
+    let remaining_blocks = i64::from(end_of_support_height.0 - tip_height.0);
+    let expected_offset = remaining_blocks * 75 - 24 * 60 * 60;
+
+    let before = Utc::now().timestamp();
+    let end_of_service = rpc
+        .get_deprecation_info()
+        .await
+        .expect("getdeprecationinfo should succeed")
+        .end_of_service
+        .expect("end_of_service should be present when an end of support height is set");
+    let after = Utc::now().timestamp();
+
+    assert_eq!(end_of_service.block_height, end_of_support_height.0);
+    assert!(end_of_service.estimated_time >= before + expected_offset);
+    assert!(end_of_service.estimated_time <= after + expected_offset);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn rpc_getdeprecationinfo_omits_end_of_service_off_mainnet() {
+    let _init_guard = zebra_test::init();
+
+    let mempool: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let read_state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+
+    let (_tx, rx) = tokio::sync::watch::channel(None);
+    let (rpc, _rpc_tx_queue) = RpcImpl::new(
+        Network::new_default_testnet(),
+        Default::default(),
+        Default::default(),
+        "0.0.1",
+        "RPC test",
+        Buffer::new(mempool.clone(), 1),
+        Buffer::new(state.clone(), 1),
+        Buffer::new(read_state.clone(), 1),
+        MockService::build().for_unit_tests(),
+        MockSyncStatus::default(),
+        NoChainTip,
+        MockAddressBookPeers::default(),
+        rx,
+        None,
+    );
+
+    // Even if an end of support height is configured, `end_of_service` is only reported on
+    // Mainnet, matching zcashd and the RPC documentation.
+    let rpc = rpc.with_end_of_support_height(Some(Height(100)));
+    let deprecation_info = rpc
+        .get_deprecation_info()
+        .await
+        .expect("getdeprecationinfo should succeed");
+    assert_eq!(deprecation_info.end_of_service, None);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn rpc_getdeprecationinfo_estimated_time_is_never_negative() {
+    let _init_guard = zebra_test::init();
+
+    let mempool: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+    let read_state: MockService<_, _, _, BoxError> = MockService::build().for_unit_tests();
+
+    // A tip so far past the end of support height that an unclamped estimate would be negative.
+    let (latest_chain_tip, latest_chain_tip_sender) = MockChainTip::new();
+    latest_chain_tip_sender.send_best_tip_height(Height::MAX);
+
+    let (_tx, rx) = tokio::sync::watch::channel(None);
+    let (rpc, _rpc_tx_queue) = RpcImpl::new(
+        Mainnet,
+        Default::default(),
+        Default::default(),
+        "0.0.1",
+        "RPC test",
+        Buffer::new(mempool.clone(), 1),
+        Buffer::new(state.clone(), 1),
+        Buffer::new(read_state.clone(), 1),
+        MockService::build().for_unit_tests(),
+        MockSyncStatus::default(),
+        latest_chain_tip,
+        MockAddressBookPeers::default(),
+        rx,
+        None,
+    );
+    let rpc = rpc.with_end_of_support_height(Some(Height(1)));
+
+    let end_of_service = rpc
+        .get_deprecation_info()
+        .await
+        .expect("getdeprecationinfo should succeed")
+        .end_of_service
+        .expect("end_of_service should be present when an end of support height is set");
+
+    assert_eq!(end_of_service.block_height, 1);
+    // The estimate is clamped to zero instead of going negative.
+    assert_eq!(end_of_service.estimated_time, 0);
+}
+
 // Helper function that returns the nonce, final sapling root and
 // block commitments of a given Block.
 async fn get_block_data(