> 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/build-with-ai.md). # Build with AI Canopy is designed for builders who use AI as a primary development collaborator. Modern coding tools can turn a clear idea into working software quickly. The hard part of blockchain development has traditionally been everything surrounding the application itself: consensus, networking, storage, cryptography, validator operations, and large infrastructure codebases. The Canopy Stack removes much of that infrastructure from the builder’s immediate task. A Canopy Template gives you a structured application codebase, while Canopy provides the blockchain runtime beneath it. This gives an AI coding assistant a smaller, clearer surface to understand and extend. You still decide what the application should do. AI helps you turn that decision into code, tests, and iterations. ### What Canopy scaffolds for you A Canopy Template is not an empty repository. It gives you a working starting point for defining a blockchain application. The Template includes transaction and state definitions, the application lifecycle, state read and write helpers, local development configuration, build tooling, tests, and context files for AI coding tools. The Canopy Stack also supports context-assist scaffolding, semantic code indexing, retrieval, repository-aware search, and abstract syntax tree parsing. These tools help an AI system find the code that matters without requiring you to identify every dependency by hand. The goal is to make a Canopy application understandable as an application, rather than requiring you or an AI assistant to reason about an entire Layer 1 implementation before making a product change. ### Start with behavior, not code The best AI-assisted workflow begins with a product rule written in plain language. Do not start with “build a blockchain for my idea.” Instead, describe one user action and its expected result. For example: > A user may create a post containing up to 280 characters. The post is permanently stored with the author’s address and an incrementing ID. Only the original author may delete it. This description gives you the basis for the transaction types, required fields, signer rules, persistent state, validation conditions, and test cases. Before asking an AI assistant to modify code, ask it to turn the product behavior into an implementation plan. ``` Read AGENTS.md, the Template README, and the existing transaction flow. I want to add an onchain guestbook. A user can create a post with up to 280 characters. Each post has an incrementing ID and an author address. Only the author may delete a post. Do not write code yet. Identify the transaction types, Protobuf messages, state records, state keys, signer rules, validation rules, execution logic, fee handling, and tests this feature requires. Call out any decision I have not specified. ``` Review the plan before moving on. This is where you decide whether the product behavior is correct, not after the assistant has modified multiple files. ### Give your assistant the right context Before editing a Template, have your AI assistant read the files that define the project’s structure and constraints. For the Go Template, begin with: ``` AGENTS.md README.md TUTORIAL.md contract/contract.go proto/tx.proto ``` `AGENTS.md` provides focused context for AI coding tools. The README explains the runtime and transaction flow. The tutorial provides a maintained example of custom transaction types. `contract.go` contains the application behavior, while `tx.proto` defines typed transaction and state messages. A useful orientation prompt is: ``` Read AGENTS.md, README.md, and TUTORIAL.md. Then inspect contract/contract.go and proto/tx.proto. Do not modify code. Explain the existing transaction lifecycle from a Protobuf message definition to CheckTx, DeliverTx, persistent state, RPC submission, and tests. Identify the files I should change to add one new application feature. ``` The goal is not to make the assistant read every file in the repository. It is to give it the right context before it makes a focused change. ### Work in small, reviewable steps AI is most useful when each request has a clear boundary. A good development loop is: 1. Define the product behavior. 2. Ask for an implementation plan. 3. Review and approve the plan. 4. Ask for one focused change. 5. Build and test the change. 6. Inspect the resulting state transition. 7. Move to the next change. For example, do not ask an assistant to implement an entire guestbook in one request. Ask it to define the Protobuf messages first. Then register the transaction type. Then implement validation. Then implement deterministic execution. Then add tests. This keeps each change understandable and easy to review. ### Prompt patterns that work #### Understand existing code Use this before changing an unfamiliar Template. ``` Trace the existing MessageSend transaction through the Canopy Go Template. Show where it is defined, registered, validated, executed, signed, submitted, and tested. Do not modify code. ``` #### Plan a feature Use this after you have written the product behavior. ``` I want to add a MessageCreateProposal transaction to this Canopy Template. A proposal has a title, a description, and an author. The author must sign. The title must be between 1 and 120 characters. The description must be no more than 5,000 characters. Each proposal receives an incrementing ID. Do not write code yet. Produce an implementation plan covering Protobuf, ContractConfig, custom state prefixes, state keys, CheckTx, DeliverTx, fees, events, queries, and tests. ``` #### Make one focused change Use this after you have approved the plan. ``` Implement only the Protobuf definitions and ContractConfig changes for the proposal feature we planned. Do not add execution logic or tests yet. Use unique custom state prefixes outside the core-reserved range. Show the diff, explain every changed line, and identify the command required to regenerate Protobuf code. ``` #### Review deterministic behavior Use this before treating application code as ready. ``` Review this proposed Canopy transaction handler for deterministic behavior. Identify any dependency on local time, random values, external APIs, local files, process memory, unordered iteration, or other inputs that could cause validators to reach different results. Recommend the smallest safe correction for each issue. ``` #### Generate a test plan Use this before writing or accepting test code. ``` Write a test plan for this Canopy transaction type. Cover successful execution, invalid fields, invalid signers, insufficient funds where applicable, duplicate or sequential IDs, state reads, state writes, emitted events, fee handling, and deterministic results across validators. Do not write implementation code yet. ``` #### Debug a failure Use this when a transaction, build, or test fails. ``` A Canopy transaction failed. Review the node log, Template log, transaction payload, test output, and relevant implementation code. Determine whether the failure occurred during transaction construction, signing, CheckTx, mempool admission, DeliverTx, state read, state write, or block inclusion. Explain the smallest safe fix and the regression test that should be added. ``` ### What AI should not decide for you AI can propose an implementation, but it should not make product, economic, or security decisions without direction. You should explicitly decide: * Who may perform an action. * Who must sign an action. * Which actions cost a fee and how the fee is applied. * Which state is public, permanent, mutable, or deletable. * Whether an action can mint, transfer, lock, or burn an asset. * How upgrades are approved and deployed. * What happens when an action fails. * Which data must remain deterministic across validators. These are application rules. They should come from your product and security requirements, not from a guessed implementation. ### Review generated code carefully Before accepting AI-generated code, verify four things. First, confirm that the transaction matches the product rule you intended. A correct-looking implementation can still encode the wrong business behavior. Second, confirm that the code is deterministic. Every validator must reach the same state from the same transactions and prior state. Third, confirm that the code handles state safely. Custom application state must use declared prefixes outside the core-reserved range, and related state changes should be written together. Fourth, confirm that tests cover both success and failure. A transaction is not complete until you have submitted it, included it in a block, queried the resulting state, and checked invalid cases. ### Keep secrets out of AI tools Do not share private keys, keystore files, seed phrases, passwords, API keys, or production configuration with an AI assistant. For local development, use the disposable keys and funded genesis accounts created by the local Canopy environment. For any shared, staging, or production environment, treat keys and configuration as sensitive operational material. ### A productive first session A successful first Canopy session does not need to end with a production launch. A good outcome is a local chain that runs, one custom transaction type that works, a test that verifies its state change, and a clear next feature to build. That is enough to move from an idea to a functioning onchain prototype. From there, you can iterate with the same loop: specify, plan, implement, test, and review. Next, prepare your local environment in [Prerequisites](app://-/prerequisites.md).