Time seems to be a universal measurement, unchanged even between metric and imperial measuring systems. However, as with many other things in life, Web3 changes how we interact with the world as developers.
For developers, the Epoch Time is a familiar benchmark for where we are, as it represents the seconds passed since January 1, 1970. In order to write complicated time based programs, it is necessary to have an unshifting shared reference point and the Epoch Time does just that. Whether you’re allowing users to create calendar inputs, or setting dates for an email campaign launch, every time setting is a measurement from the beginning of 1970.
Web3 does not base its version of time on seconds passed, but instead focuses on a metric called block height. Block height refers to the number of blocks placed on a blockchain. Just like the Epoch Time date, blockchains have their own anchor point which is often called a Genesis Block. Below, we can see some information on Stacks’s Genesis Block from Stacks Explorer:
Here we see the block height of #1, showing that this is the Genesis Block from which all other blocks will be added. What is interesting with block height as a measurement is that it is not universal between all blockchains. A blockchain built on a Bitcoin Blockchain would not at any point have the same block height as a blockchain built on an Ethereum blockchain as their Genesis blocks were created at different points and the time between their blocks being added is different.
With Clarity we care about the block height of two blockchains. Those blockchains are the Stacks blockchain and its underlying Bitcoin Blockchain. To be able to access those block heights we have two methods, block-height and burn-block-height, that we will dive deeper into below.
Blockchains
Before we talk about block height, let’s have a quick refresher on what a blockchain is, what a block is and look at our important block time measurement. A blockchain is a decentralized database that stores immutable data from different users to create a list of transactions. That is a very loaded sentence so let’s dissect it a little slower.
A decentralized database means that instead of having a single entity, like a bank or company store and control all of the information on the chain, we instead have users agree on what the information is as each block is added to the chain. There is no one central source of truth, but instead a network of users, or nodes, who agree on the current state of the database.
This mechanism, whether proof of work or proof of transfer, ensures that a consensus between users must be met before adding blocks to the blockchain instead of having a single entity decide what is and isn’t. The workings of these mechanisms are beyond the scope of this article, but this is a great video explanation by Stacks Foundation Developer Advocate, Kenny Rogers.
Now that we know what a decentralized database is, let’s talk about immutable data. Immutable data is data that can’t change. The reason it is important for users to agree on block data before a block is added to the blockchain, is that after a block is added the data is final and unchangeable. Once it’s on the chain you can’t alter the data on the block, only update the data on subsequent blocks. This is great for security and integrity as all transactions are final and leave a permanent trail for changes.
The final item to discuss are the transactions. Each block is a container for multiple records. Blockchains act as a ledger which records a number of different actions by different parties. An action we may want to record is, “Alice gives Bob $5.” This is called a transaction and a grouping of transactions is what constitutes a block. Of course with Clarity you can now create smart contracts so your transactions will be more complex than simple money movements.
Block-Height
We’ve talked about Epoch Time, Genesis Blocks and reviewed Blockchains, so now it’s time to talk about Clarity’s different block-height methods. The first, and more common method to use, is block-height. Calling this inside a Clarity smart contract produces a read-only action that looks at the current Stacks Blockchain and returns the number of blocks as an unsigned integer.
What can we use this for? Again, blockchains don’t directly measure time in seconds; instead, they use block height, the number of blocks since the Genesis Block, and block time,the average time between blocks being added to the chain to calculate time. To set actions to be performed at a later time, we need to use both block height and block time to predict when our action will run.
If we have an HOA and want to release funds for maintenance from our homeowners fund on a quarterly basis, then we would look first at the amount of time in a quarter, then divide this by block time to get the number of blocks necessary.
With the required wait time as blocks, we can now use Clarity’s block-height to get the current block-height and add our block number to it to get our target date for release funds.
Clarity’s block-height method is great when we want to interact with the Stacks blockchain, but what if we want to interact with the underlying Bitcoin Blockchain?
Burn-Block-Height
To interact with the Bitcoin Blockchain we need to use a special Clarity method called burn-block-height. Instead of returning the block height of the Stacks blockchain, this returns the height of the Bitcoin Blockchain.
Stacks is different from other smart-contract blockchains such as Ethereum and Solana as it is associated with the Bitcoin Blockchain instead of being the main blockchain. This helps decouple Stacks from Bitcoin as Stacks is not pegged to Bitcoin. This eliminates a lockstep increase and decrease of value between the two chains as Stacks uses Bitcoin more as a reliable storage means and a way to broadcast information further.
When would we use burn-block-height instead of block-height? Because Bitcoin is so widely used, there may be other applications that we would like our Clarity smart contract to look at when functioning. Again, we have to use block height to measure time as each blockchain has its own beginning point and even duration of block time.
If we want our Clarity smart contract to use the Bitcoin time system, then we can set actions to run based off a burn-block-height value or Bitcoin block height instead of the Stacks block height returned by Clarity’s block-height method.
Conclusion
I hope that you now know more about how time is measured on blockchains as well as what the different built in block height methods are for Clarity. There is so much more to learn to be an expert Clarity developer so I encourage you to review the notes below and be curious as you continue to learn as a developer in the Web3 space..
