get-tenure-info?

Function Signature

(get-tenure-info? prop-name block-height)

• Input:
  • prop-name: A TenureInfoPropertyName
  • block-height: A uint representing the Stacks block height
• Output: (optional buff) | (optional uint) | (optional principal) depending on the property

Why it matters

The get-tenure-info? function is essential for:

1. 1Accessing historical tenure data within smart contracts
2. 2Retrieving information about block miners and rewards
3. 3Accessing VRF seeds for randomness-based applications
4. 4Analyzing miner participation and spending patterns

When to use it

Use get-tenure-info? when you need to:

• Access tenure-specific data like VRF seeds or miner addresses
• Verify tenure timestamps or burnchain information
• Analyze block rewards and miner spending patterns
• Implement logic that depends on historical tenure data

Best Practices

• Always handle the none case, as it will be returned for non-existent or future blocks
• Be aware that block rewards are only available after maturity (101 blocks on mainnet)
• Consider the two-hour accuracy window when working with tenure timestamps
• Cache frequently accessed tenure information to optimize execution costs

Practical Example: Checking Miner Spending

(define-read-only (get-miner-spend-ratio (blockHeight uint)))
(let
  (
    (winnerSpend (get-tenure-info? miner-spend-winner blockHeight))
    (totalSpend (get-tenure-info? miner-spend-total blockHeight))
  )
  (match (tuple (winner winnerSpend) (total totalSpend))
    success (some (/ (get success "winner") (get success "total")))
    error none
  )
)

Available Properties

• burnchain-header-hash: Returns the burnchain block header hash (buff 32)
• miner-address: Returns the tenure miner's principal
• time: Returns the tenure time as Unix epoch timestamp (uint)
• vrf-seed: Returns the VRF seed for the tenure (buff 32)
• block-reward: Returns the total block reward (uint)
• miner-spend-total: Returns total spent by all miners for this tenure (uint)
• miner-spend-winner: Returns amount spent by winning miner (uint)

Common Pitfalls

1. 1Not accounting for block reward maturity period (101 blocks)
2. 2Relying on exact tenure times (accuracy window of two hours)
3. 3Not handling the none case for invalid or future block heights

Related Functions

• get-block-info?: Used to get information about Stacks blocks
• block-height: Returns the current block height
• burn-block-height: Returns the current burn chain block height

Conclusion

The get-tenure-info? function provides crucial access to historical tenure data in Clarity smart contracts. Introduced in Clarity 3, it enables developers to access detailed information about past tenures, including miner participation, block rewards, and VRF seeds. When used properly, it's a powerful tool for implementing sophisticated contract logic that depends on historical blockchain state.