export { convertBlockstackCLIUsageToMdx as getStaticProps } from '@common/data/cli-ref'
@ -8,14 +8,14 @@ import { CLIReferenceTable } from '@components/cli-reference'
## Introduction
The command line is intended for developers only. Developers can use the command
line to test and debug Blockstack applications in ways that the Blockstack
Browser does not yet support. Using the command line, developers can:
line to interact with the Stacks Blockchain as well as test and debug Stacks applications
- Generate and Broadcast all supported types of Blockstack transactions
- Make token transfer transactions
- Deploy smart contracts
- Call smart contract functions
- Generate new keychains
- Convert between testnet, mainnet keys
- Load, store, and list data in Gaia hubs
- Generate owner, payment and application keys from a seed phrase
- Query Stacks Nodes
- Implement a minimum viable authentication flow
!> Many of the commands operate on unencrypted private keys. For this reason, **DO NOT** use this tool for day-to-day tasks as you risk the security of your keys.
@ -23,36 +23,12 @@ You must install the command line before you can use the commands.
## How to install the command line
You must have [Node.js](https://nodejs.org/en/download/) v8 or higher (v10 recommended). macOS and Linux users can avoid `sudo` or [permissions problems](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) or by using [`nvm`](https://github.com/nvm-sh/nvm). These instructions assume you are using a macOS or Linux system.
You must have [Node.js](https://nodejs.org/en/download/) v12 or higher (v14 recommended). macOS and Linux users can avoid `sudo` or [permissions problems](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) or by using [`nvm`](https://github.com/nvm-sh/nvm). These instructions assume you are using a macOS or Linux system.
To install the command line, do the following:
### Step 1: [Download or `git clone` the command line repository code](https://github.com/blockstack/cli-blockstack).
Downloading or cloning the repo creates a `cli-blockstack` repository on your system.
### Step 2: Change directory into the `cli-blockstack` directory.
```bash
cd cli-blockstack
```
### Step 3: Install the dependencies with `npm`.
```bash
npm install
```
### Step 4: Build the command line command.
```bash
npm run build
```
### Step 5: Link the command.
```bash
sudo npm link
npm install -g @stacks/cli
```
### Troubleshooting the CLI installation
@ -64,6 +40,6 @@ If you run into `EACCES` permissions errors, try the following:
## List of commands
To see the usage and options for the command in general, enter `blockstack-cli` without any subcommands. To see a list of subcommands enter `blockstack-cli help`. Enter `blockstack-cli SUBCOMMAND_NAME help` to see a subcommand with its usage. The following are the available subcommands:
To see the usage and options for the command in general, enter `stx` without any subcommands. To see a list of subcommands enter `stx help`. Enter `stx SUBCOMMAND_NAME help` to see a subcommand with its usage. The following are the available subcommands:
@ -5,7 +5,7 @@ description: Learn how to set up a wallet via the CLI and send/receive STX on th
## Introduction
This quickstart guide will show you how to setup a Stacks wallet using the Blockstack JavaScript CLI and use it to
This quickstart guide will show you how to setup a Stacks wallet using the Stacks JavaScript CLI and use it to
send/receive Stacks tokens on Testnet. This wallet is intended for developer experimentation with Testnet only, do not use this wallet to store your tokens.
## Prerequisites
@ -14,16 +14,16 @@ You will need to have `npm` installed.
## Installation
To install the Blockstack CLI, run the following command in terminal.
To install the Stacks CLI, run the following command in terminal.
First, we are going to generate a new wallet for Testnet. To generate a wallet use the `make_keychain` command with the `-t` option for Testnet.
```bash
$ blockstack make_keychain -t
$ stx make_keychain -t
{
"mnemonic": "private unhappy random runway boil scissors remove harvest fatigue inherit inquiry still before mountain pet tail mad accuse second milk client rebuild salt chase",
@ -56,7 +56,7 @@ Once the faucet transaction has been broadcasted, you will need to wait for the
Once you’ve requested Testnet Stacks tokens from the faucet, you can check the balance of your account using the following command.
By default, using the `-t` flag causes the CLI to connect to the neon testnet node at `http://neon.blockstack.org:20443`.
By default, using the `-t` flag causes the CLI to connect to the testnet node at `http://testnet-master.blockstack.org:20443`.
To specify a node to connect to, add the `-H` flag followed by the URL of the node `"http://localhost:20443"`. This flag can be used with all commands in this guide.
@ -89,7 +89,7 @@ In order to send tokens, we will need the 5 parameters below.
Once we have the parameters, we can use the `send_tokens` command:
In the world of smart contracts, everything is a blockchain transaction. You use tokens in your wallet to deploy a smart contract in a transaction, and each call to that contract after it's published is a transaction, too. That means that at each step, tokens are being exchanged as transaction fees. This tutorial introduces you to this mode of programming, which transforms blockchains into powerful state machines capable of executing complex logic.
Clarity, Blockstack's smart contracting language, is based on LISP and uses its parenthesized notation. Clarity is an [interpreted language](https://en.wikipedia.org/wiki/Interpreted_language), and [decidable](https://en.wikipedia.org/wiki/Recursive_language). To learn more basics about the language, see the [Introduction to Clarity](overview) topic.
Clarity, the smart contracting language used on the Stacks Blockchain, is based on LISP and uses its parenthesized notation. Clarity is an [interpreted language](https://en.wikipedia.org/wiki/Interpreted_language), and [decidable](https://en.wikipedia.org/wiki/Recursive_language). To learn more basics about the language, see the [Introduction to Clarity](overview) topic.
By the end of this tutorial, you will:
@ -37,11 +37,11 @@ The Stacks 2.0 blockchain is currently in development and could experience reset
### Optional: Install Visual Studio Code with Clarity Extensions
[Visual Studio Code](https://code.visualstudio.com/) (aka VS Code) is a free development interface for which Blockstack has created custom extensions, to make it easier to create smart contracts with Clarity.
[Visual Studio Code](https://code.visualstudio.com/) (aka VS Code) is a free development environment which has Clarity extensions, to make it easier to create smart contracts with Clarity.
[Install Visual Studio Code](https://code.visualstudio.com/download) and install the following extensions for the best coding experience:
- [Clarity](https://marketplace.visualstudio.com/items?itemName=blockstack.clarity), the official language extension by Blockstack that defines the Clarity language for VS Code and provides auto-complete and syntax highlighting.
- [Clarity](https://marketplace.visualstudio.com/items?itemName=blockstack.clarity), the official language extension that defines the Clarity language for VS Code and provides auto-complete and syntax highlighting.
- [clarity-lsp](https://marketplace.visualstudio.com/items?itemName=lgalabru.clarity-lsp), which adds inline help functionality for Clarity to VS Code
- [Rainbow Brackets](https://marketplace.visualstudio.com/items?itemName=2gua.rainbow-brackets), which adds helpful colorization of matching pairs of parentheses while you code
@ -103,7 +103,7 @@ Open up the [Stacks 2.0 Explorer Sandbox view](https://testnet-explorer.blocksta
Here, we will run the code from `hello-world` right in the browser and create blockchain transactions right in the browser.
You will be asked to sign in with or sign up for a Blockstack ID. Your new ID will include a new Stacks address, which is essentially a wallet that holds funds like STX tokens. STX tokens are consumed as fees to register digital assets on the network and to publish/execute smart contracts, among other functions on the network.
You will be asked to sign in with or sign up for a Stacks ID. Your new ID will include a new Stacks address, which is essentially a wallet that holds funds like STX tokens. STX tokens are consumed as fees to register digital assets on the network and to publish/execute smart contracts, among other functions on the network.
All of the following operations will happen on the Testnet. A Testnet is an alternative Stacks 2.0 blockchain, to be used for testing. Testnet STX tokens are separate and distinct from actual STX tokens, and are never supposed to have any value.
@ -175,20 +175,20 @@ With the completion of this tutorial, you now:
## Optional: Get familiar with CLI
The steps above provide an easy way to get started with contract deployment and contract calls. If you want to stay in the terminal and get access to more advanced capabilities, you should use the Blockstack CLI.
The steps above provide an easy way to get started with contract deployment and contract calls. If you want to stay in the terminal and get access to more advanced capabilities, you should use the Stacks CLI.
The following set of commands will achieve the same goals as the above workflow.
Install an early release of the new Blockstack CLI for Stacks 2.0.
Install an early release of the new Stacks CLI for Stacks 2.0.
Create a new Stacks address and save keychain details, using the `-t` flag to target Testnet. The new keychain details will be stored in the file `cli_keychain.json`:
```bash
blockstack make_keychain -t > cli_keychain.json
stx make_keychain -t > cli_keychain.json
```
Review your new Stacks address details.
@ -229,7 +229,7 @@ The response will include a `txId` property. This is the transaction that was in
You need to wait up to a minute for the transaction to complete. After that, you can confirm that your balance increase by 0.5 STX.
With sufficient funds on your account, you can deploy a contract file to Testnet. In this example, we are deploying the `hello-world.clar` contract with the name `hello-world`.
-> To learn more about the Blockstack CLI commands, you can run `blockstack-cli help all`.
-> To learn more about the Stacks CLI commands, you can run `stx help all`.
The command will return a new contract deploy transaction ID. You have to wait up to a minute for the contract to be broadcast to the network. Keep in mind that this operation will increase the `nonce` of your account.
As soon as the contract is deployed, you can call a contract method. In this example, we are calling the `echo-number` function of the previously named `hello-world` contract. The method is defined as `read-only` and will return the result without generating a new transactions.
@ -24,15 +24,15 @@ An account is generated from a 24-word mnemonic phrase. This is often referred t
!> If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase.
The easiest way to generate a new Stacks 2.0 account is to use the [Stacks 2.0 CLI](https://github.com/blockstack/cli-blockstack/tree/feature/stacks-2.0-tx):
The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/blockstack/stacks.js/tree/master/packages/cli):
# generate a new account and store details in a new file
# '-t' option makes this a testnet account
blockstack make_keychain -t > cli_keychain.json
stx make_keychain -t > cli_keychain.json
```
`make_keychain` creates the following file:
@ -63,7 +63,7 @@ Note that a new account automatically exists for each new private key. There is
-> Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/blockstack/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method.
Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/blockstack/stacks-transactions-js) library can be used:
Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/blockstack/stacks.js/tree/master/packages/transactions) library can be used:
-> The API client is generated from the [OpenAPI specification](https://github.com/blockstack/stacks-blockchain-api/blob/master/docs/openapi.yaml) ([openapi-generator](https://github.com/OpenAPITools/openapi-generator)). Many other languages and frameworks are be supported by the generator.
- non read-only contract calls (`estimateContractFunctionCall`)
-> For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/blockstack/stacks-transactions-js/blob/master/src/builders.ts#L97).
-> For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/blockstack/stacks.js/blob/master/packages/transactions/src/builders.ts#L97).
## Nonces
@ -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-transactions-js) library supports these operations
-> 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
-> The API client is generated from the [OpenAPI specification](https://github.com/blockstack/stacks-blockchain-api/blob/master/docs/openapi.yaml) ([openapi-generator](https://github.com/OpenAPITools/openapi-generator)). Many other languages and frameworks are be supported by the generator.
@ -93,7 +93,7 @@ A transaction includes the following information. Multiple-byte fields are encod
## Construction
The easiest way to construct well-formed transactions is by [using the Stacks Transactions JS library](https://github.com/blockstack/stacks-transactions-js#post-conditions). You can construct the following transaction types:
The easiest way to construct well-formed transactions is by [using the Stacks Transactions JS library](https://github.com/blockstack/stacks.js/tree/master/packages/transactions#post-conditions). You can construct the following transaction types:
- Stacks token transfer
- Smart contract deploy
@ -106,7 +106,7 @@ When constructing transactions, it is required to set the network the transactio
### Stacks Token transfer
```js
import { makeSTXTokenTransfer, StacksTestnet } from '@blockstack/stacks-transactions';
import { makeSTXTokenTransfer, StacksTestnet } from '@stacks/transactions';
import { makeContractCall, BufferCV, StacksTestnet } from '@blockstack/stacks-transactions';
import { makeContractCall, BufferCV, StacksTestnet } from '@stacks/transactions';
const BigNum = require('bn.js');
const txOptions = {
@ -268,7 +268,7 @@ In order to broadcast transactions to and between nodes on the network, RLP data
To support an API-friendly and human-readable representation, the [Stacks Blockchain API](/references/stacks-blockchain-api) converts transactions into a JSON format.
=> [The Stacks Transactions JS library](https://github.com/blockstack/stacks-transactions-js) supports serialization of transactions.
=> [The Stacks Transactions JS library](https://github.com/blockstack/stacks.js) supports serialization of transactions.
### Raw format
@ -329,10 +329,10 @@ When called the Stacks Blockchain API or Node RPC API, transactions returned wil
### Deserializing
Serialized, raw transactions can be deserialized without access to the internet using [the Stacks Transactions JS library](https://github.com/blockstack/stacks-transactions-js):
Serialized, raw transactions can be deserialized without access to the internet using [the Stacks Transactions JS library](https://github.com/blockstack/stacks.js/tree/master/packages/transactions):
```js
import { BufferReader, deserializeTransaction } from '@blockstack/stacks-transactions';
import { BufferReader, deserializeTransaction } from '@stacks/transactions';
Ken
4 years ago
Ken Liao