description: Overview and guides for getting started building decentralized applications.
images:
large: /images/pages/build-an-app.svg
sm: /images/pages/build-an-app-sm.svg
large: /images/pages/build-apps.svg
sm: /images/pages/build-apps-sm.svg
---
## Introduction
@ -29,7 +29,7 @@ host, their users’ data. This protects users against security breaches and kee
### Smart contracts
Decentralized apps can use [smart contracts](/smart-contracts/overview) to make their backend logic public, open, and
Decentralized apps can use [smart contracts](/write-smart-contracts/overview) to make their backend logic public, open, and
permissionless. Once published on the blockchain, no one really owns or controls a smart contract. They will execute when
the terms are met, regardless of who interacts with it.
@ -41,7 +41,7 @@ other apps without requiring permission or fear of being shut out.
## Getting started
To build your decentralized app, you’ll use [authentication](/authentication/overview), [data storage](/data-storage/overview),
[data indexing](/data-storage/indexing-overview) (optional), and [smart contracts](/smart-contracts/overview) (optional).
[data indexing](/data-storage/indexing-overview) (optional), and [smart contracts](/write-smart-contracts/overview) (optional).
Get started with the documentation and tutorials below.
### Authentication and data storage
@ -72,16 +72,16 @@ You can use smart contracts to decentralize your app’s backend logic, making i
on the Stacks blockchain are written in the [Clarity language](https://clarity-lang.org). View the smart contracts documentation or get started with a tutorial.
@ -40,6 +40,8 @@ When workin locally with the site, a few things are needed:
- [`node` + `npm`,](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and [`yarn` installed](https://yarnpkg.com/getting-started/install) on your machine.
- Some kind of code editor, such as VSCode, Sublime, or WebStorm.
-> This project requires at least Node version 12
### Working with GitHub
All of the code for this site is open source, located at the [GitHub repository here](https://github.com/blockstack/docs.blockstack).
@ -132,7 +134,7 @@ If you are adding a new route, you have to add your route to a section contained
Start a node that will join and stream blocks from the public krypton testnet, powered by Blockstack via [Proof of Transfer](https://docs.blockstack.org/stacks-blockchain/overview#proof-of-transfer-pox).
Start a node that will join and stream blocks from the public krypton testnet, powered by Blockstack via [Proof of Transfer](/understand-stacks/overview#proof-of-transfer-pox).
Make sure you've followed the [Running testnet node](/stacks-blockchain/running-testnet-node) tutorial. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet.
Make sure you've followed the [Running testnet node](/understand-stacks/running-testnet-node) tutorial. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet.
[@page-reference | inline]
| /stacks-blockchain/running-testnet-node
| /understand-stacks/running-testnet-node
If you want to learn more about the technical details of minig, please review the mining guide:
[@page-reference | inline]
| /stacks-blockchain/mining
| /understand-stacks/mining
## Running bitcoind locally
@ -164,7 +164,7 @@ For a full reference of subcommands and configuration options used by `stacks-no
To read more about the technical details of mining on the Stacks 2.0 network, have a look at the minig guide:
Make sure you've followed the [Running the testnet node on Windows](stacks-blockchain/running-testnet-node#running-the-testnet-node-on-windows) tutorial before starting this tutorial.
Make sure you've followed the [Running the testnet node on Windows](understand-stacks/running-testnet-node#running-the-testnet-node-on-windows) tutorial before starting this tutorial.
### Generate keychain and get testnet tokens in Windows
@ -10,13 +10,13 @@ Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An a
If you want to jump right in to generate and query a new account, try this tutorial:
[@page-reference | inline]
| /stacks-blockchain/managing-accounts
| /understand-stacks/managing-accounts
-> The public-key signature system used for Stacks 2.0 accounts is [Ed25519](https://ed25519.cr.yp.to/).
Assets cannot leave an account without an action from the account owner. All changes to assets (and the balances of the account) require a corresponding transaction.
-> The [transaction type](/stacks-blockchain/transactions#types) doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account
-> The [transaction type](/understand-stacks/transactions#types) doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account
| `mnemonic` | A 24-word seed phrase used to access the account, generated using [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) with 256 bits of entropy |
| `keyInfo.address` | Stacks address for the account |
| `keyInfo.privateKey` | Private key for the account. Required for [token transfers](/stacks-blockchain/transactions#stacks-token-transfer) and often referred to as `senderKey` |
| `keyInfo.privateKey` | Private key for the account. Required for [token transfers](/understand-stacks/transactions#stacks-token-transfer) and often referred to as `senderKey` |
| `keyInfo.index` | Nonce for the account, starting at 0 |
| `keyInfo.btcAddress` | Corresponding BTC address for the account. A construct from the previous blockchain (Stacks 1.0) and currently unused. |
@ -110,7 +110,7 @@ npx -q stacks-gen sk --testnet
}
```
-> The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](/stacks-blockchain/stacking#bitcoin-address).
-> The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](/understand-stacks/stacking#bitcoin-address).
Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen).
@ -204,4 +204,4 @@ Sample response:
}
```
-> Read more about [pagination](/stacks-blockchain/transactions#pagination) to iterate through the entire result set of the asset events
-> Read more about [pagination](/understand-stacks/transactions#pagination) to iterate through the entire result set of the asset events
@ -29,7 +29,7 @@ This tutorial highlights the following functionality:
## Requirements
First, you'll need to understand the [Stacking mechanism](/stacks-blockchain/stacking).
First, you'll need to understand the [Stacking mechanism](/understand-stacks/stacking).
You'll also need [NodeJS](https://nodejs.org/en/download/) `8.12.0` or higher to complete this tutorial. You can verify your installation by opening up your terminal and run the following command:
@ -39,7 +39,7 @@ node --version
## Overview
In this tutorial, we'll implement the Stacking flow laid out in the [Stacking guide](/stacks-blockchain/stacking#stacking-flow).
In this tutorial, we'll implement the Stacking flow laid out in the [Stacking guide](/understand-stacks/stacking#stacking-flow).
-> Check out the sample source code for this tutorial in this GitHub repository: [stacking-integration-sample](https://github.com/agraebe/stacking-integration-sample)
-> Review the [accounts guide](/stacks-blockchain/accounts) for more details
-> Review the [accounts guide](/understand-stacks/accounts) for more details
## Step 3: Display stacking info
@ -234,7 +234,7 @@ unlockingAt.setSeconds(
At this point, your app shows Stacking details. If Stacking is executed and the user has enough funds, the user should be asked to provide input for the amount of microstacks to lockup and a bitcoin address to be used to pay out rewards.
-> The sample code used assumes usage of the bitcoin address associated with the Stacks account. You can replace this with an address provided by the users or read from your database. Read more about the [bitcoin address format](/stacks-blockchain/stacking#bitcoin-address).
-> The sample code used assumes usage of the bitcoin address associated with the Stacks account. You can replace this with an address provided by the users or read from your database. Read more about the [bitcoin address format](/understand-stacks/stacking#bitcoin-address).
With this input, and the data from previous steps, we can determine the eligibility for the next reward cycle:
-> More details on the lifecycle of transactions can be found in the [transactions guide](/stacks-blockchain/transactions#lifecycle)
-> More details on the lifecycle of transactions can be found in the [transactions guide](/understand-stacks/transactions#lifecycle)
Alternatively to the polling, the Stacks Blockchain API client library offers WebSockets. WebSockets can be used to subscribe to specific updates, like transaction status changes. Here is an example:
@ -20,7 +20,7 @@ This tutorial will walk you through the following steps:
- Reviewing account history
- Getting account balances
-> This tutorial is NodeJS-specific. If you would like to understand how to manage Stacks 2.0 accounts using a different language/framework, please [review the accounts guide](/stacks-blockchain/accounts).
-> This tutorial is NodeJS-specific. If you would like to understand how to manage Stacks 2.0 accounts using a different language/framework, please [review the accounts guide](/understand-stacks/accounts).
@ -11,7 +11,7 @@ STX amounts should be stored as integers (8 bytes long), and represent the amoun
## Fees
Fees are used to incentivize miners to confirm transactions on the Stacks 2.0 blockchain. The fee is calculated based on the estimate fee rate and the size of the [raw transaction](http://localhost:3000/stacks-blockchain/transactions#serialization) in bytes. The fee rate is a market determined variable. For the [testnet](/stacks-blockchain/testnet), it is set to 1 micro-STX.
Fees are used to incentivize miners to confirm transactions on the Stacks 2.0 blockchain. The fee is calculated based on the estimate fee rate and the size of the [raw transaction](http://localhost:3000/understand-stacks/transactions#serialization) in bytes. The fee rate is a market determined variable. For the [testnet](/understand-stacks/testnet), it is set to 1 micro-STX.
Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_fee_transfer) endpoint:
@ -41,7 +41,7 @@ Nonces are added to all transactions and help identify them in order to ensure t
-> The consensus mechanism also ensures that transactions aren't "replayed" in two ways. First, nodes query its unspent transaction outputs (UTXOs) in order to satisfy their spending conditions in a new transaction. Second, messages sent between nodes review sequence numbers.
When a new [token transfer transaction](/stacks-blockchain/transactions#stacks-token-transfer) is constructed, the most recent nonce of the account needs to fetched and set.
When a new [token transfer transaction](/understand-stacks/transactions#stacks-token-transfer) is constructed, the most recent nonce of the account needs to fetched and set.
## Confirmations
@ -49,7 +49,7 @@ The Stacks 2.0 network is anchored onto the bitcoin network. This allows transac
The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes.
The block time is hardcoded and will change throughout the implementation phases of the [testnet](/stacks-blockchain/testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_network_block_times) endpoint:
The block time is hardcoded and will change throughout the implementation phases of the [testnet](/understand-stacks/testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_network_block_times) endpoint:
@ -96,7 +96,7 @@ Sample response for a successful call:
}
```
-> To set the function call arguments and read the result, [Clarity values](http://localhost:3000/stacks-blockchain/transactions#clarity-value-types) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/blockstack/stacks.js/tree/master/packages/transactions) library supports these operations
-> To set the function call arguments and read the result, [Clarity values](http://localhost:3000/understand-stacks/transactions#clarity-value-types) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/blockstack/stacks.js/tree/master/packages/transactions) library supports these operations
## Querying
@ -147,7 +147,7 @@ The easiest way of identifying the health is by looking at the `blockRateStatus`
| `1` | Slow. The network produces new blocks at slower rate as expected. Transaction confirmation times will likely take longer than the [set block time](/stacks-blockchain/network#confirmations) |
| `1` | Slow. The network produces new blocks at slower rate as expected. Transaction confirmation times will likely take longer than the [set block time](/understand-stacks/network#confirmations) |
| `2` | Degraded. The network seems not to be fully operational |
A high-level summary of various technical aspects of the Stacks 2.0 blockchain can be found below in the [Technical Specifications](/stacks-blockchain/technical-specs).
A high-level summary of various technical aspects of the Stacks 2.0 blockchain can be found below in the [Technical Specifications](/understand-stacks/technical-specs).
### Clarity Smart Contracts
@ -48,18 +52,18 @@ Smart contracts on the Stacks 2.0 blockchain are written in a new programming la
-> The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and Algorand.
[@page-reference | inline]
| /smart-contracts/overview
| /write-smart-contracts/overview
### Stacks Mining
Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions and participate in the consensus mechanism of the Stacks 2.0 blockchain, called Proof of Transfer (PoX). To incentivize mining, miners receive freshly minted Stacks (STX) tokens.
[@page-reference | inline]
| /mining
| /start-mining
### Proof of Transfer (PoX)
[Proof of Transfer (PoX)](/stacks-blockchain/proof-of-transfer) is a novel consensus mechanism that leverages the security and stability of Bitcoin to create a new blockchain, without modifying the Bitcoin protocol.
[Proof of Transfer (PoX)](/understand-stacks/proof-of-transfer) is a novel consensus mechanism that leverages the security and stability of Bitcoin to create a new blockchain, without modifying the Bitcoin protocol.
Stacks (STX) miners transfer Bitcoin to other Stacks (STX) holders in order to mine blocks. This BTC reward mechanism is called **Stacking**.
Consensus algorithms for public blockchains require computing or financial resources to secure the blockchain. The idea being to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network.
Mining mechanisms used by these algorithms are broadly divided into proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to participate in the [consensus algorithm](/stacks-blockchain/stacking#stacking-consensus-algorithm).
Mining mechanisms used by these algorithms are broadly divided into proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to participate in the [consensus algorithm](/understand-stacks/stacking#stacking-consensus-algorithm).
A variant of proof-of-work is proof-of-burn where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources.
@ -21,7 +21,7 @@ This tutorial walks you through the following steps:
- Checking transaction completion
- Confirming updates account balances (optional)
-> This tutorial is NodeJS-specific. If you would like to understand how to initiate a token transfer by constructing and broadcasting transactions using a different language/framework, please [review the transactions guide](/stacks-blockchain/transactions).
-> This tutorial is NodeJS-specific. If you would like to understand how to initiate a token transfer by constructing and broadcasting transactions using a different language/framework, please [review the transactions guide](/understand-stacks/transactions).
## Requirements
@ -31,7 +31,7 @@ You will need [NodeJS](https://nodejs.org/en/download/) `8.12.0` or higher to co
node --version
```
You should also complete the [Managing accounts tutorial](/stacks-blockchain/managing-accounts). The following steps assume we have access to an existing Stacks 2.0 account.
You should also complete the [Managing accounts tutorial](/understand-stacks/managing-accounts). The following steps assume we have access to an existing Stacks 2.0 account.
In order to build and sign transactions, you will need a Stacks private key. You can easily generate a new, random Stacks 2.0 sender key (see ["Generating an account" from the previous tutorial](/stacks-blockchain/managing-accounts#step-2-generating-an-account)).
In order to build and sign transactions, you will need a Stacks private key. You can easily generate a new, random Stacks 2.0 sender key (see ["Generating an account" from the previous tutorial](/understand-stacks/managing-accounts#step-2-generating-an-account)).
For this tutorial, we will use an existing Stacks account and instantiate the key object from a private key string:
@ -128,7 +128,7 @@ The generation method will need a few more pieces of information, as specified i
If not specified, the transaction builder will automatically estimate the fee. Estimated fee rate is supplied by a Stacks node so network access is required.
-> Learn more about fees in the [network guide](/stacks-blockchain/network#fees)
-> Learn more about fees in the [network guide](/understand-stacks/network#fees)
Another way to estimate the fee is to use the `estimateTransfer()` function after you have constructed a transaction:
As soon as the `broadcastTransaction` is completed, a transaction ID is returned.
~> Keep in mind that the existence of a transaction ID does not mean the transaction has been successfully processed. Please review the [transaction lifecycle](/stacks-blockchain/transactions#lifecycle) for more details.
~> Keep in mind that the existence of a transaction ID does not mean the transaction has been successfully processed. Please review the [transaction lifecycle](/understand-stacks/transactions#lifecycle) for more details.
### Serializing transactions
@ -219,4 +219,4 @@ For all property formats and details, please review the [API reference](https://
## Step 6: Confirming balance (optional)
Now that the token transfer is confirmed, we can verify the new account balance on the sender address by [following the "Getting account balances" steps from the previous tutorial](/stacks-blockchain/managing-accounts#step-5-getting-account-balances).
Now that the token transfer is confirmed, we can verify the new account balance on the sender address by [following the "Getting account balances" steps from the previous tutorial](/understand-stacks/managing-accounts#step-5-getting-account-balances).
@ -13,7 +13,7 @@ Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuabl
Stacking is a built-in action, required by the "proof-of-transfer" (PoX) mechanism. The PoX mechanism is executed by every miner on the Stacks 2.0 network.
-> The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](/smart-contracts/overview). [Read more about the contract](#stacking-contract).
-> The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](/write-smart-contracts/overview). [Read more about the contract](#stacking-contract).
## Stacking flow
@ -33,7 +33,7 @@ The Stacking mechanism can be presented as a flow of actions:
If you would like to implement this flow in your own wallet, exchange, or any other application, please have a look at this tutorial:
[@page-reference | inline]
| /stacks-blockchain/integrate-stacking
| /understand-stacks/integrate-stacking
## PoX mining
@ -49,7 +49,7 @@ Miners have to run a software (mining client, aka "miner") on their machines to
- Assembly: The elected miner writes the new block and collects rewards in form of new Stacks (STX) tokens
@ -7,7 +7,7 @@ description: Summary of technical specifications of Stacks 2.0
- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-007-stacking-consensus.md)
- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-001-burn-election.md) after 10 years. More details [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-001-burn-election.md).
- For more details, see [Proof of Transfer](/stacks-blockchain/proof-of-transfer).
- For more details, see [Proof of Transfer](/understand-stacks/proof-of-transfer).
## Proof of Transfer Mining
@ -21,7 +21,7 @@ description: Summary of technical specifications of Stacks 2.0
- Reward maturity window: 100 blocks, meaning leaders will earn the coinbase reward 100 blocks after the block they successfully mine.
- Block interval: Stacks blockchain produces blocks at the same rate as the underlying burnchain. For Bitcoin, this is approximately every 10 minutes.
- For more details, see [Mining](/stacks-blockchain/mining).
- For more details, see [Mining](/understand-stacks/mining).
## Stacking
@ -31,8 +31,8 @@ description: Summary of technical specifications of Stacks 2.0
- Two reward addresses / block, for a total of 4000 addresses every reward cycle. The addresses are chosen using a VRF (verifiable random function), so each node can deterministically arrive at the same reward addresses for a given block.
- Stacking threshold: 0.025% of the participating amount of STX when participation is between 25% and 100% and when participation is below 25%, the threshold level is always 0.00625 of the liquid supply of STX.
- Delegation: An STX address can designate another address to participate in Stacking on its behalf. [Relevant section in SIP-007](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-007-stacking-consensus.md#stacker-delegation).
- Pooling: STX holders that individually do not meet the Stacking threshold can pool together their holdings to participate in Stacking. To do this, STX holders must set the (optional) reward address to the "delegate address". For more details, see [this reference](https://docs.blockstack.org/references/stacking-contract#delegate-stx).
- Further reading: [Stacking](/stacks-blockchain/stacking)
- Pooling: STX holders that individually do not meet the Stacking threshold can pool together their holdings to participate in Stacking. To do this, STX holders must set the (optional) reward address to the "delegate address". For more details, see [this reference](/references/stacking-contract#delegate-stx).
- Further reading: [Stacking](/understand-stacks/stacking)
## Accounts and Addresses
@ -43,11 +43,11 @@ description: Summary of technical specifications of Stacks 2.0
- Nonce counts number of times an account has authorized a transaction. Starts at 0, valid authorization must include the _next_ nonce value.
- Assets are a map of all asset types -- STX, any on-chain assets specified by a Clarity contract (e.g. NFTs) -- to quantities owned by that account.
- Accounts need not be explicit "created" or registered; all accounts implicitly exist and are instantiated on first-use.
- Further reading: [Accounts](/stacks-blockchain/accounts)
- Further reading: [Accounts](/understand-stacks/accounts)
- Only standard accounts (not contracts) can pay transaction fees.
- Transaction execution is governed by 3 accounts (may or may not be distinct)
1. _originating account_ is the account that creates, _authorizes_ and sends the transaction
@ -55,6 +55,6 @@ description: Summary of technical specifications of Stacks 2.0
3. _sending account_ is the account that identifies who is currently executing the transaction: this can change as a transaction executes via the `as-contract` Clarity function
- Two types of authorizations: standard authorization is where originating account is the same as paying account. _Sponsored_ authorization is where originating account and paying account are distinct. For instance, developers or service providers could pay for users to call their smart-contracts.
- For sponsored authorization, first a user signs with the originating account and then a sponsor signs with the paying account.
- Transaction encoding is described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-encoding) and [here](/stacks-blockchain/transactions#encoding)
- Transaction signing and verification are described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) and [here](/stacks-blockchain/transactions.md#signature-and-verification)
- Further reading: [Transactions](/stacks-blockchain/transactions)
- Transaction encoding is described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-encoding) and [here](/understand-stacks/transactions#encoding)
- Transaction signing and verification are described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) and [here](/understand-stacks/transactions.md#signature-and-verification)
- Further reading: [Transactions](/understand-stacks/transactions)
@ -5,12 +5,12 @@ description: Guide to Stacks 2.0 transactions
## Introduction
Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](/stacks-blockchain/accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions.
Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](/understand-stacks/accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions.
If you want to jump right in and broadcast your first transaction, try this tutorial:
[@page-reference | inline]
| /stacks-blockchain/sending-tokens
| /understand-stacks/sending-tokens
-> The information on this page is based on a design proposal. You can find more conceptual details in this document: [SIP 005: Blocks, Transaction, Accounts](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md).
@ -45,7 +45,7 @@ The Stacks 2.0 supports a set of different transaction types:
A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://blockstack.github.io/stacks-blockchain-api/#operation/get_transaction_by_id).
~> Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](/stacks-blockchain/network#read-only-function-calls).
~> Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](/understand-stacks/network#read-only-function-calls).
## Post-conditions
@ -57,12 +57,12 @@ Post-conditions are meant to be added by the user (or by the user's wallet softw
Each transaction includes a field that describes zero or more post-conditions that must all be true when the transaction finishes running. A post-condition includes the following information:
| [Principal](/smart-contracts/principals) | `SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE` | Sender of the transaction, can be a Stacks address or a contract |
| Asset name | `STX` | Asset to apply conditions to (could be Stacks, fungible, or non-fungible tokens) |
| Comparator | `>=` | Compare operation to be applied (could define "how much" or "whether or not") |
| Literal | `1000000` | Integer or boolean value used to compare instances of the asset against via the condition |
| [Principal](/write-smart-contracts/principals) | `SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE` | Sender of the transaction, can be a Stacks address or a contract |
| Asset name | `STX` | Asset to apply conditions to (could be Stacks, fungible, or non-fungible tokens) |
| Comparator | `>=` | Compare operation to be applied (could define "how much" or "whether or not") |
| Literal | `1000000` | Integer or boolean value used to compare instances of the asset against via the condition |
### Evaluation modes
@ -99,7 +99,7 @@ The easiest way to construct well-formed transactions is by [using the Stacks Tr
- Smart contract deploy
- Smart contract function call
When constructing transactions, it is required to set the network the transaction is intended for. This can be either mainnet or testnet. At the moment of this writing, the only available option is the [testnet network](/stacks-blockchain/testnet).
When constructing transactions, it is required to set the network the transaction is intended for. This can be either mainnet or testnet. At the moment of this writing, the only available option is the [testnet network](/understand-stacks/testnet).
-> Transactions can be constructed and serialized offline. However, it is required to know the nonce and estimated fees ahead of time. Once internet access is available, the transaction can be broadcasted to the network. Keep in mind that the nonce and fee might change during offline activity, making the transaction invalid.
@ -31,14 +31,14 @@ By the end of this tutorial, you will...
The Stacks 2.0 blockchain is currently in development and could experience resets and downtimes. To make sure you're not running into any challenges related to the status of the network, please open up the [Status Checker](http://status.test-blockstack.com/)
and confirm that all systems are operational. If some systems seem to have issues, it is best to wait until they are back up before you proceed with the next steps.
Furthermore, the to-do app will interact with a smart contract deployed as `ST1234....todo-registry`. he contract source code is available at [github](https://github.com/friedger/blockstack-todos/blob/tut/step1/contracts/todo-registry.clar). There might be already a deployed version available on testnet. You can use the testnet explorer to search for it. Alternatively, You have to deploy the contract as described in the [hello world tutorial](/smart-contracts/hello-world-tutorial#step-5-deploy-the-contract). Then you have to use the corresponding contract address and name in this tutorial. Throughout this tutorial, we use `ST3YPJ6BBCZCMH71TV8BK50YC6QJTWEGCNDFWEQ15.todo-registry` as an example.
Furthermore, the to-do app will interact with a smart contract deployed as `ST1234....todo-registry`. The contract source code is available at [github](https://github.com/friedger/blockstack-todos/blob/tut/step1/contracts/todo-registry.clar). There may already be a deployed version available on the testnet; the [testnet explorer](https://testnet-explorer.blockstack.org/) can be used to search for it. Alternatively, the contract can be deployed as described in the [hello world tutorial](/smart-contracts/hello-world-tutorial#step-5-deploy-the-contract). Then you have to use the corresponding contract address and name in this tutorial. Throughout this tutorial, we use `ST3YPJ6BBCZCMH71TV8BK50YC6QJTWEGCNDFWEQ15.todo-registry` as an example.
### Tutorials
You should have followed the instructions of the to-do app tutorial. You should have the code ready on your local machine. It is also helpful to have a basic understanding of Clarity as explained in the counter tutorial. If you are using mocknet or a new, empty testnet you can create transactions following the tutorial about signing transactions.
It is a simple button that calls `doContractCall` method of the Connect library when clicked. The method makes an api call to the Stacks authenticator. The authenticator creates a contract call transaction that is signed by the user and then it is broadcasted to the Stacks 2.0 blockchain as explained in the [transaction signing tutorial](/smart-contracts/signing-transactions).
It is a simple button that calls `doContractCall` method of the Connect library when clicked. The method makes an api call to the Stacks authenticator. The authenticator creates a contract call transaction that is signed by the user and then it is broadcasted to the Stacks 2.0 blockchain as explained in the [transaction signing tutorial](/write-smart-contracts/signing-transactions).
Note how the arguments are created using `bufferCVFromString`. There are similar methods for all other Clarity types, like `uintCV` or `trueCV`. See the [documentation](https://github.com/blockstack/stacks-transactions-js#constructing-clarity-values) of the stacks-transactions library for more details.
@ -451,7 +451,7 @@ In addition to `tx_result`, the transaction object also contains a timestamp (`b
## Fetch the first to-do list
There are two other ways to get state information from the blockchain: read-only functions and data map entries. Read-only functions were already discussed in the [Clarity counter tutorial](/smart-contracts/counter-tutorial). They do not require a transaction to complete. Data maps in Clarity are maps that can be read by any user. See the [Clarity reference](https://docs.blockstack.org/references/language-functions#define-map) for more details.
There are two other ways to get state information from the blockchain: read-only functions and data map entries. Read-only functions were already discussed in the [Clarity counter tutorial](/write-smart-contracts/counter-tutorial). They do not require a transaction to complete. Data maps in Clarity are maps that can be read by any user. See the [Clarity reference](/references/language-functions#define-map) for more details.
The `todo-registry` contract defines a read-only function `owner-of?` that returns the owner of a registry entry and a data map for details about entries:
@ -5,25 +5,16 @@ description: Learn how to deal with Clarity Values in JavaScript.
## Introduction
The Clarity language makes use of a strong static [type system](https://docs.blockstack.org/references/language-clarity#clarity-type-system). This simply means that every function defined in Clarity expects arguments of specific types, and that a failure to provide properly typed arguments will result in your code failing to compile, or your contract call transactions failing prior to execution.
The Clarity language makes use of a strong static [type system](/references/language-clarity#clarity-type-system). This simply means that every function defined in Clarity expects arguments of specific types, and that a failure to provide properly typed arguments will result in your code failing to compile, or your contract call transactions failing prior to execution.
In order to build web applications that interact with Clarity contracts, you will need to learn how to construct and use `ClarityValue` objects. The [@stacks/transactions](https://github.com/blockstack/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below.
## Clarity Types
Values in Clarity can have the following types:
Please see the following page for information on Clarity Types:
- `(tuple (key-name-0 key-type-0) (key-name-1 key-type-1) ...)` - a typed tuple with named fields.
- `(list max-len entry-type)` - a list of maximum length max-len, with entries of type entry-type
- `(response ok-type err-type)` - object used by public functions to commit their changes or abort. May be returned or used by other functions as well, however, only public functions have the commit/abort behavior.
- `(optional some-type)` - an option type for objects that can either be (some value) or none
- `(buff max-len)` - byte buffer or maximum length max-len.
- `(string-ascii max-len)` - ASCII string of maximum length max-len
- `(string-utf8 max-len)` - UTF-8 string of maximum length max-len
- `principal` - object representing a principal (whether a contract principal or standard principal).
- `bool` - boolean value (true or false)
- `int` - signed 128-bit integer
- `uint` - unsigned 128-bit integer
[@page-reference | inline]
| /references/language-types
## Constructing Clarity Values and accessing their data
@ -225,7 +216,7 @@ A Clarity lists underlying data can be accessed via its `list` field.
Now that you know how to construct _and_ deconstruct Clarity values, you can use them to build `contract-call` transactions that call smart contract functions, and you can utilize their responses.
This is covered in depth [here](https://docs.blockstack.org/stacks-blockchain/transactions#construction).
This is covered in depth [here](/understand-stacks/transactions#construction).
## Utilizing Clarity Values from Transaction Responses
CharlieC3
4 years ago
Alexander Graebe
