Clawback Primitive Guide
Intro
This document will show you how to use Chia's standalone clawback primitive. Wallet developers are welcome to integrate it into their GUI wallets.
For additional technical resources, see the following:
- The standalone clawback primitive doesn't implement wallet functionality to handle incoming clawbacks and resync deleted coin stores. Rather, it's for developers to understand the process of how clawbacks work.
- Chia Network, Inc has added a user-friendly implementation of the clawback primitive to version 1.8.2 of the reference wallet.
- A synced full node AND a synced wallet are required to use the clawback primitive.
- You are recommended to test the clawback primitive on either the testnet or a simulator before moving to mainnet. For your reference, this guide will use testnet10.
- The clawback primitive currently only supports XCH/TXCH. It does not support CATs or NFTs. The
-w
flag will be ignored if it points to a non-XCH (or TXCH) wallet.
About clawback
The clawback primitive was designed to guard against sending Chia assets to an incorrect address. The principal behind clawback is simple: it is an intermediate coin that cannot be sent to the destination address until a timelock has expired. In the meantime, the Sender can "claw back" the coin, returning it to their wallet in the form of standard XCH.
An Alice-Bob will demonstrate this:
- Alice wants to send 1 XCH to Bob, and she wants to verify that she has entered Bob's address correctly in her wallet.
- With this in mind, Alice creates a clawback coin with the following features:
- It exists on Chia's blockchain
- It is viewable by Alice's and Bob's wallets, as well as by block explorers
- It is worth 1 XCH, funded from Alice's wallet
- It has a 1-hour timelock
- It contains Alice's address as its clawback destination (Alice -- and no one else -- can modify this later)
- It contains Bob's address as its final destination (Bob -- and no one else -- can modify this later)
- The clawback coin therefore contains the following logic for how it may be spent:
- Before 1 hour has elapsed since the coin's creation, Alice can use p2_1_of_n to spend the coin using the same public/private key pair that created the coin. When the coin is spent in this way, a new coin is created using p2_puzzle_hash. Typically, this coin will be created in Alice's wallet, but it could be created in another wallet instead. The new coin uses the standard Chia puzzle. This is the
clawback
case. - Before 1 hour has elapsed since the coin's creation, nobody other than Alice may spend it
- After 1 hour, the timelock elapses. At this point Bob can spend the clawback coin. When this spend occurs, by default a new standard XCH coin is created in Bob's wallet. Bob can also pass in a different address than the one he originally specified if he so chooses.
- Note that the coin's clawback logic is in place for the life of the coin. This means that until the coin is spent, Alice is able to claw it back. This is true regardless of the coin's age. Because of this, after the timelock expires, Bob must spend the clawback coin in order to receive the XCH in his wallet. After this spend has completed, the clawback coin no longer exists, and the spend is final.
- Before 1 hour has elapsed since the coin's creation, Alice can use p2_1_of_n to spend the coin using the same public/private key pair that created the coin. When the coin is spent in this way, a new coin is created using p2_puzzle_hash. Typically, this coin will be created in Alice's wallet, but it could be created in another wallet instead. The new coin uses the standard Chia puzzle. This is the
This guide will show you how to perform the logic outlined above:
- Create a clawback coin
- Claw back the coin
- Claim the clawback coin
As well as a few other interesting clawback cases.
We'll start by showing you how to install the clawback primitive. This guide assumes you are running a Chia node and wallet, using mainnet, the testnet, or a simulator.
The values used in the commands from this guide are just examples. You will need to update them with the equivalent values from your local node.
Install the clawback primitive
The clawback primitive is included in the Chia-Network
organization's chia-clawback-primitive
GitHub repository.
-
Open a new terminal window and run the following command to clone the
chia-clawback-primitive
repository, using themain
branch:git clone https://github.com/Chia-Network/chia-clawback-primitive.git -b main
-
Change to the cloned repository:
cd chia-clawback-primitive
-
Create and activate a virtual environment:
- Windows
- Linux
- macOS
python -m venv venv
.\venv\Scripts\Activate.ps1
python3 -m venv venv
. ./venv/bin/activate
python3 -m venv venv
. ./venv/bin/activate
- Install the clawback primitive:
pip install .[dev]
Several packages will be installed, including a bundled copy of chia-blockchain
. This process will typically take a few minutes.
- The clawback primitive should now be installed and configured properly. To test it, run:
clawback --version
You should be shown the current version of the clawback primitive. For example:
clawback, version 0.1.dev19
At this point, you are ready to use the clawback primitive.
Create a clawback coin
For this example, we will use two wallets: a Sender and a Recipient. The Sender has a balance of 10 TXCH and the Recipient has 0 TXCH.
For your reference, here is the Sender wallet's info:
chia wallet show -f 3807629793
Result:
Wallet height: 2391281
Sync status: Synced
Balances, fingerprint: 3807629793
Chia Wallet:
-Total Balance: 8.0 txch (8000000000000 mojo)
-Pending Total Balance: 8.0 txch (8000000000000 mojo)
-Spendable: 8.0 txch (8000000000000 mojo)
-Type: STANDARD_WALLET
-Wallet ID: 1
To create the clawback coin from the Sender's wallet, run the clawback create command. The -t
(Recipient's address) and -a
(amount in XCH/TXCH) flags are required. By default, the clawback coin will be locked for two weeks. For this demo, we will override the default by using the -l
flag to specify a timelock period of 600 seconds. We will also use the -m
flag to include a fee of 0.000275 TXCH.
The testnet is constantly being dusted (filled with small transactions) in order to simulate a busy network. Because of this you are always recommended to include a fee with testnet transactions. The 275-million mojo fee from this demo should be sufficient to push your transactions through in the next transaction block.
If you are running on mainnet, a fee of 275 million mojos is likely higher than the recommended amount. The reference wallet GUI will suggest an appropriate fee to be included with all transactions.
The Sender will run the following command in this example (once again, these are only example settings; replace the values as needed):
clawback create -t txch1czxl4c42kwem8jllm4xp78jt7t0j0pu9uh9xw5jddegcu703xnpsqaaxxx -a 0.1 -l 600 -m 0.000275
Result:
Created Coin with ID: 29056b320b380c0fc4834578ca30318ae9c1d1cddbe39a91197870c4dc474532
Coin { parent_coin_info: dcedd4d573679302ee3f2a54fb51c437b8156e8cd5b1c3c08d25cadf83292c3d, puzzle_hash: 13cb7ce11775a5b42754fb382eb94c846e4be677e6d55bf665b23c075a54e930, amount: 100000000000 }
As a result of running this command, a new clawback coin has been created on the blockchain, the details of which are shown above. To view this coin, along with other clawback coins created by this wallet, run the clawback show command:
clawback show
The basic details of the clawback coin are given:
clawback show
Updating coin records...
Coin ID: 29056b320b380c0fc4834578ca30318ae9c1d1cddbe39a91197870c4dc474532
Amount: 0.1 XCH (100000000000 mojos)
Timelock: 600 seconds
Time left: 518 seconds
Claw back a coin
This guide will continue from the previous section, where we created a new clawback coin, which has not yet been spent. As a reminder, these are the clawback coin's details:
clawback show
Result:
Updating coin records...
Coin ID: 29056b320b380c0fc4834578ca30318ae9c1d1cddbe39a91197870c4dc474532
Amount: 0.1 XCH (100000000000 mojos)
Timelock: 600 seconds
Time left: 518 seconds
The same public/private key pair that created this coin must be used to claw it back.
The Sender will use the clawback claw command, passing in the ID of the coin to claw back:
clawback claw -c 29056b320b380c0fc4834578ca30318ae9c1d1cddbe39a91197870c4dc474532 -m 0.000275
As a result, the clawback coin will be spent:
Submitted spend to claw back coin: 29056b320b380c0fc4834578ca30318ae9c1d1cddbe39a91197870c4dc474532
To show the status of the clawback, run the clawback show
command once again:
clawback show
Result:
Updating coin records...
No coins found
After the clawback transaction has completed, the Sender wallet's balance has increased (minus transaction fees):
chia wallet show -f 3807629793
Result:
chia wallet show -f 3807629793
Wallet height: 2405004
Sync status: Synced
Balances, fingerprint: 3807629793
Chia Wallet:
-Total Balance: 7.99945 txch (7999450000000 mojo)
-Pending Total Balance: 7.99945 txch (7999450000000 mojo)
-Spendable: 7.99945 txch (7999450000000 mojo)
-Type: STANDARD_WALLET
-Wallet ID: 1
At this point, the clawback coin no longer exists. The Sender is of course free to create new clawback coins as they see fit.
Claim a clawback coin
In this section, we'll show how to claim a clawback coin. First, the Sender creates a new clawback coin with a 60-second timelock:
clawback create -t txch1czxl4c42kwem8jllm4xp78jt7t0j0pu9uh9xw5jddegcu703xnpsqaaxxx -a 0.1 -l 60 -m 0.000275
Result:
Created Coin with ID: ef4b69e65e99261d6e30c8d2d331a8ed84995f3452b95aaa944f76a0f9af74c5
Coin { parent_coin_info: f5e408a15299df27a00d0403ea50ed29a06f87a31b638cff1b63ef3e6060b45a, puzzle_hash: 2e91566d9549cb909109d147c79b457d15ced2d8a24dea5a125b1e5c05cdd1ec, amount: 100000000000 }
The Sender can run the clawback show
command to show the details of each of their clawback coins:
clawback show
Result:
Updating coin records...
Coin ID: ef4b69e65e99261d6e30c8d2d331a8ed84995f3452b95aaa944f76a0f9af74c5
Amount: 0.1 XCH (100000000000 mojos)
Timelock: 60 seconds
Time left: 23 seconds
The timelock expires when the Time left:
value reaches 0 seconds
:
clawback show
Result:
Updating coin records...
Coin ID: ef4b69e65e99261d6e30c8d2d331a8ed84995f3452b95aaa944f76a0f9af74c5
Amount: 0.1 XCH (100000000000 mojos)
Timelock: 60 seconds
Time left: 0 seconds