Documentation Index
Fetch the complete documentation index at: https://mintlify.com/stellar/rs-soroban-sdk/llms.txt
Use this file to discover all available pages before exploring further.
The ledger module provides types for retrieving information about the current ledger, including sequence numbers, timestamps, and network identifiers.
Overview
Access ledger information through env.ledger() in your contracts. The ledger provides metadata about the blockchain state at the time of execution.
Types
Ledger
Retrieves information about the current ledger.
Obtain via env.ledger() in contract code.
Functions
sequence
Returns the sequence number of the current ledger.
pub fn sequence(&self) -> u32
use soroban_sdk::{contract, contractimpl, Env};
#[contract]
pub struct Contract;
#[contractimpl]
impl Contract {
pub fn get_ledger_sequence(env: Env) -> u32 {
env.ledger().sequence()
}
}
timestamp
Returns the Unix timestamp when the ledger was closed.
pub fn timestamp(&self) -> u64
use soroban_sdk::{contract, contractimpl, Env};
#[contract]
pub struct Contract;
#[contractimpl]
impl Contract {
pub fn check_deadline(env: Env, deadline: u64) -> bool {
let current_time = env.ledger().timestamp();
current_time <= deadline
}
}
network_id
Returns the network identifier.
pub fn network_id(&self) -> BytesN<32>
- Public Network:
SHA256("Public Global Stellar Network ; September 2015")
- Test Network:
SHA256("Test SDF Network ; September 2015")
Example:
use soroban_sdk::{contract, contractimpl, BytesN, Env};
#[contract]
pub struct Contract;
#[contractimpl]
impl Contract {
pub fn get_network_id(env: Env) -> BytesN<32> {
env.ledger().network_id()
}
}
protocol_version (deprecated)
Returns the protocol version of the ledger.
#[deprecated(note = "Protocol version won't be available in the future")]
pub fn protocol_version(&self) -> u32
max_live_until_ledger (hidden)
Returns the maximum ledger sequence number that data can live until.
#[doc(hidden)]
pub fn max_live_until_ledger(&self) -> u32
Examples
Time-based Logic
use soroban_sdk::{contract, contractimpl, Env, Address};
#[contract]
pub struct Escrow;
#[contractimpl]
impl Escrow {
pub fn release(
env: Env,
release_time: u64,
recipient: Address
) -> Result<(), &'static str> {
let current_time = env.ledger().timestamp();
if current_time < release_time {
return Err("Release time not reached");
}
// Release funds to recipient
Ok(())
}
}
Sequence-based Logic
use soroban_sdk::{contract, contractimpl, Env};
#[contract]
pub struct Auction;
#[contractimpl]
impl Auction {
pub fn end_auction(
env: Env,
end_sequence: u32
) -> Result<(), &'static str> {
let current_sequence = env.ledger().sequence();
if current_sequence < end_sequence {
return Err("Auction still ongoing");
}
// Finalize auction
Ok(())
}
}
Network Detection
use soroban_sdk::{contract, contractimpl, BytesN, Env};
#[contract]
pub struct Contract;
#[contractimpl]
impl Contract {
pub fn is_mainnet(env: Env) -> bool {
// Check if running on mainnet by comparing network ID
let network_id = env.ledger().network_id();
// Compare with known mainnet network ID
// (This is an example - actual implementation would need the real hash)
network_id == BytesN::from_array(&env, &[/* mainnet hash */])
}
}
Test Utilities
When the testutils feature is enabled, additional functions are available for controlling ledger state in tests:
set
Sets complete ledger info.
pub fn set(&self, ledger_info: LedgerInfo)
set_sequence_number
Sets the ledger sequence number.
pub fn set_sequence_number(&self, sequence_number: u32)
set_timestamp
Sets the ledger timestamp.
pub fn set_timestamp(&self, timestamp: u64)
set_network_id
Sets the network ID.
pub fn set_network_id(&self, network_id: [u8; 32])
set_protocol_version
Sets the protocol version.
pub fn set_protocol_version(&self, protocol_version: u32)
set_base_reserve
Sets the base reserve.
pub fn set_base_reserve(&self, base_reserve: u32)
set_min_temp_entry_ttl
Sets the minimum temporary entry TTL.
pub fn set_min_temp_entry_ttl(&self, min_temp_entry_ttl: u32)
set_min_persistent_entry_ttl
Sets the minimum persistent entry TTL.
pub fn set_min_persistent_entry_ttl(&self, min_persistent_entry_ttl: u32)
set_max_entry_ttl
Sets the maximum entry TTL.
pub fn set_max_entry_ttl(&self, max_entry_ttl: u32)
get
Gets the current ledger info.
pub fn get(&self) -> LedgerInfo
with_mut
Modifies ledger info using a closure.
pub fn with_mut<F>(&self, f: F)
where
F: FnMut(&mut LedgerInfo)
Test Example
use soroban_sdk::{Env, testutils::Ledger};
#[test]
fn test_time_based_function() {
let env = Env::default();
// Set ledger timestamp to a specific value
env.ledger().set_timestamp(1234567890);
let contract_id = env.register(Contract, ());
let client = ContractClient::new(&env, &contract_id);
// Test with specific timestamp
let result = client.check_deadline(&2000000000);
assert!(result);
// Advance time
env.ledger().set_timestamp(3000000000);
let result = client.check_deadline(&2000000000);
assert!(!result);
}
LedgerInfo
Complete ledger information structure (available with testutils):
pub struct LedgerInfo {
pub protocol_version: u32,
pub sequence_number: u32,
pub timestamp: u64,
pub network_id: [u8; 32],
pub base_reserve: u32,
pub min_temp_entry_ttl: u32,
pub min_persistent_entry_ttl: u32,
pub max_entry_ttl: u32,
}
Best Practices
- Use timestamps for real-world time: Use
timestamp() when working with real-world deadlines
- Use sequence for block-based logic: Use
sequence() for logic tied to blockchain progression
- Cache ledger values: If using multiple times, cache the value to save computation
- Test time-based logic: Use testutils to thoroughly test time-dependent behavior
- Handle time drift: Remember that timestamps may not be perfectly accurate
See Also
- Env - For accessing ledger functions
- Bytes - For byte arrays and fixed-size BytesN
- Ledger Headers - Stellar documentation on ledger headers