Add missing Clarity3 functions

reference/functions.md

@@ -1232,31 +1232,30 @@ Introduced in: **Clarity 1**
 **signature:** `(get-block-info? prop-name block-height)`
 
 **description:**
+In Clarity 3, `get-block-info?` is removed. In its place, `get-stacks-block-info?` can be used to retrieve information about a Stacks block and `get-tenure-info?` can be used to get information pertaining to the tenure. The `get-block-info?` function fetches data for a block of the given *Stacks* block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `block-height` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are as follows:
 
-The `get-block-info?` function fetches data for a block of the given _Stacks_ block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `block-height` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are as follows:
+- `burnchain-header-hash`: This property returns a `(buff 32)` value containing the header hash of the burnchain (Bitcoin) block that selected the Stacks block at the given Stacks chain height.
 
-`burnchain-header-hash`: This property returns a `(buff 32)` value containing the header hash of the burnchain (Bitcoin) block that selected the Stacks block at the given Stacks chain height.
+- `id-header-hash`: This property returns a `(buff 32)` value containing the _index block hash_ of a Stacks block. This hash is globally unique, and is derived from the block hash and the history of accepted PoX operations.  This is also the block hash value you would pass into `(at-block)`.
 
-`id-header-hash`: This property returns a `(buff 32)` value containing the _index block hash_ of a Stacks block. This hash is globally unique, and is derived from the block hash and the history of accepted PoX operations. This is also the block hash value you would pass into `(at-block)`.
+- `header-hash`: This property returns a `(buff 32)` value containing the header hash of a Stacks block, given a Stacks chain height.  **WARNING* this hash is not guaranteed to be globally unique, since the same Stacks block can be mined in different PoX forks.  If you need global uniqueness, you should use `id-header-hash`.
 
-`header-hash`: This property returns a `(buff 32)` value containing the header hash of a Stacks block, given a Stacks chain height. \*_WARNING_ this hash is not guaranteed to be globally unique, since the same Stacks block can be mined in different PoX forks. If you need global uniqueness, you should use `id-header-hash`.
+- `miner-address`: This property returns a `principal` value corresponding to the miner of the given block.  **WARNING** In Stacks 2.1, this is not guaranteed to be the same `principal` that received the block reward, since Stacks 2.1 supports coinbase transactions that pay the reward to a contract address.  This is merely the address of the `principal` that produced the block.
 
-`miner-address`: This property returns a `principal` value corresponding to the miner of the given block. **WARNING** In Stacks 2.1, this is not guaranteed to be the same `principal` that received the block reward, since Stacks 2.1 supports coinbase transactions that pay the reward to a contract address. This is merely the address of the `principal` that produced the block.
+- `time`: This property returns a `uint` value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. This timestamp comes from the burnchain block. **Note**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. For blocks mined after epoch 3.0, all Stacks blocks in one tenure will share the same timestamp. To get the Stacks block time for a block in epoch 3.0+, use `get-stacks-block-info?`.
 
-`time`: This property returns a `uint` value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. **Note**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information.
+- `vrf-seed`: This property returns a `(buff 32)` value of the VRF seed for the corresponding block.
 
-New in Stacks 2.1:
+- `block-reward`: This property returns a `uint` value for the total block reward of the indicated Stacks block. This value is only available once the reward for the block matures.  That is, the latest `block-reward` value available is at least 101 Stacks blocks in the past (on mainnet).  The reward includes the coinbase, the anchored block's transaction fees, and the shares of the confirmed and produced microblock transaction fees earned by this block's miner.  Note that this value may be smaller than the Stacks coinbase at this height, because the miner may have been punished with a valid `PoisonMicroblock` transaction in the event that the miner published two or more microblock stream forks. Added in Clarity 2.
 
-`block-reward`: This property returns a `uint` value for the total block reward of the indicated Stacks block. This value is only available once the reward for the block matures. That is, the latest `block-reward` value available is at least 101 Stacks blocks in the past (on mainnet). The reward includes the coinbase, the anchored block's transaction fees, and the shares of the confirmed and produced microblock transaction fees earned by this block's miner. Note that this value may be smaller than the Stacks coinbase at this height, because the miner may have been punished with a valid `PoisonMicroblock` transaction in the event that the miner published two or more microblock stream forks.
+- `miner-spend-total`: This property returns a `uint` value for the total number of burnchain tokens (i.e. satoshis) spent by all miners trying to win this block. Added in Clarity 2.
 
-`miner-spend-total`: This property returns a `uint` value for the total number of burnchain tokens (i.e. satoshis) spent by all miners trying to win this block.
-
-`miner-spend-winner`: This property returns a `uint` value for the number of burnchain tokens (i.e. satoshis) spent by the winning miner for this Stacks block. Note that this value is less than or equal to the value for `miner-spend-total` at the same block height.
+- `miner-spend-winner`: This property returns a `uint` value for the number of burnchain tokens (i.e. satoshis) spent by the winning miner for this Stacks block.  Note that this value is less than or equal to the value for `miner-spend-total` at the same block height. Added in Clarity 2.
 
 **example:**
 
 ```
-(get-block-info? time u0) ;; Returns (some u1557860301)
+(get-block-info? time u0) ;; Returns (some u1557860301) 
 (get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb)
 (get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4)
 ```
