{"id":19291810,"url":"https://github.com/hirosystems/stacks-subnets","last_synced_at":"2025-10-29T20:36:07.438Z","repository":{"id":37084985,"uuid":"446915671","full_name":"hirosystems/stacks-subnets","owner":"hirosystems","description":"Stacks Subnets: a layer-2 scaling solution for Stacks, intended for high-throughput, low-latency workloads","archived":false,"fork":false,"pushed_at":"2024-01-27T12:07:02.000Z","size":99809,"stargazers_count":52,"open_issues_count":44,"forks_count":12,"subscribers_count":13,"default_branch":"develop","last_synced_at":"2025-04-15T21:43:55.870Z","etag":null,"topics":["stacks"],"latest_commit_sha":null,"homepage":"http://docs.hiro.so","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"stacks-network/stacks-blockchain","license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hirosystems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-01-11T17:20:49.000Z","updated_at":"2025-04-02T20:06:43.000Z","dependencies_parsed_at":"2024-01-27T13:26:51.231Z","dependency_job_id":"399a866f-8c41-479c-88c6-56f101266119","html_url":"https://github.com/hirosystems/stacks-subnets","commit_stats":null,"previous_names":[],"tags_count":113,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-subnets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-subnets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-subnets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-subnets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hirosystems","download_url":"https://codeload.github.com/hirosystems/stacks-subnets/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250183245,"owners_count":21388682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["stacks"],"created_at":"2024-11-09T22:27:59.791Z","updated_at":"2025-10-29T20:36:07.358Z","avatar_url":"https://github.com/hirosystems.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Subnets\n\nSubnets 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.\n\n## Overview\n\nSubnets 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.\n\n\u003e **_NOTE:_**\n\u003e \n\u003e The current implementation of subnets uses a 2-phase commit protocol amongst a fully-trusted pool of miners.\n\nBelow are some of the features of subnets:\n\n- 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.\n- Interacting with a subnet is similar to interacting with a different Stacks network (example: testnet vs. mainnet).\n- The Stacks blockchain can support many different subnets.\n- Each subnet may use the same or different consensus rules.\n- This repository implements a consensus mechanism that uses a two-phase commit among a federated pool of miners.\n- To deposit into a subnet, users submit a layer-1 transaction to invoke the deposit method on that subnet's smart contract.\n- 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.\n\n## Architecture\n\nThis diagram outlines the interaction between a subnet and the Stacks layer-1 chain.\n\n![Architecture of subnets.](/docs/images/subnets-architecture.png)\n\nWhen 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.\n\n![Screenshot of subnet miners proposing and approving the blocks.](/docs/images/subnet-miners.png)\n\n### Trust models in Subnets\n\nThe 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.\n\nIn a fully - trusted model:\n\n- Miners are responsible for issuing subnet blocks.\n- Users can validate, but subnet miners control withdrawals.\n- Trust can be federated with a 2-phase commit and BFT protocol for miner block issuance.\n- Federation requires a majority of miners to approve withdrawals.\n\n\n## Getting Started\n\nYou can build subnets using any of the following methods:\n- Build with Clarinet\n  - You'll build with Clarinet using the NFT use case highlighting the deposit-withdraw features on subnets.\n- Build with Testnet\n  - You can build with testnet to run your subnets-node.\n- Test Locally\n  - You can test the deposit and withdrawal of funds in this method.\n\n\u003e **_NOTE:_**\n\u003e\n\u003e 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).\n\n### Build with Clarinet\n\nYou 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.\n\n### Build with Testnet\n\nYou can set up configurations for subnet miners on testnet using the instructions noted [here](https://github.com/hirosystems/stacks-subnets/blob/master/DEPLOYING.md).\n\n### Test locally\n\nYou 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).\n\n## Run Tests\n\nIn your terminal, you can run tests by navigating to the `testnet/stacks-node/` directory and running the following command:\n\n`cargo test`\n\nIf you want to ignore some tests, you can use the following command:\n\n`cargo test -- --ignored --num-threads=1`\n\n## Resources\n\n- [Introductions to subnets.](https://www.youtube.com/watch?v=PFPwuVCGGuI)\n- [Introducing Hyperchains by Hiro.](https://www.hiro.so/blog/introducing-hyperchains-by-hiro)\n- [An Update on Hyperchains: a Scaling Solution for Stacks.](https://www.hiro.so/blog/an-update-on-hyperchains-a-scaling-solution-for-stacks)\n\n\n## License information\n\n- Copyright (C) Hiro Systems PBC\n- Copyright (C) Stacks Open Internet Foundation, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhirosystems%2Fstacks-subnets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhirosystems%2Fstacks-subnets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhirosystems%2Fstacks-subnets/lists"}