From ff89af1ada08d2d8c9bf88a4896b0db3c2568a83 Mon Sep 17 00:00:00 2001 From: Alexander Graebe Date: Fri, 18 Sep 2020 16:20:20 -0700 Subject: [PATCH] docs: updates based on feedback, move pagination to includes --- src/includes/stacks-api-pagination.md | 10 ++ src/pages/stacks-blockchain/accounts.md | 141 +++++++++++++++++++- src/pages/stacks-blockchain/network.md | 41 +++++- src/pages/stacks-blockchain/testnet.md | 4 +- src/pages/stacks-blockchain/transactions.md | 21 ++- 5 files changed, 197 insertions(+), 20 deletions(-) create mode 100644 src/includes/stacks-api-pagination.md diff --git a/src/includes/stacks-api-pagination.md b/src/includes/stacks-api-pagination.md new file mode 100644 index 00000000..11393f0d --- /dev/null +++ b/src/includes/stacks-api-pagination.md @@ -0,0 +1,10 @@ +### Pagination + +To make API responses more compact, lists returned by the API are paginated. For lists, the response body includes: + +- `limit`: the number of list items return per response (max is `200`) +- `offset`: the number of elements to skip (starting from `0`) +- `total`: the number of all available list items +- `results`: the array of list items (length of array is between 0 and the set limit) + +Using the `limit` and `offset` properties, you can paginate through the entire list by increasing the offset by the limit until you reach the end of the list (as indicated by the `total` field). diff --git a/src/pages/stacks-blockchain/accounts.md b/src/pages/stacks-blockchain/accounts.md index 4a00585d..5e690b50 100644 --- a/src/pages/stacks-blockchain/accounts.md +++ b/src/pages/stacks-blockchain/accounts.md @@ -1,6 +1,143 @@ --- -title: Account management -description: Guide to Stacks 2.0 account management +title: Accounts +description: Guide to Stacks 2.0 accounts --- ## Introduction + +Stacks 2.0 accounts are entities that own assets, like Stacks tokens. An account has an address, private key, nonce, and one or more asset balances. + +-> The public-key signature system used for Stacks 2.0 accounts is [Ed25519](https://ed25519.cr.yp.to/). + +## Creation + +When an account is created, a 24-phrase mnemonic is generated. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. + +!> 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): + +```shell +# install CLI globally +sudo npm install -g "https://github.com/blockstack/cli-blockstack#feature/stacks-2.0-tx" + +# 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 +``` + +The `make_keychain` command will create following file: + +```js +{ + "mnemonic": "aaa bbb ccc ddd ...", + "keyInfo": { + "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", + "privateKey": "5a3f1f15245bb3fb...", + "index": 0, + "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1" + } +} +``` + +| Field | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `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.index` | Nonce for the account, starting at 0 | +| `keyInfo.btcAddress` | Corresponding BTC address for the account | + +Note that the new account is instantiated implicitly. There is no need to manually instantiate it on the Stacks 2.0 blockchain. + +-> Addresses are generated by hashing the public key and encoding it with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding) + +## Querying + +### Get STX balance and nonce + +STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_account_info) endpoint: + +```shell +curl 'https://stacks-node-api-latest.argon.blockstack.xyz/v2/accounts/' +``` + +Sample response: + +```js +{ + "balance": "0x0000000000000000002386f26f3f40ec", + "nonce": 17 +} +``` + +-> The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding + +### Get all token balances + +All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_account_balance) endpoint: + +```shell +curl 'https://stacks-node-api-latest.argon.blockstack.xyz/extended/v1/address//balances' +``` + +Sample response: + +```js +{ + "stx": { + "balance": "0", + "total_sent": "0", + "total_received": "0" + }, + "fungible_tokens": {}, + "non_fungible_tokens": {} +} +``` + +### Get all asset events + +All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_account_balance) endpoint: + +```shell +curl 'https://stacks-node-api-latest.argon.blockstack.xyz/extended/v1/address//assets' +``` + +Sample response: + +```js +{ + "limit": 20, + "offset": 0, + "total": 0, + "results": [ + { + "event_index": 5, + "event_type": "non_fungible_token_asset", + "asset": { + "asset_event_type": "transfer", + "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", + "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", + "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", + "value": { + "hex": "0x0100000000000000000000000000000001", + "repr": "u1" + } + } + }, + { + "event_index": 3, + "event_type": "fungible_token_asset", + "asset": { + "asset_event_type": "mint", + "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", + "sender": "", + "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", + "amount": "12" + } + } + ] +} +``` + +-> Read more about [pagination](/stacks-blockchain/transactions#pagination) to iterate through the entire result set of the asset events diff --git a/src/pages/stacks-blockchain/network.md b/src/pages/stacks-blockchain/network.md index 68641e74..f8321734 100644 --- a/src/pages/stacks-blockchain/network.md +++ b/src/pages/stacks-blockchain/network.md @@ -1,6 +1,6 @@ --- -title: Stacks 2.0 network -description: Guide to Stacks 2.0 network concepts, architectures, and implications +title: Network +description: Guide to the Stacks 2.0 network --- ## Introduction @@ -9,12 +9,47 @@ description: Guide to Stacks 2.0 network concepts, architectures, and implicatio Stacks ("STX") are the native tokens on the Stacks 2.0 blockchain. The smallest fraction of a STX is one micro-STX. 1.000.000 micro-STXs make one STX. --> In order to correctly represent micro-STX, a decimal precision of 6 is required. 8 bytes should be allocated to store STX amounts appropriately. +-> STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1.000.000 (decimal precision of 6). ## Fees +- How is the transaction fee calculated? + ## Nonces +Every account carries a nonce property that indicates the number of transactions processed for the given account. Nonces are one-time codes and are by 1 with every transaction. + +Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. + +-> 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. + +## Confirmations + +The Stacks 2.0 network is anchored onto the bitcoin network. The time to mine a block, in order 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: + +```shell +curl 'https://stacks-node-api-latest.argon.blockstack.xyz/extended/v1/info/network_block_times' +``` + +The API will respond with the block time (in seconds) for the testnet and: + +```js +{ + "testnet": { + "target_block_time": 120 + }, + "mainnet": { + "target_block_time": 600 + } +} +``` + +-> The finality of the Stacks 2.0 network matches the bitcoin network finality. + ## Read-only function calls ## Block Height diff --git a/src/pages/stacks-blockchain/testnet.md b/src/pages/stacks-blockchain/testnet.md index 320a044b..4b8c2f81 100644 --- a/src/pages/stacks-blockchain/testnet.md +++ b/src/pages/stacks-blockchain/testnet.md @@ -12,7 +12,7 @@ The Stacks 2.0 testnet is an altenrative blockchain, to be used for testing. It With the completion of the Stacks 2.0 blockchain, a production-ready, stable version will be released as "mainnet". While work for the mainnet is in progress, the testnet reflects the most recent implementation of the Stacks 2.0 blockchain. -## Testnet phases +## Release phases The work towards mainnet is split up into four sequential phases: @@ -21,7 +21,7 @@ The work towards mainnet is split up into four sequential phases: - [ ] **Phase 3:** is the upcoming version that we're anticipating to ship in Q3 2020. This version focus on the PoX basics (miner get rewards, Stackers get BTC distributions, etc). - [ ] **Phase 4** is the fully functional version, that we're intending to ship in Q4 2020. -## Testnet roadmap +## Roadmap Each phase add capabilities to the Stacks 2.0 blockchain: diff --git a/src/pages/stacks-blockchain/transactions.md b/src/pages/stacks-blockchain/transactions.md index 2792e946..fb1694ac 100644 --- a/src/pages/stacks-blockchain/transactions.md +++ b/src/pages/stacks-blockchain/transactions.md @@ -1,5 +1,5 @@ --- -title: Transaction generation +title: Transactions description: Guide to Stacks 2.0 transactions --- @@ -87,13 +87,15 @@ A transaction includes the following information. Multiple-byte fields are encod ## Construction -The easies 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 follow transaction types: +The easies 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: - Stacks token transfer - Smart contract deploy - Smart contract function call --> Note that transaction construction requires setting the network the transaction is for. This can be either mainnet or testnet. At the moment of this writing, the only available option is the testnet network. Learn more about it [here](/stacks-blockchain/testnet). +When constructing transactions, it is requireq 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). + +-> Transactions can be constructed and serialized offline. Internet access is only required to broadcast the transaction to the network. ### Stacks Token transfer @@ -114,6 +116,8 @@ const txOptions = { const transaction = await makeSTXTokenTransfer(txOptions); ``` +-> Read more about [nonces](http://localhost:3000/stacks-blockchain/network#nonces) in the network guide + ### Smart contract deployment ```js @@ -365,16 +369,7 @@ For convenience, a Postman Collection was created and published: [![Run in Postm -> Note: The API can be easily consumed using a generated [JS client library](https://blockstack.github.io/stacks-blockchain-api/client/index.html). The generator uses an OpenAPI specification and supports other languages and frameworks. -### Pagination - -To make API responses more compact, lists returned by the API are paginated. For lists, the response body includes: - -- `limit`: the number of list items return per response (max is `200`) -- `offset`: the number of elements to skip (starting from `0`) -- `total`: the number of all available list items -- `results`: the array of list items (length of array is between 0 and the set limit) - -Using the `limit` and `offset` properties, you can paginate through the entire list by increasing the offset by the limit until you reach the end of the list (as indicated by the `total` field). +@include "stacks-api-pagination.md" ### Filter