Chialisp Guide Pt 2: Coins, Puzzles & Conditions

Key Takeaways

• Every Chialisp “coin” is a UTXO locked by a puzzle program, and spending means running the puzzle with a solution to get a list of conditions
• A coin’s ID is the hash of three components: parent coin ID, puzzle hash, and amount in mojos—changing any creates a completely different coin
• Conditions returned by puzzles control spending behavior, from CREATE_COIN to AGG_SIG_ME, and all must be valid for the spend to succeed
• Password-only puzzles are insecure because farmers can see and modify solutions—always use signatures and proper announcements for security
• Inner and outer puzzle structures enable composability, allowing CATs, NFTs, and complex DeFi applications to layer rules efficiently

Article Summary: Chialisp coins are UTXOs on the Chia blockchain, each secured by a puzzle program that outputs conditions when solved. Understanding how coins, puzzles, and conditions work together is essential for building secure smart contracts and avoiding common security pitfalls in Chia development.

What Are Chialisp Coins and How Do They Work?

In the Chia blockchain, everything is a coin. Unlike traditional account-based blockchains where you have a balance, Chia uses a coin model similar to Bitcoin’s UTXO system but with powerful smart contract capabilities. Each coin is a self-contained unit of value locked by a Chialisp program called a puzzle.

A coin consists of exactly three pieces of information that define its unique identity. The parent coin ID tells you which coin created this one when it was spent. The puzzle hash is the hashed version of the Chialisp program that locks the coin and determines how it can be spent. The amount represents the coin’s value measured in mojos, where one trillion mojos equals one XCH.

When you spend a coin on Chia, you’re not transferring a balance like you would in a bank account. Instead, you’re destroying the old coin completely and creating brand new coins in the same block. This happens through a process where you provide the original puzzle and a valid solution. If the puzzle runs successfully, it returns a list of conditions that tell the network what to do next.

Understanding Coin IDs and Their Importance

Every coin has a unique identifier called a coin ID. This ID is calculated by hashing together the parent coin ID, puzzle hash, and amount. Because the ID is a sha256 hash, coins can never be changed once created—they can only be spent once and then they’re gone forever.

The coin ID calculation is critical for security. If you change even one byte of any component, you get a completely different coin ID. This immutability prevents attackers from modifying coin values or ownership rules after creation.

How Coins Differ From Bitcoin UTXOs

While Chia’s coin model is inspired by Bitcoin’s UTXO model, there are important differences. In Bitcoin, transactions are first-class objects with their own IDs. In Chia, coins are first-class objects and transactions are just ephemeral justifications for destroying some coins and creating others.

This design simplifies the system dramatically. Instead of tracking transaction IDs and output numbers like Bitcoin, Chia only needs to track which coins exist and which have been spent. This makes the blockchain more efficient and reduces the complexity needed to validate transactions.

Understanding Puzzles: The Smart Contracts of Chia

A puzzle is the Chialisp program that locks a coin and determines the rules for spending it. Think of it as a smart contract that lives directly on the coin itself. When someone wants to spend a coin, they must provide both the original puzzle and a valid solution that satisfies the puzzle’s requirements.

The puzzle runs on the Chialisp Virtual Machine when a spend is attempted. If the program executes successfully without failing, it returns a list of conditions. These conditions are instructions that tell the blockchain what should happen, like creating new coins or requiring specific signatures.

How Puzzles Get Locked to Coins

When you create a coin, you don’t store the entire puzzle on the blockchain. Instead, you store only the puzzle hash. This hash is created by hashing the complete Chialisp program. When someone wants to spend the coin later, they must reveal the original puzzle that matches this hash.

This design saves blockchain space and provides privacy. Nobody can see how a coin can be spent until someone attempts to spend it. The puzzle hash serves as the coin’s address, similar to how Bitcoin addresses work.

Currying: Customizing Puzzles for Different Users

Currying is a technique that lets you take a base puzzle and bind specific values into it before creating a coin. This allows the same puzzle code to be reused for many different coins with different parameters.

