🛠️
Stacks Documentation
  • Start Here
  • đź§ Concepts
    • Stacks 101
      • What Is Stacks?
      • Bitcoin Connection
      • Proof of Transfer
      • Stacks Among Other Layers
      • Financial Incentive and Security Budget
    • Network Fundamentals
      • Network Basics
      • Mainnet and Testnets
      • Accounts
      • Authentication
      • Bitcoin Name System
      • SIPs
      • Technical Specifications
    • Block Production
      • Mining
      • Signing
      • Bitcoin Finality
      • Bitcoin Reorgs
      • Stacking
    • Transactions
      • How Transactions Work
      • Post Conditions
    • Clarity
      • Overview
      • Decidability
    • sBTC
      • Core Features
      • sBTC Operations
        • Deposit
        • Withdrawal
        • Deposit vs Withdrawal Times
      • Emily API
      • Peg Wallet UTXO
      • Clarity Contracts
        • sBTC Registry
        • sBTC Token
        • sBTC Deposit
        • sBTC Withdrawal
      • Auxiliary Features
        • Transaction Fee Sponsorship
        • Signer Wallet Rotation
      • Walkthroughs
        • Signer Process Walkthrough
        • sBTC Transaction Walkthrough
      • sBTC FAQ
    • Gaia
      • Configuration
      • Deploy Gaia Hub
      • Amazon EC2
      • Linux
      • Mac OS
  • 🛠️Guides & Tutorials
    • Developer Quickstart
    • Clarity Crash Course
    • Build a Borrowing & Lending Protocol
    • Bitcoin Integration
      • Sending Bitcoin with Leather Wallet
      • Verifying a Bitcoin Transaction
      • Parsing a Bitcoin Transaction
    • Create Tokens
      • Creating a NFT
      • Creating a Fungible Token
    • Build a Frontend
      • Post Conditions with Stacks.js
      • Authentication with Stacks.js
      • Sending Transactions with Stacks.js
    • Testing Smart Contracts
      • Fuzz Testing
    • Run a Node
      • Run a Node with Docker
      • Run a Node with Digital Ocean
      • Run a Node with a Hosted Provider
      • Run a Node with Quicknode
      • Run a Bitcoin Node
      • Run a Pruned Bitcoin Node
    • Run a Miner
      • Miner Prerequisites
      • Miner Costs and Fees
      • Mine Testnet Stacks Tokens
      • Mine Mainnet Stacks Tokens
      • Verify Miner
    • Run a Signer
      • Signer Quickstart
      • How to Read Signer Logs
      • How to Monitor a Signer
      • Best practices for running a Signer
      • OpSec Best Practices
    • sBTC
      • How to Run an sBTC Signer
      • Best practices for running an sBTC Signer
      • How to Use the sBTC Bridge
      • Earn sBTC Rewards
    • Stack STX
      • Solo Stack
      • Operate a Pool
      • Stack with a Pool
      • Increase Stacked Position
      • Stop Stacking
    • Oracles
    • Community Tutorials
  • 📚Reference
    • API
    • Clarity Types
    • Clarity Functions
    • Clarity Keywords
    • Stacks Node Configuration
    • Signer Configuration
    • Stacks Tooling
  • 🏗️Example Contracts
    • Audited Starter Contracts
    • Stacking
    • BNS
    • Multi Send
  • 🧡Press & Top Links
    • đź”¶2024
      • 🔸January 2024
      • 🔸February 2024
      • 🔸March 2024
      • 🔸April 2024
      • 🔸May 2024
      • 🔸June 2024
      • 🔸July 2024
      • 🔸August 2024
      • 🔸September 2024
      • 🔸October 2024
      • 🔸November 2024
      • 🔸December 2024
    • đź”¶2025
      • 🔸January 2025
      • 🔸February 2025
      • 🔸March 2025
      • 🔸April 2025
      • 🔸May 2025
  • 🧡Bitcoin Theses and Reports
    • đźź Bitcoin Theses
    • đź“™Bitcoin Reports
  • Contribute
Powered by GitBook
On this page
  • block-height​
  • burn-block-height​
  • chain-id​
  • contract-caller​
  • false​
  • is-in-mainnet​
  • is-in-regtest​
  • none​
  • stacks-block-height
  • stx-liquid-supply​
  • tenure-height
  • true​
  • tx-sender​
  • tx-sponsor?​

