Chialisp Guide Pt 15: Upgradability Patterns

Key Takeaways

• Chialisp upgradability works through state migration rather than code mutation, using replaceable coins and puzzles instead of in-place updates
• Singletons provide persistent identity through launcher IDs while allowing inner puzzle upgrades across versions¹
• Governance-controlled and admin-gated upgrade patterns give you flexible control over who can upgrade your smart contracts^1,2
• Real-world Chia projects like DAOs and Circuit DAO demonstrate successful implementation of these upgrade patterns^2,12,17
• Understanding these patterns helps you build flexible smart contracts that can evolve without breaking user trust

Article Summary

Chialisp upgradability patterns enable your smart contracts to evolve over time without losing their identity or user trust. Unlike Ethereum’s storage-based upgrades, Chia uses state migration through coin replacement, where singletons maintain persistent identity while inner puzzles can be swapped during authorized spends.^1,10

Understanding Upgradability in Chialisp

When you build smart contracts on most blockchains, you face a tough problem. What happens when you need to fix a bug or add new features? On networks like Ethereum, developers use special proxy patterns that let them point to new code. But Chia Network works differently.

Chialisp doesn’t have EVM-style storage or special functions like delegatecall.¹⁰ Instead, upgradability in Chialisp means moving your state from one coin to another coin with updated logic. Think of it like moving into a new house rather than remodeling your current one. You pack up your belongings (state) and move them to a new location (new puzzle) while keeping your family name (launcher ID) the same.

The core principle is state migration, not code mutation. Your smart contract’s state lives in the coin graph and in the puzzle curried into each coin.¹ To upgrade, you spend a coin under old logic and recreate the same state under new logic, with on-chain rules controlling who can make that migration.

Why This Matters for Developers

This approach gives you powerful benefits. Users and integrators can track a singleton launcher ID as the stable identity, even though the inner puzzle controlling it evolves across versions.¹ This means your application can improve over time without breaking trust with users who rely on it.

Unlike account-based blockchains where code can change suddenly, Chia’s approach makes upgrades visible and auditable on-chain. Every upgrade creates a clear trail that anyone can verify.

Common Upgradability Patterns in Practice

Singleton with Replaceable Inner Puzzle

The most popular pattern wraps your application logic inside a singleton top layer.¹ The singleton’s launcher ID becomes your persistent identity and history anchor. Meanwhile, the inner puzzle contains things like admin keys, allowed upgrade paths, or version numbers.

When you need to upgrade, you create a spend that replaces the inner puzzle with a new one while keeping the singleton wrapper and launcher ID unchanged. This works similar to an EVM proxy whose address never changes, while the implementation logic gets swapped. On Chia, the singleton top layer acts as your “proxy” and the inner puzzle serves as your “implementation.”

Here’s what makes this powerful: external applications only need to track your singleton’s launcher ID. They don’t care which version of your inner puzzle you’re running. This separation between identity and implementation gives you freedom to upgrade without breaking integrations.

Admin-Gated Upgrade Spends

Sometimes you want tight control over who can upgrade your contracts. Admin-gated patterns require upgrades to be signed by designated admin keys or multi-signature setups. The puzzle checks that the spend is signed properly and recreates a singleton child whose inner puzzle hash matches a new, whitelisted implementation.

You can make this progressively more restrictive over time. For example, you might start by allowing any upgrade signed by admins, then limit upgrades to a specific family of hashes, or add a flag that permanently disables future upgrades after releasing a final version. This gradual reduction in upgrade power builds user confidence as your project matures.

Governance-Controlled Upgrades

Instead of giving upgrade power to a raw key, you can make “who may upgrade” a puzzle of its own. A voting singleton can authorize specific new inner puzzle hashes for your main contract singleton based on community votes.

An upgrade then becomes a coordinated spend where the governance singleton outputs a condition that the app singleton must reference through announcements or asserted coin IDs when moving to a new implementation. Chia DAOs use this pattern, where each DAO is represented as a singleton treasury that can only take actions when proposals pass through the voting process.^2,12,14

Quick Decision Table: Choosing Your Upgrade Pattern

Two-Step Consent Pattern

For user-held positions like vaults, NFTs, or staking positions, you might want each position coin to spend into a new version only when that position’s owner participates in the spend. This gives users explicit consent over the new logic.

This avoids having a central admin silently change behavior for all users. Instead, each user’s coin upgrades on first interaction or through a dedicated migration spend, with the puzzle enforcing the allowed upgrade path. While this requires more coordination, it provides maximum user protection and trust.

Composable Upgrade Logic

Some projects implement special mechanics where an NFT or contract instance can combine with other coins to unlock new behavior or versions. This might look like upgrading NFT traits or capabilities through “fusion” mechanics.

Functionally, this is still an upgrade pattern. The old NFT or state coin gets spent, and a new one with different puzzle or metadata gets created, following strict rules about allowed transformations. The creativity comes in how you design those transformation rules.

