Chialisp Guide Pt 3: Curry – Master Modular Puzzle Design for Reusable Smart Coins

Key Takeaways

• Chialisp curry pre-fills puzzle parameters before blockchain deployment, creating unique coin addresses from reusable code templates
• Use SCREAMING_SNAKE_CASE naming convention to identify parameters meant for currying, making your code intentions clear
• Curry powers essential Chia primitives including standard transactions, CATs, NFTs, and DID wallets through modular composition
• Inner and outer puzzle patterns let you layer functionality, building complex smart coins from simple building blocks
• Command-line currying with cdv clsp curry embeds parameters into compiled CLVM bytecode for deployment

Article Summary

Chialisp curry is the process of pre-defining parameters in a puzzle before it hits the blockchain, allowing developers to create unique smart coin instances from a single reusable template. This technique enables modular puzzle design where one base program can generate countless specialized coins by simply changing the curried values.

What Is Chialisp Curry and Why It Matters

When you’re building with Chialisp’s transformational smart contract capabilities, you quickly realize that writing a brand new puzzle for every single coin would be a nightmare. That’s where chialisp curry comes in to save the day.

Chialisp curry lets you take a general-purpose puzzle template and bake specific values directly into it before deployment. Think of it like a cookie cutter – you have one shape (your base puzzle), but you can create thousands of unique cookies (coins) by pressing it into different dough (parameters). Each curried puzzle produces a different puzzle hash, which means a different on-chain address, even though they all use the same source code.

This matters because Chia farmers and blockchain developers need efficient ways to manage coins at scale. Instead of maintaining hundreds of different puzzle files, you maintain one template and curry in the specifics when needed. The standard transaction puzzle that creates your wallet addresses? It uses curry to inject your synthetic public key. Every CAT token? Curried with its TAIL program. Every NFT? Curried with unique identifiers.

The real power comes from commitment. Once you curry a value into a puzzle and that puzzle becomes a coin’s address, those values are locked in stone. Nobody can change them when spending the coin. This creates trustless guarantees that other smart contract platforms struggle to achieve without complex verification logic.

How Chialisp Curry Works Under the Hood

Understanding curry starts with grasping what happens when you compile Chialisp code. Your human-readable .clsp file compiles down to CLVM bytecode, which defines how coins can be spent through puzzles and conditions – the low-level instruction set that the Chia Virtual Machine actually runs.

The Compilation and Currying Process

When you curry parameters into a puzzle, you’re not just storing them as variables that get passed at runtime. You’re actually modifying the compiled bytecode itself. The curried values become part of the program’s structure. This is fundamentally different from how most programming languages work, and it’s why curry is so powerful for blockchain applications.

Here’s a simple example. Say you write a multiply puzzle that takes two numbers and multiplies them together. In basic form, it would require both numbers as solution inputs every time you spend the coin. But if you curry the first number (let’s say 5), the compiled program now only needs one input – the second number. The 5 is permanently embedded in the bytecode. You’ve turned a multiplier into a “times-five-er.”

The magic happens because currying changes the puzzle’s tree hash. In Chia’s UTXO model, every coin is identified by its parent coin ID, puzzle hash, and amount. When you curry different values, you get different puzzle hashes, creating mathematically distinct on-chain addresses. This enables you to use the same base logic for millions of coins while keeping each one uniquely identifiable.

SCREAMING_SNAKE_CASE Convention Explained

Chialisp developers follow a crucial naming convention: parameters meant to be curried are written in ALL CAPS with underscores. This isn’t just style – it’s communication. When you see SYNTHETIC_PUBLIC_KEY or PASSWORD_HASH in puzzle code, you immediately know these values should be curried in before coin creation, not passed as solution arguments during spending.

Regular function parameters that get passed in solutions use lowercase or camelCase. This visual distinction helps prevent a common beginner mistake where someone tries to pass a curried parameter as a solution argument, which breaks the puzzle entirely. The Chia blockchain doesn’t enforce this convention technically, but every professional developer follows it because clear code prevents expensive mistakes.

Chialisp Curry Quick Reference Guide

Modular Puzzle Design Patterns with Curry

The real breakthrough in Chialisp architecture comes from combining curry with inner and outer puzzle patterns. This approach lets you build complex functionality from simple, auditable components.

Inner and Outer Puzzle Architecture

Imagine a Russian nesting doll. The outer doll provides structure and protection, while inner dolls contain the actual contents. Chialisp puzzles work the same way. An outer puzzle enforces high-level rules (like “this is a CAT token” or “this follows singleton behavior”), while an inner puzzle handles specific ownership and spending conditions.

