Programming
Pay to Ref
Pay to ref is a powerful new script built using Radiant's unique induction proof system. This script provides a way of composing contracts from multiple outputs, introducing efficiencies and flexibility previously very difficult on UTXO based blockchains.
OP_REFTYPE_UTXO OP_0 OP_NUMNOTEQUALThe above script uses OP_REFTYPE_UTXO to take a given ref from the stack and return the
type of any ref found in the transaction's inputs. If the returned value is not equal to zero then we
know the ref has been found in the inputs. We can check for any ref type or a specific type.
OP_REFTYPE_UTXO returns one of the following:
- 0 - Ref not found in inputs
- 1 - Ref found in inputs, of normal type
- 2 - Ref found in inputs, of singleton type
Composing contracts from multiple UTXOs
This script can be used to break a contract up into multiple parts. For example a complex NFT contract, split into a token contract and ownership contract:
UTXO for contract functions
// Contract functions
// function 1...
// function 2...
OP_PUSHINPUTREFSINGLETON <ref1> OP_DROP
<ref2> OP_REFTYPE_UTXO OP_2 OP_NUMEQUAL
UTXO for token ownership/control
OP_PUSHINPUTREFSINGLETON <ref2> OP_DROP
OP_DUP OP_HASH160 <pubKeyHash OP_EQUALVERIFY OP_CHECKSIG
The above contract is composed of two outputs. A singleton ref has been assigned to each output. The first UTXO can only be spent if the second "control" UTXO is also an input.
We can now handle token transfers using only the P2PKH output and not have to touch the rest of the contract. Since the token contract doesn't contain the P2PKH script, only a pay to ref, it is automatically carried forward with the transfer. For wallets to support transfers of this token, they only need to handle a simple singleton + P2PKH script and not be concerned with custom functionality or parsing custom contract templates.
Diagram: Transferring control of a token contract
The two singletons are best created as a contiguous set, so if any script needs to read from another part of the contract, it can check for the existence of a ref within its own set to verify the authenticity of the input. This also makes it easy for wallets to find all parts of the contract.
In this example we have only used two outputs, but this can be extended to compose contracts from three or more outputs.
Upgrading contracts
Another powerful use case is to extend a contract's functionality by permitting the UTXO to be spent alongside one of a range of refs. These contract extensions can be defined at a later date, providing a way of upgrading contracts or adding new functionality.
The developer must plan this in advance, by keeping some refs in reserve, coded into the contract so they can be deployed and distributed to users later.
For example, a contract that allows locking conditions to be delegated to an input containing any ref from a specific transaction hash. The ref index is provided as a parameter in the unlocking script:
<extensionTxId> OP_SWAP OP_CAT OP_REFTYPE_UTXO OP_0 OP_NUMNOTEQUAL
The above script takes a ref index from the unlocking script, appends to the transaction ID to construct the ref and checks if the ref exists in an input.
Care must be taken to ensure the user remains in control of their coins and complete control is not given over to the developer. Requiring the owner's signature will ensure the developer cannot spend the coins.
Radiant Opcodes
The Radiant blockchain introduces a set of opcodes that significantly improves on the capability of the Bitcoin technology it's based on. All these opcodes are outlined below:
Terms
- Ref: A 36 byte reference, either of normal or singleton type. A reference is created from an input's outpoint and can be propagated with every spend of a UTXO. For a ref to exist in an output there must be a matching input ref of the same type or an input with a matching outpoint. The ref type cannot be changed once it is created.
- Normal ref: A type of reference that can be propagated to one or more outputs.
- Singleton ref: A type of reference that can only ever exist in a single UTXO. Cannot be propagated to multiple outputs.
- State script: The part of the script before and not including an
OP_STATESEPARATOR. Useful for storing state data that can be changed by the contract. - Code script The part of the script from and including an
OP_STATESEPARATOR. If no state separator is present, the code script is the entire script. codeScriptHash: The double SHA-256 of the code script.
Hash Functions
SHA-512/256 is the hash function used by Radiant's proof of work algorithm. It is available in script as single and double hash functions. These can be used to validate Radiant block headers in script.
| Opcode | Hex | Input | Output | Description |
|---|---|---|---|---|
|
OP_SHA512_256 |
ce | bytes | hash | SHA-512/256 |
|
OP_HASH512_256 |
cf | bytes | hash | Double SHA-512/256 |
Induction Opcodes
| Opcode | Hex | Input | Output | Description |
|---|---|---|---|---|
|
OP_PUSHINPUTREF |
d0 | ref | ref | Propagates a ref to an output. A ref of normal type must exist in an input or an input must have an outpoint matching the ref. Ref will be left on the stack. |
|
OP_PUSHINPUTREFSINGLETON |
d8 | ref | ref | Propagates a singleton ref to an output. A ref of singleton type must exist in an input or an input must have an outpoint matching the ref. Ref will be left on the stack. |
|
OP_REQUIREINPUTREF |
d1 | ref | ref | A ref of normal type must exist in an input. Ref is not propagated. Ref will be left on the stack. |
|
OP_DISALLOWPUSHINPUTREF |
d2 | ref | ref | Requires a ref to not exist in any input. Leaves the ref on the stack. |
|
OP_DISALLOWPUSHINPUTREFSIBLING |
d3 | ref | ref | Requires a ref to not exist in any input sibling. Leaves the ref on the stack. |
|
OP_REFTYPE_UTXO |
d9 | ref | type | Get the type of a ref from transaction inputs. Returns 0 (not found), 1 (normal type) or 2 (singleton type). |
|
OP_REFTYPE_OUTPUT |
da | ref | type | Get the type of a ref from transaction outputs. Returns 0 (not found), 1 (normal type) or 2 (singleton type). |
|
OP_REFHASHDATASUMMARY_UTXO |
d4 | inputIndex | summary | For the input of the given index returns a hash256 of
<nValue><hash256(scriptPubKey)><numRefs><hash(sortedMap(pushRefs))>
|
|
OP_REFHASHDATASUMMARY_OUTPUT |
d6 | outputIndex | summary | For the output of the given index returns a hash256 of
<nValue><hash256(scriptPubKey)><numRefs><hash(sortedMap(pushRefs))>
|
|
OP_REFDATASUMMARY_UTXO |
e1 | inputIndex | summary | Return refs used within an input. Pushes a vector of the form
<ref1><ref2><ref3>.... If an input UTXO does not contain at least
one reference, then the 36 byte zeroes are pushed.
|
|
OP_REFDATASUMMARY_OUTPUT |
e2 | outputIndex | summary | Return refs used within an output. Pushes a vector of the form
<ref1><ref2><ref3>.... If an input UTXO does not contain at least
one reference, then the 36 byte zeroes are pushed.
|
State/code Script Opcodes
| Opcode | Hex | Input | Output | Description |
|---|---|---|---|---|
|
OP_STATESEPARATOR |
bd | Separates the state script from the code script. Only one can exist in a script and it must not exist within an OP_IF. No OP_RETURN can exist in the script when used. | ||
|
OP_STATESEPARATORINDEX_UTXO |
be | inputIndex | separatorIndex | Returns the byte index of the state separator for an input. Returns zero if no separator exists. |
|
OP_STATESEPARATORINDEX_OUTPUT |
bf | outputIndex | separatorIndex | Returns the byte index of the state separator for an output. Returns zero if no separator exists. |
|
OP_CODESCRIPTBYTECODE_UTXO |
e9 | inputIndex | bytecode | Returns the code script bytecode for an input. |
|
OP_CODESCRIPTBYTECODE_OUTPUT |
ea | outputIndex | bytecode | Returns the code script bytecode for an output. |
|
OP_STATESCRIPTBYTECODE_UTXO |
eb | inputIndex | bytecode | Returns the state script bytecode for an output. Does not include the OP_STATESEPARATOR. |
|
OP_STATESCRIPTBYTECODE_OUTPUT |
ec | outputIndex | bytecode | Returns the state script bytecode for an output. Does not include the OP_STATESEPARATOR. |
Count and Sum Opcodes
These opcodes provide a set queries on inputs and outputs by ref, ref hash and code script hash. Counts and sums can be performed over many outputs with a single opcode, meaning an unrolled loop in the script is not required.
| Opcode | Hex | Input | Output | Description |
|---|---|---|---|---|
|
OP_REFHASHVALUESUM_UTXOS |
d5 | refHash | photons | Returns the total sum of photons for inputs that match a 32 byte hash of the sorted set of ref asset ids. |
|
OP_REFHASHVALUESUM_OUTPUTS |
d7 | refHash | photons | Returns the total sum of photons for outputs that match a 32 byte hash of the sorted set of ref asset ids. |
|
OP_REFVALUESUM_UTXOS |
db | ref | photons | Returns the total sum of photons for inputs that contain a ref. |
|
OP_REFVALUESUM_OUTPUTS |
dc | ref | photons | Returns the total sum of photons for outputs that contain a ref. |
|
OP_REFOUTPUTCOUNT_UTXOS |
dd | ref | count | Returns the count of inputs that contain a ref. |
|
OP_REFOUTPUTCOUNT_OUTPUTS |
de | ref | count | Returns the count of outputs that contain a ref. |
|
OP_REFOUTPUTCOUNTZEROVALUED_UTXOS |
df | ref | count | Returns the count of inputs that contain a ref and contain zero photons. |
|
OP_REFOUTPUTCOUNTZEROVALUED_OUTPUTS |
e0 | ref | count | Returns the count of inputs that contain a ref and contain zero photons. |
|
OP_CODESCRIPTHASHVALUESUM_UTXOS |
e3 | codeScriptHash | photons | Returns the total sum of photons for inputs that have a
codeScriptHash
|
|
OP_CODESCRIPTHASHVALUESUM_OUTPUTS |
e4 | codeScriptHash | photons | Returns the total sum of photons for outputs that have a
codeScriptHash
|
|
OP_CODESCRIPTHASHOUTPUTCOUNT_UTXOS |
e5 | codeScriptHash | count | Returns the count of inputs that have a
codeScriptHash
|
|
OP_CODESCRIPTHASHOUTPUTCOUNT_OUTPUTS |
e6 | codeScriptHash | count | Returns the count of outputs that have a
codeScriptHash
|
|
OP_CODESCRIPTHASHZEROVALUEDOUTPUTCOUNT_UTXOS |
e7 | codeScriptHash | count | Returns the count of inputs that have a
codeScriptHash and contain zero photons.
|
|
OP_CODESCRIPTHASHZEROVALUEDOUTPUTCOUNT_OUTPUTS |
e8 | codeScriptHash | count | Returns the count of outputs that have a
codeScriptHash and contain zero photons.
|
NFTs on Radiant
Radiant's singleton references are ideal for the creation of NFTs. A singleton ref is a type of reference which can only ever exist in a single UTXO. A transaction is invalid if a singleton ref is pushed to more than one output. References cannot change type, so a singleton ref must be created as a singleton. Therefore we can be sure that there has only ever been one instance of a singleton ref.
The opcode for pushing a singleton ref is OP_PUSHINPUTREFSINGLETON.
A simple NFT contract
We will define a contract for an immutable NFT by adding a singleton ref to a standard P2PKH script:
OP_PUSHINPUTREFSINGLETON <ref> OP_DROP
OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
Following Radiant's ref rules, the ref must match an outpoint or
a ref of the same type in an input. If the ref matches an outpoint then this is the "mint" transaction.
OP_PUSHINPUTREFSINGLETON leaves the ref on the stack, and since we don't need it later in
the script it is immediately dropped.
Diagram: Mint and transfer of an NFT, followed by an invalid transaction
As seen in the diagram above, an outpoint in the first transaction is used to create a singleton ref. The referenced output also contains an "immutable token payload" which can be stored as a push data. This is a simple way of associating data with our token, where the token data can be fetched from the referenced output. The payload could be an image or more complex data structure. Token UTXOs are kept light weight by not carrying the payload.
This token protocol can be used for a wide variety of use cases such as tickets, coupons and collectibles. Wallet integration is simple since the script only requires a singleton ref in addition to a standard P2PKH script.
Melting a token
Melting a token only requires that the token be spent and the singleton ref not pushed forward. Once the singleton does not exist in a UTXO it cannot be recreated.
Conclusion
Singleton refs are a simple yet effective way of creating an NFT protocol. We have demonstrated how a token protocol can be created with only a small change to a standard P2PKH script. In future articles we will explore how to extend this contract to support mutable data.
Pay to Token
Token-controlled contracts revolutionize contract composition and management on Radiant, facilitating the separation of contracts into multiple UTXOs, each with distinct functionalities. With token ownership housed in its UTXO and additional UTXOs for data storage and specialized functionalities, developers can seamlessly integrate custom functionalities with standard token scripts, extending contract capabilities effortlessly.
OP_REFTYPE_UTXO OP_0 OP_NUMNOTEQUALScript Details
Token Input
A standard singleton + P2PKH token script:
OP_PUSHINPUTREFSINGLETON <tokenRef> OP_DROP <p2pkh>Token Output
The token output features a state script binding it to the contract input using
OP_REQUIREINPUTREF, followed by the contract's script signature hash:
OP_REQUIREINPUTREF <contractRef>
<contractScriptSigHash> OP_2DROP // Hash256 of contract's script sig
OP_STATESEPARATOR
OP_PUSHINPUTREFSINGLETON <tokenRef> OP_DROP <p2pkh> // Standard token scriptScript Sig
<hashIndex> // Position of ref + hash in token output
<refIndex> // Index of ref in token output data summary
<outputIndex> // Output index of tokenScript Pub Key
// Contract ref
OP_PUSHINPUTREFSINGLETON <contractRef> OP_DROP
// Check token ref exists in the token output
OP_DUP OP_ROT OP_REFDATASUMMARY_OUTPUT OP_SWAP 36 OP_MUL OP_SPLIT OP_NIP 32 OP_SPLIT OP_DROP <tokenRef> OP_DUP OP_ROT OP_EQUALVERIFY
// Get ref + hash in token output script
OP_ROT OP_STATESCRIPTBYTECODE_OUTPUT OP_SWAP OP_SPLIT OP_NIP 69 OP_SPLIT OP_DROP
// Compare ref + hash in token output to ref + hash of this script's unlocking code
OP_SWAP 32 OP_INPUTINDEX OP_INPUTBYTECODE OP_HASH256 OP_CAT OP_CAT OP_EQUALVERIFY
// Propagate the contract
OP_INPUTINDEX OP_CODESCRIPTBYTECODE_UTXO OP_HASH256 OP_CODESCRIPTHASHOUTPUTCOUNT_OUTPUTS 1 OP_NUMEQUALVERIFY
//
// Contract code...
//This script empowers complex contracts composed of multiple UTXOs, each with unique responsibilities. Token scripts maintain standard scripts easily understood by wallets but can be associated with custom contracts. Pay to token contracts can be deployed at any time to expand token functionality.
Advantages
- Enhanced Functionality: Contracts can be extended with custom functionalities effortlessly.
- Streamlined Updates: Token transfers and data updates are segregated, simplifying history tracking.
- Reduced Load: Wallets can focus on relevant transaction histories, improving efficiency.
- This script can be used to break a contract up into multiple parts. For example a complex NFT contract, split into a token contract and ownership contract:
Token-controlled contracts pave the way for more flexible and manageable blockchain contracts, fostering innovation and scalability in decentralized applications.