From 2b6ade74f579b0cc1c331e041c7bfdb6d7666a47 Mon Sep 17 00:00:00 2001 From: Alexander Graebe Date: Mon, 7 Dec 2020 14:36:21 -0800 Subject: [PATCH] docs: updare content to make this a guide --- src/common/navigation.yaml | 2 +- .../command-line-interface.md | 126 ++++++++++++++++++ src/pages/understand-stacks/using-the-cli.md | 111 --------------- 3 files changed, 127 insertions(+), 112 deletions(-) create mode 100644 src/pages/understand-stacks/command-line-interface.md delete mode 100644 src/pages/understand-stacks/using-the-cli.md diff --git a/src/common/navigation.yaml b/src/common/navigation.yaml index 2065f1c8..260fc0be 100644 --- a/src/common/navigation.yaml +++ b/src/common/navigation.yaml @@ -11,6 +11,7 @@ sections: - path: /transactions - path: /network - path: /stacking + - path: /command-line-interface - path: /local-development - path: /technical-specs - path: /stacks-blockchain-api @@ -36,7 +37,6 @@ sections: - path: /overview - path: /principals - path: /values - - path: /cli-wallet-quickstart sections: - title: Tutorials pages: diff --git a/src/pages/understand-stacks/command-line-interface.md b/src/pages/understand-stacks/command-line-interface.md new file mode 100644 index 00000000..ac68a6fc --- /dev/null +++ b/src/pages/understand-stacks/command-line-interface.md @@ -0,0 +1,126 @@ +--- +title: Understanding the Stacks CLI +description: Learn more about the Stacks CLI capabilities +--- + +The Stacks CLI enables interactions with the Stacks 2.0 blockchain through a set of commands. At the current stage, the CLI is intended for developer experimentation on the testnet only. + +## Installation + +First, ensure tou have `npm` installed. Next, run the following command in your terminal: + +`npm install -g @stacks/cli` + +-> The `-g` flag makes the CLI commands available globally + +## Network selection + +By default, the CLI will attempt to interact with the mainnet of the Stacks 2.0 blockchian. However, it is possible to override the network and set it to the testnet: + +```bash +stx -t +``` + +-> For account usage, that means adresses generated will _only_ be available for the specific network. An account generated for the testnet cannot be used on the mainnet. + +By default, using the `-t` flag causes the CLI to connect to the testnet node at `http://stacks-node-api.blockstack.org:20443`. To specify a node to connect to, add the `-H` flag followed by the URL of the node: + +```bash +stx -H "http://localhost:20443" +``` + +## Account + +This section describes how to use the CLI to manage an account. + +~> It is not recommended to use the CLI to handle accounts with real STX tokens on the mainnet. Using an appropriate wallet build to support secure token holding is recommended. + +### Creating an account + +You can generate a new account for testnet by using the `make_keychain` command with the `-t` option: + +```bash +stx make_keychain -t +``` + +Your response should look like this: + +```json +{ + "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", + "keyInfo": { + "privateKey": "381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301", + "address": "ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ", + "btcAddress": "n4X37UmRZYk9HawtS1w4xRtqJWhByxiz3c", + "index": 0 + } +} +``` + +The mnemonic is your 24 word seed phrase which you should back up securely if you want access to this account again in the future. Once lost, it cannot be recovered. + +The Stacks address associated with the newly generated account is: +`ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ` + +-> This is a testnet address for use with the testnet only + +It is best to store the response of the CLI somewhere. You will need the private key, for instance, to send tokens to others. + +### Checking balance + +You can check the balance of your account using the following command: + +```bash +stx balance ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ -t +``` + +The response will look like this: + +```json +{ + "balance": "10000", + "nonce": 0 +} +``` + +-> To receive testnet STX tokens, please use the faucet [faucet](https://testnet.blockstack.org/faucet) + +Take note that the nonce for the account is `0`. This number is important for transaction broadcasting. + +## Transactions + +This section describes how to use the CLI to generate and broadcast transactions. + +### Sending Tokens + +In order to send tokens, the CLI command requires 5 parameters: + +- **Recipient Address**: The Stacks address of the recipient +- **Amount**: The number of Stacks to send denoted in microstacks (1 STX = 1000000 microstacks) +- **Fee Rate**: The transaction fee rate for this transaction. You can safely set a fee rate of 1 for Testnet +- **Nonce**: The nonce is a number that needs to be incremented monotonically for each transaction from the account. This ensures transactions are not duplicated +- **Private Key**: This is the private key corresponding to your account that was generated when + +The CLI command to use with these parameters is `send_tokens`: + +```bash +$ stx send_tokens ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7 1000 200 0 381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301 -t + +d32de0d66b4a07e0d7eeca320c37a10111c8c703315e79e17df76de6950c622c +``` + +With this command we’re sending 1000 microstacks to the Stacks address `ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7`. + +We set the fee rate to `200` microstacks. If you're not sure how much your transaction will cost. + +-> You can add the `-e` flag to estimate the transaction fee needed to get processed by the network, without broadcasting your transaction. + +The nonce is set to `0` for this transaction, since it will be the first transaction we send from this account. For subsequent transactions, you will need to increment this number by `1` each time. You can check the current nonce for the account using the `balance` command. + +Finally, the last parameter is the private key for the account. `381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301` + +Once again, we’re using the `-t` option to indicate that this is a Testnet transaction, so it should be broadcasted to Testnet. + +If valid, the transaction will be broadcasted to the network and the command will respond with a transaction ID. + +-> To obtain the raw, serialized transaction payload without broadcasting it, you can add the `-x` flag diff --git a/src/pages/understand-stacks/using-the-cli.md b/src/pages/understand-stacks/using-the-cli.md deleted file mode 100644 index 4ce73a9a..00000000 --- a/src/pages/understand-stacks/using-the-cli.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: CLI Wallet quickstart -description: Learn how to set up a wallet via the CLI and send/receive STX on the Testnet. ---- - -## Introduction - -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 - -You will need to have `npm` installed. - -## Installation - -To install the Stacks CLI, run the following command in terminal. - -`npm install -g @stacks/cli` - --> Check out the [Stacks CLI reference](/references/stacks-cli) for more details - -## Creating a Wallet - -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 -$ 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", - "keyInfo": { - "privateKey": "381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301", - "address": "ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ", - "btcAddress": "n4X37UmRZYk9HawtS1w4xRtqJWhByxiz3c", - "index": 0 - } -} -``` - -The mnemonic is your 24 word seed phrase which you should back up securely if you want access to this wallet again in the future. Once lost, it cannot be recovered. - -The Stacks address associated with this wallet is: -`ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ` - -Note that this is a Testnet address for use with Testnet only. You will use this address to receive tokens from the Testnet faucet or other people. - -The private key is what you will need to send tokens later. - -## Getting Tokens - -To receive Testnet Stacks tokens, visit the Testnet stacks token [faucet](https://testnet.blockstack.org/faucet). Enter the Stacks address you generated above into the address field on the faucet page and click "Get STX". - -Once the faucet transaction has been broadcasted, you will need to wait for the balance to be reflected in your account. - -## Checking Balance - -Once you’ve requested Testnet Stacks tokens from the faucet, you can check the balance of your account using the following command. - -```bash -$ stx balance ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ -t - -{ - "balance": "10000", - "nonce": 0 -} -``` - -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. - -Verify that your account has tokens before continuing to the next step to send tokens. - -Take note that the nonce for the account is `0`. We will be using this number in the next step. - -## Sending Tokens - -In order to send tokens, we will need the 5 parameters below. - -**Recipient Address** - The Stacks address of the recipient - -**Amount** - The number of Stacks to send denoted in microstacks (1 STX = 1000000 microstacks) - -**Fee Rate** - The transaction fee rate for this transaction. You can safely set a fee rate of 1 for Testnet. - -**Nonce** - The nonce is a number that needs to be incremented monotonically for each transaction from the account. This ensures transactions are not duplicated. You can get the latest valid nonce for each account using the `balance` command. - -**Private Key** - This is the private key corresponding to your account that was generated when you created the wallet earlier using the CLI. - -Once we have the parameters, we can use the `send_tokens` command: - -```bash -$ stx send_tokens ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7 1000 200 0 381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301 -t - -d32de0d66b4a07e0d7eeca320c37a10111c8c703315e79e17df76de6950c622c -``` - -With this command we’re sending 1000 microstacks to the Stacks address `ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7`. - -We set the fee rate to `200` microstacks. If you're not sure how much your transaction will cost. You can add the `-e` flag to estimate the transaction fee needed to get processed by the network, without broadcasting your transaction. - -The nonce is set to `0` for this transaction, since it will be the first transaction we send from this account. For subsequent transactions, you will need to increment this number by `1` each time. You can check the current nonce for the account using the `balance` command. - -Finally, the last parameter is the private key from earlier. `381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301` - -Once again, we’re using the `-t` option to indicate that this is a Testnet transaction, so it should be broadcasted to Testnet. - -If valid, your transaction will now be broadcasted to the network and you will see the transaction ID displayed on the screen. - -To view the raw transaction without broadcasting, add the `-x` flag to your command.