Here’s how it works in practice. The CAT outer puzzle wraps around any inner puzzle you choose – typically the standard transaction puzzle. When you create a CAT coin, you curry the TAIL program hash into the outer puzzle (defining what kind of token it is) and curry the owner’s public key into the inner puzzle (defining who can spend it). The outer puzzle ensures token rules are followed, while the inner puzzle handles signature verification.

This separation of concerns makes code auditing dramatically easier. You can verify the CAT outer puzzle once and trust it for all tokens. You can verify the standard transaction inner puzzle once and trust it for all ownership scenarios. Then you just need to verify how they connect, which is straightforward. Contrast this with Solidity contracts where token logic and ownership logic often intertwine in ways that create security vulnerabilities.

Composability Through Curry

Curry enables true composability – the ability to combine pre-built, tested components into new functionality without rewriting code. Want to create a time-locked CAT? Curry a timelock puzzle as the inner puzzle inside your CAT outer puzzle. Want a multi-signature NFT? Curry a multisig puzzle inside your NFT outer puzzle.

The Chia developer community has built libraries of well-tested puzzle components. When you need specific functionality, you don’t start from scratch. You take proven outer puzzles (CAT, singleton, DID) and proven inner puzzles (standard transaction, multisig, timelock) and curry them together. This is why Chia’s smart coin ecosystem can grow quickly without sacrificing security.

Expert Insight on Modular Design

“The UTXO approach is much simpler, easier to implement, has lower overhead on full nodes, and results in much more reliable, secure, and succinct smart transactions. The Solidity model is much more dangerous, expensive, and unreliable, but has more expressive power. What we’ve figured out with Chialisp is how to keep the UTXO model but add in the general power of Solidity.”

– Bram Cohen, Founder of Chia Network, “Introducing Chialisp” (2019)

This modular, UTXO-based approach that Chialisp enables through curry stands in stark contrast to account-based models. When every piece of state is self-contained in a coin, and every coin’s behavior is fully determined by its curried puzzle, you eliminate entire classes of reentrancy and state manipulation vulnerabilities that plague other platforms. To learn more about how Chialisp’s approach differs from traditional smart contract languages, see our guide on how Chialisp transforms blockchain development.

Chialisp Curry vs. Traditional Smart Contract Parameterization

The key difference is philosophical. Ethereum and EVM chains treat smart contracts as persistent programs that maintain state. Chia treats coins as ephemeral puzzle solutions that create new coins. Curry enables this model by letting each coin carry its own parameterized logic without needing centralized state management.

Practical Command-Line Curry Examples

Let’s get hands-on with how you actually use curry when developing Chialisp puzzles. The Chia Dev Tools (cdv) provide command-line interfaces for currying values into compiled puzzles.

Note: These commands assume you’ve already compiled your Chialisp (.clsp) file to CLVM bytecode (.clvm.hex). Use cdv clsp build to compile before currying.

Basic Curry Command Structure

The basic curry command follows this pattern:

cdv clsp curry program.clsp.hex -a 'argument1' -a 'argument2' -a 'argument3'

Each -a flag adds an argument that gets curried into the puzzle in order. The output is compiled CLVM bytecode with your arguments permanently embedded. This bytecode is what gets used to create coins on the blockchain.

Password Puzzle Curry Example

Let’s walk through currying a password-protected coin. First, you hash your password to get its SHA256 hash. For the password “hello”, the hash is 0x2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824. Then you curry this hash into your password puzzle:

cdv clsp curry password.clsp.hex -a '0x2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'

The 0x prefix is critical – it tells CLVM to interpret the value as bytes rather than a string. If you forget this prefix, your curry will fail or produce incorrect results. The output is a new compiled puzzle where the password hash is permanently embedded. Anyone wanting to spend this coin must provide the original password in their solution, which the puzzle will hash and compare to the curried value.

CAT Token Curry Example

Creating a CAT token involves currying the coin ID that will serve as the genesis identifier. Using the cats admin tool, you first select a coin, then curry its ID:

cats --tail ./genesis_by_coin_id.clsp.hex --curry 0x<Coin_ID> --send-to <address> --amount <mojos>

This curry operation embeds the genesis coin ID into the TAIL program, ensuring only coins descended from that original genesis can be part of this token type. The TAIL program hash then gets curried into every CAT coin of this type, creating a chain of cryptographic verification.

Important: The current CAT standard is CAT2 (released July 2022), which replaced CAT1 after a security audit discovered vulnerabilities. All CAT tokens on Chia now use the improved CAT2 implementation with enhanced security features.

Uncurrying Compiled Puzzles

Sometimes you need to reverse-engineer a curried puzzle to see what values were embedded. The cdv clsp uncurry command does exactly this. Point it at compiled CLVM bytecode, and it separates the base program from the curried arguments. This is invaluable for auditing coins on the blockchain or debugging your own puzzles during development.

