Hans Schmidt :  May 22 2022

hans_schm1dt@protonmail.com


Anatomy of a Ravencoin Asset Transaction Script

*Note: This document is a "work in progress". If you see errors, please enter an "Issue" on github*

This page describes the encoding of a Ravencoin Asset Script.

Asset scripts are used to create an asset, transfer an asset, modify data associated with an asset, or modify the behavior of an asset.

An asset script is always placed into one of the output structures of a transaction, with the value of that output set at value=0. Usually the asset script is appended to a bitcoin-style scriptPubKey in the output. There are, however, some asset scripts (called nullasset scripts) which are placed into an output which has no bitcoin-style scriptPubKey at all.

For more context and examples of how a complete transaction is constructed, please look HERE.


Asset Owner script

The asset owner script gives the Owner Asset to an address. The Owner Asset (represented by a NAME followed by the symbol '!') proves ownership of that NAME, which provides certain authority such as the authority to reissue assets using that NAME, to create subassets and unique assets under that NAME, and to  create restricted assets using that NAME. The Owner Asset is given as an output when a new Main_Asset (Root Asset) is created. It is also used as an input and given back as an output in any transactions which needs the Owner Asset to authorize one of the authority-requiring asset operations just described.

Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
Bytelength of script 1 byte
 0c
Asset_type Header("rvn" in ASCII) 3 bytes
 72766e
Asset operation type: owner(o)=6f 1 byte
 6f
Bytelength of Asset_Name 1 byte
 05
Asset_Name: (root_asset! is the owner asset for root_asset) >=3 and <=30 bytes not including the owner asset !
OP_DROP 1 byte
 75




New Asset script