For example, imagine a signature puzzle that requires a specific public key. Instead of writing a new puzzle for every user, you can curry the user’s public key into the base puzzle. This creates a customized version where that specific public key is required, but the underlying logic stays the same.

Solutions: Providing the Keys to Unlock Coins

A solution is the input you provide when spending a coin. It contains the arguments that the puzzle needs to execute successfully. In most cases, the solution includes conditions that specify what should happen when the coin is spent, along with any data needed to satisfy the puzzle’s requirements.

When you construct a spend, you’re essentially saying “here’s the puzzle that locks this coin, and here’s the solution that proves I’m allowed to spend it.” The puzzle runs with your solution as input, and if everything checks out, it returns the conditions you specified.

The Relationship Between Puzzles and Solutions

Think of puzzles and solutions like a lock and key system. The puzzle is the lock that secures the coin. The solution is the key that opens it. But unlike physical locks, Chialisp puzzles can be as complex as you need them to be.

A simple puzzle might just check if you know a password. A complex puzzle might require multiple signatures, enforce time delays, check announcements from other coins, or verify complex mathematical relationships. The solution must provide everything the puzzle needs to return valid conditions.

What Goes Into a Solution

Most solutions contain two key components. First, they include proof that you’re allowed to spend the coin—this might be a password, a signature, or other verification data. Second, they include the list of conditions you want the puzzle to output, usually starting with CREATE_COIN conditions that specify where the coin’s value should go.

For a standard wallet transaction, the solution typically contains just the list of conditions since the puzzle itself enforces the signature requirement. The conditions might create a new coin for the recipient and another coin back to yourself as change.

Conditions: Controlling What Happens When Coins Are Spent

Conditions are the output of puzzle execution. They’re numbered codes followed by arguments that tell the Chia blockchain what to do. When a puzzle runs successfully, it must return a list of conditions for the spend to be valid.

There are two types of conditions. Some conditions cause something to happen if the spend is valid, like creating new coins. Other conditions require something to be true for the spend to be valid, like checking that enough time has passed or that a required signature is present.

CREATE_COIN: The Foundation of All Transactions

The CREATE_COIN condition is condition number 51 and it’s the most important condition in Chialisp. It creates a new coin with a specified puzzle hash and amount. Every transaction uses this condition to redistribute a coin’s value when it’s spent.

When you spend a 10 XCH coin to pay someone 7 XCH, you create two new coins using CREATE_COIN conditions. One coin goes to the recipient with 7 XCH, and another coin comes back to you with 3 XCH as change. The original 10 XCH coin is destroyed in the process.

Each CREATE_COIN condition costs 1,800,000 in CLVM execution costs because creating coins adds to the blockchain’s coin set. This is one of the more expensive operations, so minimizing the number of coins you create helps keep transaction fees low.

AGG_SIG_ME: Securing Coins With Signatures

The AGG_SIG_ME condition requires a BLS signature over a specific message that includes the coin’s ID. This prevents farmers from stealing your coins by modifying the solution as it goes through the mempool.

When a puzzle includes AGG_SIG_ME, it’s saying “this spend is only valid if there’s a signature from this public key over a message that includes this specific coin’s ID.” Because the signature is tied to the coin ID, it can’t be reused on other coins. This makes AGG_SIG_ME the recommended way to secure wallet transactions.

The condition adds an additional CLVM cost of 1,200,000, reflecting the computational work needed to verify BLS signatures. But this cost is worth it for the security it provides.

SEND_MESSAGE and RECEIVE_MESSAGE: The Modern Way to Link Coin Spends

As of the CHIP-25 soft fork that activated at block 5,716,000 on July 30, 2024, the recommended way to ensure multiple coins spend together is using SEND_MESSAGE and RECEIVE_MESSAGE conditions. These replaced the older ASSERT_COIN_ANNOUNCEMENT conditions that were more prone to security issues.

