Key Takeaways
- Chialisp singletons create uniquely identifiable coins that maintain state over time through a linear chain of descendants
- Every singleton has a unique Launcher ID that proves authenticity and prevents duplication
- Singletons use a two-layer architecture: an outer security wrapper and an inner puzzle for custom logic
- Common applications include NFTs, DIDs, Plot NFTs for pooling, and oracle feeds
- Building on Lessons 01-03, you’ll learn to create launcher coins and implement singleton patterns in your smart coins
Article Summary
A Chialisp singleton is a fundamental smart contract primitive that creates provably unique coins capable of maintaining and updating state over time. By using a launcher coin to establish identity and enforcing odd-valued outputs, singletons emulate stateful contracts within Chia’s UTXO model while preventing duplication.
What Are Chialisp Singletons?
In Lesson 02, we learned that Chia’s blockchain uses a coin set model where every coin is immutable once created. But what happens when you need something that acts like a traditional smart contract with changeable state? That’s where chialisp singletons come in.
A singleton is a special type of coin that guarantees it’s one-of-a-kind on the blockchain. Think of it like a digital identity card that can be updated but never duplicated. Every time you spend a singleton, it creates exactly one new singleton coin, forming a chain of descendants that you can trace back to the original creation.
This unique approach solves a major challenge in blockchain development: how do you track state changes in a system where everything is supposed to be permanent? Singletons create a linear history of state transitions, similar to how Ethereum smart contracts work, but they do it using Chia’s coin-based architecture. Singletons represent one of the key innovations that makes Chialisp’s unique approach to smart contracts fundamentally different from other blockchain platforms.
The Three Core Features of Singletons
Uniqueness Through Lineage: Every singleton carries a unique Launcher ID, which is the coin ID of the special launcher coin that created it. This ID never changes throughout the singleton’s entire lifetime. The singleton proves its authenticity by providing a lineage proof showing it’s a direct descendant of that original launcher.
Indivisibility Protection: A singleton must always have an odd amount, typically just 1 mojo (the smallest unit in Chia). The network enforces that when you spend a singleton, you can only create exactly one new singleton child with an odd value. This prevents anyone from splitting or duplicating the singleton.
State Management: By creating a linear chain of coins, singletons emulate the stateful nature of Ethereum-style smart contracts while staying within Chia’s UTXO-based coin set model. Each spend updates the state by destroying the current coin and creating a new one with updated information.
Why Singletons Matter for Chia Developers
If you’re building on Chia, understanding chialisp singletons is essential because they power almost every major application in the ecosystem. From NFTs to decentralized identifiers, singletons provide the foundation for creating unique, trackable digital assets.
Unlike simple coins that can only be spent once, chialisp singletons give you superpowers: you can update them, transfer ownership, or even “melt” them when they’re no longer needed. This flexibility stems from Chialisp’s programming paradigm, which enables stateful behavior within a UTXO-based system.
Real-World Impact
Consider how Chia’s NFT1 standard launched in June 2022 uses singletons. Each NFT is a singleton containing metadata about the artwork, creator royalties, and provenance information. When someone buys or transfers the NFT, they’re really spending the singleton and creating a new one with updated ownership information. The Launcher ID stays the same, so anyone can verify the NFT’s entire history back to when it was first minted.
“Singletons allow you to keep track of the state of something on the blockchain, with the ability to verify and check any part of its history using a unique id. It proves that the puzzle is unique and cannot be duplicated.” – Chialisp.com Official Documentation
How Singleton Architecture Works
Understanding the architecture of chialisp singletons requires looking at two distinct layers that work together. This design is brilliant because it separates security concerns from application logic, making your code both safer and easier to maintain.
The Outer Layer: singleton_top_layer_v1_1
The outer layer is a wrapper puzzle that handles all the security logic. It’s called singleton_top_layer_v1_1 in the Chia blockchain repository. This layer does three critical things:
First, it verifies lineage. Every time you spend a singleton, the outer layer checks the lineage proof to make sure this coin is really a descendant of the original launcher. This prevents someone from creating a fake singleton with the same Launcher ID.
Second, it enforces the odd-amount rule. The outer layer examines all the outputs from your spend and makes absolutely sure that exactly one output has an odd amount. If you try to create zero singleton outputs or multiple singleton outputs, the spend fails. This is how singletons prevent duplication.
Third, it morphs the inner puzzle’s output. The outer layer takes whatever conditions your inner puzzle creates and wraps the next coin in another singleton layer. This ensures the chain continues unbroken.
The Inner Puzzle: Your Custom Logic
The inner puzzle is where you put your actual application logic. This could be anything – an NFT puzzle, a DID puzzle, a pooling puzzle, or completely custom code. The beauty is that the outer layer handles all the singleton-specific security, so your inner puzzle can focus purely on what makes your application unique. The separation between security logic and application logic demonstrates how Chialisp enables complex smart contract logic while maintaining code clarity and auditability.
When you curry (a concept from Lesson 03!) values into a singleton, you’re currying them into both layers. The outer layer gets the SINGLETON_STRUCT that contains your Launcher ID and mod hash. The inner puzzle gets whatever values your application needs.
How the Two Layers Interact
Here’s what happens when you spend a singleton:
- The solution provides both lineage proof and the inner puzzle’s solution
- The outer layer verifies the lineage and calculates your coin ID
- The outer layer runs your inner puzzle with the solution you provided
- Your inner puzzle returns conditions (like CREATE_COIN or AGG_SIG_ME)
- The outer layer checks those conditions and morphs them to ensure the next coin is also a singleton
- The network validates everything and creates your new singleton coin
This architecture is similar to how decorators work in Python or higher-order functions in functional programming – the outer layer wraps your code with additional behavior without changing what your code does.
Understanding Launcher Coins
Before you can create a singleton, you need a launcher coin. The launcher is a one-time-use coin with a very special purpose: it establishes the unique identity that will follow your singleton forever.
What Makes Launchers Special
The launcher coin uses a standard puzzle called singleton_launcher.clvm that’s the same for every singleton ever created. This is important because it means anyone can verify that a singleton really came from a legitimate launcher just by checking the puzzle hash.
When you spend a launcher coin, it takes three parameters:
- singleton_full_puzzle_hash: The complete puzzle hash of your first singleton coin (called the “eve” singleton)
- amount: How much value the singleton will hold (typically 1 mojo)
- key_value_list: Optional metadata you want to announce when creating the singleton
The launcher creates exactly two conditions: a CREATE_COIN condition to make your eve singleton, and a CREATE_COIN_ANNOUNCEMENT to announce the creation with all the parameters. This announcement is crucial because it lets everyone know a new singleton was born.
The Launcher ID: Your Singleton’s DNA
Once you spend the launcher coin, its coin ID becomes the Launcher ID for your singleton. This ID is permanent and unique because:
- Coin IDs are calculated from parent ID, puzzle hash, and amount
- No two coins can ever have the exact same combination of these three things
- Therefore, no two launchers can ever have the same coin ID
- Therefore, no two singletons can ever have the same Launcher ID
This is how Chia guarantees uniqueness without needing a central registry or authority. The blockchain itself enforces that Launcher IDs are one-of-a-kind through the fundamental mathematics of coin ID calculation.
Building Your First Singleton
Now let’s put everything together from Lessons 01-03 and build a simple singleton. We’ll create a launcher, spend it to make a singleton, and then update the singleton’s state.
Step 1: Setting Up (From Lesson 01)
Make sure you have your Chialisp development environment ready from Lesson 01. You’ll need the Chia developer tools installed and a test wallet with some XCH or mojos.
# Verify your environment
cdv --version
chia wallet showIf you need a refresher on environment setup, review Lesson 01: Environment Setup & Hello-Coin.
Step 2: Creating the Launcher Coin (Applying Lesson 02 Concepts)
Remember from Lesson 02 that every coin has a puzzle and a solution. For our launcher, we’ll use the standard launcher puzzle. Here’s how you create a launcher using the Chia wallet RPC:
chia rpc wallet create_new_wallet '{
"wallet_type": "pool_wallet",
"mode": "new",
"initial_target_state": {
"state": "SELF_POOLING",
"target_puzzle_hash": "your_puzzle_hash_here"
}
}'This creates a Plot NFT singleton, which is one of the standard singleton types. For custom singletons, you’d interact with the blockchain more directly, but the principle is the same.
Step 3: Currying Your Inner Puzzle (Using Lesson 03)
In Lesson 03, we learned about CURRY and how it bakes values into puzzles. For a singleton, you need to curry both the outer layer and your inner puzzle:
(mod (SINGLETON_STRUCT INNER_PUZZLE lineage_proof my_amount inner_solution)
;; SINGLETON_STRUCT contains:
;; (MOD_HASH . (LAUNCHER_ID . LAUNCHER_PUZZLE_HASH))
;; Your inner puzzle logic here
;; This is where you implement your application
)The SINGLETON_STRUCT is curried into the outer layer and contains your unique Launcher ID. The INNER_PUZZLE is where you curry your application-specific values.
Step 4: Spending and Updating Your Singleton
When you want to update your singleton’s state, you create a spend that:
- Provides the lineage proof (parent coin info, inner puzzle hash, amount)
- Includes your inner puzzle’s solution
- Creates exactly one odd-valued output
- Announces any necessary information
The network validates all of this and creates your new singleton coin with the updated state. The Launcher ID stays the same, but the coin ID changes because it’s technically a new coin.
Common Singleton Patterns You’ll Use
As you build with chialisp singletons, you’ll encounter several common patterns that other developers have established. Understanding these patterns will help you build better applications faster.
The p2_singleton Pattern
One of the most useful patterns is paying to a singleton. This lets you lock up coins in a way that only a specific singleton can claim them. The puzzle curries in the singleton’s Launcher ID and waits for an announcement.
When the singleton wants to claim the funds, it includes a CREATE_PUZZLE_ANNOUNCEMENT in its spend. The p2_singleton puzzle sees this announcement, verifies it came from the correct singleton, and allows the coins to be spent. This pattern is used extensively in pooling and NFT marketplaces.
The Melting Pattern
Sometimes you need to end a singleton’s lifecycle. This is called “melting” the singleton. The inner puzzle creates a CREATE_COIN condition with an amount of -113 (a magic number), which signals to the outer layer to stop creating a child singleton.
When melted, the singleton’s remaining value is released into normal coins that can be spent freely. This is useful for Plot NFTs when leaving a pool permanently or for NFTs that need to be burned.
The Fast Forward Pattern (2024 Update)
On February 28, 2024, Chia introduced Singleton Fast Forward in version 2.2.1. This allows multiple transactions to reference the same singleton in the same block, solving a major scalability challenge for oracles.
Previously, if two people tried to use the same oracle singleton in one block, one transaction would fail because they’d both be trying to spend the same coin. Fast Forward lets the network “fast forward” the singleton state, so both transactions can succeed. This is particularly important for DataLayer-based oracles that multiple users might query simultaneously.
Case Studies: Singletons in Production
Chia Friends NFT Launch: When Chia launched its NFT1 standard in June 2022, they created 10,000 Chia Friends profile pictures. Each NFT used a singleton to store metadata URIs, creator information, and on-chain royalty configurations. The singleton architecture ensured each Chia Friend remained unique and traceable throughout all future trades.
DAO Treasury Management: Chia’s DAO1 standard uses singletons to represent organizational treasuries. Each DAO singleton manages funds locked in p2_singleton puzzles, processes proposals through voting, and executes approved transactions. The singleton ensures only one valid state exists for the DAO at any time, preventing conflicting proposals from executing simultaneously.
Practical Integration Tips
When building with chialisp singletons in your own projects, keep these best practices in mind:
Always verify lineage proofs. Don’t trust user-provided singleton information without checking the lineage back to a known launcher. This prevents spoofing attacks.
Use appropriate inner puzzle complexity. Remember that every singleton spend costs transaction fees based on the puzzle complexity. Keep your inner puzzles as simple as possible while still meeting your requirements.
Plan for state migrations. If you might need to upgrade your singleton logic in the future, design your inner puzzle to support migration to a new puzzle hash while preserving the Launcher ID.
Test with simulator before mainnet. The Chia simulator (covered more in Lesson 14) lets you test singleton creation and spending without using real XCH. Always test complex singleton logic thoroughly in the simulator first.
Troubleshooting Common Issues
New developers often encounter a few common problems when working with singletons:
Issue: “Invalid lineage proof” error
Solution: Make sure you’re providing the correct parent coin info, inner puzzle hash, and amount. The lineage proof must match the singleton’s actual parent.
Issue: Creating even-valued singleton outputs
Solution: Always ensure your CREATE_COIN condition for the next singleton uses an odd amount. The outer layer will reject even amounts.
Issue: Multiple singleton outputs in one spend
Solution: Your inner puzzle can only create one odd-valued output per spend. If you need to create multiple coins, make sure only one has an odd amount.
Issue: Lost singletons with no way to recover
Solution: Always track your singleton coin IDs carefully. Consider implementing a recovery mechanism in your inner puzzle, especially for valuable singletons like DIDs.
Conclusion
You’ve now learned the fundamentals of chialisp singletons and how they create unique, stateful smart coins on the Chia blockchain. By using a launcher coin to establish identity and enforcing odd-valued outputs through the outer layer, singletons emulate traditional smart contracts while maintaining Chia’s security and efficiency advantages.
As you continue through this Chialisp curriculum, you’ll see singletons appear again and again. In Lesson 05, we’ll use them to create Chia Asset Tokens (CATs). In Lesson 06, we’ll build offers that interact with singletons. And in Lesson 08, we’ll implement DIDs using everything you’ve learned here.
The singleton pattern is one of Chialisp’s most powerful primitives. Master it well, and you’ll be able to build sophisticated on-chain applications that rival anything on Ethereum or other smart contract platforms – but with Chia’s superior security and sustainability. To learn more about Chialisp’s powerful capabilities beyond singletons, explore how this language is transforming blockchain development.
Keep experimenting with singleton creation and spending. Try implementing a simple singleton with custom state, or examine the reference implementations for NFTs and DIDs in the Chia blockchain repository. The more you work with singletons hands-on, the more natural they’ll become.
Chialisp Singletons FAQs
What is a chialisp singleton and why is it important?
A chialisp singleton is a unique smart contract primitive that creates provably one-of-a-kind coins on the Chia blockchain. It’s important because singletons enable stateful applications like NFTs, DIDs, and DAOs by maintaining a linear chain of state updates while preventing duplication through odd-amount enforcement and lineage verification.
How do chialisp singletons prevent duplication?
Chialisp singletons prevent duplication through two mechanisms: they must always have an odd amount (typically 1 mojo), and the outer layer enforces that exactly one odd-valued output is created per spend. Any attempt to create multiple singleton outputs or even-valued singletons will fail validation, ensuring only one valid singleton exists at a time.
What is a Launcher ID in chialisp singletons?
A Launcher ID is the unique identifier for a chialisp singleton, derived from the coin ID of the original launcher coin that created it. This ID never changes throughout the singleton’s lifetime and serves as the singleton’s permanent identity, similar to a serial number that proves authenticity and enables lineage verification.
Can I use chialisp singletons for custom applications beyond NFTs?
Yes, chialisp singletons are highly flexible and can be used for any application requiring unique state management. Beyond NFTs, developers use singletons for decentralized identifiers, DAO treasuries, oracle feeds, vault management, streaming payment contracts, and custom financial instruments like on-chain options contracts.
How do chialisp singletons differ from Ethereum smart contracts?
Chialisp singletons achieve similar stateful behavior to Ethereum contracts but use a UTXO coin model instead of an account model. Each singleton state update creates a new coin in a linear chain rather than modifying storage variables, providing better security through immutability while maintaining composability through announcements and offer files.
Chialisp Singletons Citations
- Chialisp.com. “Singletons | Chialisp.” Available at: https://chialisp.com/singletons/
- Chia Network. “Chia Documentation – Pool Protocol Summary.” Available at: https://docs.chia.net/pool-protocol/
- Chia Network. “Chia Documentation – State Management Guide.” Available at: https://docs.chia.net/guides/crash-course/state/
- Chia Network GitHub. “pool-reference Repository – Specification.” Available at: https://github.com/Chia-Network/pool-reference/blob/main/SPECIFICATION.md
- Chia Network GitHub. “CHIPs Repository – CHIP-0004 DID Standard.” Available at: https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0004.md
- Fizpawiz. “Singleton Fast Forward.” Medium, March 5, 2025. Available at: https://medium.com/@fizpawiz/singleton-fast-forward-71a8f1ef37ba
- XCH.today. “Understanding DAOs on Chia and How They’re Better.” January 13, 2024. Available at: https://xch.today/2024/01/13/understanding-daos-on-chia-and-how-theyre-better/
- XCH.today. “CHIPs Ahoy! Understanding recent Chia Improvement Proposals.” Available at: https://xch.today/2025/03/16/chips-ahoy-understanding-recent-chia-improvement-proposals/
- Chia Network. “Chia Launches Innovative Expanded NFT Functionality in NFT1 Standard.” Business Wire, June 29, 2022. Available at: https://www.businesswire.com/news/home/20220629005363/en/
- Chialisp.com. “DIDs | Chialisp.” Available at: https://chialisp.com/dids/
