https://github.com/hirosystems/stacks-subnets

Stacks Subnets: a layer-2 scaling solution for Stacks, intended for high-throughput, low-latency workloads
https://github.com/hirosystems/stacks-subnets

stacks

Last synced: 8 months ago
JSON representation

Stacks Subnets: a layer-2 scaling solution for Stacks, intended for high-throughput, low-latency workloads

• Host: GitHub
• URL: https://github.com/hirosystems/stacks-subnets
• Owner: hirosystems
• License: gpl-3.0
• Created: 2022-01-11T17:20:49.000Z (over 4 years ago)
• Default Branch: develop
• Last Pushed: 2024-01-27T12:07:02.000Z (over 2 years ago)
• Last Synced: 2025-04-15T21:43:55.870Z (about 1 year ago)
• Topics: stacks
• Language: Rust
• Homepage: http://docs.hiro.so
• Size: 95.2 MB
• Stars: 52
• Watchers: 13
• Forks: 12
• Open Issues: 44
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

          
# Subnets

Subnets are a layer-2 scaling solution in the Stacks blockchain that offers low latency and high throughput workloads. It enables developers to build fast and reliable experiences on Stacks.

## Overview

Subnets are designed to transact on Stacks assets, meaning users can move assets in and out of subnets. While a user’s assets are in a subnet, they trust that subnet’s consensus rules. This subnet will interact with the Stacks chain using a smart contract specific to that subnet.

> **_NOTE:_**

> 

> The current implementation of subnets uses a 2-phase commit protocol amongst a fully-trusted pool of miners.

Below are some of the features of subnets:

- Each subnet may define its throughput settings. The default implementation should support at least 4x high throughput for transactions and may reduce confirmation time from 10 minutes to 1 minute.

- Interacting with a subnet is similar to interacting with a different Stacks network (example: testnet vs. mainnet).

- The Stacks blockchain can support many different subnets.

- Each subnet may use the same or different consensus rules.

- This repository implements a consensus mechanism that uses a two-phase commit among a federated pool of miners.

- To deposit into a subnet, users submit a layer-1 transaction to invoke the deposit method on that subnet's smart contract.

- For withdrawals, users commit the withdrawal on the subnet and then submit a layer-1 transaction to invoke the subnet's smart contract's withdraw method.

## Architecture

This diagram outlines the interaction between a subnet and the Stacks layer-1 chain.

![Architecture of subnets.](/docs/images/subnets-architecture.png)

When a miner proposes a block to the other miners, the other miners must approve and sign the block before it can be committed to the subnet.

![Screenshot of subnet miners proposing and approving the blocks.](/docs/images/subnet-miners.png)

### Trust models in Subnets

The current implementation of subnets uses a federated system of miners. This federation is fully-trusted, but future work on subnets will explore alternative trust models.

In a fully - trusted model:

- Miners are responsible for issuing subnet blocks.

- Users can validate, but subnet miners control withdrawals.

- Trust can be federated with a 2-phase commit and BFT protocol for miner block issuance.

- Federation requires a majority of miners to approve withdrawals.

## Getting Started

You can build subnets using any of the following methods:

- Build with Clarinet

  - You'll build with Clarinet using the NFT use case highlighting the deposit-withdraw features on subnets.

- Build with Testnet

  - You can build with testnet to run your subnets-node.

- Test Locally

  - You can test the deposit and withdrawal of funds in this method.

> **_NOTE:_**

>

> Hyperchains have been renamed "subnets" due to the trademark for "hyperchains" already being registered. Learn more [here](https://www.hiro.so/blog/its-official-hyperchains-are-now-named-subnets).

### Build with Clarinet

You can start building with Clarinet using the instructions noted [here](https://github.com/hirosystems/stacks-subnets/blob/master/NFT_USE_CASE.md#setup). You can run through all the six steps indicated in the Setup section of the [NFT_USE_CASE.md](https://github.com/hirosystems/stacks-subnets/blob/master/NFT_USE_CASE.md) document to finish the deposit and withdrawal of NFT.

### Build with Testnet

You can set up configurations for subnet miners on testnet using the instructions noted [here](https://github.com/hirosystems/stacks-subnets/blob/master/DEPLOYING.md).

### Test locally

You can launch your contracts, deposit funds to your subnets layer and withdraw funds using the instructions noted [here](https://github.com/hirosystems/stacks-subnets/blob/master/LOCAL_TESTING.md).

## Run Tests

In your terminal, you can run tests by navigating to the `testnet/stacks-node/` directory and running the following command:

`cargo test`

If you want to ignore some tests, you can use the following command:

`cargo test -- --ignored --num-threads=1`

## Resources

- [Introductions to subnets.](https://www.youtube.com/watch?v=PFPwuVCGGuI)

- [Introducing Hyperchains by Hiro.](https://www.hiro.so/blog/introducing-hyperchains-by-hiro)

- [An Update on Hyperchains: a Scaling Solution for Stacks.](https://www.hiro.so/blog/an-update-on-hyperchains-a-scaling-solution-for-stacks)

## License information

- Copyright (C) Hiro Systems PBC

- Copyright (C) Stacks Open Internet Foundation, Inc.