可撤回交易原语使用指南
Intro
This document will show you how to use Chia's standalone clawback primitive. 欢迎钱包开发者将其整合到开发的GUI钱包中。 欢迎钱包开发者将其整合到开发的GUI钱包中。
有关其他技术资源,请参阅以下内容:
- 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. 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 a testnet.
- 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.
关于可撤回交易(clawback)
可撤回交易原语的目的是防止将Chia资产发送到一个错误的地址。 可撤回交易的原理很简单:它是一种中间硬币,直到时间锁定过期之前,无法发送到目标地址。 与此同时,发送者可以"撤回"该硬币,将其以标准XCH的形式退回到他们的钱包中。
下面使用A、B两人来进行演示:
- 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. 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 theclawback
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
For your reference, the Recipient wallet currently has a balance of 0 XCH:
chia wallet show -f 1231588123
Result:
Wallet height: 2405060
Sync status: Synced
Balances, fingerprint: 1231588123
Chia Wallet:
-Total Balance: 0.0 txch (0 mojo)
-Pending Total Balance: 0.0 txch (0 mojo)
-Spendable: 0.0 txch (0 mojo)
-Type: STANDARD_WALLET
-Wallet ID: 1
The Recipient (or anyone else) can view the status of the clawback coin if they know the coin ID:
clawback show -c ef4b69e65e99261d6e30c8d2d331a8ed84995f3452b95aaa944f76a0f9af74c5
Result:
Updating coin records...
Coin ID: ef4b69e65e99261d6e30c8d2d331a8ed84995f3452b95aaa944f76a0f9af74c5
Amount: 0.1 XCH (100000000000 mojos)
Timelock: 60 seconds
Time left: 0 seconds
The value of Time left:
is 0 seconds
. In most cases (see the info box below for more info), the Recipient can now run the clawback claim command to claim the coin:
clawback claim -c ef4b69e65e99261d6e30c8d2d331a8ed84995f3452b95aaa944f76a0f9af74c5
Result:
Submitted spend to claim coin: ef4b69e65e99261d6e30c8d2d331a8ed84995f3452b95aaa944f76a0f9af74c5
In most cases, if the output of the clawback show
command contains Time left: 0 seconds
, this indicates that the Recipient can proceed with the claim
call.
However, there is a small window of time where the timer has expired, but a block still hasn't been farmed with a timestamp after the expiry. If the Recipient attempts to make the claim
call during this window, they will receive the following error:
You are trying to claim the coin too early
In this case, the Recipient needs to wait for one more transaction block to be farmed before proceeding with the claim
call. As a reminder, a new transaction block is farmed every 52 seconds, on average. As a reminder, a new transaction block is farmed every 52 seconds, on average.
While the claim
transaction is being processed, it will show in the Pending Total Balance:
of the Recipient's wallet:
chia wallet show -f 1231588123