From cd60de329a71b5818b59dc2a931b8a9312d8bde7 Mon Sep 17 00:00:00 2001
From: Alexander Graebe <alex@blockstack.com>
Date: Tue, 10 Nov 2020 00:06:02 +0000
Subject: [PATCH] docs: add mining guide

Fixes blockstack/docs#824
---
 src/common/navigation.yaml            |  1 +
 src/pages/mining.md                   | 11 +++++++
 src/pages/stacks-blockchain/mining.md | 47 +++++++++++++++++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100644 src/pages/stacks-blockchain/mining.md

diff --git a/src/common/navigation.yaml b/src/common/navigation.yaml
index 5e586273..9d68a343 100644
--- a/src/common/navigation.yaml
+++ b/src/common/navigation.yaml
@@ -50,6 +50,7 @@ sections:
           - path: /overview
           - path: /testnet
           - path: /proof-of-transfer
+          - path: /mining
           - path: /accounts
           - path: /transactions
           - path: /network
diff --git a/src/pages/mining.md b/src/pages/mining.md
index 46aa9398..a561c38d 100644
--- a/src/pages/mining.md
+++ b/src/pages/mining.md
@@ -18,6 +18,11 @@ Make sure you've followed the [Running testnet node](/stacks-blockchain/running-
 [@page-reference | inline]
 | /stacks-blockchain/running-testnet-node
 
+If you want to learn more about the technical details of minig, please review the mining guide:
+
+[@page-reference | inline]
+| /stacks-blockchain/mining
+
 ## Running a miner
 
 First, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining.
@@ -115,9 +120,15 @@ cd ../..
 ```
 
 For a full reference of subcommands and configuration options used by `stacks-node`, please see this page.
+
 [@page-reference | inline]
 | /references/stacks-node-configuration
 
+To read more about the technical details of mining on the Stacks 2.0 network, have a look at the minig guide:
+
+[@page-reference | inline]
+| /stacks-blockchain/mining
+
 ### Enable debug logging
 
 In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run:
diff --git a/src/pages/stacks-blockchain/mining.md b/src/pages/stacks-blockchain/mining.md
new file mode 100644
index 00000000..9522fb51
--- /dev/null
+++ b/src/pages/stacks-blockchain/mining.md
@@ -0,0 +1,47 @@
+---
+title: Understand Mining
+description: A guide to mining on Stacks 2.0
+icon: TestnetIcon
+images:
+  large: /images/pages/testnet.svg
+  sm: /images/pages/testnet-sm.svg
+---
+
+## Introduction
+
+This guide highlights some technical details related to minig on the Stacks 2.0 network.
+
+## Mining frequency
+
+A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee.
+
+## Coinbase Rewards
+
+Miners receive coinbase rewards for blocks they mine. These rewards are shared (proportional to the amount committed to) with an user burn support operations that support the block.
+
+The reward amounts are:
+
+- 1000 STX per block are released in the first 4 years of mining
+- 500 STX per block are released during the following 4 years
+- 250 Stacks tokens per block are released during the following 4 years
+- 125 STX per block are released from then on indefinitely.
+
+These "halvings" are synchronized with Bitcoin halvings.
+
+## Transaction fees
+
+Miners receives Stacks fees for transactions mined in any block they produce.
+
+For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees.
+
+## Reward maturity
+
+Miner rewards take 100 blocks to mature.
+
+## Mining with Proof-of-Transfer
+
+Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of Stacking participants. The choice of addresses is done using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the stacks chain.
+
+100,000 Bitcoin blocks **after** mining begins, the PoX sunset phase begins. During this phase, an increasing proportion of the block commit must be burnt. To burn this sunset fee, the miner must send the sunset fee amount to the first output of their block commit transaction (i.e., the OPRETURN output).
+
+400,000 Bitcoin blocks after the sunset phase begins, the sunset phase ends. After this point, PoX is no longer active, and miners must burn all of their leader block commits. They do so by sending Bitcoin to the canonical burn address `1111111111111111111114oLvT2`.