This document is a guide for using the clawback functionality introduced in version 1.8.2 of Chia's reference wallet. Clawback is a new feature that offers protection against sending XCH to the wrong address.
If you are a developer or a CLI user, see the following resources for more info:
- Clawback Standalone Primitive Guide
- Clawback Standalone Primitive CLI Reference
- Youtube video explaining clawback
In order to use Chia clawbacks, you must have:
- Version 1.8.2 or later of Chia's reference light wallet or full node. See our downloads page to obtain a copy.
- A sufficient amount of XCH or TXCH to send a transaction and pay fees. If you do not have a sufficient amount, you can obtain some from our mainnet and testnet faucets.
Clawback allows the sender of XCH to return funds to their wallet during a fixed window of time before the transaction can be completed.
The following demonstrates an example workflow of this process:
- The sender sets up a 1-XCH transaction to the receiver's wallet, and adds a 10-minute clawback
- Instead of being sent directly to the receiver's wallet, the 1 XCH is sent to an intermediate location (see below for an explanation)
- For the next 10 minutes:
- The sender and receiver both see the pending 1-XCH transaction in their wallets
- The sender can choose to return the 1 XCH to his/her wallet (this is a clawback)
- The receiver cannot yet claim the money
- The sender and receiver could communicate off-chain. For example, the sender could call the receiver and ask if the pending transaction appears in their wallet.
- If yes, then both parties can be confident that the money was sent to the correct address
- If no, then the money was sent to an incorrect address, so the sender will claw it back
- After 10 minutes, if the sender has not clawed the 1 XCH back, the receiver can claim it
- After the receiver has claimed the money, it appears in both wallets as a normal transaction. At this point, the transaction is complete; clawback is no longer possible
The "intermediate location" is actually a coin with two rules:
- Before a certain timestamp, only the sender can spend the coin
- After the timestamp, the receiver can also spend the coin
Nobody else is allowed to spend the coin. It is not held in escrow by any third parties. It is a decentralized solution, created in Chialisp, that is one of many potential custody options in Chia.
This guide will show you how to perform the above workflow.
Before initiating a clawback transaction, it's a good idea to review your wallet's settings. Click
Settings (the gear icon in the lower-left corner of your wallet) and click the
From this menu:
- The Sender wallet can enable clawback for all outgoing transactions
- The Receiver wallet can automatically claim all clawback transactions by adding a default transaction fee
For this tutorial, both of these settings will be disabled:
This section will show you how to initiate a transaction and claw it back.
SEND menu as shown below, enter the recipient's address, the amount to send, and an optional blockchain fee.
- Prior to initiating the transaction, the sender's wallet from this example contained 5 TXCH. The amount to be sent was 1 TXCH.
- This example was executed on Chia's testnet, which has higher fee requirements than mainnet. For this reason, a large fee of 100 million mojos was added.
After you have entered these parameters, click the dropdown for
Add option to claw back transaction.
Add the time (days, minutes, hours) during which the transaction will be able to be clawed back. In this case, we'll use 10 minutes.
Optionally add a memo to describe this transaction, and click
The transaction has been added to the mempool. This means that it is still in the
Pending state for inclusion on the blockchain. At this point, there is no indication in the GUI that this is a clawback transaction.
Eventually the clawback transaction will be confirmed on the blockchain. Note that the average time between transaction blocks is 52 seconds. Depending on how busy the mempool is, as well as the size of the included fee, confirmation could take much longer.
After the transaction has been confirmed, a green
CLAW BACK THIS TRANSACTION button will appear. This means that the recipient can also see this transaction, but has yet to claim it. While the transaction is in this state, you can claw it back by clicking the button, which will be demonstrated next.
clawback action requires another on-chain transaction. Enter a transaction fee and click
CLAW BACK TRANSACTION to claw it back.
Just like the original transaction, the clawback will require some time to be confirmed on the blockchain.
After the clawback has been confirmed, the pending amount is returned to the sender's wallet.
In this example, the wallet started with 5 TXCH. Because of the two transaction fees, it now contains 4.9998 TXCH.
At this point, the transaction is final. The sender has the same amount of XCH they started with, minus the two transaction fees. Due to the clawback, the original "receiver" did not receive anything.