Stacks 2.0

Reference implementation of the Blockstack Technical Whitepaper in Rust.

Repository

Blockstack Topic/Tech	Where to learn more more
Stacks 2.0	master branch
Stacks 1.0	legacy branch
Use the package	our core docs
Develop a Blockstack App	our developer docs
Use a Blockstack App	our browser docs
Blockstack the company	our website

Design Thesis

Stacks 2.0 is an open-membership replicated state machine produced by the coordination of a non-enumerable set of peers.

To unpack this definition:

• A replicated state machine is two or more copies (“replicas”) of a given set of rules (a “machine”) that, in processing a common input (such as the same sequence of transactions), will arrive at the same configuration (“state”). Bitcoin is a replicated state machine — its state is the set of UTXOs, which each peer has a full copy of, and given a block, all peers will independently calculate the same new UTXO set from the existing one.
• Open-membership means that any host on the Internet can join the blockchain and independently calculate the same full replica as all other peers.
• Non-enumerable means that the set of peers that are producing the blocks don’t know about one another — they don’t know their identities, or even how many exist and are online. They are indistinguishable.

Roadmap

• SIP 001: Burn Election
• SIP 002: Clarity, a language for predictable smart contracts
• SIP 003: Peer Network
• SIP 004: Cryptographic Committment to Materialized Views
• SIP 005: Blocks, Transactions, and Accounts
• SIP 006: Clarity Execution Cost Assessment (Q2 2020)
• SIP 007: Stacking Consensus (Q2 2020)

Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions.

See SIP 000 for more details.

Testnet versions

• Helium is a developer local setup, mono-node, assembling SIP 001, SIP 002, SIP 004 and SIP 005. With this version, developers can not only run Stacks 2.0 on their development machines, but also write, execute, and test smart contracts. See the instructions below for more details.

• Neon is the upcoming version of our public testnet, that we're anticipating will ship in Q2 2020. This testnet will ship with SIP 003, and will be an open-membership public network, where participants will be able to validate and participate in mining testnet blocks.

• Mainnet is the fully functional version, that we're intending to ship in Q3 2020.

Getting started

Download and build stacks-blockchain

The first step is to ensure that you have Rust and the support software installed.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

For building on Windows, follow the rustup installer instructions at https://rustup.rs/

From there, you can clone this repository:

git clone https://github.com/blockstack/stacks-blockchain.git

cd stacks-blockchain

Then build the project:

cargo build

Run the tests:

cargo test testnet  -- --test-threads=1

Encode and sign transactions

Let's start by generating a keypair, that will be used for signing the upcoming transactions:

cargo run --bin blockstack-cli generate-sk --testnet

# Output
# {
#  secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001",
#  publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5",
#  stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH"
# }

We will interact with the following simple contract kv-store. In our examples, we will assume this contract is saved to ./kv-store.clar:

(define-map store ((key (buff 32))) ((value (buff 32))))

(define-public (get-value (key (buff 32)))
    (match (map-get? store {key: key})
        entry (ok (get value entry))
        (err 0)))

(define-public (set-value (key (buff 32)) (value (buff 32)))
    (begin
        (map-set store {key: key} {value: value})
        (ok true)))

We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes.

Our first step is to generate and sign, using your private key, the transaction that will publish the contract kv-store. To do that, we will use the subcommand:

cargo run --bin blockstack-cli publish --help

With the following arguments:

cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 0 kv-store ./kv-store.clar --testnet

The 500 is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 500 bytes.

This command will output the binary format of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial.

cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin

Run the testnet

You can observe the state machine in action locally by running:

cargo testnet start --config=./testnet/stacks-node/Stacks.toml

Stacks.toml is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries:

[[mstx_balance]]
address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT"
amount = 100000000

The address field is the Stacks testnet address, and the amount field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added.

Publish your contract

Assuming that the testnet is running, we can publish our kv-store contract.

In another terminal (or file explorer), you can move the tx1.bin generated earlier, to the mempool:

curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions

In the terminal window running the testnet, you can observe the state machine's reactions.

Reading from / Writing to the contract

Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key foo.

To do that, we will use the subcommand:

cargo run --bin blockstack-cli contract-call --help

With the following arguments:

cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin

contract-call generates and signs a contract-call transaction. Note: the third argument 1 is a nonce, that must be increased monotonically with each new transaction.

We can submit the transaction by moving it to the mempool path:

curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions

Similarly, we can generate a transaction that would be setting the key foo to the value bar:

cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin

And submit it by moving it to the mempool path:

curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions

Finally, we can issue a third transaction, reading the key foo again, for ensuring that the previous transaction has successfully updated the state machine:

cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin

And submit this last transaction by moving it to the mempool path:

curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions

Congratulations, you can now write your own smart contracts with Clarity.

Platform support

Officially supported platforms: Linux 64-bit, MacOS 64-bit, Windows 64-bit.

Platforms with second-tier status (builds are provided but not tested): Linux ARMv7, Linux ARM64.

Community

Beyond this Github project, Blockstack maintains a public forum and an opened Discord channel. In addition, the project maintains a mailing list which sends out community announcements.

The greater Blockstack community regularly hosts in-person meetups. The project's YouTube channel includes videos from some of these meetups, as well as video tutorials to help new users get started and help developers wrap their heads around the system's design.

For help cross-compiling on memory-constrained devices, please see the community supported documentation here: Cross Compiling.

Further Reading

You can learn more by visiting the Blockstack Website and checking out the in-depth articles and documentation:

• How Blockstack Works (white paper)
• Blockstack General FAQ

You can also read peer-reviewed Blockstack papers:

• "Blockstack: A Global Naming and Storage System Secured by Blockchains", Proc. USENIX Annual Technical Conference (ATC '16), June 2016
• "Extending Existing Blockchains with Virtualchain", Distributed Cryptocurrencies and Consensus Ledgers (DCCL '16 workshop, at ACM PODC 2016), July 2016

If you have high-level questions about Blockstack, try searching our forum and start a new question if your question is not answered there.

Contributing

PRs must include test coverage. However, if your PR includes large tests or tests which cannot run in parallel (which is the default operation of the cargo test command), these tests should be decorated with #[ignore]. If you add #[ignore] tests, you should add your branch to the filters for the all_tests job in our circle.yml (or if you are working on net code or marf code, your branch should be named such that it matches the existing filters there).

A test should be marked #[ignore] if:

1. It does not always pass cargo test in a vanilla environment (i.e., it does not need to run with --test-threads 1).
2. Or, it runs for over a minute via a normal cargo test execution (the cargo test command will warn if this is not the case).

Copyright and License

The code and documentation copyright are attributed to blockstack.org for the year of 2020.

This code is released under the GPL v3 license, and the docs are released under the Creative Commons license.