GITBOOK-8: adding back nakamoto pages

Author: eric-stacks

docs/reference/.gitbook/assets/image (1) (1).png

@@ -89,3 +89,16 @@
 * [RPC API](rpc-api.md)
 * [Stacks Node Configuration](stacks-node-configuration.md)
 * [Signer Configuration](signer-configuration.md)
+
+## Nakamoto Upgrade
+
+* [Nakamoto Upgrade Start Here](nakamoto-upgrade/nakamoto-upgrade-start-here.md)
+* [What is the Nakamoto Release?](nakamoto-upgrade/what-is-the-nakamoto-release.md)
+* [Nakamoto in 10 Minutes](nakamoto-upgrade/nakamoto-in-10-minutes.md)
+* [Nakamoto Rollout Plan](nakamoto-upgrade/nakamoto-rollout-plan/README.md)
+  * [Nakamoto for Stackers](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-stackers.md)
+  * [Nakamoto for Exchanges](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md)
+  * [Nakamoto for Stacking Providers](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-stacking-providers.md)
+  * [Nakamoto for App Developers](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-app-developers.md)
+* [Nakamoto Activation Guide for Signers](nakamoto-upgrade/nakamoto-activation-guide-for-signers.md)
+* [Setting Up a Primary Post Nakamoto Testnet Node](nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md)

docs/reference/.gitbook/assets/image (1).png

@@ -4,7 +4,7 @@ description: Practical guide to testing smart contracts with the Clarinet JS SDK
 
 # Overview
 
-<figure><img src="../.gitbook/assets/image (1).png" alt=""><figcaption><p>source: <a href="https://www.hiro.so/blog/announcing-the-clarinet-sdk-a-javascript-programming-model-for-easy-smart-contract-testing">Hiro blog</a></p></figcaption></figure>
+<figure><img src="../.gitbook/assets/image (1) (1).png" alt=""><figcaption><p>source: <a href="https://www.hiro.so/blog/announcing-the-clarinet-sdk-a-javascript-programming-model-for-easy-smart-contract-testing">Hiro blog</a></p></figcaption></figure>
 
 The Clarinet JS SDK provides a powerful testing framework for Clarity smart contracts. It integrates with Vitest to let you run comprehensive tests against a simulated blockchain environment.
 

docs/reference/.gitbook/assets/image.png

@@ -8,7 +8,7 @@ description: >-
 
 Clarinet is the fastest way to build, test, and deploy smart contracts on the Stacks blockchain. It gives you a local devnet, REPL, testing framework, and debugging tools to ship high-quality Clarity code with confidence.
 
-<div data-with-frame="true"><figure><img src="../.gitbook/assets/image.png" alt=""><figcaption></figcaption></figure></div>
+<div data-with-frame="true"><figure><img src="../.gitbook/assets/image (1).png" alt=""><figcaption></figcaption></figure></div>
 
 ## Key features
 

docs/reference/SUMMARY.md

@@ -0,0 +1,83 @@
+# Nakamoto Activation Guide for Signers
+
+{% hint style="info" %}
+The block for Nakamoto activation has been chosen as Bitcoin block 867,867, which is currently expected on October 28th. This block is subject to change should core developers need additional time for testing or unexpected issues.
+
+Binaries will be provided roughly a week in advance and your normal upgrade procedure should apply here, you’ll want to be running the latest node and Signer software. Note that if you do not upgrade ahead of the hard fork, your nodes will be dropped from the network.
+{% endhint %}
+
+#### Testnet Activation Window (August 19)
+
+This initial phase focuses on testing Signer 3.0 readiness in a testnet environment (Primary Testnet).
+
+{% stepper %}
+{% step %}
+### Update stacks-node
+
+Update stacks-node to version 3.1.0.0.5.
+
+Release link: https://github.com/stacks-network/stacks-core/releases/latest
+{% endstep %}
+
+{% step %}
+### Update signer
+
+Update signer to version 3.1.0.0.5.0.
+
+Release link: https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.5.0
+{% endstep %}
+
+{% step %}
+### Run a Primary Testnet node
+
+Run a Primary Testnet node alongside your Signer.
+{% endstep %}
+
+{% step %}
+### Create a testnet wallet address
+
+Create a testnet wallet address to be used for delegated testing.
+{% endstep %}
+
+{% step %}
+### Submit the provided form
+
+Complete the provided form to register for testnet delegation:
+
+https://blocksurvey.io/signer-nakamoto-activation-upgrade-GrOV5aivQ2.z2fh3bqEyLQ?v=o
+{% endstep %}
+
+{% step %}
+### Await testnet STX delegation
+
+Await testnet STX delegation from the team and participate in testing.
+
+Goals: monitor for issues, implement fixes, and test Signing and Signer hand-off for multiple Epoch 2.5 cycles.
+
+Moving forward, please report any Signer-related bugs, issues or feature requests using the issue template in the stacks-core repo (here)
+{% endstep %}
+{% endstepper %}
+
+#### Mainnet Activation Window (Starting August 28)
+
+Pending successful testnet phases, we will initiate the mainnet activation window.
+
+**Action Required:**
+
+* ALL Mainnet Signers must update to the latest Stacks-Core and Signer binary versions (specifics to be confirmed)
+
+We will test for at least 1.5 Stacking Cycles to ensure stability.
+
+#### Key Points
+
+* Your participation in all phases is crucial
+* Report any issues or unexpected behavior immediately
+* Stay alert for further communications
+
+#### Conclusion
+
+Your dedication to the Stacks network's security and efficiency is invaluable. We appreciate your prompt attention to these critical steps and your ongoing support.
+
+For any questions or concerns, please don't hesitate to reach out.
+
+Thank you for your commitment to the Stacks ecosystem.