Design Tips and Best Practices

Prefer Singletons for Long-Lived Applications

For anything that needs to exist long-term like pools, registries, or protocol controllers, use singletons.^4,5 Treat the launcher ID as the canonical handle that off-chain systems track. This single point of reference makes integration much simpler for other developers.

Keep Your Top-Level Puzzle Thin

Your singleton puzzle should focus on core invariants, identity checks, and upgrade gating. Push your business logic into the inner puzzle.¹ This makes upgrades smaller and easier to audit. Reviewers can focus on what actually changed in the business logic rather than wading through identity verification code.

Encode Upgrade Policy On-Chain

Where possible, curry a list of allowed implementation hashes into your puzzle, or require a governance puzzle to co-spend to authorize a hash. This makes your upgrade policy transparent and verifiable. Anyone can check which implementations are allowed without trusting your documentation.

Make Upgrades Observable

Use coin announcements linking old and new singleton children. Document the hash of each released version so indexers and users can track exactly which logic controls a given singleton. Transparency builds trust, especially when users are entrusting value to your contracts.

Build User Trust Over Time

Strongly consider using time-delayed upgrade flows, multi-signature governance for the upgrade key, or an eventual “finalize” upgrade that permanently removes the ability to change logic. Users need to see you’re committed to decentralization, not just talking about it.

Real-World Example: CAT1 to CAT2 Upgrade

The Chia Network faced a real upgrade challenge when a security vulnerability was discovered in the CAT1 (Chia Asset Token) standard.¹⁶ The team discovered the vulnerability through an outside security audit conducted by Trail of Bits, and needed to upgrade all CAT1 tokens to the new CAT2 standard.

Rather than forcing users to manually migrate, Chia Network created a comprehensive reissuance toolkit. Original CAT issuers could use these tools to recreate their tokens on the CAT2 standard, and users received their new tokens through an airdrop process based on balances at block height 2,311,760.¹⁶ The upgrade preserved user balances while fixing the security issue.

This demonstrates the power of planned upgrade paths. Because the Chia team had considered upgradability from the start, they could coordinate a network-wide token standard upgrade without losing user funds or breaking existing applications.

Real-World Example: Circuit DAO Implementation

Circuit DAO is an on-chain collateralized stablecoin protocol on Chia, implementing the proven CDP model that MakerDAO pioneered but adapted to Chia’s smart coin architecture.¹⁷ The project uses singleton patterns to maintain protocol identity while allowing upgrades through governance.

Circuit’s treasury singleton holds collateral and can be upgraded through governance votes from CRT token holders.¹⁷ This shows how real DeFi protocols use these patterns in production. The singleton launcher ID remains constant, providing a stable reference point for integrators, while the inner puzzle can evolve as the protocol adds new features or fixes issues.

Mapping EVM Patterns to Chialisp

Understanding the Delegated Puzzle Pattern

Chialisp’s delegated puzzle pattern uses the (a) operator to let the solver provide code to execute at spend time.⁶ A delegated puzzle allows the solver to specify the puzzle and solution they would like to run when the coin is spent, rather than when the coin is created, creating maximum flexibility.

For security, this typically pairs with a signature check. The coin essentially says “I will run any code you give me, provided it is signed by the owner’s key.”⁶ This allows owners to execute new logic without having pre-defined it when the coin was created.

Step-by-Step: Implementing a Basic Singleton Upgrade

Let’s walk through how you would implement a simple admin-controlled singleton upgrade:

Step 1: Create Your Singleton

Start by creating a singleton with your initial inner puzzle.¹ The singleton top layer handles identity verification, while your inner puzzle contains the actual logic plus an admin public key for upgrades.

Step 2: Curry in Upgrade Controls

Your inner puzzle should include curried parameters for the admin key and potentially a list of allowed upgrade hashes.¹⁵ This embeds your upgrade policy directly in the code.

Step 3: Define Upgrade Conditions

Your puzzle checks for an upgrade spend by looking for specific conditions: a signature from the admin key and a new inner puzzle hash that matches your allowed list.

Step 4: Execute the Upgrade Spend

When you need to upgrade, create a spend that includes the admin signature and specifies the new inner puzzle. The spend destroys the current singleton coin and creates a new one with the updated inner puzzle, preserving the launcher ID.

Step 5: Verify On-Chain

After the upgrade, anyone can verify that the new singleton maintains the same launcher ID and that the upgrade followed the rules embedded in the previous puzzle.

Advanced Pattern: Layered Puzzle Architecture

Complex applications often use a stack of puzzles where each layer serves a specific purpose. A typical coin might have Singleton Layer → Metadata Layer → Ownership Layer. Each layer can be designed to be replaceable.⁷

For example, a user could upgrade their security from a single-key ownership layer to a multi-signature layer without moving the underlying asset to a new identity. The singleton and metadata layers stay the same, providing continuity, while just the ownership layer gets replaced.