These conditions use a 1-byte mode parameter that commits to the sender and receiver of messages. The mode is a bitmask where three bits represent the sender and three bits represent the receiver, allowing for 64 possible combinations of parent coin ID, puzzle hash, and amount matching.

This ensures that when you need multiple coins to be spent together atomically, they actually are. If any coin in the set can’t be spent, the entire transaction fails. This prevents attacks where someone might try to separate your spend or add unwanted spends to your transaction.

Inner Puzzles and Outer Puzzles: Building Composable Smart Coins

One of Chialisp’s most powerful features is the ability to nest puzzles. An outer puzzle can wrap an inner puzzle to create layers of rules and security. This inner-outer structure is fundamental to how CATs, NFTs, and other advanced features work on Chia.

The outer puzzle typically enforces global rules that apply to all instances of a particular type of coin. For CATs, the outer puzzle ensures the total supply of tokens follows the TAIL rules and that tokens can’t be created or destroyed improperly. The inner puzzle handles the user-level spending logic, like requiring the owner’s signature to spend the token.

How CATs Use Inner and Outer Puzzles

CATs are a perfect example of puzzle composition. The CAT outer puzzle wraps around a standard wallet puzzle as its inner puzzle. When you try to spend a CAT, the outer puzzle first verifies that the token supply remains constant across the spend, checking that the sum of input CAT amounts equals the sum of output CAT amounts.

Only after the outer puzzle verifies the supply constraints does it pass control to the inner puzzle. The inner puzzle then handles the actual spending authorization, typically by requiring a signature from the token owner. This separation of concerns makes the code more modular and easier to audit.

The Magic Condition That Triggers TAIL Execution

CATs can have their TAIL program run during a spend by including a special magic condition. The condition looks like a CREATE_COIN with an amount of -113 mojos. Negative amounts are normally invalid, but -113 is the magic number that signals the CAT layer to execute the TAIL program.

The TAIL program defines the rules for how tokens can be issued and whether they have a fixed supply or can be minted over time. By only running when explicitly triggered, TAILs give token creators flexibility in how strictly they want to control issuance.

Common Beginner Mistakes and How to Avoid Them

Learning Chialisp means understanding not just what works, but what doesn’t. Several common mistakes can make your coins insecure or cause spending failures. Let’s explore the most important pitfalls and how to avoid them.

Mistake 1: Using Password-Only Puzzles in Production

Password-only puzzles are great for learning, but they’re completely insecure for real coins. When you spend a coin, your solution goes into the mempool where farmers can see it. If your puzzle just checks a password, a farmer can see the password, ignore your solution, and spend the coin themselves with different conditions that send the value to their own address.

The fix is to always use signatures instead of passwords. With AGG_SIG_ME, even if a farmer sees your solution, they can’t modify it without invalidating the signature. The signature proves you authorized that specific spend with those specific conditions. Once you’ve set up your Chialisp development environment, you can practice building secure signature-based puzzles on testnet.

Mistake 2: Creating Unprotected Announcements

When multiple coins need to be spent together, you must ensure the announcements include the coin ID of the coin being spent. If you just announce a generic message like “mint” or “burn,” multiple coins could assert the same announcement within the same block. This leads to replay attacks where an attacker can exploit your announcement to drain multiple coins.

The TibetSwap v1 vulnerability is a famous example of this mistake. The liquidity TAIL created announcements without including coin IDs, allowing attackers to drain liquidity pools. TibetSwap v2 fixed this by including the singleton_coin_id in every announcement.

Mistake 3: Not Validating Component Lengths in Coin IDs

When a puzzle concatenates and hashes values to create a coin ID, it must verify the length of each component. Without length checks, an attacker might shift bytes between the puzzle hash and amount fields. Depending on the values of those extra bytes, this could inflate the coin’s value.

The coinid operator introduced in CHIP-11 automatically verifies that hashes are 32 bytes and amounts are valid. Using coinid instead of manually hashing components prevents this entire class of attacks at no extra CLVM cost.

Mistake 4: Using Announcements in Puzzles Instead of Solutions

