From c394617aa1a462ea985c91e01bccd69f30a4056b Mon Sep 17 00:00:00 2001 From: Alexander Graebe Date: Mon, 7 Jun 2021 15:30:51 -0700 Subject: [PATCH] feat: add microblocks overview page --- src/common/navigation.yaml | 1 + src/pages/understand-stacks/microblocks.md | 56 +++++++++++++++++++ src/pages/understand-stacks/network.md | 2 +- src/pages/understand-stacks/overview.md | 2 +- .../stacks-blockchain-api.md | 6 +- .../understand-stacks/technical-specs.md | 2 +- src/pages/understand-stacks/transactions.md | 6 +- 7 files changed, 62 insertions(+), 13 deletions(-) create mode 100644 src/pages/understand-stacks/microblocks.md diff --git a/src/common/navigation.yaml b/src/common/navigation.yaml index c634da1a..ba1945dc 100644 --- a/src/common/navigation.yaml +++ b/src/common/navigation.yaml @@ -9,6 +9,7 @@ sections: - path: /regtest - path: /proof-of-transfer - path: /mining + - path: /microblocks - path: /accounts - path: /transactions - path: /network diff --git a/src/pages/understand-stacks/microblocks.md b/src/pages/understand-stacks/microblocks.md new file mode 100644 index 00000000..825882b2 --- /dev/null +++ b/src/pages/understand-stacks/microblocks.md @@ -0,0 +1,56 @@ +--- +title: Microblocks +description: Guide to Stacks Microblocks +icon: TestnetIcon +images: + large: /images/pages/testnet.svg + sm: /images/pages/testnet-sm.svg +--- + +## Introduction + +Microblocks represent a protocol-level feature that focuses on solving one technical difficulty: latency of transaction confirmations. + +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. + +## Transaction states + +![microblocks states](/images/microblock-states.png) + +TODO: Describe the flow diagram + +## Tradeoffs + +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. + +## 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). + +> Stacks miners have to enable microblock mining. Lern more on the [Mining overview])(/understand-stacks/mining#microblocks). + +## Tooling support + +### Stacks.js libraries + +TODO: Setting the anchor mode + +https://stacks-js-git-master-blockstack.vercel.app/enums/transactions.anchormode.html + +### API + +!> API support for microblocks is current being worked on. The details are subject to changes. + +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. + +## Best practices + +### Handling nonces + +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. + +### Dapps design guidelines + +Microblock states should be cerfully communicated to end users. We are working on dapp design guidelines for developers. Stay tuned! diff --git a/src/pages/understand-stacks/network.md b/src/pages/understand-stacks/network.md index a5170069..e8545422 100644 --- a/src/pages/understand-stacks/network.md +++ b/src/pages/understand-stacks/network.md @@ -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/transactions#anchor-mode). +> Transactions can also be mined in microblocks, reducing the latency significantly. Learn more [here](/understand-stacks/microblocks). 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/overview.md b/src/pages/understand-stacks/overview.md index b578211f..e5fbb03f 100644 --- a/src/pages/understand-stacks/overview.md +++ b/src/pages/understand-stacks/overview.md @@ -85,7 +85,7 @@ Stacks 2.0 enabled building decentralized apps that are user-owned and avoid cen Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. [@page-reference | grid-small] -| /understand-stacks/accounts, /understand-stacks/transactions, /understand-stacks/network +| /understand-stacks/accounts, /understand-stacks/transactions, /understand-stacks/network, /understand-stacks/microblocks ## Try it out diff --git a/src/pages/understand-stacks/stacks-blockchain-api.md b/src/pages/understand-stacks/stacks-blockchain-api.md index e732203e..1486061d 100644 --- a/src/pages/understand-stacks/stacks-blockchain-api.md +++ b/src/pages/understand-stacks/stacks-blockchain-api.md @@ -300,9 +300,7 @@ This API supports [v1.4.6 of the Rosetta specification](https://www.rosetta-api. ## Microblocks support -!> API support for [microblocks](/understand-stacks/mining#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 change for now. - -The [transaction anchor mode](/understand-stacks/transactions#anchor-mode) defines if a transaction should be included in a microblock. If so, the latency for a transaction to be confirmed can be reduced. +!> 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. The API allows querying the most recently streamed microblocks: @@ -334,8 +332,6 @@ curl 'https://stacks-node-api-microblocks.testnet.stacks.co/extended/v1/microblo } ``` -Microblocks are a trdeoff between finality and latency. The initial confirmation of a transaction inside a microblock does not imply finality. Microblocks are subject to reorganization. Thus, the order of processing for confirmed transactions can change. Only once the microblock was added to an anchor block, finality can be assumed. - ## 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: diff --git a/src/pages/understand-stacks/technical-specs.md b/src/pages/understand-stacks/technical-specs.md index 5f4ffb97..167850dd 100644 --- a/src/pages/understand-stacks/technical-specs.md +++ b/src/pages/understand-stacks/technical-specs.md @@ -61,7 +61,7 @@ description: Summary of technical specifications of Stacks 2.0 1. _originating account_ is the account that creates, _authorizes_ and sends the transaction 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction 3. _sending account_ is the account that identifies who is currently executing the transaction: this can change as a transaction executes via the `as-contract` Clarity function -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming (microblocks), a faster confirmation time is possible. +- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](/understand-stacks/microblocks)), a faster confirmation time is possible. - Two types of authorizations: standard authorization is where originating account is the same as paying account. _Sponsored_ authorization is where originating account and paying account are distinct. For instance, developers or service providers could pay for users to call their smart-contracts. - For sponsored authorization, first a user signs with the originating account and then a sponsor signs with the paying account. - Mempool limit for concurrent pending transactions is 25 per account diff --git a/src/pages/understand-stacks/transactions.md b/src/pages/understand-stacks/transactions.md index c252543d..59393d78 100644 --- a/src/pages/understand-stacks/transactions.md +++ b/src/pages/understand-stacks/transactions.md @@ -53,11 +53,7 @@ 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. If microblock-anchoring is selected, the transaction can be confirmed much quicker that the target block time. However, microblocks can be subject to re-organization, thus changing the order of transaction processing: - -![microblock-states](/images/microblock-states.png) - -If your transaction relies on a state that could be altered by a previous transactions with serious implications, you should carefully evalute if microblock-anchoring should be set. +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. The anchor mode has three options: