| CHIP Number | 0025 |
|---|---|
| Title | Chialisp Message Conditions |
| Description | Add new MESSAGE conditions to Chialisp |
| Author | Cameron Cooper |
| Editor | Dan Perry |
| Comments-URI | CHIPs repo, PR #98 |
| Status | Final |
| Category | Standards Track |
| Sub-Category | Chialisp |
| Created | 2024-01-30 |
| Requires | None |
| Replaces | None |
| Superseded-By | None |
The Chialisp language currently includes conditions to create and assert coin announcements and puzzle announcements. These conditions are often necessary, but not sufficient, for keeping coins secure. In fact, if announcements are used improperly, they might provide the illusion of security, even while the coins being spent remain vulnerable to attacks. This CHIP attempts to mitigate this issue by introducing two new conditions to ensure that an exact set of coins is spent together. The existing announcement conditions will continue to be usable, but they will no longer be recommended.
When forming a Chia transaction that includes multiple coin spends, it is vital to ensure that nobody (mempool watchers, Chia farmers, etc) can either separate those spends, or add any unwanted spends. Prior to this CHIP, there existed recommendations to prevent both of these scenarios, as described in the following paragraphs.
The current recommended technique to prevent the separation of spends is to use coin announcements. When multiple coins must be spent together, they should each make an announcement, as well as assert the other coins' announcements. If each coin makes and asserts the correct announcements, then all coin spends must be included for any of them to be valid. For more information, see the section on announcements in the Chialisp documentation.
The current recommended technique to prevent the addition of unwanted spends is to add the ID of the coin being spent to the announcement's message. If this ID is included, the announcement can only be asserted once. However, if the ID is omitted from an announcement's message, then multiple coins can assert the same announcement from within the same block. For more details, see the section on unprotected announcements in the Chialisp documentation.
When applied correctly to a spend bundle, the preceding recommendations will ensure that nobody can separate the coin spends from the bundle, or add any unwanted spends to it. However, if a coin neglects to create an announcement, or if it doesn't assert the announcements from every coin that must be spent with it, or if it does not include the correct coin ID in its announcement, then the coin spends could be vulnerable to attacks.
This CHIP introduces two new message conditions that will make it more difficult to create inadvertently insecure spends of the types mentioned here. These new conditions will require a soft fork, which will occur at block 5 716 000 (five million, seven hundred and sixteen thousand).
After the fork has been activated, the RPCs and other tooling for wallets will be recommended to warn against using the following conditions:
CREATE_COIN_ANNOUNCEMENT(condition code 60)ASSERT_COIN_ANNOUNCEMENT(condition code 61)CREATE_PUZZLE_ANNOUNCEMENT(condition code 62)ASSERT_PUZZLE_ANNOUNCEMENT(condition code 63)
Instead, the new conditions from this CHIP will be recommended. Note that the original conditions will continue to function as they did before the fork.
The Chialisp conditions introduced in this CHIP are backwards compatible -- if a condition is issued successfully after the CHIP has been implemented, it also would have been successful no-op beforehand.
However, the Chialisp conditions to be added are not forward compatible -- before this CHIP has been implemented, the CLVM condition codes could have been issued in an attempt to do something not specified in this CHIP. They would have resulted in successful no-ops beforehand, but they will no longer succeed afterward.
Because of the forward incompatibility of the conditions to be added, this CHIP will require a soft fork of Chia's blockchain. As with all forks, there will be a risk of a chain split. The soft fork could also fail to be adopted. This might happen if an insufficient number of nodes have been upgraded to include the changes introduced by this CHIP prior to the fork's block height.
Part of Chialisp's design includes the ability to add new condition codes with a soft fork, as is the case in this CHIP. It is likely that the only alternative implementation for adding new Chialisp condition codes would be with a hard fork, which would come with the additional risks associated with all hard forks, with no upside versus this CHIP's implementation.
As the condition codes introduced in this CHIP are optional, the primary risk associated with this CHIP's implementation would occur if the soft fork were to fail to be adopted. In this case, the condition codes would succeed, but they might not protect coins as intended.
This CHIP includes two new conditions, each of which requires a 1-byte mode parameter to commit to the sender and receiver of the message. This parameter is a bitmask of three bits for the sender, and three bits for the receiver. Only the lowest six bits are used (the highest two bits are unused).
Each bit represents whether an attribute from the coin is required (1) or not (0):
- The first bit represents the parent coin.
- The second bit represents the puzzle hash of the coin.
- The third bit represents the amount (value) of the coin.
The sender and receiver bits each use the following convention:
| Type | Bits | Parent | Puzzle | Amount |
|---|---|---|---|---|
| Coin | 111 | True | True | True |
| Parent | 100 | True | False | False |
| Puzzle | 010 | False | True | False |
| Amount | 001 | False | False | True |
| Parent-Puzzle | 110 | True | True | False |
| Parent-Amount | 101 | True | False | True |
| Puzzle-Amount | 011 | False | True | True |
| None | 000 | False | False | False |
The eight conditions from this table apply to both the sender and receiver coins. Therefore, there are 64 possible combinations (8 * 8). For example, if a specific coin sends a message, and a coin with a specific parent coin and puzzle hash receives it, the bitmask would be 111 concatenated with 110, or 111110.
Additional parameters will depend on these six bits. This enables a coin that can send a message to another coin based on a parent/puzzle/amount combination of that destination coin. The receipient coin can receive that message if it also specifies which coin sent it.
Note 1: The mode parameter must be identical for both the SEND_MESSAGE and the corresponding RECEIVE_MESSAGE. In the above example, the sender's mode parameter was 111110. In this case, the receiver's mode parameter must also be 111110 in order for the spend to succeed.
Note 2: The consensus and the mempool will each allow any of the eight possible combinations from the above table.
Both of this CHIP's conditions include a varargs (...) parameter. This parameter is required for asserting the parent coin ID, puzzle hash, and/or amount of the coin that sent or received the message, depending on the condition:
- When using
SEND_MESSAGE, the...parameter refers to the coin that will receive the message. - When using
RECEIVE_MESSAGE, the...parameter refers to the coin that sent the message.
The length of this parameter depends on mode. Continuing with the table from the previous section, the following arguments are required in the ... parameter:
| Type | Bits | Arguments required in ... |
|---|---|---|
| Coin | 111 | <coin ID> |
| Parent | 100 | <parent coin ID> |
| Puzzle | 010 | <puzzle hash> |
| Amount | 001 | <amount> |
| Parent-Puzzle | 110 | <parent coin ID> <puzzle hash> |
| Parent-Amount | 101 | <parent coin ID> <amount> |
| Puzzle-Amount | 011 | <puzzle hash> <amount> |
| None | 000 | Not used |
Note that when all three bits are set, the coin ID will be passed instead of its components parts.
Just as with existing announcement and assertion conditions, the conditions listed in this CHIP do not carry a CLVM cost. To prevent spam, there is a combined limit of 1024 announcements and assertions per spend. In addition, the message parameter has a maximum length of 1024 bytes. This limitations will apply to the new conditions from this CHIP as well.
This CHIP introduces the following new conditions:
Condition code: 66
Functionality: Sends a message using the specified mode and ... arguments
Usage: (SEND_MESSAGE mode message ...)
Note 1: If this condition's message is not received in the same block where this condition is used, the spend bundle containing this condition will fail.
Note 2: This condition can be issued multiple times, to send identical messages in a single block. In this case, there must be a separate RECEIVE_MESSAGE condition to match each SEND_MESSAGE condition, and the RECEIVE_MESSAGE condition(s) must be issed in the same block where the messages are sent. If the number of messages sent does not equal the number of messages received, the condition will fail.
Note 3: The message parameter has a maximum size of 1024 bytes.
Condition code: 67
Functionality: Receives the message using the specified mode and ... arguments
Usage: (RECEIVE_MESSAGE mode message ...)
There are a large number of test cases in /crates/chia-consensus/src/gen/conditions.rs:
-
test_message_strict_args_count() makes sure we allow unknown additional parameters, unless
STRICT_ARGS_COUNTis set (i.e. mempool mode) -
test_message_conditions_single_spend() has test cases where a single spend sends a message to itself. Some valid in mempool mode, some not.
-
test_limit_messages() ensures that the 1024 limit applies to these new conditions, just like it does to the existing create announcement and assert announcement.
-
test_message_conditions_failures() ensures parse failures are correctly caught and yields the expected error code.
-
test_message_conditions_two_spends() has test cases where one spend sends a message to another spend.
-
test_all_message_conditions() programatically generates all combinations of messages that can be sent from one spend to another. These are only positive tests.
-
test_message_eligible_for_ff() tests all combinations of messages between coins where one coin is eligible for fast-forward. The test ensures that it remains eligible as long as its parent ID is not committed to by the message (both by sending or receiving a message).
Testing of the message conditions is also covered in PR #17819, specifically in the following locations:
This CHIP was implemented in PR #430 of the chia_rs repository.
The fork height and message conditions were implemented in PR #17772 of the chia-blockchain repository.
We renamed the fork to soft fork 4 in PR #17799. The previous name, soft fork 3, had been used in a different fork. We renamed this fork in order to avoid confusion between the two.
We updated the activation block height in PR #17892.
Chia Network, Inc. has conducted an internal review of the code involved with this CHIP.
None
Copyright and related rights waived via CC0.