Key Takeaways:
- Offer-to-claim flows use partial spend bundles that let someone else claim coins later under specific conditions
- Settlement puzzles control when and how claim spends are allowed, creating trustless exchanges
- Atomic transactions ensure all parts of an offer happen together in one block or not at all
- Using announcements and signatures together keeps your coins safe from farmers who might try to steal them
- Common mistakes like password-only security or missing coin IDs in announcements can lead to lost funds
Article Summary: Chialisp offer files secure trading creates partial transactions where one person makes an offer and another person claims coins under specific rules. Settlement puzzles enforce these rules automatically, while atomic transactions guarantee everything happens together safely in one block.
What Are Chialisp Offer-to-Claim Flows
Think of offer-to-claim flows like leaving a locked treasure chest with instructions for someone else. You create the chest (the offer), lock it with specific rules (the settlement puzzle), and someone else can claim the treasure later if they follow those rules exactly. This is how Chia Network enables trustless peer-to-peer exchanges without needing a middleman.
An offer-to-claim flow in Chialisp combines two main pieces. First, there is an offer file that acts like an incomplete transaction. This offer describes what the maker gives away and what they want to receive. Second, there are settlement puzzles that control the coins created by that offer. These puzzles enforce the rules about who can claim those coins and when they can do it.
The beauty of this system is that nobody needs to trust anyone else. The blockchain enforces all the rules automatically. If someone tries to cheat or change the terms, the whole transaction fails. This trustless design makes chialisp offer files secure trading perfect for trading tokens, creating payment channels, and building complex smart contracts powered by Chialisp that involve multiple parties.
The Core Components of an Offer
Every offer contains several important pieces that work together. The maker creates a partial spend bundle where their coins get spent into settlement puzzles. These puzzles are special programs that define exactly how the new coins can be claimed. The offer also includes “requested payments” which are described as notarized payments that a taker must satisfy.
When you create an offer, you are not making a complete transaction that can go on the blockchain right away. Instead, you are creating half of a transaction that waits for someone else to complete it. The settlement coins created by your offer have puzzles that enforce specific conditions like requiring the right signature, waiting for a certain block height, or checking for matching announcements.
How Atomic Transactions Protect Both Parties
Chia’s blockchain processes all events in a block at the exact same time. This means there is never a moment where one person has both assets or where neither person has anything. The offer and the acceptance either both succeed together in one block, or they both fail completely. This atomic nature prevents anyone from running away with half of a trade.
For example, imagine you want to trade 10 XCH for 1000 CAT tokens. You create an offer that burns your 10 XCH and requests 1000 CAT tokens. Someone else who has those tokens can take your offer by adding their own partial transaction that provides the tokens and claims your XCH. Both parts get combined into one spend bundle that either completes entirely or fails entirely.
Understanding Settlement Puzzles and Claim Conditions
Settlement puzzles are the smart contracts that control how offer-to-claim flows work. When a maker creates an offer, they specify settlement puzzles for the coins that will be created. These puzzles encode rules like “these funds may be claimed later if condition X is satisfied.” The conditions might require a specific public key signature, a matching announcement from another coin spend, or waiting until a certain block height passes.
The claim spend happens later when someone wants to actually get those coins. They create a transaction that spends the settlement coin with a solution that proves they meet all the requirements. If they have the right key, or the right timing, or whatever else the puzzle demands, the claim succeeds and they get the coins. If not, their transaction fails and the coins stay locked.
Common Use Cases for Timed Claims
Timed payouts are one popular use for offer-to-claim patterns. You might create an offer that locks funds until a future block height, giving someone else the ability to claim those funds but only after enough time has passed. This works like a time-locked payment or a delayed reward system. The settlement puzzle checks the block height and only allows the claim spend if enough blocks have been mined since the offer was accepted.
Another common use is streaming payments where the initial offer sets up a smart coin that releases funds over time. The receiver can periodically claim rewards or portions of the streamed amount from that coin. Each claim transaction spends a settlement coin and creates a new one with updated state, allowing the stream to continue.
Pooling: A Real-World Offer-to-Claim Example
Chia’s pooling system provides a perfect real-world example of offer-to-claim flows in action. When farmers join a pool, they create a special singleton (a unique coin) that uses settlement puzzles to ensure pool rewards go to the right place. The singleton allows the pool to claim block rewards that farmers win, while preventing the farmer from stealing those rewards prematurely.
When a farmer finds a block, 7/8 of the reward (0.875 XCH as of January 2026, after the first halving) goes into their singleton. The pool can then claim these rewards by spending the singleton with proof they should receive the funds. The settlement puzzle verifies everything matches correctly, including the pool’s target address and the reward amount. This creates a trustless arrangement where neither the farmer nor the pool can cheat the other.
The Maker-Taker Flow Explained Simply
The offer-to-claim process involves two main roles. The maker creates the initial offer, and the taker accepts it by completing the transaction. Understanding this flow helps you see how chialisp offer files secure trading works without any central authority or escrow service.
What the Maker Does
The maker starts by constructing a partial spend bundle. They decide what assets they want to give away and what they want to receive in return. Their wallet creates special puzzles called settlement payment puzzles that will control the coins created in the trade. The maker signs their part of the transaction and shares the resulting offer file through email, social media, a website, or any other method they choose.
During this process, the maker’s wallet calculates announcements that need to be asserted for the payment to work correctly. These announcements act like cryptographic receipts that prove all parts of the transaction are happening together. The offer file contains all this information in a format that takers can verify and complete.
What the Taker Does
When someone wants to accept an offer, they first receive and import the offer file into their wallet. The taker’s wallet validates that the offer is legitimate and hasn’t been tampered with. Then the taker creates their own partial transaction that provides the requested assets (like CAT tokens or NFTs) and claims the assets offered by the maker (like XCH).
The wallet combines both partial transactions into a single spend bundle. This combined bundle includes all the coin spends, all the announcements, and all the signatures needed from both parties. Finally, the taker submits this complete spend bundle to the mempool where miners will include it in a block. Because Chia processes everything atomically, both parties get exactly what they expected or the whole trade fails.
How Announcements Keep Offers Secure
Announcements are cryptographic messages that coins create when they get spent. They serve as proof that specific spends are happening together in the same block. For chialisp offer files secure trading, announcements prevent attackers from separating parts of a transaction or adding unwanted spends that could steal funds.
Coin announcements and puzzle announcements work together to create an unbreakable link between different coin spends. A coin announcement ties a message to a specific coin’s ID, while a puzzle announcement ties a message to a puzzle hash. Other coins can assert these announcements, meaning they require proof that certain announcements exist before they will successfully spend.
ASSERT_COIN_ANNOUNCEMENT and Why It Matters
The ASSERT_COIN_ANNOUNCEMENT condition tells a coin “I will only spend if this other specific coin also spends with this exact message.” This creates a dependency where multiple coins must be spent together. For offers, this ensures the maker’s coins and the taker’s coins all spend in the same block or not at all.
The announcement ID gets calculated by hashing together the coin ID and the message. This means you cannot fake an announcement from a different coin, and you cannot reuse the same announcement multiple times unless you intend to. When settlement puzzles use announcements correctly, they create ironclad security that prevents partial executions or replay attacks.
Modern Best Practices: SEND_MESSAGE and RECEIVE_MESSAGE
Newer versions of Chialisp introduced SEND_MESSAGE and RECEIVE_MESSAGE conditions that improve on the older announcement system. While ASSERT_COIN_ANNOUNCEMENT and CREATE_COIN_ANNOUNCEMENT still work, the modern conditions make it harder to accidentally create insecure spends. They enforce stricter requirements about how messages get used.
These new conditions prevent common mistakes like forgetting to include coin IDs in announcement messages. However, when working with older coins or existing protocols, you still need to understand the traditional announcement system since many offer-to-claim flows were built before these new conditions existed.
Critical Safety Mistakes to Avoid
Security in Chialisp requires understanding what can go wrong. Many beginners make similar mistakes that put their coins at risk. Learning these common problems helps you write safer code from the start and avoid losing funds to preventable attacks.
Never Use Password-Only Security
Password-secured coins seem simple to create, which makes them popular in tutorials. You hash a password, curry it into a puzzle, and require that hash to spend the coin. The problem is that farmers can see passwords in transaction solutions. When you submit a spend to the mempool, every farmer can read the password you used. A malicious farmer can then change where your coins go before adding your transaction to their block.
Instead of passwords, always use announcements combined with the AGG_SIG_ME condition. This creates a cryptographic signature that proves you authorized the transaction. If anyone tries to modify your solution, the signature becomes invalid and the spend fails. This protects your coins even if farmers can see everything in your transaction.
Protect Announcements with Coin IDs
Creating announcements without including the coin ID in the message creates a replay attack vulnerability. Multiple coins can assert the same announcement if you omit the coin ID. This means an attacker might use your announcement multiple times to claim coins you did not intend to release.
For example, the original TibetSwap v1 created coin announcements with just keywords like “mint” or “burn” without coin IDs. This allowed the same announcement to be asserted multiple times in the same block, leading to a vulnerability where attackers could drain liquidity pools. The fix required including the singleton coin ID in every announcement to prevent replay attacks. TibetSwap v2 has operated securely since May 2023 using this corrected approach.
Only Use Announcements in Solutions, Not Puzzles
If you put ASSERT_COIN_ANNOUNCEMENT directly in a coin’s puzzle (instead of in the solution), you create a dangerous situation. The assertion requires a specific coin to be spent in the same block. If that other coin gets spent before your coin, your coin becomes permanently unspendable or “bricked.” There is no way to remove that assertion from the puzzle.
By keeping assertions in the solution instead of the puzzle, you maintain flexibility. If the coin you wanted to assert has already been spent, you can just use a different solution later that does not include that assertion. This prevents your coins from becoming permanently locked due to timing issues.
Verify Component Lengths When Hashing
Some puzzles concatenate values like parent coin ID, puzzle hash, and amount before hashing them together. If you do not verify the length of each component, an attacker can shift bytes between components. For instance, they might shift one byte from the puzzle hash into the amount field, changing the coin value while still producing a valid hash.
The solution is using a function that verifies parent coin ID and puzzle hash are each exactly 32 bytes, and that amount is at least zero. This prevents byte-shifting attacks that could let someone claim more coins than they should.
Building Your First Offer-to-Claim Flow
Creating a simple offer-to-claim flow helps you understand the concepts in practice. Start with a basic timed payment where you lock coins that someone can claim after a certain number of blocks have passed. This introduces settlement puzzles and claim conditions without too much complexity.
Your settlement puzzle needs to check the block height using assertions. Chialisp provides conditions that let you assert the current block height is above a certain value. When someone tries to claim the coins, your puzzle checks if enough blocks have been mined. If yes, it creates conditions to release the coins. If no, it fails and the coins stay locked.
Implementing Settlement Puzzle Logic
The settlement puzzle typically curries in important values like the claimer’s public key hash and the unlock block height. When the puzzle runs, it receives a solution containing the signature and any other data needed to prove the claim is valid. The puzzle verifies the signature matches the curried public key, checks the block height meets requirements, and creates coin conditions to release the funds.
Remember to include proper announcements that prevent farmers from modifying the destination of your coins. Use CREATE_COIN_ANNOUNCEMENT with the coin ID included in the message, and make sure any coins claiming your settlement coins assert that announcement. This creates the atomic link that keeps everything secure.
Testing with Small Amounts First
Always test new offer-to-claim flows on testnet before using real money. Create offers with tiny amounts of TXCH (testnet XCH) to verify your settlement puzzles work correctly. Try to break your own code by attempting different attacks. Can you claim coins early? Can you redirect them to a different address? Can you replay announcements?
If your test coins get stolen or locked, you learned something valuable without losing real money. Once you have tested thoroughly and understand all the security implications, you can consider deploying on mainnet. Even then, start with small amounts until you have proven your code works in production.
Expert Insights on Chialisp Security
According to Bram Cohen, Chia’s founder, “Writing actually secure and auditable code in Chialisp is easier than in Solidity because mistakes tend to make things simply fail rather than having security problems.” This fail-safe design philosophy means Chialisp puzzles are less likely to have hidden vulnerabilities compared to other smart contract languages.
The official Chialisp documentation emphasizes that “when creating smart coins, security concerns should be at the front of your mind. The language is specifically designed to secure money on a network with no centralized authority to enforce rules. The only thing standing in the way of attackers and potentially large sums of money is how you design smart coins.”
Real-World Case Study: Chia Pooling Protocol
Chia’s innovative blockchain pooling system demonstrates offer-to-claim flows at scale. Over 30 exabytes of storage participate in pooling using singleton smart coins that implement sophisticated settlement and claim logic. Farmers create plot NFTs (singletons) that allow pools to claim 7/8 of block rewards (currently 0.875 XCH per block after the 2024 halving) while farmers retain the other 1/8 plus all transaction fees.
The pool periodically scans the blockchain for new rewards sent to farmer singletons, then submits claim transactions that send pool rewards to the pool’s target address. This system has processed thousands of block rewards without major security incidents since the pooling protocol launched in mid-2021.
Conclusion
Chialisp offer files secure trading gives you powerful tools for creating trustless exchanges and smart contracts on Chia. By combining settlement puzzles, atomic transactions, and proper announcement usage, you can build systems where nobody needs to trust anyone else. The blockchain enforces all rules automatically, preventing both parties from cheating. Start with simple examples, test thoroughly on testnet, and always prioritize security over convenience. With careful design and proper testing, you can create offer-to-claim flows that safely handle real value in production environments.
Chialisp Offer-to-Claim Flows FAQs
What are chialisp offer-to-claim flows used for?
Chialisp offer-to-claim flows enable trustless peer-to-peer exchanges where one party creates an offer and another party claims coins under specific conditions. They are commonly used for token swaps, timed payments, streaming rewards, and pooling protocols where security and atomicity are critical.
How do chialisp offer-to-claim flows prevent cheating?
Offer-to-claim flows use atomic transactions where all parts complete together in one block or fail completely. Settlement puzzles enforce rules automatically, and announcements create cryptographic links between coin spends that prevent separation or modification by malicious actors.
Can I use chialisp offer files secure trading for NFT trades?
Yes, chialisp offer files secure trading works perfectly for NFT trading. You can create an offer that swaps XCH for an NFT, or trade one NFT for another. The atomic nature ensures both parties receive their assets simultaneously or the trade does not happen at all.
What happens if someone modifies my offer file?
Any modification to an offer file invalidates the cryptographic signatures and announcements it contains. When a taker tries to submit a modified offer, the blockchain rejects it because the signatures no longer match. This protects both maker and taker from tampering.
Why should I avoid using ASSERT_COIN_ANNOUNCEMENT in puzzles?
Using ASSERT_COIN_ANNOUNCEMENT directly in a puzzle creates a permanent requirement that a specific coin must be spent alongside your coin. If that other coin gets spent before yours, your coin becomes permanently unspendable or “bricked” because the puzzle cannot change its assertions.
Chialisp Offer-to-Claim Flows Citations
Chialisp Documentation – Offers Overview: https://chialisp.com/offers/
Chialisp Documentation – Common Issues and Security: https://chialisp.com/common_issues/
Chialisp Documentation – Conditions Reference: https://chialisp.com/conditions/
Chialisp Documentation – Pooling Protocol: https://chialisp.com/pooling/
Chia Network – Pool Protocol Summary: https://docs.chia.net/pool-protocol/
Chia Network – Offers CLI Tutorial: https://chialisp.com/docs/tutorials/offers_cli_tutorial/
GitHub – CHIP-0025 Message Conditions: https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0025.md
Bram Cohen Substack – Ongoing Chialisp Development: https://bramcohen.com/p/ongoing-chialisp-development
Chia Network – Pool Reference Implementation: https://github.com/Chia-Network/pool-reference
Chialisp Documentation – CATs (Chia Asset Tokens): https://chialisp.com/cats/
