* UTXO sharing schemes like Ark, CoinPools, Timeout Trees, etc. use various types of output restrictions in order to enable multiple parties to share the control of a UTXO, while ensuring that each participant controls their own balance.
* <code>OP_VAULT</code><ref>[[bip-0345.mediawiki|BIP-345]]</ref> is a proposed opcode to implement a 2-step withdrawal process, enabling on-chain reactive security.
* <code>OP_CHECKTEMPLATEVERIFY</code><ref>[[bip-0119.mediawiki|BIP-119]]</ref> is a long-proposed opcode to constrain a transaction to a ''template'' with a fixed set of outputs.
* Sidechains and rollups could be implemented via a UTXO encumbered with a recursive covenant, updating the sidechain state root every time it is spent.
Constructions like BitVM<ref>https://bitvm.org/</ref> try to side-step the lack of a primitive allowing UTXOs to carry
state with a clever use of Lamport Signatures, and optimistic execution of smart contracts. This comes with an extremely
high cost in term of complexity, interactivity, and (potentially) in block size occupation, for some of the possible
execution paths. Moreover, the design of fully trustless bridges remains elusive.
Rather than providing a construct optimized for a specific application, this BIP aims to provide a fundamental building
block that is widely applicable, and common to many constructions.
== Design ==
<code>OP_CHECKCONTRACTVERIFY</code> is an implementation of a new primitive that could be called
''state-carrying UTXOs''. It allows to embed a commitment to a piece of data in a UTXO, and to validate it during the
execution of the script, and ''carry'' a (possibly dynamically computed) piece of data to the new UTXOs that are
produced.
We consider the ''program'' of a P2TR UTXO to be composed of an x-only public key (that we call the ''naked key''), and
a Merkle tree of scripts. If there is no data committed in the UTXO, then the naked key is the internal key as defined
in BIP-341.
If the UTXO carries a commitment to a 32-byte hash (the ''data''), the naked key is tweaked with a hash of the data.
The resulting key is the taproot internal key per BIP-341.
This allows to embed a commitment to the data that can be validated during the script execution, while staying fully
compatible with taproot. Notably:
* the committed data does not make the UTXO any larger;
* the keypath spend is still available to any party that possesses the private key of the naked key, as long as they have knowledge of the embedded data (or at least the data’s hash)<ref>For example, in a multi-party contract, the naked key could be an aggregate key using [[bip-0327.mediawiki|MuSig2]]; the taproot keypath would therefore allow a ''cooperative'' spend, without executing any script at all. Like for all taproot transactions, this is indeed the
cheapest way of spending the UTXO — albeit not always possible in practice.</ref>;
* if multiple scripts are in different leaves of the taptree, only the ones that actually need to access the data have to pay a cost for it, in terms of additional witness bytes.
<code>OP_CHECKCONTRACTVERIFY</code> can be applied to introspect the program and data of one of the inputs of the
transaction (typically, the UTXO being spent, in order to access its committed data), or one of the outputs of the
transaction (in order to define its program, and possibly its committed data).
=== Output amounts ===
When checking the script of one or more outputs with <code>OP_CHECKCONTRACTVERIFY</code>, it is usually necessary to
also check that the amount of the current input (that is, the UTXO being spent) is correctly distributed among the
outputs in the expected way. Therefore, the opcode already includes an amount semantic that covers the common use cases.
There are three supported modes for the opcode when checking an output, depending on the value of the <code>mode</code>
parameter:
* ''default'': the residual amount of the current input must be preserved in the output (aggregate across the inputs that specify the output);
* ''ignore'': the output amount is ignored.
* ''deduct'': the amount of the checked output is subtracted from the amount of the current input (the residual amount is then available for further checks);
The ''default'' logic covers the common case where a UTXO’s full amount is required to be sent to a specific output.
The ''deduct'' logic allows to assign portions of the input amount to one or more outputs; the residual amount, checked
with a final check using the ''default'' logic, can be used to enforce that the total amount is preserved.
The following figures illustrate some common examples of supported use cases for the amount logic. This list is not
exhaustive, as there are many more possible combinations.
'''Remark:''' validation fails if the amount of an output is checked with both the ''default'' and the ''deduct'' logic
in the same transaction, or multiple times with the ''deduct'' logic. This prevents duplicate or inconsistent counting
::'''Figure 1:''' A UTXO <code>A</code> sends the entire amount to some output contract <code>B</code>, using <code>CCV</code> with the <i>default</i> semantic.
::'''Figure 3:''' A UTXO <code>A</code> sends a portion of its amount to a contract <code>A'</code> identical to itself, and the rest to a different contract <code>B</code>. It would use <code>CCV</code> to introspect its own input's program, then to check the first output with the <i>deduct</i> semantic, then to check the second output with the <i>default</i> semantic to assign the residual amount.
-----
::[[File:bip-0443/amount_example_4.png|framed|center|alt=split and aggregate amount logic|600px]]
::'''Figure 4:''' Similar to the previous example, but a second input <code>B</code> also checks the same output <code>X</code> with the <i>default</i> semantic, aggregating its input with the residual amount of the first input.
-----
Note that the ''deduct'' semantic does not allow to check the exact amount of its output. Therefore, in contracts using
a scheme similar to figure 3 or 4 above, amounts should be constrained either with a signature, or with future
introspection opcodes that allow fixing the amount. In lack of that, amounts would be malleable.
* <code><mode></code> is a minimally encoded integer, according to one of the values defined below.
* <code><taptree></code> is the Merkle root of the taproot tree, or a minimally encoded <code>-1</code>, or the empty buffer.
* <code><pk></code> is called the ''naked key'', and it's a valid 32-byte x-only public key, or a minimally encoded <code>-1</code>, or the empty buffer.
* <code><index></code> is a minimally encoded -1, or a minimally encoded non-negative integer.
* <code><data></code> is a buffer of arbitrary length.
In short, the semantics of the opcode with respect to the script can be summarized as follows:
<blockquote>
Verify that the input/output with the given 'index' is a P2TR UTXO whose taproot output key is obtained from 'pk',
tweaked with the hash of 'data' (if non-empty), then taptweaked with 'taptree' (if non-empty).
</blockquote>
If the <code><data></code> is non-empty, then the additive tweak for the data is computed as:
<source lang="python">
data_tweak = sha256(pk || data)
</source>
In the following, the ''current input'' is the input whose script is being executed.
The following value of the <code><mode></code> are defined:
* <code>CCV_MODE_CHECK_INPUT = -1</code>: Check an input's script; no amount check.
* <code>CCV_MODE_CHECK_OUTPUT = 0</code>: Check an output's script; preserve the (possibly residual) amount.
* <code>CCV_MODE_CHECK_OUTPUT_IGNORE_AMOUNT = 1</code>: Check an output's script; ignore amounts.
* <code>CCV_MODE_CHECK_OUTPUT_DEDUCT_AMOUNT = 2</code>: Check an output's script; deduct the output amount from the input's residual amount.
Any other value of the <code><mode></code> makes the opcode succeed validation immediately for the current
input<ref>This allows to soft-fork future behavior by introducing new values for the <code><mode></code>. As the mode
would always be hard-coded via a push in the script, the risk of mistakes seems negligible.</ref>.
The following values of the other parameters have special meanings:
* If the <code><taptree></code> is -1, it is replaced with the Merkle root of the current input's tapscript tree. If the taptree is the empty buffer, then the taptweak is skipped.
* If the <code><pk></code> is 0, it is replaced with the NUMS x-only pubkey <code>0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0</code> defined in [[bip-0341.mediawiki|BIP-341]]. If the <code><pk></code> is -1, it is replaced with the taproot internal key of the current input.
