Add Connection#get_block_height

gem/lib/solace/connection.rb

@@ -157,6 +157,17 @@ def get_latest_blockhash
       [@last_fetched_blockhash, @last_fetched_block_height]
     end
 
+    # Get the current block height from the Solana node
+    #
+    # Defaults to the connection's commitment so comparisons against the
+    # +lastValidBlockHeight+ from {#get_latest_blockhash} stay consistent.
+    #
+    # @param commitment [String] The commitment level for the request
+    # @return [Integer] The current block height
+    def get_block_height(commitment: default_options[:commitment])
+      @rpc_client.rpc_request('getBlockHeight', [{ commitment: commitment }])['result']
+    end
+
     # Get the minimum required lamports for rent exemption
     #
     # @param space [Integer] Number of bytes to allocate for the account

gem/test/solace/connection_test.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+describe Solace::Connection do
+  let(:connection) { Solace::Connection.new(commitment: 'processed') }
+
+  describe '#get_block_height' do
+    it 'returns the current block height' do
+      assert_kind_of Integer, connection.get_block_height
+    end
+
+    it 'accepts a commitment override' do
+      finalized = connection.get_block_height(commitment: 'finalized')
+      processed = connection.get_block_height(commitment: 'processed')
+
+      assert_operator finalized, :<=, processed
+    end
+
+    it 'stays at or below the last valid block height' do
+      _blockhash, last_valid_block_height = connection.get_latest_blockhash
+
+      assert_operator connection.get_block_height, :<=, last_valid_block_height
+    end
+  end
+end

site/concepts/connection-and-rpc.md

@@ -35,6 +35,7 @@ test suite and most examples assume.
 | `get_mint_program_id(mint)` | `String \| nil` | Which token program owns a mint (SPL vs. Token-2022). |
 | `get_minimum_lamports_for_rent_exemption(space)` | `Integer` | Rent-exempt minimum for `space` bytes. |
 | `get_program_accounts(program_id, filters)` | `Array` | Accounts owned by a program. |
+| `get_block_height(commitment:)` | `Integer` | Current block height (defaults to the connection's commitment). |
 | `get_version` / `get_health` / `get_genesis_hash` | varies | Node metadata. |
 
 ## Blockhash and rent
@@ -44,10 +45,14 @@ array — the blockhash and the last valid block height:
 
 ```ruby
 blockhash, last_valid_height = connection.get_latest_blockhash
+
+# The blockhash stays usable until the chain passes last_valid_height:
+connection.get_block_height <= last_valid_height # => true while the blockhash is usable
 ```
 
 The composer layer fetches this for you; you only call it directly when assembling a
-[`Message`](/concepts/transactions-and-messages) by hand.
+[`Message`](/concepts/transactions-and-messages) by hand. `get_block_height` uses the
+connection's commitment by default, so the expiry comparison is apples-to-apples.
 
 ## Sending and confirming