<img src="https://gaia.blockstack.org/hub/1KwTnsTj6Rqm26zRfhJuNdQUG63ieozxbB/photos/8ljPEmYw2LNJlHgobAcV6/A57OAwwU-3TTMxHOyoxsA-FAW1DIFXsAAUahh.png" />Image credit : <a href="https://twitter.com/axopoa" target="_blank">axopoa</a> <a href="https://gist.github.com/jcnelson/edc40f883b9105aac4e04420cc4d536a" target="_blank">Blockchains don't scale</a>. The fact that all nodes process all transactions means that the blockchain only goes as fast as the slowest node allowed on the network. If that's something like a Raspberry Pi, then that's as fast as the blockchain goes.And that's okay! The upside is that the more people can run nodes, the more resilient the blockchain will be. It's much harder to break a 10,000-node blockchain where most nodes run on home computers all across the world than a 10,000-node blockchain where most nodes run in a few datacenters.But the demand for cheap transactions isn't going anywhere. What's a distributed systems hacker to do?<h3>A Composite Blockchain</h3>A single blockchain can't handle unbound transaction volumes, but many blockchains can. Just like how the world's most expensive high-powered mainframe cannot match the capacity of a cloud made out of cheap servers, a single high-powered blockchain cannot match the combined capacity of a linked network of many small blockchains. This is especially true if adding new blockchains to the network is a permissionless act, since this would let the network grow with user demand.Enter appchains. The PoX consensus algorithm in Stacks lets it use the hashpower of Bitcoin to securely host its chain structure. With a couple modifications, it also allows on instance of the Stacks blockchain to use another instance of the Stacks blockchain to host its chain structure as well! PoX generalizes: many, many L1 blockchains may run at varying degress of separation between themselves and Bitcoin, but Bitcoin will commit to the chain structures of all of them.So, now the world looks like this at each Bitcoin block:<img src="https://gaia.blockstack.org/hub/1KwTnsTj6Rqm26zRfhJuNdQUG63ieozxbB/photos/8ljPEmYw2LNJlHgobAcV6/RprYyy-9G3fl3M6qlMGKb-Screenshot 2021-09-28 at 12.35.32.png" />Each time a Bitcoin block is mined, it causes a Stacks block to be mined. Now, each time a Stacks block is mined, it causes one or more appchain blocks to get mined, which in turn can trigger their own subsequent appchain blocks to be mined.The appchain approach makes Stacks a composite blockchain. You can add more capacity to the Stacks blockchain by adding more appchains. Instantiating an appchain is just a matter of deploying a specially-crafted smart contract that can store the relevant mining state. Just as with Stacks and Bitcoin, each appchain's blocks are hashed to a single transaction in the host chain, so to host chain nodes, mining an appchain just looks like doing a particular contract-call? transaction.App chains are classified by degress of separation from Bitcoin. This is the number of host chains between the chain and Bitcoin. For Stacks, this is 1 -- Bitcoin is its host chain. For appchains mining on Stacks, this is 2 -- appchain state is separated from Bitcoin by two blockchains. For appchains running on those appchains, this is 3, and so on and so forth. However, because each host chain contains the hashes of its client chains' blocks, it still ends up being the case that Bitcoin commits to the state of all appchains, everywhere.The reason this scales is because the host chain doesn't need to know or care about the state of its client chains (just like how Bitcoin doesn't know or care about Stacks). Only the people who want to use your smart contracts need to run nodes for your appchain; everyone else can ignore it entirely.<h3>When to use Appchains</h3>Appchains are one of several possible scalability solutions for Stacks being developed, but they are some trade-offs. If you're a developer, you'd use an appchain if all of the following are true:<ul><li>Your app has its own token that is distinct from STX.</li><li>Your smart contract(s) don't need to interact with many other different smart contracts.</li><li>Users need lots of block capacity to use your smart contracts, and/or need to send lots of transactions.</li></ul>If these are all true, then it might make sense for you to start your own appchain. Your appchain will be instantiated with your smart contracts built-in, and it will have its own distinct token separate from STX. Your appchain will have its own miners, who will send transactions on the host chain to mine blocks in your appchain and in doing so, earn a block reward in your appchain's token.Because appchains are simply instances of Stacks, they come with all the features Stacks currently has. In particular:<ul><li>Your appchain comes with its own PoX, its own cost-voting, and its own BNS pre-installed.</li><li>Your users can Stack your appchain's token and earn a yield in STX (or whatever token powers the host chain).</li><li>You can choose your own PoX parameters and block capacity limits.</li></ul>In addition, appchains have the following new features enabled by mining on Stacks as a host chain:<ul><li>You're free to make any changes to the appchain consensus rules without affecting Stacks (or whatever host chain).</li><li>You can implement your own rules on who gets to mine and under what circumstances via the mining contract on the host chain. If you can write them in Clarity, you can make them apply to your appchain.</li></ul><h3>Limitations</h3>Because appchains are independently mined from their host chains, the security budget for resisting a reorg is dependent on how much miners of that appchain are willing to spend to keep the chain safe. This budget is going to be less than the budget for Stacks, which in turn is less than the budget for Bitcoin. However, the set of blocks that exist in your appchain across all its forks (even non-canonical ones) is secured by the host chain's security budget. So even if your appchain gets reorged, it would be temporary, since the old canonical fork is still visible in the host chain.App chain P2P messages and transactions are made non-replayable on other networks by a 4-byte chain ID field. However, there is currently no convention or means of forcing all appchains to have globally-unique chain IDs. Someone could clone your appchain and use its chain ID, thereby making your chain's transactions replayable on their network. This will need to be solved later by a dedicated appchain registry smart contract, which will first need to be spec'ed out and ratified via the SIP process. We're still in the very early days!I don't know off the top of my head if the distinct chain ID makes it impossible to use a hardware wallet at this time. I'd imagine that adding support would be trivial, though.<h3>Setting Up an Appchain</h3>The code for this is currently in a feature branch on the Stacks blockchain. You can build a copy yourself as follows: <code>$ git clone https://github.com/blockstack/stacks-blockchain appchains $ cd appchains $ git checkout feat/app-chain-mvp $ cd testnet/stacks-node</code><code> </code><code>$ cargo build --release</code>First, you'll need to deploy a Stacks mainnet or testnet node from this feature branch (depending on where you want to run your appchain). I highly recommend using only testnet for now. This step is required because the new Stacks node software includes RPC endpoints that appchains need, such as querying Stacks headers and data var state.After you have that running, you will need to create a mining contract for your appchain. The mining contract has a few required <code>define-data-var</code> and <code>define-data-map</code> definitions that will be needed for the appchain to query it and boot up, in addition to having a few required <code>define-public</code> functions. I've reproduced the one I'm testing with <a href="https://gist.github.com/jcnelson/bb67cdd6b3c6ea0f5f447b33dee0425e" target="_blank">here</a>, with source comments. Feel free to adapt to your needs. Note in particular that the mining contract has a way to list the bootstrap nodes for your appchain.Once the contract is deployed, you'll need to spin up a boot node for your appchain at the IP and port listed in the mining contract. To do so, you'll first need to figure out the contract's address, as well as the appchain's genesis hash.Let's say the contract address is <code>ST17ABWV76GQCGWKFQR4G5N23HDXGZ3D3869A8Z5N.appchains-mvp-v1</code>. You will want to add that to your config file as follows: <code>[burnchain] chain = "stacks" mining_contract = "ST17ABWV76GQCGWKFQR4G5N23HDXGZ3D3869A8Z5N.appchains-mvp-v1" # since the address is a testnet address, you'll also want this: mode = "testnet" # Fill this in with the mainchain Stacks node you deployed earlier peer_host = "44.199.104.134" rpc_port = 30443 peer_port = 30444 </code> To get the genesis hash, you run the following: <code>$ stacks-node appchain-genesis --config /path/to/your/config.toml Appchain genesis state instantiated in /tmp/appchain-genesis-1632538390 Appchain genesis hash: a32a3ff4b42a3d87d771396ca5ffab850afbc1376927ad2789726a43c881fe72</code>You'll put that hash into your config as follows: <code>[burnchain] genesis_hash = "a32a3ff4b42a3d87d771396ca5ffab850afbc1376927ad2789726a43c881fe72"</code>So, your [burnchain] section should now have four fields:<ul><li><code>chain="stacks"</code></li><li>`mining_contract = "ST17ABWV76GQCGWKFQR4G5N23HDXGZ3D3869A8Z5N.appchains-mvp-v1"</li></ul><ul><li><code>mode = "testnet"</code></li><li><code>genesis_hash = "a32a3ff4b42a3d87d771396ca5ffab850afbc1376927ad2789726a43c881fe72"</code></li></ul>Now you're ready to go. Simply start up your appchain boot node as follows: <code>$ stacks-node appchain --config /path/to/your/config.toml</code>As long as you tell your other users and miners the mining_contract and genesis_hash values, they can go and do likewise and join your appchain network.<h3>Adding Bootcode</h3>One thing you can do with appchains that you can't do with Stacks is add additional boot code. This is code that will live under the boot address <code>ST000000000000000000002AMW42H</code> on testnet, along with <code>.pox</code>,<code> .bns</code>, and <code>.costs</code>. If you want to make sure your custom smart contracts are available the minute your chain boots up, you can ship them as boot code.Shipping your appchain's desired smart contracts as boot code is advantageous for a few reasons:<ul><li>Shipping code as boot code ensures that it's always available for the duration of the chain's existence. No one can reorg it away.</li><li>There's no block limit on the boot code, so you can run any expensive pre-calculations you want in a boot code smart contract. This includes things like importing data from another chain, or pre-populating a set of accounts.</li></ul>To deploy your own boot code, you'll need to do the following three things:<ul><li>Add the contract names to the list of boot code contracts in the mining contract, within the <code>appchain-config</code> data var's boot-code list. In the linked example above, this includes "hello-world".</li><li>Generate the genesis hash with the boot code. You can do this by passing in the <code>--boot-code</code> ClI argument. You can pass it multiple times for multiple contracts. They must have the same filenames as the contract names</li><code>$ stacks-node appchain-genesis --config /path/to/your/config.toml --boot-code ./hello-world.clar</code><li>Launch the boot node with the boot code, so other appchain nodes can go and download it from you. You do this by also passing the source files in with <code>--boot-code</code>:</li></ul><code>$ stacks-node appchain --config /path/to/your/config.toml --boot-code ./hello-world.clar</code>Other users do not need to pass <code>--boot-code</code>; only the appchain creator and people who cold-boot their nodes will need to do this (which will basically be just you, the developer). However, other users will of course need both the contract address and the genesis hash, which you can provide them out-of-band.One day, there will be a registry for appchains so developers can both reserve chain IDs and publish their mining contract addresses and genesis hashes under a human-readable identifier. Maybe there could be a BNS namespace for it. I haven't thought that far ahead.<h3>Runinng a Node</h3>I have deployed a <a href="https://explorer.stacks.co/txid/0xaf93a4ec4349584bed4c9eeefd88fef8371e3bc2c099993ca54903eea0750652?chain=testnet" target="_blank">sample appchain</a>: on the Stacks testnet that you can play around with. Here is a sample config you can use to connect to it: <code>[node] rpc_bind = "0.0.0.0:15301" p2p_bind = "0.0.0.0:15300" seed = "&lt;FIXME: fill in with your private key&gt;" miner = false # you may want to change this working_dir = "/var/stacks/appchain-follower/chainstate" mine_microblocks = true microblock_frequency = 1000 wait_time_for_microblocks = 5000 deny_nodes = ""</code> <code>[burnchain] mining_contract = "ST17ABWV76GQCGWKFQR4G5N23HDXGZ3D3869A8Z5N.appchains-mvp-v1" genesis_hash = "a32a3ff4b42a3d87d771396ca5ffab850afbc1376927ad2789726a43c881fe72" chain = "stacks" mode = "xenon" peer_host = "44.199.104.134" rpc_port = 30443 peer_port = 30444 poll_time_secs = 10</code> <code>[connection_options] connect_timeout = 5 handshake_timeout = 5</code> <code># if you want to mine...</code> <code>[miner] min_tx_fee = 600 first_attempt_time_ms = 1000 subsequent_attempt_time_ms = 1000</code>To run the node, simply execute: <code>$ stacks-node appchain --config /path/to/the/above/config.toml</code>Your node should boot up and remain in sync with the appchain described in <a href="https://explorer.stacks.co/txid/0xaf93a4ec4349584bed4c9eeefd88fef8371e3bc2c099993ca54903eea0750652?chain=testnet" target="_blank">this contract</a>. Do note that you must use a <code>stacks-node</code> built from the <code>feat/app-chain-mvp</code> feature branch.<h3>Sending Appchain Transactions</h3>If you have some appchain tokens, then sending transactions is basically the same as sending them to the Stacks network. The only difference is that you must supply the appchain's chain ID to the transaction. In this example, this is <code>0x80000002</code>, or 2147483650. You can get the chain ID from the mining contract, in the <code>appchain-config</code> data var. To interact with the example appchain above, you would pass <code>--chain_id 2147483650</code> to <code>blockstack-cli</code> to generate transactions. For example: <code>$ blockstack-cli --testnet --chain_id 2147483650 publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar</code>Note that in addition to supplying a chain ID, you must also supply --testnet. This is because the appchain itself is the testnet variant of chain ID 2147483650 (there could also be a mainnet chain 2147483650).<h3>Future work</h3>I consider appchains to be in an alpha state. They work -- you could even ship products with them! -- but there are known limitations in the ecosystem that I'd like to get done before we can declare them a fully-supported feature.<ul><li>There needs to be a SIP that standardizes the mining contract's structure. This includes providing a trait definition for mining, as well as standardizing the data types for the <code>appchain-version</code>, <code>appchain-config</code>, and <code>appchain</code> state. </li><li>There needs to be an authoritative registry contract for appchains on the Stacks mainchains, whereby developers can claim their appchains' chain IDs and specify their mining contract addresses and genesis hashes. There also needs to be a way to expire and re-use chain IDs for defunct appchains. This could be BNS, but I'm not married to the idea if that proves difficult for whatever reason. This registry should be standardized via the SIP process. </li><li>The appchain codebase needs to use the appchain registry contract to resolve appchain names to their mining contracts and genesis hashes, so the act of spinning up an appchain only requires the user to know the human-readable identifier of the appchain, instead of its more inscrutible (and spoofable) metadata. </li><li>The<a href="https://github.com/blockstack/stacks.js" target="_blank"> stacks.js</a> library needs to permit the application to specify the chain ID.</li><li>There needs to be wallet support for appchains, including Ledger at some point. The web wallet needs to learn the chain ID(s) of the per-application appchain(s) in use. I have not looked into how difficult this will be.</li><li>There needs to be a fully fleshed-out light client for Stacks, which would permit the user to boot up an appchain without having to boot up instances of all of its ancestor chains. This is blocked on <a href="https://github.com/blockstack/stacks-blockchain/pull/2707" target="_blank">feat/1805</a>, which will ship in Stacks 2.1. </li></ul>Link to original gist is <a href="https://gist.github.com/jcnelson/c982e52075337ba75e00b79942164e31" target="_blank">here</a>.

All things Stacks app chains by Jude Nelson. 

Jude Nelson: App Chains