> For the complete documentation index, see [llms.txt](https://canopy-network.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://canopy-network.gitbook.io/docs/build/key-concepts.md). # Key Concepts Canopy is built for a new way of developing software. AI coding tools can now turn a clear product idea into a working prototype quickly. But blockchain development has not kept pace. Building an application-specific chain has traditionally meant understanding consensus, networking, cryptography, validator operations, state storage, and a large infrastructure codebase before writing the first line of application logic. The Canopy Stack is designed to remove that barrier. It gives builders a focused, scaffolded application layer that works with modern AI coding tools. You define what your chain does. Canopy provides the systems required to run it. A Nested Chain can be defined in approximately 200 lines of application code, then extended through normal software development workflows. The goal is to let a builder arrive with an idea, work with an AI coding assistant, and leave a single development session with a functioning onchain prototype. ### Build with AI, not around infrastructure Canopy treats AI as a primary development collaborator. The Canopy Stack supports Go, TypeScript, Python, Kotlin, and C#. These are widely used languages with strong representation in modern AI coding tools, making it practical to generate, inspect, debug, and extend application code with tools such as Claude, Codex, and Cursor. The Stack abstracts the infrastructure that normally makes blockchain development difficult. You do not begin by writing consensus code, creating a peer-to-peer network, designing a state database, or coordinating a validator set. You begin with the application layer: the rules, state, and transactions that define the product you want to build. This does not mean AI replaces engineering judgment. A builder is still responsible for defining product rules, reviewing generated code, testing state transitions, and ensuring that application logic is deterministic. The Stack makes those responsibilities focused and manageable. ### AI-native scaffolding A Canopy Template gives a builder and their AI coding assistant a structured starting point rather than an empty repository or a large legacy Layer 1 codebase. Templates include the application structure, typed transaction definitions, state helpers, block-lifecycle methods, local development configuration, and context files that explain how the parts of the application fit together. The scaffold narrows the task from “build a blockchain” to “define the application’s behavior.” This is particularly useful for AI-assisted development. An AI tool works best when it can understand the relevant code, interfaces, and constraints without searching through unrelated infrastructure. Canopy’s scaffolding is designed to make that context available. The Stack includes context-assist files that document the chain’s architecture and development conventions for AI coding tools. In the default template, this includes an `AGENTS.md` file that gives an assistant focused guidance about the codebase and the expected development workflow. Canopy's code was created with AI in mind, allowing an AI system to locate relevant parts of the application without requiring the builder to identify every dependency manually. The codebase is written and documented so that LLMs can understand it quickly, and the code itself is simple enough to keep the required context small. The result is a development environment that is easier to navigate, easier to modify, and easier to explain to an AI collaborator. ### From idea to working chain The expected workflow is similar to building a conventional application, but the output is a dedicated blockchain. First, define the product in plain language. What should users be able to do? What records should the application keep? Which actions should be permissioned, paid, irreversible, or publicly verifiable? Next, use a Canopy Template to create the starting application. The template gives you the structure for transaction types, persistent state, block processing, local configuration, and testing. Then, work with an AI coding tool or directly in the codebase to define the application’s messages and rules. A guestbook application might add a `PostMessage` transaction. A marketplace might add `CreateOrder`, `FillOrder`, and `CancelOrder`. A game might add transaction types for players, moves, items, and rewards. Run the chain locally, submit transactions through RPC, inspect the resulting state, and iterate. Once the application logic works as intended, the same development model can extend to a broader validator deployment and launch workflow. ### What you are actually building A Canopy application is a Nested Chain, which is an application-specific blockchain with its own state, transaction types, rules, and block history. Unlike a smart contract on a shared network, a Nested Chain does not compete with unrelated applications for the same execution environment. Builders can define application-specific fees, transaction formats, token logic, governance rules, and upgrade paths. Canopy provides the underlying blockchain systems. Your application implementation defines the product-specific behavior. | **Canopy provides** | **You define** | | ------------------------------- | -------------------------------- | | Peer-to-peer networking | Transaction types | | NestBFT consensus | Validation rules | | State-machine infrastructure | State model | | Persistent storage and indexing | Application logic | | RPC services | Events and client behavior | | Shared-security architecture | Product economics and governance | This separation lets builders focus on the problem they are trying to solve rather than rebuilding infrastructure that every blockchain requires. ### Canopy Templates and language-specific implementations A **Canopy Template** is the builder-facing starting point for a new chain. It is an opinionated scaffold that gives you the code structure and runtime hooks needed to define a blockchain application. Under the hood, each template uses a language-specific plugin implementation. The implementation is a separate local process that runs beside the Canopy node and communicates with the Canopy finite state machine through a Unix socket using Protocol Buffers. Canopy provides official template implementations for Go, TypeScript, Python, Kotlin, and C#. The template is not a smart contract. It is a normal program that implements the application logic for the chain. Every validator responsible for the chain runs the same implementation locally. This means the application behaves like a conventional codebase. You can use normal language tooling, write tests, inspect logs, review diffs, and work with an AI coding assistant. The difference is that the code’s state changes are executed as part of a deterministic blockchain protocol. ### The runtime model At runtime, a validator runs the Canopy node and the application implementation together. ``` Client, frontend, or CLI │ │ RPC requests and signed transactions ▼ Canopy node ├── P2P networking ├── NestBFT consensus ├── FSM and transaction routing ├── Persistent state and indexing └── RPC services │ │ Unix socket, Protocol Buffers ▼ Canopy Template implementation ├── Application validation ├── Application state transitions ├── Application events └── Application-specific block logic ``` The Canopy node receives transactions, communicates with other nodes, participates in consensus, maintains protocol state, and invokes the local application implementation at defined points in the block lifecycle. The application implementation does not write to a database directly. It reads and writes persistent state through the Canopy finite state machine. This ensures that every validator applies the same rules to the same ordered transactions. ### Deterministic application logic Every validator on a chain must reach the same result when processing the same block. This is called deterministic execution. Given the same starting state and the same ordered transactions, each validator must produce the same state changes and events. Application logic cannot depend on local machine state, a random external API response, or any other input that may differ between validators. This is the central engineering constraint when building a chain. AI-generated code must still meet it. For example, an application should not ask a third-party API for the current exchange rate during transaction execution. Different validators could receive different values. Instead, an authorized transaction can submit a value to the chain, and every validator can process that same value according to the application’s rules. ### The application lifecycle Canopy calls the application implementation at defined points during block processing. | Method | When it runs | What it is for | | -------------- | ------------------------------------------ | ---------------------------------------------------------------------- | | `Genesis()` | When the chain is initialized | Imports or creates the application’s initial state. | | `BeginBlock()` | At the start of each block | Performs optional block-level setup. | | `CheckTx()` | When a transaction enters a node’s mempool | Rejects malformed or unauthorized transactions before block inclusion. | | `DeliverTx()` | When a transaction is applied in a block | Performs the transaction’s authoritative state transition. | | `EndBlock()` | After all transactions in a block | Performs optional block-level finalization. | `CheckTx()` is the early validation step. It should check transaction format, expected fields, message types, and required signers. It must not write persistent state. `DeliverTx()` is where the application’s state changes happen. It reads the current state, applies the transaction’s rules, writes the resulting changes, and may emit events for clients or indexers. `BeginBlock()` and `EndBlock()` support logic that belongs to the block as a whole rather than to an individual transaction. This may include updating counters, expiring records, calculating aggregate values, or emitting block-level events. ### Transactions, state, and events A transaction is a signed message that requests a change to the application’s state. You define which transaction types your chain accepts and how each one behaves. Canopy uses Protocol Buffers, or Protobuf, to define transaction messages, state objects, events, and the messages exchanged between the Canopy node and the application implementation. This gives the chain typed, language-neutral interfaces that work across the supported template implementations. Persistent application data is stored as key-value state. The implementation reads state through batched read operations and writes state through batched write operations. A single write request can update or delete multiple keys atomically. For example, a marketplace transaction may read an order, the buyer’s account, the seller’s account, and a fee pool together. If the transaction is valid, it can update each record in one state-write operation. If it is invalid, it returns an error and does not apply the intended state change. Events are optional records emitted during block processing. They give frontends, indexers, and other services a way to observe application activity without repeatedly scanning all chain state. ### Shared security and Nested Chains A Nested Chain is application-specific, but it does not need to begin by creating an entirely separate validator ecosystem. Canopy Network acts as a Security Root. Validators can opt in to support a Nested Chain through a committee, which is the validator group responsible for that chain’s consensus. This gives a new chain a path to shared security and validator services while it focuses on its product and community. The chain still defines its own application logic, state, economics, and user experience. Builders do not need to understand every aspect of committee operations before they begin coding locally. The important builder-level idea is that Canopy separates application development from the infrastructure and security work that historically made sovereign-chain development inaccessible. ### Iteration and upgrades Software improves through iteration. Canopy is designed to support this reality. The Stack includes development workflows and upgrade pathways intended to let builders improve their applications without treating a deployed chain as permanently frozen. This is important for AI-native development, where teams can test ideas quickly, learn from users, and refine the product continuously. A chain’s upgrade process still requires careful engineering and governance. Builders should version interfaces deliberately, test changes before deployment, and understand the effect of an upgrade on validators, clients, state, and users. ### Key terms | **Term** | **Meaning** | | ------------------------- | ------------------------------------------------------------------------------------------------ | | **Canopy Stack** | The AI-native development environment for defining and iterating on Canopy applications. | | **Canopy Template** | A builder-facing scaffold for creating a Canopy application chain. | | **Plugin implementation** | The language-specific runtime implementation behind a Canopy Template. | | **Nested Chain** | An application-specific blockchain built with Canopy. | | **Security Root** | The network layer whose validators can provide shared security services to Nested Chains. | | **Committee** | The validator group responsible for consensus for a specific Nested Chain. | | **FSM** | The finite state machine that applies deterministic protocol rules and manages persistent state. | | **Transaction** | A signed message that requests a state change. | | **Mempool** | The temporary collection of transactions received by a node before they are included in a block. | | **RPC** | The interface clients use to submit transactions and query a Canopy node. | | **Protocol Buffers** | The typed message format used by Canopy and the template implementation. | Next, set up your local environment in [Prerequisites](app://-/prerequisites.md).