add new clarity 3 functions

content/docs/stacks/clarity/functions/get-stacks-block-info.mdx

@@ -0,0 +1,89 @@
+---
+title: get-stacks-block-info?
+description: Fetching information about Stacks blocks in Clarity smart contracts.
+---
+
+<Callout>
+In Clarity 3, this function replaces the deprecated `get-block-info?` function.
+</Callout>
+
+## Function Signature
+
+```clarity
+(get-stacks-block-info? prop-name block-height)
+```
+
+- Input: 
+  - `prop-name`: A StacksBlockInfoPropertyName
+  - `block-height`: A uint representing the Stacks block height
+- Output: `(optional buff) | (optional uint)` depending on the property
+
+## Why it matters
+
+The `get-stacks-block-info?` function is crucial for:
+
+1. Accessing historical Stacks block data within smart contracts
+2. Retrieving globally unique block identifiers
+3. Implementing time-based logic using block information
+4. Verifying block-related properties for security or validation purposes
+
+## When to use it
+
+Use `get-stacks-block-info?` when you need to:
+
+- Retrieve unique identifiers for Stacks blocks
+- Access block timestamps for time-based logic
+- Verify block hashes for validation purposes
+- Implement logic that depends on block information
+
+## Best Practices
+
+- Always use `id-header-hash` when global uniqueness is required
+- Handle the `none` case for non-existent or future blocks
+- Be aware of the different timestamp sources before and after epoch 3.0
+- Consider caching frequently accessed block information
+
+## Practical Example: Block Hash Verification
+
+```clarity
+(define-read-only (verify-block-hash (blockHeight uint) (expectedHash (buff 32)))
+  (match (get-stacks-block-info? id-header-hash blockHeight)
+    hash (is-eq hash expectedHash)
+    false
+  )
+)
+
+;; Usage
+(verify-block-hash u100 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb)
+```
+
+This example demonstrates:
+1. Retrieving a block's unique identifier
+2. Handling the optional return value
+3. Comparing block hashes for verification
+
+## Available Properties
+
+- `id-header-hash`: Returns the globally unique index block hash (buff 32)
+- `header-hash`: Returns the Stacks block's header hash (buff 32)
+- `time`: Returns the block time as Unix epoch timestamp (uint)
+
+## Common Pitfalls
+
+1. Using `header-hash` when global uniqueness is required (use `id-header-hash` instead)
+2. Not handling the `none` case for invalid or future block heights
+3. Assuming block times are exact (accuracy varies by epoch):
+   - Pre-epoch 3.0: Accurate within two hours
+   - Post-epoch 3.0: Must be greater than previous block and at most 15 seconds in the future
+4. Not considering the different timestamp sources across epochs
+
+## Related Functions
+
+- `get-tenure-info?`: Used to get information about block tenures
+- `block-height`: Returns the current block height
+- `at-block`: Used with `id-header-hash` for historical state access
+
+## Conclusion
+
+The `get-stacks-block-info?` function, introduced in Clarity 3, provides essential access to Stacks block data in smart contracts. It offers reliable ways to access block identifiers and timestamps, with important considerations for global uniqueness and time accuracy across different epochs. Understanding its properties and limitations is crucial for building robust smart contracts that interact with historical blockchain state.
+

content/docs/stacks/clarity/functions/get-tenure-info.mdx

@@ -0,0 +1,83 @@
+---
+title: get-tenure-info?
+description: Fetching information about Stacks tenures in Clarity smart contracts.
+---
+
+## Function Signature
+
+
+```clarity
+(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. Accessing historical tenure data within smart contracts
+2. Retrieving information about block miners and rewards
+3. Accessing VRF seeds for randomness-based applications
+4. Analyzing 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
+
+```clarity
+(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. Not accounting for block reward maturity period (101 blocks)
+2. Relying on exact tenure times (accuracy window of two hours)
+3. Not 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.