ASSERT_COIN_ANNOUNCEMENT and ASSERT_PUZZLE_ANNOUNCEMENT should typically only appear in a coin’s solution, not hardcoded into the puzzle itself. If coin A’s puzzle asserts an announcement from coin B, and coin B gets spent before coin A, then coin A becomes permanently unspendable.

By putting announcement assertions in the solution instead, you maintain flexibility. If the announced coin has already been spent, you can simply provide a different solution later without different announcement requirements.

Mistake 5: Not Understanding That Farmers Can Modify Solutions

Always remember that farmers can attempt to modify any part of a coin’s solution before including it in a block. If modifying your solution would still result in a valid spend, a rational farmer will do exactly that to benefit themselves.

This means every element of your solution must either be signed (protected by AGG_SIG_ME) or validated in some other way that makes modification unprofitable or impossible. You can’t rely on farmers being “honest”—you must make dishonesty cryptographically impossible or economically irrational.

Real-World Examples of Chialisp in Action

Case Study 1 – TibetSwap Vulnerability and Fix: TibetSwap v1 used CREATE_COIN_ANNOUNCEMENT conditions with only keywords like “mint” or “burn” without including coin IDs. This allowed multiple coins to assert the same announcement in one block, enabling replay attacks that drained liquidity pools. TibetSwap v2 fixed this by including singleton_coin_id in all announcements, preventing replay attacks. The patched version has run since May 2023 without incident.

Case Study 2 – Tsunami DEX Front-Running Prevention: Tsunami Protocol leverages Chia’s coin set model to prevent front-running attacks that plague Ethereum DEXs. Because the market price comes from a specific order where the maker coin has already been spent, users see the pre-execution result before submitting. Even if someone tries to front-run, the user won’t submit an unfavorable order. This front-running prevention is only possible with UTXO-based models and impossible on global state machine chains like Ethereum.

“What we’ve figured out with Chialisp is how to keep the UTXO model but add in the general power of Solidity. Coins are first class objects and transactions are ephemeral justifications of destroying some of them and creating others. The format of coins is dramatically simplified—it’s just a parent input, puzzle hash, and amount. Transactions happen simultaneously rather than sequentially.”

— Bram Cohen, Creator of BitTorrent and Chia Network

Conclusion: Mastering the Foundation of Chia Smart Contracts

Understanding coins, puzzles, and conditions is the foundation of Chialisp development. Unlike account-based blockchains, Chia’s coin model treats every asset as an independent UTXO with its own rules encoded in a puzzle. This design provides better parallelization, enhanced security through sandboxing, and deterministic execution of every spend.

The key is remembering that coins are destroyed and recreated with each transaction, puzzles define spending rules but are revealed only at spend time, and conditions returned by puzzles control everything from coin creation to signature requirements. Master these concepts and you’ll be ready to build secure smart contracts, create tokens, and leverage Chialisp’s full power.

Start by creating simple password-locked puzzles on testnet to understand the mechanics. Then progress to signature-based puzzles with AGG_SIG_ME for security. As you advance, explore inner and outer puzzle structures to build composable smart coins. Most importantly, always validate your puzzles carefully and avoid the common security mistakes that can make coins vulnerable to attacks.

Chialisp Coins, Puzzles FAQs

What are chialisp coins, puzzles and how do they differ from Ethereum smart contracts?

Chialisp coins are UTXOs where each coin has its own puzzle program that defines spending rules, while Ethereum uses account-based smart contracts with global state. Chialisp coins, puzzles execute independently without accessing external data, returning conditions that control coin creation and spending requirements. This design provides better parallelization and security through sandboxing, unlike Ethereum’s sequential transaction model where contracts can interact with global state.

How do I create my first chialisp coin with a puzzle on mainnet?

Creating a chialisp coin requires compiling your puzzle to get its puzzle hash, then sending XCH to that hash as the destination address. For learning purposes, start with a password-locked puzzle on testnet (never mainnet), curry in the sha256 hash of your password, compile the puzzle to get its hex representation, and use the Chia wallet to send coins to the puzzle hash. Remember that password puzzles are insecure for real value—use signature-based puzzles with AGG_SIG_ME instead.

