From 2c7891f5443f221040dc630833036c69afe20e95 Mon Sep 17 00:00:00 2001 From: Patrick Gray Date: Fri, 11 Jun 2021 16:45:24 -0400 Subject: [PATCH] docs: edit and expand microblocks content --- src/pages/understand-stacks/microblocks.md | 81 ++++++++++++++----- src/pages/understand-stacks/mining.md | 13 +-- src/pages/understand-stacks/network.md | 4 +- .../stacks-blockchain-api.md | 8 +- src/pages/understand-stacks/transactions.md | 5 +- 5 files changed, 79 insertions(+), 32 deletions(-) diff --git a/src/pages/understand-stacks/microblocks.md b/src/pages/understand-stacks/microblocks.md index 825882b2..d5070a87 100644 --- a/src/pages/understand-stacks/microblocks.md +++ b/src/pages/understand-stacks/microblocks.md @@ -9,48 +9,89 @@ images: ## Introduction -Microblocks represent a protocol-level feature that focuses on solving one technical difficulty: latency of transaction confirmations. +Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction +latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism][], +Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to +perform state transitions with a high degree of confidence between final settlements against Bitcoin. -The [Proof-of-Transfer consensus mechanism](/understand-stacks/proof-of-transfer) anchors on Bitcoin blocks and is bound by the block production time (~ one block every 10 minutes). with microblocks, the Stack blockchain can continue to build up the chain in between Bitcoin blocks. +Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while +still inheriting the security of Bitcoin. ## Transaction states -![microblocks states](/images/microblock-states.png) +The Stacks block production model is described in [SIP-001][]. The standard outlines the mechanism by which elected +block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. +Microblocks are the product of the streaming model. -TODO: Describe the flow diagram +If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them +into microblocks during the current epoch. Transactions included in microblocks don't achieve finality until they're +included in an anchor block, but can assumed to be highly likely to achieve finality in the order in which the leader +packaged them. -## Tradeoffs +While there is a high degree of confidence that streamed blocks are finalized in the order in which a block leader +selects them, there is still a chance that microblocks can be reorganized in an anchor block. The processing order of +transactions in microblocks can change depending on on how the microblock is finalized in the anchor block. -Just like regular blocks, microblocks can be subject to re-organization. The processing order of transactions in microblocks can change based on how they were ultimately added to an anchor block. - -> If your transaction relies on a state that could be altered by a previous transactions with serious implications, you should carefully evalute if microblocks should be used. +-> If a transaction is dependent on a chain state that could by altered by previous transactions with serious +implications, you should carefully consider whether it should be performed using microblocks. ## Enabling microblocks -Transactions include an option to determin if they should be added to microblocks or regular anchor blocks: the [Anchor Mode](/understand-stacks/transactions#anchor-mode). +Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, you should enable +microblock mining. When an application or user submits a transaction, the transaction can include an argument that +requires the transaction to be in a microblock, an anchor block, or in either. -> Stacks miners have to enable microblock mining. Lern more on the [Mining overview])(/understand-stacks/mining#microblocks). +### Transactions -## Tooling support +Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The +[anchor mode][] transaction option is an optional argument that controls whether a transaction must be included in +an anchor block or a microblock, or is eligible for either. -### Stacks.js libraries +### Mining + +Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more +information, see [mining microblocks][]. + +## Developing with microblocks -TODO: Setting the anchor mode +Stacks allows you to choose how any transaction should be included on the blockchain by the miners. This flexibility +means you can submit transactions that require low latency processing for inclusion in microblocks, and require that +high stakes transactions wait for anchor block finality. -https://stacks-js-git-master-blockstack.vercel.app/enums/transactions.anchormode.html +### Stacks.js libraries + +Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks +preference for transactions. ### API -!> API support for microblocks is current being worked on. The details are subject to changes. +!> API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to +ensure that you are up-to-date on the latest implementation details for microblocks. -The Stacks Blockchain API exposes microblock details through several endpoints. Please review the [Stacks Blockchain API guide](/understand-stacks/stacks-blockchain-api#microblocks-support) for more details. +The Stacks Blockchain API exposes microblocks through several endpoints. Please review the +[Stacks Blockchain API guide][] for more details. ## Best practices -### Handling nonces +Working with microblocks is a design decision that you must make for your own application. When working with +microblocks, the following best practices are recommended. + +### Handling nonce + +Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values +included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API +[provides an endpoint][] to retrieve the next none for a given principal. -Nonce handling is more difficult with microblocks because the next nonce to be used relies on transactions included in microblocks, but potentially not yet mined. The Stacks Blockchain API [provides an endpoint](/stacks-blockchain-api#nonce-handling) to retrieve the possible next nonce. +### Application design -### Dapps design guidelines +The state of microblock transactions should be carefully communicated to users. No transaction is final until it's +included in an anchor block, and your application design should reflect this. -Microblock states should be cerfully communicated to end users. We are working on dapp design guidelines for developers. Stay tuned! +[proof-of-transfer consensus mechanism]: /understand-stacks/proof-of-transfer +[sip-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader +[mining microblocks]: /understand-stacks/mining#microblocks +[anchor mode]: /understand-stacks/transactions#anchor-mode +[anchormode]: https://stacks-js-git-master-blockstack.vercel.app/enums/transactions.anchormode.html +[stacks blockchain api guide]: /understand-stacks/stacks-blockchain-api#microblocks-support +[provides an endpoint]: /stacks-blockchain-api#nonce-handling +[microblocks_api]: https://stacks-blockchain-api-git-feat-microblocks-blockstack.vercel.app/#tag/Microblocks diff --git a/src/pages/understand-stacks/mining.md b/src/pages/understand-stacks/mining.md index 34c0ba2e..7629f4b5 100644 --- a/src/pages/understand-stacks/mining.md +++ b/src/pages/understand-stacks/mining.md @@ -65,12 +65,13 @@ To calculate the amount of BTC to send miners should: ## Microblocks -Unlike most existing blockchains, Stacks blocks are not produced atomically. Instead, leaders may dynamically package transactions into a sequence of microblocks as they are received from users. +The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency +transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions +and include their state transitions in the current epoch. -A leader can "stream" a block over the course of its tenure by selecting transactions from the mempool as they arrive and packaging them into microblocks. These microblocks contain small batches of transactions, which are organized into a hash chain to encode the order in which they were processed. If a leader produces microblocks, then the new chain tip the next leader builds off of will be the last microblock the new leader has seen. +If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the +current leader produces. -The advantage of the streaming approach is that a leader's transaction can be included in a block during the current epoch, reducing latency. +The block streaming model is described in [SIP-001][]. -Whether a transactions should be included in a microbloc can be [defined in the transaction encoding](/understand-stacks/transactions#anchor-mode). - -> More details can be found in [SIP001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). +[sip-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/src/pages/understand-stacks/network.md b/src/pages/understand-stacks/network.md index e8545422..920325dd 100644 --- a/src/pages/understand-stacks/network.md +++ b/src/pages/understand-stacks/network.md @@ -48,7 +48,7 @@ Nonces are added to all transactions and help identify them in order to ensure t 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. -> The API provides an endpoint to [simplify nonce handling](/understand-stacks/stacks-blockchain-api#nonce-handling). +-> The API provides an endpoint to [simplify nonce handling](/understand-stacks/stacks-blockchain-api#nonce-handling). ## Confirmations @@ -56,7 +56,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. -> Transactions can also be mined in microblocks, reducing the latency significantly. Learn more [here](/understand-stacks/microblocks). +-> Transactions can also be mined in [microblocks](/understand-stacks/microblocks), reducing the latency significantly. 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: diff --git a/src/pages/understand-stacks/stacks-blockchain-api.md b/src/pages/understand-stacks/stacks-blockchain-api.md index 1486061d..7e3fe93a 100644 --- a/src/pages/understand-stacks/stacks-blockchain-api.md +++ b/src/pages/understand-stacks/stacks-blockchain-api.md @@ -300,7 +300,8 @@ This API supports [v1.4.6 of the Rosetta specification](https://www.rosetta-api. ## Microblocks support -!> API support for [microblocks](/understand-stacks/microblocks) is current being worked on. New API endpoints are documented [here](https://stacks-blockchain-api-git-feat-microblocks-blockstack.vercel.app/#tag/Microblocks). The details are subject to changes. +!> API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to +ensure that you are up-to-date on the latest implementation details for microblocks. The API allows querying the most recently streamed microblocks: @@ -334,7 +335,8 @@ curl 'https://stacks-node-api-microblocks.testnet.stacks.co/extended/v1/microblo ## Nonce handling -Developer have to keep track of the last nonce used in a transaction. The API provides an endpoint to make nonce handling simpler: +In order to prevent stuck transactions, you must track the next available nonce for principals issuing transactions. The +API provides an endpoint to make nonce handling simpler: ```bash # for mainnet, remove `.testnet` @@ -361,3 +363,5 @@ While Hiro provides a hosted API server of the Stacks Blockchain API, anyone can | /understand-stacks/local-development -> Once started, the API will be available on `localhost:3999` + +[microblocks_api]: https://stacks-blockchain-api-git-feat-microblocks-blockstack.vercel.app/#tag/Microblocks diff --git a/src/pages/understand-stacks/transactions.md b/src/pages/understand-stacks/transactions.md index 59393d78..ae4839cf 100644 --- a/src/pages/understand-stacks/transactions.md +++ b/src/pages/understand-stacks/transactions.md @@ -53,9 +53,10 @@ A sample of each transaction type can be found in the [Stacks Blockchain API res ## Anchor mode -Transactions can be mined either in an anchor block or in a [microblock](/understand-stacks/microblocks). If microblock-anchoring is selected, the transaction can be confirmed much quicker that the target block time. +Transactions can be mined either in an anchor block or in a [microblock](/understand-stacks/microblocks). If microblocks +are selected, the transaction can be confirmed with a lower latency than the anchor block time. -The anchor mode has three options: +The anchor mode enum has three options: - `OnChainOnly` The transaction MUST be included in an anchored block - `OffChainOnly`: The transaction MUST be included in a microblock