This modular approach gives you surgical precision when upgrading. You only change what needs changing, reducing risk and making audits easier.

Security Considerations for Upgrades

The Upgrade Key is Critical

If you use admin-gated upgrades, the admin key becomes extremely valuable. Anyone who controls it can change your contract logic. Use multi-signature setups or hardware security modules to protect these keys. Better yet, plan to transition to governance control over time.

Verify Before You Upgrade

Always test upgrades thoroughly on testnet before executing on mainnet.² Unlike some upgrade patterns where you can roll back, Chialisp upgrades are one-way transactions. Once you spend the old coin and create the new one, you can’t undo it without another upgrade.

Communication is Essential

Users need to know when upgrades are coming. Even with perfect technical implementation, surprise upgrades damage trust. Announce your plans, explain what’s changing, and give users time to understand the new version.

Parameterization: The Simplest Upgrade

Sometimes you don’t need to change your code at all. Parameterization means changing the values that influence your puzzle’s behavior without changing the logic itself. Your puzzle might have a limit, fee amount, or admin key as a constant. While you can’t change the constant in the existing coin, you can spend it into a new coin where that constant has a different value.

This works great for adjusting economic parameters, updating addresses, or changing thresholds. The logic stays the same and well-tested, while the parameters adapt to new conditions.

Conclusion

Chialisp upgradability patterns give you the tools to build smart contracts that can evolve without breaking user trust or losing identity. By using singletons for persistent identity, implementing proper governance controls, and making upgrades observable, you create systems that can adapt to bugs, add features, and improve over time.

The key insight is that state migration beats code mutation. Rather than trying to change code in place like account-based blockchains, you move state forward to better implementations. This approach is more transparent, more auditable, and ultimately more trustworthy.

Start simple with admin-controlled upgrades for your early projects. As you gain experience and users, transition to governance-controlled or even time-locked final versions. Your upgrade strategy should mature along with your project, always moving toward more decentralization and user control.

Your next step: review the singletons from Lessons 1-14 and think about which upgrade pattern would work best for each use case. Practice is how you master these concepts.

Chialisp Upgradability Patterns FAQs

What is the difference between Chialisp upgradability and Ethereum proxy patterns?

Chialisp upgradability uses state migration where you spend old coins and create new ones with updated logic, while Ethereum proxy patterns use delegatecall to point stored data at new implementation contracts. Chialisp’s approach is more transparent because each upgrade creates a visible on-chain transaction, whereas Ethereum proxies can change implementation silently.

How do Chialisp upgradability patterns maintain contract identity across upgrades?

Chialisp upgradability patterns maintain identity through singleton launcher IDs, which remain constant even as the inner puzzle changes across versions.¹ External systems and users track the launcher ID rather than the puzzle hash, so they can trust they’re interacting with the same logical entity regardless of implementation updates.

Can users lose funds during a Chialisp upgrade if something goes wrong?

If an upgrade is properly implemented, users should not lose funds because the state migration from old to new puzzle is atomic – it either succeeds completely or fails without executing. However, bugs in the new puzzle could lock funds, which is why thorough testing on testnet and security audits are critical before mainnet upgrades.¹⁶

What is a delegated puzzle in Chialisp and how does it enable upgradability?

A delegated puzzle in Chialisp allows the solver to provide code to execute at spend time using the (a) operator, rather than having all logic pre-defined when the coin is created.⁶ This enables upgradability by letting authorized users specify new behavior through signed solutions, similar to how Ethereum’s delegatecall works but with explicit authorization requirements.

Should I use admin-gated or governance-controlled upgrades for my Chialisp project?

Use admin-gated upgrades for early-stage projects where you need flexibility to fix bugs quickly, but plan to transition to governance-controlled upgrades as your project matures and attracts more users.^2,12,14 Admin control is simpler but requires trust, while governance is more complex but provides decentralization that users prefer for high-value applications.

Chialisp Upgradability Patterns Citations

1. Chialisp.com – Singletons | Chialisp
2. Chia Network – Version 2.3.0 Release
3. GitHub – Cypher Chialisp Library
4. Chia Documentation – Pool Protocol Summary
5. Chialisp.com – Pooling Implementation
6. Chialisp.com – Standard Transactions
7. GitHub – Chia Network CHIP-0035
8. GitHub – Chia Blockchain DAO Review
9. Chia Documentation – Chialisp Introduction
10. Chia Network – Introducing Chialisp
11. Chialisp.com – CLVM Reference
12. XCH.today – Understanding DAOs on Chia
13. Chia Documentation – DAO CLI Guide
14. Chia Network – Version 2.1.2 Release
15. Chia Documentation – Prefarm Audit Tutorial
16. Chia Network – Upgrading the CAT Standard
17. Circuit DAO – Asset-Backed Stablecoin Platform
18. Chia Network – Version 2.2.1 Release