Merge pull request #791 from hirosystems/max-crawford-patch-2

update nakamoto section

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

@@ -3,6 +3,10 @@ title: get-block-info?
 description: Fetching information about Stacks blocks in Clarity smart contracts.
 ---
 
+<Callout>
+In Clarity 3, this function is being deprecated for [`get-stacks-block-info?`](/stacks/clarity/functions/get-stacks-block-info).
+</Callout>
+
 ## Function Signature
 
 ```clarity

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.

content/docs/stacks/nakamoto/guides/clarinet.mdx

@@ -74,3 +74,14 @@ epoch = 3.0
 
 Start devnet with `clarinet devnet start`, you should see epoch 3.0 and fast blocks at Bitcoin
 block 144.
+
+<Callout title="New Clarity keywords">
+Clarity 3 introduces two new keywords after the Nakamoto hard fork:
+
+- `tenure-height`: Returns the number of tenures passed.
+- `stacks-block-height`: Returns the current Stacks block height.
+
+Note: `block-height` is deprecated.
+
+For more details on these and other Clarity keywords, see the [Clarity Keywords Reference](https://docs.stacks.co/reference/keywords).
+</Callout>

content/docs/stacks/nakamoto/index.mdx

@@ -4,7 +4,13 @@ description: Discover updates to Hiro tools related to the Nakamoto upgrade.
 toc: false
 ---
 
-Nakamoto is an upcoming upgrade to the Stacks network. [Start here](https://docs.stacks.co/nakamoto-upgrade/nakamoto-upgrade-start-here) for an overview of how Nakamoto impacts the network, and below you will find how Hiro tools have been updated to support the Nakamoto upgrade.
+Nakamoto is an upcoming upgrade to Stacks that brings faster blocks and paves the way for sBTC. [Start here](https://docs.stacks.co/nakamoto-upgrade/nakamoto-upgrade-start-here) if you need an overview of how Nakamoto impacts the network. This document is about how Nakamoto impacts your applications and Hiro tooling specifically.
+
+The good news for you is that the Nakamoto upgrade does not bring breaking changes to applications on Stacks. Your app will continue to work as expected post-upgrade, apart from you and your users experiencing the better UX of faster block times.
+
+In terms of what you need to do to prepare for Nakamoto, just make sure you are running the latest versions of our tooling. We are shipping updates across all Hiro tools to make sure they support Nakamoto and that you can stay focused on building.
+
+Below find a list of how Hiro tools have been updated to support Nakamoto:
 
 ## Stacks Explorer: What's new