The New Asset script serves to create a new asset, which can be a Main_Asset (Root Asset), a Subasset, a Restricted_Asset, a Qualifier asset, or a Subqualifier asset. Metadata will also be associated with the created asset as detailed below. If the New Asset being created is a Main_Asset (Root Asset), then an Owner Asset is also created.

Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
Either:
a) The number (#) of bytes below not counting OP_DROP (if #<=75)
or
b) 0x4c followed by the number (#) of bytes below not counting OP_DROP (if #>75)		 1 or 2 bytes
 48
Asset_type Header("rvn" in ASCII) 3 bytes
 72766e
Asset operation type: new(q)=71 1 byte
 71
Bytelength of Asset_Name 1 byte
 05
Asset_Name:
root_asset, root_asset!, root/subasset, root#unique, $restricted_asset, #qualifier, #qualifier/#subqualifier
>=3 and <=30 bytes not including the owner asset !
8 Bytes of Little Endian hex: "Amount" of assets in satoshis 8 bytes
 00743ba40b000000
Divisible-by range: (00..08) units
 1 byte
 08
is reissueable (01 yes: 00 no) 1 byte
 01
Has userdata (01 yes: 00 no) 1 byte
 01
userdata Type (usually 0x12 or 0x54)
 1 byte
userdata Length (usually 0x20)
 1 byte
userdata; usually:
   IPFS_base58_converted_to_hex (type=0x12)
or Transaction_Hash_ID (type=0x54)
 		32 bytes max
optional
variable (max 34 bytes)
 1220c9ae8712366f46a43e
7403e50d1967f2f068d6f42c
c65f742edc0cc1706c109f

  (equivalent to Qmbuw1XZV8i4uFucmKSSYH7
gGhD5B1B1NPMseh9tp5hgea)
OP_DROP 1 byte
 75

Note:

For Unique Asset:
  • Unit is always set to Zero (0)
  • Reissuable is always set to false

For Qualifier or SubQualifier:
  • Amount is a number between 1 and 10
  • Unit is always set to Zero (0)
  • Reissuable is always set to false
  • Note that the purpose of the ability to issue more than quantity=1 of a Qualifier or SubQualifier is to give the Qualifier owner the ability to delegate tagging authority to other entities by transferring a Qualifier or SubQualifier to an address they control. Using a Qualifier or SubQualifier to tag an address does not consume that Qualifier or SubQualifier (a tag operation is not a transfer).

For Restricted Asset:
  • Unit is always set to Zero (0)
  • Reissuable is true/false for whether additional asset quantity can be created and if the verifier string can be changed

Divisible:
  • Specifies how many decimal places the "Amount" has to the right of the decimal point. Zero means "Amount" is always an integer number of assets. Amount of eight means "Amount" varies in increments of 0.00000001 assets.



Asset Transfer script

The Asset Transfer script simply moves an asset from one address to another address. Any asset type can be transferred, but the movement of a Restricted Asset may be restricted based on the associated Verifier String, an Address Freeze, or a Global Freeze. Asset transfer scripts support the embedding of a message and a message expiry time into the transaction output.

Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
Either:
a) The number (#) of bytes below not counting OP_DROP (if #<=75)
or
b) 0x4c followed by the number (#) of bytes below not counting OP_DROP (if #>75)		 1 or 2 bytes
 38
Asset_type Header("rvn" in ASCII) 3 bytes
 72766e
Asset operation type: transfer(t)=74 1 byte
 74
Bytelength of Asset_Name 1 byte
 05
Asset_Name:
root_asset, root_asset!, root/subasset, root#unique, $restricted_asset, #qualifier, #qualifier/#subqualifier 		>=3 and <=30 bytes not including the owner asset !
8 Bytes of Little Endian hex: Amount of assets in satoshis 8 bytes
 00743ba40b000000
userdata Type (usually 0x12 or 0x54)
 1 byte
userdata Length (usually 0x20)
 1 byte
userdata; usually:
   IPFS_base58_converted_to_hex (type=0x12)
or Transaction_Hash_ID (type=0x54)
 		32 bytes max
optional;
variable (max 34 bytes) 		1220c9ae8712366f46a43e
7403e50d1967f2f068d6f42c
c65f742edc0cc1706c109f

  (equivalent to Qmbuw1XZV8i4uFucmKSSYH7
gGhD5B1B1NPMseh9tp5hgea)
userdata Expiry Time (UTC Unix timestamp format)
 optional;
8 bytes
 00000000625a168a
OP_DROP 1 byte
 75




Asset Reissue script

The Asset Reissue script issues an additional quantity of an asset or modifies the metadata associated with that asset. Asset Reissue requires possession of the Owner Asset, which is used as an input of the transaction containing a Reissue (to prove authority), and is returned as an output of the same transaction. Asset Reissue is also only possible if the reissue authority is indicated in the metadata of the asset, based on a choice made during the original Issue operation of the asset or during a subsequent Reissue operation. Note that during a Reissue operation, divisibility (how many decimal places to the right of the decimal point) may only be increased or kept the same, and any increase in divisibility cannot be used until after the increase has taken effect by being mined. Unique assets can never be reissued.

Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
Either:
a) The number (#) of bytes below not counting OP_DROP (if #<=75)
or
b) 0x4c followed by the number (#) of bytes below not counting OP_DROP (if #>75)		 1 or 2 bytes
 38
Asset_type Header("rvn" in ASCII) 3 bytes
 72766e
Asset operation type: reissue(r)=72 1 byte
 71
Bytelength of Asset_Name 1 byte
 05
Asset_Name:
root_asset, root_asset!, root/subasset, root#unique, $restricted_asset, #qualifier, #qualifier/#subqualifier 		>=3 and <=30 bytes not including the owner asset !
8 Bytes of Little Endian hex: Amount of assets in satoshis 8 bytes
 00743ba40b000000
Divisible-by range: (00..08) units
 1 byte
 08
is reissueable (01 yes: 00 no) 1 byte
 01
Has userdata (01 yes: 00 no) 1 byte
 01
userdata Type (usually 0x12 or 0x54)
 1 byte
userdata Length (usually 0x20)
 1 byte
userdata; usually:
   IPFS_base58_converted_to_hex (type=0x12)
or Transaction_Hash_ID (type=0x54)
 		32 bytes max
optional;
variable (max 34 bytes) 		1220c9ae8712366f46a43e
7403e50d1967f2f068d6f42c
c65f742edc0cc1706c109f

  (equivalent to Qmbuw1XZV8i4uFucmKSSYH7
gGhD5B1B1NPMseh9tp5hgea)
OP_DROP 1 byte
 75

Note:

For Restricted Asset:
  • Unit is always set to Zero (0)
  • Reissuable is true/false for whether additional asset quantity can be created and if the VerifierString can be changed



Tag/Untag Address script
(a type of nullasset script)
The Tag/Untag Address script is used to tag or untag an address using a Qualifier or SubQualifier asset. This operation determines whether a particular Restricted Asset may be received by that address depending on whether or not the address satisfies the requirements of the VerifierString (a boolean of Qualifiers) associated with that Restricted Asset.

Note that although a SubQualifier can be used to tag an address, only the root Qualifier has any effect and is stored with the address since VerifierStrings can consist only of Qualifiers.

Note also that using a Qualifier or SubQualifier to tag an address does not consume that Qualifier or SubQualifier (a tag operation is not a transfer). The purpose of the ability to issue more than quantity=1 of a Qualifier or SubQualifier asset is to give the Qualifier owner the ability to delegate tagging authority to other entities by transferring a Qualifier or SubQualifier to an address they control. Typically this is done using a SubQualifier. Although an address tagged by such an entity using a SubQualifier is affected only by the root Qualifier, the blockchain maintains the transaction history of the SubQualifier used to tag that address. This provides a record of the use of the delegated authority.


Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
NullAssetTxDataScript identifier
 1 byte
 14
Hash-160 Address
 20 bytes
Bytelength of Script 1 byte
 0b
Bytelength of Qualifier Name
 1 byte
 05
Qualifier Name (#qualifier or #qualifier/#subqualifier) >=3 and <=30 bytes not including the owner asset !
Operation (1=Add, 0=Remove)
 1 bytes
 01
userdata Type (usually 0x12 or 0x54)
 1 byte
userdata Length (usually 0x20)
 1 byte
userdata; usually:
   IPFS_base58_converted_to_hex (type=0x12)
or Transaction_Hash_ID (type=0x54)
 		32 bytes max
optional;
variable (max 34 bytes)		 1220c9ae8712366f46a43e
7403e50d1967f2f068d6f42c
c65f742edc0cc1706c109f

  (equivalent to Qmbuw1XZV8i4uFucmKSSYH7
gGhD5B1B1NPMseh9tp5hgea)
userdata Expiry Time (UTC Unix timestamp format) optional;
8 bytes		 00000000625a168a
OP_DROP 1 byte
 75

Note that if the first two bytes are "c014" and the Name (up to 31 bytes) is a valid "Qualifier Name" (ie starts  with "#"), then this is a "Tag/Untag Address" type of nullasset script, rather than a "Freeze/Unfreeze Address" type.


Freeze/Unfreeze Address script
(a type of nullasset script)
The Freeze/Unfreeze Address script is used to freeze or unfreeze the movements of a particular Restricted Asset at a particular address. When frozen, the specified Restricted Asset may not be transferred into or out of the specified address.

Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
NullAssetTxDataScript identifier
 1 byte
 14
Hash-160 Address
 20 bytes
Bytelength of Script 1 byte
 0b
Bytelength of Restricted Asset Name
 1 byte
 05
Restricted Asset Name ($restricted_asset) >=3 and <=30 bytes not including the $
Operation (1=Freeze, 0=Unfreeze)
 1 bytes
 01
userdata Type (usually 0x12 or 0x54)
 1 byte
userdata Length (usually 0x20)
 1 byte
userdata; usually:
   IPFS_base58_converted_to_hex (type=0x12)
or Transaction_Hash_ID (type=0x54)
 		32 bytes max
optional;
variable (max 34 bytes)		 1220c9ae8712366f46a43e
7403e50d1967f2f068d6f42c
c65f742edc0cc1706c109f

  (equivalent to Qmbuw1XZV8i4uFucmKSSYH7
gGhD5B1B1NPMseh9tp5hgea)
userdata Expiry Time (UTC Unix timestamp format) optional;
8 bytes		 00000000625a168a
OP_DROP 1 byte
 75

Note that if the first two bytes are "c014" and the Name (up to 31 bytes) is a valid "Restricted Asset Name" (ie starts  with "$"), then this is a "Freeze/Unfreeze Address" type of nullasset script, rather than a "Tag/Untag Address" type.


Global Freeze/Unfreeze script
(a type of nullasset script)
The Global Freeze/Unfreeze script is used to freeze or unfreeze the movements of a particular Restricted Asset at all addresses. When frozen, the specified Restricted Asset may not be transferred into or out of any addresses.

Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
NullGlobalRestrictionAssetTxDataScript identifier
 2 bytes
 5050
Bytelength of Script 1 byte
 0b
Bytelength of Restricted Asset Name
 1 byte
 05
Restricted Asset Name ($restricted_asset) >=3 and <=30 bytes not including the $
Operation (1=Freeze, 0=Unfreeze)
 1 bytes
 01
userdata Type (usually 0x12 or 0x54)
 1 byte
userdata Length (usually 0x20)
 1 byte
userdata; usually:
   IPFS_base58_converted_to_hex (type=0x12)
or Transaction_Hash_ID (type=0x54)
 		32 bytes max
optional;
variable (max 34 bytes)		 1220c9ae8712366f46a43e
7403e50d1967f2f068d6f42c
c65f742edc0cc1706c109f

  (equivalent to Qmbuw1XZV8i4uFucmKSSYH7
gGhD5B1B1NPMseh9tp5hgea)
userdata Expiry Time (UTC Unix timestamp format) optional;
8 bytes		 00000000625a168a
OP_DROP 1 byte
 75




VerifierString Assignment script
(a type of nullasset script)
A VerifierString is a boolean expression comprised of Qualifiers and boolean operators. It is associated with a Restricted Asset and determines the qualifiers which must have tagged an address in order for that address to be allowed to receive that Restricted Asset. In a transaction in which a Restricted Asset is issued or reissued by an output New Asset script or Reissue Asset script, an additional output containing a VerifierString nullasset script as described here is created in the transaction which associates that VerifierString with that Restricted Asset. A Restricted Asset requires a VerifierString, and the VerifierString "true" must be used when no Qualifiers are desired.

Description  Length 
Hex Value Example
OP_RVN_ASSET 1 byte
 c0
NullAssetVerifierTxDataScript identifier
 1 byte
 50
Bytelength of Script 1 byte
 anything except 50
Bytelength of VerifierString (<=80 bytes after whitespace and "#"s are removed) 1 byte
 05
VerifierString  <= 80 bytes
 (RED&BLUE)&!GREEN
OP_DROP 1 byte
 75




Asset Naming Rules

ROOT_ASSET: Root asset name valid characters are: A-Z 0-9 . _
    special characters can't be the first or last characters or repeated
OWNER: Owner asset will be the Root asset with ! appended

SUB_ASSET: Sub_asset name valid characters are: A-Z 0-9 . _
    / must be the first character. special characters can't be the first or last characters or repeated

UNIQUE: Unique name valid characters are: A-Z a-z 0-9 @ $ % & * ( ) [ ] { } _ . ? : -
    # must be the first character.

MSGCHANNEL: Message Channel name valid characters are: A-Z 0-9 _ .
    ~ must be the first character. Special characters can't be the first or last characters or repeated

VOTE: Vote name valid characters are: A-Z 0-9 _ .
    ^ must be the first character. Special characters can't be the first or last characters or repeated

QUALIFIER or SUB_QUALIFIER: Qualifier or Sub_qualifier name valid characters are: A-Z 0-9 _ .
    # must be the first character. Special characters can't be the first or last characters or repeated

RESTRICTED: Restricted name valid characters are: A-Z 0-9 _ .
    $ must be the first character. Special characters can't be the first or last characters or repeated

VerifierString: Boolean expression comprised of root Qualifiers and boolean operators
    Parentheses () are allowed for grouping
    Legal operators are: & | !
    SubQualifiers may NOT be used

The names RVN, RAVEN, and RAVENCOIN are reserved

Excluding the owner tag ('!') =>
    Maximum non-channel asset name length = 31
    Maximum channel asset name length = 12
    Minimum asset name length = 3
    Max VerifierString Length: 80 bytes after whitespace and "#"s are removed

Copyright 2021, 2022 by Hans Schmidt