Merge pull request #324 from hirosystems/release/next

.github/workflows/ci.yml

@@ -12,6 +12,7 @@ on:
     paths-ignore:
       - '**/CHANGELOG.md'
       - '**/.releaserc'
+      - 'docs/**'
   pull_request:
   workflow_dispatch:
 

docs/feature-guides/subnet-participants.md

@@ -0,0 +1,70 @@
+---
+title: Subnet Participants
+---
+
+This guide outlines the potential participants required to run a subnet. The participants are classified into two categories:
+
+- The **primary participants** need to agree on trust parameters and incentives to launch a subnet
+- The **secondary participants** listed here are meant to illustrate different parties involved when using/interacting with a subnet on Stacks
+
+:::note
+
+_Hiro does not intend to participate in running a subnet on Stacks mainnet._
+:::
+
+## Primary Participants
+
+The following are the required entities to run a subnet.
+
+### Miners
+
+- The initial version of subnets uses a Byzantine Fault Tolerance (BFT) consensus mechanism, and the miners are a Federated pool and fully trusted.
+- Miners have arbitrary control over STX deposited on the subnets. A minimum of three miners will be required for the subnet’s BFT consensus to materialize and support a 2n/3 majority
+- Miners are motivated by subnet transaction fees. The supporting applications and the use case will set the subnet fees
+- Miners will require specific hardware/software to validate and process subnet transactions. Miners may include the supporting application, use case, and facilitator or none of these
+
+To understand the resource recommendation for miner, refer to the [miner resource recommendation document](https://github.com/hirosystems/stacks-subnets/blob/develop/docs/miner-resource-recommendation.md)
+
+**Key Activities**
+
+- Miners are responsible for approving and signing transactions and submitting them to the Stacks chain for finality
+- Miners must agree to subnet parameters and incentives. Example: transaction fees, duration, performance requirements
+
+### Supporting Application (Example: NFT Marketplace)
+
+This application supports subnets and owns the user experience. For an NFT use case, the supporting application might be an NFT marketplace. For a DeFi use case, the supporting application might be an exchange, and it may be independent of miners or elect to participate as a miner.
+
+**Key Activities**
+
+- Own user experience for people who want to use a subnet as an application, specifically support connecting a Stacks Wallet to a subnet and minting and trading on a subnet
+- Must agree to subnet parameters and incentives—for example, transaction fees, duration, and performance requirements
+
+### Supporting UseCase (Example: NFT Collection Mint)
+
+- The supporting use case refers to the event that drives people to use a subnet, for example, a mint for a popular NFT collection
+- The supporting use case includes any other parties involved with the use case. In the example above, it could be the artist for a mint collection. The supporting application may be independent of miners
+
+**Key Activities**
+
+Must agree to subnet parameters and incentives—for example, transaction fees, duration, and performance requirements.
+
+## Secondary Participants
+
+These participants use a subnet and do not need to agree to the parameters and incentives of a subnet.
+
+### Wallets
+
+Users interact with applications using wallets, so subnet support is crucial.
+
+**Key Activities**
+
+- Own user experience for people who want to use a subnet via a wallet
+- Deposit of STX from Stacks main chain to a subnet
+- Connect to subnets for mints and transfers
+- Support withdrawals of STX and NFTs from subnet to Stacks main chain
+- Display subnet address balances
+
+### End Users
+
+- Users interact with subnets to experience faster throughput and lower latency for specific use cases (DeFi trades or purchasing or trading NFTs)
+- Users interact primarily with wallets and supporting applications to complete the specific use case (NFT mint)

docs/getting-started.md

@@ -227,9 +227,9 @@ Also, we can see a few default settings that `clarinet` will be using for our su
 # L1 Subnet contract which the subnet will attempt to communicate with
 subnet_contract_id = "ST167FDXCJGS54J1T0J42VTX46G0QQQFRJGBK28RN.subnet-v3-0-1"
 # Docker image of subnet node
-subnet_node_image_url = "hirosystems/stacks-subnets:0.7.0"
+subnet_node_image_url = "hirosystems/stacks-subnets:0.8.1"
 # Docker image of subnet API
-subnet_api_image_url = "hirosystems/stacks-blockchain-api:7.2.0-beta.4"
+subnet_api_image_url = "hirosystems/stacks-blockchain-api:latest"
 ```
 
 ### Launching the Devnet

docs/miner-resource-recommendation.md

@@ -0,0 +1,58 @@
+---
+title: Miner Resource Recommendation
+---
+
+# Miner Resource Recommendation
+
+These are our suggested miner resource requirements to spin up a Subnet Miner.
+
+## Features
+
+- Higher CPU speed results in higher throughput and lower latency
+- Higher RAM will lead to faster transaction validation and faster blocks
+- An additional layer on Stacks warrants more disk space to accommodate the additional subnets’ blocks and microblocks
+
+## What problem does it solve?
+
+The specifications below help you increase the transaction throughput by 4X times and reduce the block confirmation time from 10 minutes to 1 minute.
+
+## Virtual Machine Specifications
+
+We assume a [Debian](https://www.debian.org/) host with `x86_64` architecture for the following example. Note that the commands may also work on any Debian-derived distribution. You can run your machine on Google Compute Engine(GCE) and choose the specifications below.
+
+:::note
+
+_Bitcoin chainstate is approximately 529 GB, and Stacks chainstate is approximately 84 GB._
+
+:::
+
+- Run on GCE n2-standard-4 (4 vCPUs, greater than or equal to 16 GB memory) instances with 2048 GB SSD
+- Annual cost is approximately $1100 per year
+- Minimum CPU greater than or equal to 4 vCPUs
+- Minimum memory greater than or equal to 16 GB Memory
+- Minimum storage is 2 TB Disk to allow chainstate growth
+
+## Hardware Specifications
+
+The following are the hardware specifications for running a subnet on the mainnet.
+
+### CPU
+
+- Processing speed greater than or equal to 2.8 GHz
+- CPU greater than or equal to 4 vCPUs
+
+### RAM
+
+The minimum size of the RAM is 16 GB.
+
+### Disk
+
+- NVMe-based Solid State Drive(SSD) storage: You can use local SSDs through Small Computer System Interface(SCSI). For higher performance in production settings, we recommend upgrading to NVMe interfaces:
+- high TBW (Total Bytes Written)
+- greater than or equal to 3.4 GB per second sequential read and sequential write performance
+- greater than or equal to 1 TB to allow for chainstate growth
+
+### Networking
+
+- Preferred 1 GBit/s
+- Minimum: 300 MBit/s symmetric, commercial