> 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-a-basic-app.md). # Build a Basic App ## Build a Basic App This guide explains how to turn a Canopy Template into a small, custom onchain application. You will use two custom transaction types as the example: faucet and reward. A signer requests tokens for any address, or an admin authorizes a mint while paying the fee; the chain validates the addresses and amount, then writes the new balances (and a small faucet or reward record) into persistent state. The same pattern applies to nearly every application feature you may build: a token transfer, a controlled mint, a test faucet, or any other operation that updates on-chain records. The key idea is simple: 1. Define a typed transaction message. 2. Register that message with the Template runtime. 3. Validate the message before it enters the mempool. 4. Apply deterministic state changes when it is included in a block. 5. Test the full transaction flow. ### Start with a product specification Before changing code, define the behavior you want in plain language. For this tutorial, the faucet and reward rules are: > Faucet: Any valid Canopy address may request a positive token amount for any recipient. The chain mints those tokens to the recipient’s account and records the mint. Anyone can query faucet history. > > Reward: An admin address may mint a positive token amount to any recipient and pays the transaction fee. The chain credits the recipient, deducts the fee from the admin, and records the reward. Anyone can query reward history. This specification gives you the information required to design the transactions: | Question | Faucet answer | Reward answer | | ------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | What action can a user take? | Request a mint to an address. | Mint a reward to a recipient. | | Who may take that action? | Any valid address. | An admin address. | | What data is required? | Signer address, recipient address, and amount. | Admin address, recipient address, and amount. | | What makes the action invalid? | An invalid address or a zero amount. | An invalid address, a zero amount, or an admin who cannot pay the fee. | | What state changes? | The recipient’s balance, plus a faucet record (total amount and count). | The recipient’s balance, the admin’s balance, the fee pool, plus a reward record (last admin, total amount, and count). | | Who must sign? | The signer address. | The admin address. | | What can clients read later? | Faucet records and account balances. | Reward records and account balances. | Then your next step is to choose your development language — Go, Python, C#, Kotlin, or TypeScript — which becomes the value of `` referenced throughout these instructions. This is also the right point to use an AI coding assistant. Give it the product behavior first, then ask it to map the behavior onto the existing Template patterns. ``` Read plugin//AGENTS.md, plugin//README.md, and the existing send transaction flow. I want to add an onchain guestbook. A user submits a non-empty message of no more than 280 characters. Store each post with an incrementing ID and the author's address. Before changing code, identify the Protobuf definitions, ContractConfig changes, state keys, validation rules, execution logic, and tests that this feature requires. ``` Do not ask an assistant to write code before it has identified the relevant files and constraints. ### Understand the Template The default template separates infrastructure from application logic. ``` plugin// ├── AGENTS.md AI-assisted development context ├── README.md Template architecture and transaction flow ├── TUTORIAL.md Maintained custom-transaction reference ├── main.go Starts the Template runtime ├── chain.json Chain metadata ├── contract/ │ ├── contract.go Application logic and transaction routing │ ├── plugin.go Runtime communication with the Canopy FSM │ ├── error.go Template-specific error definitions │ └── rpc.go Optional application-specific RPC routes └── proto/ ├── tx.proto Transaction and application state definitions ├── account.proto Account and pool definitions ├── event.proto Event definitions ├── plugin.proto Runtime protocol definitions └── _generate.sh Protobuf code-generation script ``` Your application work belongs primarily in `proto/tx.proto` and `contract/contract.go`. Avoid modifying the socket protocol, runtime startup code, or core Template infrastructure unless you are deliberately extending the runtime itself. ### Templates Tutorials The tutorials below walk through the template for each supported language and stay up to date with the code. * [Go](https://github.com/canopy-network/canopy/blob/main/plugin/go/TUTORIAL.md) * [TypeScript](https://github.com/canopy-network/canopy/blob/main/plugin/typescript/TUTORIAL.md) * [C#](https://github.com/canopy-network/canopy/blob/main/plugin/csharp/TUTORIAL.md) * [Kotlin](https://github.com/canopy-network/canopy/blob/main/plugin/kotlin/TUTORIAL.md) * [Python](https://github.com/canopy-network/canopy/blob/main/plugin/python/TUTORIAL.md) ### What you learned You now have the core pattern for building a Canopy application: * Define a typed action in Protobuf. * Register it with the Template runtime. * Claim and declare a safe application state namespace. * Validate messages in `CheckTx()`. * Apply deterministic state changes in `DeliverTx()`. * Build, restart, and test the complete transaction path. Next, learn how to run, test, and configure a Canopy application in [Run, Test, and Configure](app://-/run-test-and-configure.md).