docs/reference/clarinet-js-sdk/overview.md

@@ -0,0 +1,57 @@
+# Nakamoto in 10 Minutes
+
+On the previous page, we outlined three primary changes to the way Stacks works that Nakamoto introduces:
+
+* **Fast blocks:** The time taken for a user-submitted transaction to be mined within a block (and thus confirmed) will now take on the order of seconds, instead of tens of minutes. This is achieved by separating block production from cryptographic sortitions -- a winning miner may produce many blocks between two subsequent sortitions.
+* **Bitcoin finality:** Once a transaction is confirmed, reversing it is at least as hard as reversing a Bitcoin transaction. The Stacks blockchain no longer forks on its own.
+* **Bitcoin Miner MEV Resistance:** This proposal alters the sortition algorithm to ensure that Bitcoin miners do not have an advantage as Stacks miners. They must spend competitive amounts of Bitcoin currency to have a chance of earning STX.
+
+Here is a video that covers exactly what happens to a Stacks transaction under Nakamoto rules. In it we cover exactly how Nakamoto achieves Bitcoin finality.
+
+{% embed url="https://www.youtube.com/watch?v=DFBZTSsZUOs" %}
+
+In the rest of this doc, we'll cover some of the key components of Nakamoto in a bit more detail.
+
+### Fast Blocks
+
+One of the most significant changes coming in Nakamoto is how new blocks are produced. Historically, because Stacks blocks have been anchored 1:1 to Bitcoin blocks, slow block times and transaction times have been one of the biggest pain points for Stacks users and developers.
+
+Nakamoto brings significantly faster block times by decoupling Stacks block production from Bitcoin block production. In Nakamoto, new Stacks blocks are produced roughly every 5 seconds.
+
+#### Tenure-Based Block Production
+
+This is achieved via the use of tenure-based block production. Each Bitcoin block introduces a new tenure, in which a single miner cryptographically selected for that tenure is responsible for producing all Stacks blocks.
+
+Rather than single Stacks blocks being tied to a single Bitcoin block, Bitcoin blocks are now tied to a miner tenure, during which they mine several Stacks blocks which settle in around 5 seconds.
+
+But if a single miner is only cryptographically selected for their tenure, and not their produced blocks, what mechanisms exist to ensure the validity of their block production?
+
+#### Stackers
+
+This is where Stackers come in. In pre-Nakamoto Stacks, Stackers were responsible only for locking their STX tokens to contribute to the economic security of the network.
+
+In Nakamoto, Stackers are responsible for validating and approving each block produced during a miner's tenure.
+
+To ensure network consistency, the Stacks protocol commits to the state of the Stacks blockchain with each new Bitcoin block by referencing the first Stacks block produced in the previous tenure. Such a design reinforces the fidelity of transaction data and the synchronization between the two chains. It also links the Stacker’s actions with the actions of miners producing a partnership between the two to create both fast and secure blocks.
+
+As part of this tenure change, Stackers also agree on a last signed block and require the next miner to build off of this, which prevents new Stacks forks. Stacks does not fork on its own and automatically forks with Bitcoin.
+
+This symbiotic relationship between Stackers and miners is what creates the capability for both fast blocks and 100% Bitcoin finality.
+
+This elegant design creates a cooperative relationship between miners and stackers while achieving the best of both worlds with block production and transaction speed and security.
+
+Here is a diagram outlining miner and signer behavior.
+
+<div data-with-frame="true"><figure><img src="../.gitbook/assets/image.png" alt=""><figcaption></figcaption></figure></div>
+
+### Bitcoin MEV Mitigation
+
+Miner Extractable Value (MEV) has been a longstanding issue across many blockchains, including Stacks pre-Nakamoto.
+
+MEV refers to the potential profit miners can extract from the manipulation of transaction inclusion and ordering within the blocks they produce, which can lead to unfair practices and diminished trust in the network.
+
+Specifically in pre-Nakamoto releases of Stacks, Bitcoin miners with a significant percentage of Bitcoin’s hashrate had the ability to censor commitment transactions of other Stacks miners ensuring they were able to win the block rewards and fees of Stacks blocks where they were also the winner of the Bitcoin block as a Bitcoin miner.
+
+The Nakamoto system uses a variation of the Assumed Total Commitment with Carryforward (ATC-C) MEV mitigation strategy described in [this document](https://github.com/stacksgov/sips/blob/main/sips/sip-021/MEV-Report.pdf) to allocate block rewards to miners. The probability a miner will win the block and be granted the current tenure will be based on a function that accounts for the total block commit spend on the blocks leading up to the current block.
+
+The ATC solution leaves the option for a block to have no valid winner. The TenureChange-Extend transaction mitigates the majority of adverse effects caused by a missed block.

docs/reference/clarinet/overview.md

@@ -0,0 +1,45 @@
+# Nakamoto Rollout Plan
+
+{% hint style="info" %}
+Nakamoto has completed step 1 of the rollout (Instantiation). Next, a hard fork that follows an Activation sequence outlined below will make Nakamoto features available to the whole network.
+{% endhint %}
+
+#### Step 1, Step 2: Instantiation & Activation
+
+The rollout will follow this two-step process, each of which is implemented via hard fork.
+
+{% stepper %}
+{% step %}
+### Instantiation
+
+The pox-4 contract and the majority of the Nakamoto code are shipped, but Nakamoto rules are inactive. This is so other aspects of the contract can be tested before layering on the complexity that comes with the testnet (and later mainnet) being dependent on it. Importantly, this phase also allows time for Signers to register without the network being dependent on them to sign blocks.
+{% endstep %}
+
+{% step %}
+### Activation
+
+Once completely rolled out, the full set of Nakamoto features including Signer-based functions, fast blocks, and Bitcoin finality. In other words, ‘the switch is flipped’! This switch is scheduled to occur at Bitcoin Block #867867 (\~October 29th).
+{% endstep %}
+{% endstepper %}
+
+It’s important to note the heaviest lift of any hard fork is historically the sync from genesis. With the two Nakamoto forks, one goal is not to require this, making the upgrade more akin to a push-button software update and much simpler for all node operators.
+
+<details>
+
+<summary><strong>What are ‘Nakamoto Rules’?</strong></summary>
+
+Nakamoto rules are the logic that makes Nakamoto different than the version before it called Stacks 2.4. The key difference is that under Nakamoto, block validation logic requires Signers to sign the blocks to be confirmed as anchor blocks. At Step 1 (Instantiation), this logic, or the ‘Nakamoto Rules’ remains inactive, meaning the network follows the block validation rules of Stacks 2.4. Once the testnet (and later mainnet) reaches Activation, the network switches to running these Nakamoto rules and all the features we’re excited about go live for everybody.
+
+</details>
+
+#### Nakamoto Activation Sequence
+
+<table><thead><tr><th width="106"></th><th width="169">Step</th><th width="319">Overview</th><th>Date/Period</th></tr></thead><tbody><tr><td>✅ A, B</td><td><strong>A</strong>ctivation Window Opens &#x26; <strong>B</strong>inaries Delivered</td><td>Pending no new bugs, final binaries are delivered - this is all the code Signers, Miners, and Node Operators need to run the network.</td><td>Aug 28th</td></tr><tr><td>✅ C</td><td><strong>C</strong>ycle Handoff - Signers</td><td>At the end of Cycle 92, core developers will watch for a successful ‘handoff’, meaning a successful change of the Signer sets between Stacking cycles.</td><td>Cycle 92 to Cycle 93</td></tr><tr><td>✅ D</td><td>First Testnet Hard Fork</td><td>Core developers performed a successful testnet hardfork (on Nakamoto testnet).</td><td>Sept 27</td></tr><tr><td>✅ E</td><td>Determine Hard Fork Block</td><td>Core developers have selected Bitcoin block #867867.</td><td>October 17</td></tr><tr><td>F</td><td>Epoch 3.0 - Nakamoto Rules Start</td><td>Fast blocks, full Bitcoin finality! Nakamoto rules go live on mainnet at hard fork block.</td><td>~October 29</td></tr></tbody></table>
+
+#### Factors that could affect timelines
+
+* **Testing & Audit Results:** A top-notch group of researchers, contractors, and testers, along with security auditors from Clarity Alliance and Quantstamp, continue to hammer away at Nakamoto as they have for the past several months. This testing is ongoing, so there is always the possibility they surface an issue that needs to be addressed before the final hard fork.
+* **Signer Needs:** The ecosystem is proud to have industry leaders comprising its leading Signer network. Signers are a critical new network player so if a clear issue or unexpected need arises during activation, additional time would be taken to address it.
+* **Miner adoption:** As always, miners must choose to adopt the new code. Should they be delayed or experience issues with their setups, it could cause a delay in Activation.
+
+As always, core developers are committed to a safe, secure launch. Several factors could warrant additional time added to the Nakamoto activation sequence outlined above and result in a new hard fork block being selected.

docs/reference/nakamoto-upgrade/nakamoto-activation-guide-for-signers.md

@@ -0,0 +1,49 @@
+# Nakamoto for App Developers
+
+### API Endpoints
+
+* API status
+  * Tesnet: https://api.testnet.hiro.so/extended/
+  * Mainnet: https://api.hiro.so/extended/
+* Burn Block endpoint. This will allow you to get the hashes of fast Stacks blocks as they are added to the chain and see their associated burn blocks.
+  * Testnet: https://api.testnet.hiro.so/extended/v2/burn-blocks
+  * Mainnet: https://api.hiro.so/extended/v2/burn-blocks
+* Pox endpoint. This allows you to get information about proof of transfer, including the currently deployed pox-4 contract. This will be helpful for anyone looking to incorporate stacking into their app.
+  * Testnet: https://api.testnet.hiro.so/v2/pox
+  * Mainnet: https://api.hiro.so/v2/pox
+
+#### PoX-4 Contract
+
+`pox-4.clar` is the stacking contract. If you are interested in experimenting with proof of transfer use cases including state changes, solo stacking, and pool stacking, all the functions you’ll need can be found at the deployed contract:
+
+* Testnet: https://explorer.hiro.so/txid/0xfba7f786fae1953fa56f4e56aeac053575fd48bf72360523366d739e96613da3?chain=testnet
+* Mainnet: https://explorer.hiro.so/txid/0xc6d6e6ec82cabb2d7a9f4b85fcc298778d01186cabaee01685537aca390cdb46?chain=mainnet
+
+#### Signers Voting Contract
+
+After a DKG (Distributed Key Generation) round, signer votes are submitted to this contract. For more on DKG, you can read the Stackers and Signing section of Nakamoto In-Depth:
+
+https://explorer.hiro.so/txid/0x69af1dbed501acdbc0d1c79e1ecbc17e1904edacc15cf4b39d6783e720e21c00?chain=testnet
+
+#### Block Explorer
+
+The explorer will allow you to view fast blocks as they come in. Be sure to turn on “Live updates” to see them coming in in real time.\
+https://explorer.hiro.so/?chain=testnet
+
+#### Local Development Environment
+
+Clarinet has been updated to work with Nakamoto as of version 2.4. That means you can use Clarinet to build locally using Nakamoto rules in your local development environment and use Clarinet and deployment plans to deploy to Nakamoto Testnet.
+
+Be sure to update Clarinet to the newest version: https://docs.hiro.so/clarinet/getting-started
+
+#### Running a signer
+
+If you are interested in running a signer, you can take a look at the How to Run a Signer doc which will get you up to speed on how to get the signer software set up using Nakamoto:
+
+../../guides-and-tutorials/running-a-signer/
+
+#### Office Hours
+
+If you need support or just want to ask questions while experimenting with the Nakamoto Testnet, you can join the weekly office hours with the Stacks' Foundation's Developer Advocate, Kenny Rogers:
+
+https://events.stacks.co/event/HD16484710