# Utility ### Architecture Every Canopy chain comes pre-built with Security Root functionality: The ability to provide security for multiple external blockchains (Nested-Chains) simultaneously. This is accomplished by allowing Root-Chain Validators to organize in subsets called [Committees](/docs/canopy-network/how-does-canopy-work/state-machine.md#committee). Within each Committee, Validators `opt-in` to [restake](/docs/canopy-network/core-features/capital-efficient-restaking.md) their [collateral](/docs/canopy-network/how-does-canopy-work/state-machine.md#validators) on the Root-Chain to perform [Consensus](/docs/canopy-network/how-does-canopy-work/consensus.md) (BFT) on behalf of the Nested-Chain. {% hint style="info" %} A Nested Chain’s **Security Root** is where its Validators are registered and bonded with staked collateral. {% endhint %} Validators registered in a Committee **run a full instance of the Nested-Chain software**, which includes its own consensus rules, block timing, and execution environment, entirely independent from the Root-Chain. ⇪ The Nested Chain software may be [built](#building) from the Canopy template, and is configured with their `Validator_Private_Key` for consistent identity across chains. {% hint style="info" %} This design positions the Nested Chain as a fully independent network from the start — without the [Cold Start problem](/docs/canopy-network/why-canopy/background-and-industry-state.md#have-the-cold-start-problem) of L1s. {% endhint %} Nested Chain instances connect over dedicated P2P channels, where BFT consensus is executed ➛ using the Root-Chain Validator's economic collateral **only for as long as it’s designated as the security source**. The result: Nested-Chains gain strong security guarantees **without becoming dependent** on the Root Chain, meaning the Security Root is just a pluggable Validator provider to the Nested Chain. *** Nested-Chains continue to operate under this security model throughout their incubation phase — steadily maturing at their own pace, becoming economically secure, growing their ecosystem, and improving decentralization. ⇨ Importantly, the Nested-Chain is able to switch Security Roots at any time, executing a governance transaction which triggers a Root-Chain switch. **This enables a Nested-Chain to achieve full independence by changing itself as its own Security Root.** If the Nested-Chain is built with the Canopy template, it too is able to have Nested-Chains, at which point the recursive lifecycle starts again. ### Nested Chains At its core, a Committee is simply an on-chain coordination of trustless Validators running specific software. This flexibility allows for multiple flavors of Nested Chains, including: * **New utility blockchains** tailored for specific applications. * **Consensus-driven decentralized oracles** that aggregate and validate external data (such as the state of another blockchain or some DePIN application). * **On-the-fly horizontal scaling** for a subset of functionality or state (sharding) To qualify as a Nested Chain for the Canopy protocol, a chain must satisfy the following interface: ```protobuf message NestedChainInterface { // receive validator updates from the Root-Chain via Websocket connection UpdateValidators(v Validators) // execute a consensus instance in order to produce a certificate result // send the certificate result to the Root-Chain using the RPC ExecuteQuorum() CertificateResult // change the source of the validator set UpdateSecurityRoot(rootChainId uint64, websocketURL string) } message Validator { // the public key that is used to validate signatures from the operator bytes public_key = 1; // the weight of this node's vote, typically 1 to 1 matched to staked tokens uint64 voting_power = 2; // the p2p tcp address of the validator node string net_address = 3; } message CertificateResult { // the recipients who are rewarded based on the quorum decision // specifically who the committee agreed to reward from the committee pool RewardRecipients reward_recipients = 1; // the recipients who are penalized (slashed) by quorum decision // specifically who the committee agreed to slash due to evidence of bad behavior SlashRecipients slash_recipients = 2; // OPTIONAL: contains information regarding the 'buying side' of sell orders // including actions like 'buy/reserve order' or 'close/complete order' Orders orders = 3; // OPTIONAL: contains block information to allow provide Checkpoint-as-a-Service Checkpoint checkpoint = 4; // tombstone a committee by quorum decision bool retired = 5; } ``` ### Default Implementation The default implementation of a Nested Chain is the [Canopy](https://github.com/canopy-network/canopy) `go client`. Builders simply **fork and clone** the software to have a fully functional Nested-Chain *out of the box*. Developers may modify the template as needed, like changing [State Machine](/docs/canopy-network/how-does-canopy-work/state-machine.md) logic to add new utility, or updating NestBFT to use Proof-of-Work instead of Proof-of-Age. The template comes pre-packaged with L0 functionality, enabling a recursive architecture where *Nested-Chains* may have *Nested-Chains*. *** By default, Canopy Nested-Chains **connect** to the Root-Chain via web-sockets. This connection enables the Nested-Chain to subscribe to critical information from the Root Chain like Validator updates. ```protobuf message RootChainInfo { // root_chain_id: the chain id of the root chain uint64 root_chain_id = 1; // height: the block height of the root chain uint64 height = 2; // the current validator set ConsensusValidators validator_set = 3; // the selected delegate/pseudo-validator who receives rewards LotteryWinner lottery_winner = 4; // the swap order book from the 'root chain' for the 'nested chain' OrderBook orders = 5; } ``` The connection to the Root-Chain can be 'trustless' by utilizing proofs of inclusion from the [Storage](/docs/canopy-network/how-does-canopy-work/storage.md#canotrie). For simplicity, the default implementation assumes the Nested-Chains has access to a Root-Chain full-node. Once connected to the Root-Chain, the Nested-Chain functions like a typical blockchain — syncing, validating, and executing transactions — with one key distinction: its validator set is sourced externally. {% hint style="warning" %} If Validator updates are received from the Root-Chain in the middle of executing an instance of [NestBFT](/docs/canopy-network/how-does-canopy-work/consensus.md), the process resets consensus but maintains `Locks` for BFT safety. {% endhint %} ### Decentralized Oracles Nested-Chains may also be implemented as consensus-driven decentralized oracles — enabling many interesting use-cases. #### **Example 1: ****Permissionless Token Swaps to Bitcoin** The Canopy community wants token swaps to Bitcoin without requiring Bitcoin to make any changes to their software. The Canopy community build a Nested-Chain that requires the Committee to come to consensus on the state of finalized Bitcoin data by using a local full-node or light client: 1. A Sell Orders (Ask) is created on Canopy - their CNPY is transferred to the [Escrow Pool ](/docs/canopy-network/how-does-canopy-work/state-machine.md#pool)of the Committee. 2. A Bitcoin participant self-send an BTC transaction - embedding an **intent to buy** this order in the `sigscript` field. 3. The Committee **witnesses** the lock by reading the Bitcoin blockchain, coming to a +⅔ quorum agreement, and locks the SellOrder on the Root-Chain via the `CertificateResultTx` 4. Seeing the lock, the buyer **sends BTC directly** to the seller’s `BTCReceiveAddress`. 5. The Committee **witnesses** the BTC transfer, comes to another **+⅔ quorum**, and **releases the seller’s CNPY** on the Canopy to the buyer’s `RootChainAddress`. #### **Example 2: ****Validator Quality of Service for Cosmos** The community of a Cosmos chain decides that too many invalid transactions are being included in the block, but they don't want to make any changes to their software. Canopy patrons build a Nested-Chain that requires the Committee to come to consensus on finalized Cosmos data by using a local full-node or light client: 1. A Validator on Cosmos creates the next block with `no invalid transactions` 2. The Committee **witnesses** this behavior by reading the external blockchain, coming to a +⅔ quorum agreement, and embeds the Validator as a reward recipient in the `CertificateResultTx`. 3. The Validator is able to claim those funds using the same SECP256K1 public key the validator uses on Cosmos, binding their identity across chains. ### Incentives Nested-Chains pay for Consensus services using their native cryptocurrency. Each time a new block is produced, the Validator who produced the block is rewarded. Most Nested Chains are predicted to be [auto-subsidized](/docs/canopy-network/how-does-canopy-work/state-machine.md#subsidization) by the native cryptocurrency of their Root Chain. Thus, Validators performing Consensus services for the Nested-Chain are paid in the native currency of both the Nested-Chain and the Root-Chain. Patrons of the Nested-Chain may further subsidize the Committee on either the Root-Chain or the Nested-Chain via a manual `Subsidize Transaction`. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://canopy-network.gitbook.io/docs/canopy-network/how-does-canopy-work/utility.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.