What conditions should I use in chialisp puzzles for secure transactions?

For secure chialisp puzzle transactions, always use AGG_SIG_ME (condition 50) to require BLS signatures tied to specific coin IDs, preventing farmers from modifying solutions. Use CREATE_COIN (condition 51) to specify where coin value should go when spent. For multi-coin transactions, use SEND_MESSAGE and RECEIVE_MESSAGE conditions introduced in CHIP-25 instead of legacy announcement conditions. Avoid hardcoding assertion conditions in puzzles—put them in solutions instead for flexibility.

Why can’t I use password-only puzzles for real chialisp coins?

Password-only chialisp puzzles are insecure because farmers can see and modify solutions before including them in blocks. When your solution contains the password and your desired conditions, a malicious farmer can keep the password but replace your conditions with their own, sending your coins to themselves instead. This is why signatures are required—AGG_SIG_ME creates a cryptographic signature over the entire solution that becomes invalid if any part is changed, making farmer theft impossible.

How do inner and outer puzzles work in Chialisp for CATs and NFTs?

Inner and outer puzzles in Chialisp create composability by nesting one puzzle inside another. The outer puzzle enforces global rules like CAT supply constraints or NFT uniqueness requirements, while the inner puzzle handles user-level spending logic like signature verification. When spending, the outer puzzle validates first, then passes control to the inner puzzle. This separation makes code modular, auditable, and allows the same inner puzzle to work with different outer puzzle wrappers like CATs or singletons.

Chialisp Coins, Puzzles Citations

1. Chialisp Documentation – Conditions (2024). Retrieved from //chialisp.com/conditions/
2. Chia Network – CHIP-25: SEND_MESSAGE and RECEIVE_MESSAGE Conditions (2024). Retrieved from //github.com/Chia-Network/chips/blob/main/CHIPs/chip-0025.md
3. Chia Documentation – Coin Set Introduction (2024). Retrieved from //docs.chia.net/docs/04coin-set-model/intro/
4. Chialisp Documentation – First Smart Coin Tutorial (2024). Retrieved from //chialisp.com/chialisp-first-smart-coin/
5. Chialisp Documentation – Common Issues and Security Pitfalls (2024). Retrieved from //chialisp.com/common_issues/
6. XCH Arcane – The Coinset Model: Unlocking the Magical Vaults of Chia’s Blockchain (May 2025). Retrieved from //xcharcane.com/articles/coinset-model-intro
7. Chia Documentation – Coins, Puzzles and Solutions (2024). Retrieved from //docs.chia.net/docs/04coin-set-model/what-is-a-coin/
8. Chia Network – Version 2.3.0 Release Notes (May 2024). Retrieved from //www.chia.net/2024/05/01/version-2-3-0-release/
9. Chialisp Documentation – CATs Overview (2024). Retrieved from //chialisp.com/cats/
10. XCH Arcane – Understanding Transaction Costs in Chia (May 2025). Retrieved from //xcharcane.com/articles/understanding-transaction-costs
11. Chia Network – Introducing Chialisp (November 2019). Retrieved from //www.chia.net/2019/11/27/chialisp/
12. Chia Documentation – Coin Set vs UTXO Model (2024). Retrieved from //docs.chia.net/coin-set-vs-utxo/
13. Tsunami DEX – TsunamiProtocol GitHub Repository (2024). Retrieved from //github.com/HashPocket/TsunamiProtocol
14. CoinMarketCap – Chia Network (XCH) Overview (2026). Retrieved from //coinmarketcap.com/currencies/chia-network/
15. BeInCrypto – Chia Coin: An Explainer on XCH Cryptocurrency (January 2025). Retrieved from //beincrypto.com/learn/chia-network-xch-coin/
16. Yakuhito – TibetSwap V1 Post-Mortem (May 2023). Retrieved from //blog.kuhi.to/tibetswap-v1-post-mortem