From 80ec296327b44954c492303794d70f45d4f7c0f5 Mon Sep 17 00:00:00 2001 From: wileyj <2847772+wileyj@users.noreply.github.com> Date: Fri, 17 Jan 2025 13:59:42 -0800 Subject: [PATCH 1/6] Add missing Clarity3 functions --- reference/functions.md | 57 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/reference/functions.md b/reference/functions.md index e3a4f2abe9..8a34669ca9 100644 --- a/reference/functions.md +++ b/reference/functions.md @@ -1239,7 +1239,7 @@ The `get-block-info?` function fetches data for a block of the given _Stacks_ bl `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. @@ -1299,6 +1299,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** From 903a29e8e29848e4c610fc1516e8fbc194bab6f5 Mon Sep 17 00:00:00 2001 From: wileyj <2847772+wileyj@users.noreply.github.com> Date: Sun, 19 Jan 2025 21:34:34 -0800 Subject: [PATCH 2/6] Update some keywords/functions for Clarity 3 --- reference/functions.md | 25 +++++++++++-------------- reference/keywords.md | 5 +++-- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/reference/functions.md b/reference/functions.md index 8a34669ca9..3cc9d65a0e 100644 --- a/reference/functions.md +++ b/reference/functions.md @@ -1232,33 +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? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) +(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) ``` ## get-burn-block-info?​ diff --git a/reference/keywords.md b/reference/keywords.md index b62aa93ec1..d53b9e7821 100644 --- a/reference/keywords.md +++ b/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​ From 04d318cefc7d21506f645c534927dcde9f8bba53 Mon Sep 17 00:00:00 2001 From: wileyj <2847772+wileyj@users.noreply.github.com> Date: Wed, 22 Jan 2025 12:28:51 -0800 Subject: [PATCH 3/6] Update reference/keywords.md Co-authored-by: Brice --- reference/keywords.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/keywords.md b/reference/keywords.md index d53b9e7821..2403363104 100644 --- a/reference/keywords.md +++ b/reference/keywords.md @@ -12,7 +12,7 @@ Introduced in: Clarity 1 **description:** -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`. +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:** From ae1995686ee5e83e4d4946849efc9b4ad6d9b794 Mon Sep 17 00:00:00 2001 From: wileyj <2847772+wileyj@users.noreply.github.com> Date: Wed, 22 Jan 2025 12:30:30 -0800 Subject: [PATCH 4/6] re-add missing newlines --- reference/functions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reference/functions.md b/reference/functions.md index 3cc9d65a0e..d8c506d7c9 100644 --- a/reference/functions.md +++ b/reference/functions.md @@ -1255,7 +1255,9 @@ In Clarity 3, `get-block-info?` is removed. In its place, `get-stacks-block-info **example:** ``` -(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) +(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) ``` ## get-burn-block-info?​ From c309da96717d1a581c8646851e8091d64cb7aa7b Mon Sep 17 00:00:00 2001 From: wileyj <2847772+wileyj@users.noreply.github.com> Date: Wed, 22 Jan 2025 12:34:12 -0800 Subject: [PATCH 5/6] removed warnings that are no longer needed --- reference/functions.md | 2 +- reference/keywords.md | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/reference/functions.md b/reference/functions.md index d8c506d7c9..94336b46ef 100644 --- a/reference/functions.md +++ b/reference/functions.md @@ -1313,7 +1313,7 @@ Introduced in: **Clarity 3** 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`. +- `header-hash`: This property returns a `(buff 32)` value containing the header hash of a Stacks block, given a Stacks chain height. - `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 diff --git a/reference/keywords.md b/reference/keywords.md index 2403363104..4681d29a07 100644 --- a/reference/keywords.md +++ b/reference/keywords.md @@ -189,10 +189,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`** From 54ac603ffbdf59908c43c32c78cfb852d25980e9 Mon Sep 17 00:00:00 2001 From: wileyj <2847772+wileyj@users.noreply.github.com> Date: Thu, 23 Jan 2025 09:19:06 -0800 Subject: [PATCH 6/6] address pr feedback --- reference/functions.md | 2 +- reference/keywords.md | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/reference/functions.md b/reference/functions.md index 94336b46ef..d8c506d7c9 100644 --- a/reference/functions.md +++ b/reference/functions.md @@ -1313,7 +1313,7 @@ Introduced in: **Clarity 3** 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. +- `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 diff --git a/reference/keywords.md b/reference/keywords.md index 4681d29a07..a3c83b877f 100644 --- a/reference/keywords.md +++ b/reference/keywords.md @@ -153,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`**