@@ -1299,6 +1298,61 @@ The `addrs` list contains the same PoX address values passed into the PoX smart
 (get-burn-block-info? pox-addrs u677050) ;; Returns (some (tuple (addrs ( (tuple (hashbytes 0x395f3643cea07ec4eec73b4d9a973dcce56b9bf1) (version 0x00)) (tuple (hashbytes 0x7c6775e20e3e938d2d7e9d79ac310108ba501ddb) (version 0x01)))) (payout u123)))
 ```
 
+## get-stacks-block-info?
+
+Introduced in: **Clarity 3**
+
+**input:** `StacksBlockInfoPropertyName, uint`
+
+**output:** `(optional buff), (optional uint)`
+
+**signature:** `(get-stacks-block-info? prop-name stacks-block-height)`
+
+**description:**
+
+The `get-stacks-block-info?` function fetches data for a block of the given *Stacks* block height. The value and type returned are determined by the specified `StacksBlockInfoPropertyName`. If the provided `stacks-block-height` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are as follows:
+
+- `id-header-hash`: This property returns a `(buff 32)` value containing the _index block hash_ of a Stacks block.   This hash is globally unique, and is derived from the block hash and the history of accepted PoX operations.  This is also the block hash value you would pass into `(at-block)`.
+- `header-hash`: This property returns a `(buff 32)` value containing the header hash of a Stacks block, given a Stacks chain height. **WARNING** this hash is not guaranteed to be globally unique, since the same Stacks block can be mined in different PoX forks.  If you need global uniqueness, you should use `id-header-hash`.
+- `time`: This property returns a `uint` value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. For a block mined before epoch 3.0, this timestamp comes from the burnchain block. **Note**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information.
+For a block mined after epoch 3.0, this timestamp comes from the Stacks block header. **Note**: this is the time, according to the miner, when the mining of this block started, but is not guaranteed to be accurate. This time will be validated by the signers to be:
+- Greater than the timestamp of the previous block
+- At most 15 seconds into the future (according to their own local clocks)
+
+**example:**
+```
+(get-stacks-block-info? time u0) ;; Returns (some u1557860301)
+(get-stacks-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb)
+```
+
+## get-tenure-info?
+
+Introduced in: **Clarity 3**
+
+**input:** `TenureInfoPropertyName, uint`
+
+**output:** `(optional buff) | (optional uint)`
+
+**signature:** `(get-tenure-info? prop-name stacks-block-height)`
+
+**description:**
+
+The `get-tenure-info?` function fetches data for the tenure at the given block height. The value and type returned are determined by the specified `TenureInfoPropertyName`. If the provided `stacks-block-height` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are as follows:
+
+- `burnchain-header-hash`: This property returns a `(buff 32)` value containing the header hash of the burnchain (Bitcoin) block that selected the tenure at the given height.
+- `miner-address`: This property returns a `principal` value corresponding to the miner of the given tenure.  **WARNING** This is not guaranteed to be the same `principal` that received the block reward, since Stacks 2.1+ supports coinbase transactions that pay the reward to a contract address.  This is merely the address of the `principal` that produced the tenure.
+- `time`: This property returns a `uint` Unix epoch timestamp in seconds which roughly corresponds to when the tenure was started. This timestamp comes from the burnchain block. **Note**: this does not increase monotonically with each tenure and tenure times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information.
+- `vrf-seed`: This property returns a `(buff 32)` value of the VRF seed for the corresponding tenure.
+- `block-reward`: This property returns a `uint` value for the total block reward of the indicated tenure. This value is only available once the reward for the tenure matures.  That is, the latest `block-reward` value available is at least 101 Stacks blocks in the past (on mainnet).  The reward includes the coinbase, the anchored tenure's transaction fees, and the shares of the confirmed and produced microblock transaction fees earned by this block's miner.  Note that this value may be smaller than the Stacks coinbase at this height, because the miner may have been punished with a valid `PoisonMicroblock` transaction in the event that the miner published two or more microblock stream forks.
+- `miner-spend-total`: This property returns a `uint` value for the total number of burnchain tokens (i.e. satoshis) spent by all miners trying to win this tenure.
+- `miner-spend-winner`: This property returns a `uint` value for the number of burnchain tokens (i.e. satoshis) spent by the winning miner for this tennure.  Note that this value is less than or equal to the value for `miner-spend-total` at the same tenure height.
+
+**example:**
+```
+(get-tenure-info? time u0) ;; Returns (some u1557860301)
+(get-tenure-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4)
+```
+
 ## hash160​
 
 Introduced in: **Clarity 1**

reference/keywords.md

@@ -12,12 +12,13 @@ Introduced in: Clarity 1
 
 **description:**
 
-Returns the current block height of the Stacks blockchain as an uint
+Returns the current block height of the Stacks blockchain in Clarity 1 and 2. Upon activation of epoch 3.0, `block-height` will return the same value as `tenure-height`. In Clarity 3, `block-height` is removed and has been replaced with `stacks-block-height`.
 
 **example:**
 
 ```
-(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks.
+(> block-height u1000) ;; returns true if the current block-height has passed 1000 blocks.
+
 ```
 
 ### burn-block-height​ <a href="#burn-block-height" id="burn-block-height"></a>
@@ -152,10 +153,6 @@ Represents the _none_ option indicating no value for a given optional (analogous
 
 ### **stacks-block-height**
 
-{% hint style="warning" %}
-Will be available after the Nakamoto hard fork
-{% endhint %}
-
 Introduced in: Clarity 3
 
 **output: `uint`**
@@ -188,10 +185,6 @@ Returns the total number of micro-STX (uSTX) that are liquid in the system as of
 
 ### **tenure-height**
 
-{% hint style="warning" %}
-Will be available after Nakamoto hard fork
-{% endhint %}
-
 Introduced in: Clarity 3
 
 **output: `uint`**