Common Use Cases for Chialisp Curry in Chia Development

Understanding curry theory is one thing. Knowing when and how to apply it in real projects is another. Let’s explore the most common scenarios where curry makes Chia development practical.

Standard Transaction Wallet Addresses

Every time your Chia wallet generates a new receive address, curry is working behind the scenes. The wallet derives a synthetic public key for that address using your master public key and a derivation path. This synthetic public key gets curried into the standard transaction puzzle, producing a unique puzzle hash that becomes your XCH address.

This approach gives you HD wallet functionality (one seed phrase, infinite addresses) while maintaining the simplicity of the coin model. Each coin is independently spendable with no need for the wallet to track complex state relationships. The curried public key proves ownership, and that’s all you need. For a deeper understanding of how coins, puzzles, and conditions work together in Chialisp, see our comprehensive guide to coin mechanics.

CAT Token Implementation

CATs (Chia Asset Tokens) rely heavily on curry to function. The CAT outer puzzle requires two critical curried values: the TAIL program hash (defining what kind of token this is) and the inner puzzle (defining who owns it). When you spend a CAT, the puzzle automatically wraps any output coins in the same CAT outer puzzle, currying in the same TAIL hash to maintain token integrity.

This design means you don’t need separate token contract deployments like in Ethereum. One CAT outer puzzle code serves all tokens. The curried TAIL hash differentiates your token (such as Marmot Coin or Spacebucks) from other CAT tokens on the network. The curried inner puzzle differentiates your coins from another user’s coins of the same token type.

Singleton and DID Wallets

Singletons are Chia’s primitive for maintaining unique, mutable state on-chain. They’re used for DIDs (Decentralized Identifiers), NFTs, and pooling plots. The singleton outer puzzle gets curried with a launcher ID and launcher puzzle hash, which cryptographically proves there’s only ever one coin of this singleton lineage in existence at any time.

DIDs take this further by currying recovery public keys into the DID inner puzzle. This lets you set up social recovery where trusted contacts can help restore your DID if you lose access. The curried recovery configuration is part of the DID’s permanent structure, making the recovery mechanism as secure as the blockchain itself.

Custom Puzzle Development

When building custom Chialisp applications, curry becomes your tool for configuration. Need a marketplace contract that takes fees? Curry the fee recipient address and fee percentage. Building a timelock vault? Curry the unlock timestamp and beneficiary public key. Creating a multisig wallet? Curry the required signature threshold and the list of authorized public keys.

The pattern is consistent: identify what should be set once at coin creation (curry those), separate what should be provided at spend time (those are solution arguments), and use clear SCREAMING_SNAKE_CASE to mark the difference in your code.

Real-World Case Studies

Case Study 1 – Legacy Coin Implementation: The LeaveALegacy project demonstrates advanced curry composition by creating nested inheritance puzzles where Alice’s outer puzzle contains Bob’s curried puzzle, which itself contains a password puzzle. This three-layer curry structure enables complex “what happens to crypto when you die” scenarios using only proven puzzle components.

Case Study 2 – TibetSwap Vulnerability: TibetSwap v1 experienced a security issue because it created coin announcements without currying the coin ID into the announcement message, allowing replay attacks. The fix required currying unique identifiers into announcements, demonstrating why proper curry design prevents exploits.

Best Practices and Common Mistakes

Curry Best Practices

Always use explicit byte prefixes (0x) when currying hexadecimal values. The CLVM interpreter needs to know whether you’re passing bytes or strings, and mixing these up creates subtle bugs that only appear during on-chain spending.

Test your curried puzzles extensively on testnet before mainnet deployment. Once a coin is created with a curried puzzle hash, you cannot change those curried values. If you curry the wrong public key or hash, those funds are potentially unspendable. The Chia blockchain is unforgiving of parameter mistakes.

Document your curry requirements clearly in code comments. Future developers (including future you) need to know which parameters must be curried and in what order. The SCREAMING_SNAKE_CASE convention helps, but explicit documentation prevents errors.

Common Mistakes to Avoid

The most common curry mistake is forgetting the 0x prefix on byte arguments. This makes CLVM interpret your hash as a string rather than bytes, producing an incorrect puzzle hash and creating coins you cannot spend.

Another frequent error is currying parameters in the wrong order. Chialisp curry is positional – the first -a argument fills the first curried parameter, the second fills the second, and so on. Mixing up this order creates puzzles that don’t match your expectations and fail when spent.

Password puzzles without signature requirements are inherently insecure, even with proper curry. Farmers can see the password in your spend transaction and replace your conditions with their own. Always combine password authentication with signature requirements or use passwords only for educational purposes, not real funds.