Was this helpful?

  1. Reference

Clarity Keywords

PreviousClarity FunctionsNextStacks Node Configuration

Last updated 3 months ago

Was this helpful?

block-height​

The Nakamoto hard fork will introduce a few new Clarity keywords. It's important to note that even with the new , the block-height keyword behavior will not change. It will simply correspond to the current tenure height. This means any Clarity contracts using this keyword will be backwards compatible after the Nakamoto Upgrade.

Introduced in: Clarity 1

output: uint

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.

example:

(> block-height u1000) ;; returns true if the current block-height has passed 1000 blocks.

burn-block-height​

There is a bug in Clarity 3 when burn-block-height is used within an at-block expression. Normally, keywords executed within an at-block expression will return the data for that specified block. This bug causes burn-block-height to always return the burn block at the current chain tip, even within an at-block expression. This behavior affects any Clarity 3 contracts and will be fixed in a future hard fork.

Introduced in: Clarity 1

output: uint

description:

Returns the current block height of the underlying burn blockchain as a uint

example:

(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks.

chain-id​

Introduced in: Clarity 2

output: uint

description:

Returns the 32-bit chain ID of the blockchain running this transaction

example:

(print chain-id) ;; Will print 'u1' if the code is running on mainnet, and 'u2147483648' on testnet, and other values on different chains.

contract-caller​

Introduced in: Clarity 1

output: principal

description:

Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If contract-call? was used to invoke a function from a new contract, contract-caller changes to the calling contract's principal. If as-contract is used to change the tx-sender context, contract-caller also changes to the same contract principal.

example:

(print contract-caller) ;; Will print out a Stacks address of the transaction sender

false​

Introduced in: Clarity 1

output: bool

description:

Boolean false constant.

example:

(and true false) ;; Evaluates to false
(or false true)  ;; Evaluates to true

is-in-mainnet​

Introduced in: Clarity 2

output: bool

description:

Returns a boolean indicating whether or not the code is running on the mainnet

example:

(print is-in-mainnet) ;; Will print 'true' if the code is running on the mainnet

is-in-regtest​

Introduced in: Clarity 1

output: bool

description:

Returns whether or not the code is running in a regression test

example:

(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test

none​

Introduced in: Clarity 1

output: (optional ?)

description:

Represents the none option indicating no value for a given optional (analogous to a null value).

example:

(define-public (only-if-positive (a int))
  (if (> a 0)
      (some a)
      none))
(only-if-positive 4) ;; Returns (some 4)
(only-if-positive (- 3)) ;; Returns none
(print stx-liquid-supply) ;; Will print out the total number of liqui

stacks-block-height

Introduced in: Clarity 3

output: uint

description:

Returns the current Stacks block height.

example:

(print stacks-block-height) ;; Will print out the current Stacks block height

stx-liquid-supply​

Introduced in: Clarity 1

output: uint

description:

Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block.

example:

(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX

tenure-height

Introduced in: Clarity 3

output: uint

description:

Returns the number of tenures that have passed. When the Nakamoto block-processing starts, this will be equal to the chain length.

example:

(print tenure-height) ;; Will print out the current tenure height

true​

Introduced in: Clarity 1

output: bool

description:

Boolean true constant.

example:

(and true false) ;; Evaluates to false
(or false true)  ;; Evaluates to true

tx-sender​

Introduced in: Clarity 1

output: principal

description:

Returns the original sender of the current transaction, or if as-contract was called to modify the sending context, it returns that contract principal.

example:

(print tx-sender) ;; Will print out a Stacks address of the transaction sender

tx-sponsor?​

Introduced in: Clarity 2

output: optional principal

description:

Returns the sponsor of the current transaction if there is a sponsor, otherwise returns None.

example:

(print tx-sponsor?) ;; Will print out an optional value containing the Stacks address of the transaction sponsor

Use caution when leveraging all contract calls, particularly tx-sender and contract-caller as based on the design, you can unintentionally introduce attack surface area. .

Use caution when leveraging all contract calls, particularly tx-sender and contract-caller as based on the design, you can unintentionally introduce attack surface area. .

📚
block production mechanism
Read more
Read more