Security Considerations

Be cautious about what you curry versus what you accept as solution arguments. Curried values are visible in the compiled puzzle hash, so don’t curry sensitive information that should remain hidden until spend time. Use hashes of sensitive data (like password hashes) rather than the raw data itself.

Remember that curry doesn’t provide inherent security – it provides commitment. The security comes from how you design your puzzle logic to use those curried values. A poorly designed puzzle with perfect curry is still insecure. Always conduct thorough security audits of your puzzle logic before deploying to mainnet.

Conclusion

Mastering chialisp curry transforms you from a Chialisp beginner into someone who can build production-quality smart coins. You now understand that curry isn’t just a technical feature – it’s the foundation that makes Chia’s entire coin model practical. By pre-defining parameters in puzzle templates, you create reusable code that generates unique, secure, composable smart coins.

The modular puzzle design patterns curry enables – inner and outer puzzle layers, singleton wrappers, CAT tokens, DIDs – all build on this same principle of parameterizing general logic into specific instances. Start small by currying values into simple puzzles, then progress to composing multi-layer structures as your confidence grows.

Take action today by setting up your Chia development environment and experimenting with basic curry operations. Clone the example puzzles from the official Chialisp documentation, curry different parameters, and observe how the puzzle hashes change. Build your understanding through hands-on practice, and soon you’ll be architecting sophisticated smart coin applications that leverage curry’s full power.

Chialisp Curry FAQs

What is the difference between currying and passing solution arguments in Chialisp?

Currying in chialisp embeds parameters directly into the compiled puzzle bytecode before coin creation, making them immutable and part of the coin’s address. Solution arguments are provided at spend time and can vary with each spend. Curried values use SCREAMING_SNAKE_CASE naming, while solution arguments use lowercase.

Can I change curried values after creating a coin?

No, curried values in chialisp cannot be changed after coin creation because they’re embedded in the puzzle hash that defines the coin’s address. The only way to change curried parameters is to spend the old coin and create a new coin with a new curried puzzle. This immutability provides security guarantees.

How does chialisp curry work with CAT tokens?

Chialisp curry powers CAT tokens by embedding the TAIL program hash (defining token type) and inner puzzle (defining ownership) into every CAT coin. When you spend a CAT, the puzzle automatically curries these same values into output coins, maintaining token integrity across transactions.

What’s the best way to learn chialisp curry for beginners?

Start with the official Chialisp documentation’s currying tutorial at chialisp.com, which walks through simple multiply puzzles and password coins. Practice currying parameters using cdv clsp curry on testnet before moving to complex patterns like inner/outer puzzles. Hands-on experimentation builds understanding faster than reading alone.

Why is SCREAMING_SNAKE_CASE used for curried parameters?

The SCREAMING_SNAKE_CASE convention for chialisp curry parameters is a visual signal to developers that these values must be curried before coin creation, not passed as solution arguments at spend time. This naming pattern prevents common mistakes and makes puzzle intentions clear during code review and auditing.

Chialisp Curry Citations

1. Chialisp.com. “Currying.” Chialisp Official Documentation. https://chialisp.com/chialisp-currying/
2. Chialisp.com. “Standard Transactions.” Chialisp Official Documentation. https://chialisp.com/standard-transactions/
3. Chialisp.com. “About Chialisp.” Chialisp Official Documentation. https://chialisp.com
4. Chialisp.com. “CATs.” Chialisp Official Documentation. https://chialisp.com/cats/
5. GitHub. “py-chialisp-inner_outer: Chialisp – Inner/Outer Puzzle – Python Driver Study.” Gerald Neale. https://github.com/geraldneale/py-chialisp-inner_outer
6. Chia Network. “Introducing Chialisp.” Chia Network Blog. https://chia.net/2019/11/27/chialisp.en.html
7. Chia Documentation. “Smart Coins.” Chia Crash Course. https://docs.chia.net/guides/crash-course/smart-coins/
8. Chia Documentation. “CAT Creation Tutorial.” Chia Guides. https://docs.chia.net/guides/cat-creation-tutorial/
9. GitHub. “chialisp-web/docs/primitives/cats.md.” Chia Network. https://github.com/Chia-Network/chialisp-web/blob/main/docs/primitives/cats.md
10. Chialisp.com. “Singletons.” Chialisp Official Documentation. https://chialisp.com/docs/puzzles/singletons/
11. GitHub. “LeaveALegacy.” Daniel Perry. https://github.com/danieljperry/LeaveALegacy
12. Chialisp.com. “Common Issues.” Chialisp Official Documentation. https://chialisp.com/common_issues/