From b84f5d6b9e4280f4892e758ac51727a3b2c84664 Mon Sep 17 00:00:00 2001 From: Christopher-Zeng <32022231+Christopher-Zeng@users.noreply.github.com> Date: Thu, 28 Jan 2021 09:57:10 -0500 Subject: [PATCH] Added the SLP topic page and message format pages. (#14) SLP pages. --- protocol/slp/commit.md | 28 +++++++++++++++ protocol/slp/genesis.md | 48 +++++++++++++++++++++++++ protocol/slp/mint.md | 19 ++++++++++ protocol/slp/send.md | 19 ++++++++++ protocol/slp/slp.md | 79 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 193 insertions(+) create mode 100644 protocol/slp/commit.md create mode 100644 protocol/slp/genesis.md create mode 100644 protocol/slp/mint.md create mode 100644 protocol/slp/send.md create mode 100644 protocol/slp/slp.md diff --git a/protocol/slp/commit.md b/protocol/slp/commit.md new file mode 100644 index 0000000..5191cb9 --- /dev/null +++ b/protocol/slp/commit.md @@ -0,0 +1,28 @@ +# COMMIT - Checksum Commitment Transaction + +As previously discussed, a token issuer should make regular commitments of the SHA-256 hash of previous transactions made for this token. +Although this is not part of the consensus rules (commitments may occur outside of the token transaction graph, and commitment data is never used in consensus rules), it allows a user to verify that the issuer is accurately honoring the token's consensus rules. +This increases confidence that tokens will be judged as expected at the time of redemption. + +Initial implementations will focus on supporting the consensus-based forms of validation, and so at this time the exact format for the commitment document is not specified. +General expectations of a commitment format should include: + +* The committed information will be in regards to only the transactions that exist in the blockchain leading up to and including the block with hash `for_bitcoin_block_hash`. +(If the block is orphaned, users should ignore this commitment.) The chain height of this block will be stored in the integer `block_height` (even though this is redundant, it aids in lookup for light wallets). + +* The committed set of SLP information will be hashed using an *ordered* merkle tree (such as [merklix](https://www.deadalnix.me/2016/09/24/introducing-merklix-tree-as-an-unordered-merkle-tree-on-steroid/)) that allows lite clients to obtain short merkle proofs of the presence *or absence* of a given SLP item (presence indicating valid, absence indicating invalid). + +* These commitments will thus enable checkpoint based validation, discussed later. +From this set it is also possible to audit the total number of tokens in circulation (tokens issued minus tokens burned) for that block. + +* The set items will relate to one specific `token_id`, and might be transactions, or transaction outputs; all, or only unspent. +The set will be carefully chosen to satisfy the above requirements with a minimal size. + +**Transaction inputs**: At least one input should use an address controlled by a trusted validator (could be original issuer, or a respected member of the token community) and this input's signed data should include the OP_RETURN output. + +**Transaction outputs**: + +| vout | ScriptPubKey ("Address") | BCH amount | +|-|-|-| +| 0 | OP_RETURN
<lokad_id: 'SLP\x00'> (4 bytes, ascii)
<token_type: 1> (1 to 2 byte integer)
<transaction_type: 'COMMIT'> (6 bytes, ascii)
<token_id> (32 bytes)
<for_bitcoin_block_hash> (32 bytes)
<block_height> (8 byte integer)
<token_txn_set_hash> (32 bytes)
<txn_set_data_url> (0 to ∞ bytes, ascii) [to be determined] | any | +| ... | Any | any | diff --git a/protocol/slp/genesis.md b/protocol/slp/genesis.md new file mode 100644 index 0000000..1d9654b --- /dev/null +++ b/protocol/slp/genesis.md @@ -0,0 +1,48 @@ +# GENESIS - Token Genesis Transaction + +This is the first transaction which defines the properties, metadata and initial mint quantity of the token +The token is thereafter uniquely identified by the token genesis transaction hash which is referred to as `token_id`. + +`token_type` indicates the SLP sub-protocol: + +* 1 - Permissionless Token Type +* 2 - Reserved for Security Token Type +* 3 - Reserved for Voting Token Type +* 4 - Reserved for Ticketing Token Type +* ... + +This document specifies the rules and operation of the Permissionless Token Type (1) only. +Tokens of different types cannot be mixed, and so future specifications of other token types will not affect the consensus validity of type 1. + +`mint_baton_vout`: Future token supply increases are made possible if the genesis endows a specific transaction output with a "minting baton" that can be passed along and used for future minting (using ['MINT'](/protocol/slp/mint) transactions) +If `mint_baton_vout` is not present or refers to a nonexistent output, then the baton does not exist and the token provably has a one-time issuance. + +`decimals`: indicates that 1 token is divisible into 10^`decimals` base units +SLP messages store whole numbers indicating token amounts as measured in the base unit, analogous to how bitcoin transactions store BCH amounts measured in the base unit 'satoshis' +With a token FOO having `decimals` of 6 indicated in the genesis, for example, the quantity 12.53 FOO (as displayed in wallet software) would be represented by 12530000 base units (as 8 bytes, hex 0000000000bf3150) +A `decimals` of 8 would give the same divisibility as bitcoin, whereas 0 would give indivisible tokens. + +The genesis transaction includes an initial minting of `initial_token_mint_quantity` base units, placed on the second transaction output (vout=1). + +**Transaction inputs**: Any number of inputs or content of inputs, in any order. + +**Transaction outputs**: + +| vout | ScriptPubKey ("Address")| BCH amount| Implied token amount (base units) | +| - | - | - | - | +| 0 | OP_RETURN
<lokad_id: 'SLP\x00'> (4 bytes, ascii)1
<token_type: 1> (1 to 2 byte integer)
<transaction_type: 'GENESIS'> (7 bytes, ascii)
<token_ticker> (0 to ∞ bytes, suggested utf-8)
<token_name> (0 to ∞ bytes, suggested utf-8)
<token_document_url> (0 to ∞ bytes, suggested ascii)
<token_document_hash> (0 bytes or 32 bytes)
<decimals> (1 byte in range 0x00-0x09)
<mint_baton_vout> (0 bytes, or 1 byte in range 0x02-0xff)
<initial_token_mint_quantity> (8 byte integer)
| any2 | 0 | +| 1 | Initial mint receiver | any2 | initial_token_mint_quantity | +| ... | Any | any2 | 0 | +| M | (M=mint_baton_vout) Mint baton receiver | any2 | 0
+ 'baton' | +| ... | Any | any2 | 0 | + + + + +1 - +The Lokad identifier is registered as the number 0x504c53 (which, when encoded in the 4-byte little-endian format expected for Lokad IDs, gives the ascii string 'SLP\x00') +Inquiries and additional information about the Lokad system of OP_RETURN protocol identifiers can be found at [https://github.com/Lokad/Terab](https://github.com/Lokad/Terab) maintained by Joannes Vermorel. + +2 - +SLP does not impose any restrictions on BCH output amounts +Typically however the OP_RETURN output would have 0 BCH (as any BCH sent would be burned), and outputs receiving tokens / mint batons would be sent only the minimal 'dust' amount of 0.00000546 BCH. diff --git a/protocol/slp/mint.md b/protocol/slp/mint.md new file mode 100644 index 0000000..cded8a2 --- /dev/null +++ b/protocol/slp/mint.md @@ -0,0 +1,19 @@ +# MINT - Extended Minting Transaction + +Subsequent minting transactions of `additional_token_quantity` can be performed by spending the "minting baton" UTXO in a special MINT transaction, described here. +Note that this could be done by someone other than the [GENESIS](/protocol/slp/genesis) issuer, if the baton minting authority had been passed to another address. + +As with GENESIS, the MINT allows to end the baton, or further pass on the baton to future mint operations: if `mint_baton_vout` is empty or refers to a nonexistent vout, the transaction is valid but the baton is lost. +This makes it possible to prove end-of-minting capabilities for a token even after several minting events (it is impossible to duplicate this baton as that would require double-spending the transaction output associated with the baton). + +**Transaction inputs**: Any number of inputs or content of inputs, in any order, but with required presence of a 'baton' input (see [Consensus Rules](/protocol/slp/slp#consensus-rules)). + +**Transaction outputs**: + +| vout | ScriptPubKey ("Address") | BCH amount | Implied token amount (base units) | +|-|-|-|-| +| 0 | OP_RETURN
< lokad_id: 'SLP\x00'> (4 bytes, ascii)
< token_type: 1> (1 to 2 byte integer)
< transaction_type: 'MINT'> (4 bytes, ascii)
< token_id> (32 bytes)
< mint_baton_vout> (0 bytes or 1 byte between 0x02-0xff)
< additional_token_quantity> (8 byte integer) | any | 0 | +| 1 | Token mint receiver | any | additional_token_quantity | +| ... | Any | any | 0 | +| M | Mint baton receiver (M=mint_baton_vout) | any | 0 + 'baton' | +| ... | Any | any | 0 | diff --git a/protocol/slp/send.md b/protocol/slp/send.md new file mode 100644 index 0000000..fb5a713 --- /dev/null +++ b/protocol/slp/send.md @@ -0,0 +1,19 @@ +# SEND - Spend Transaction + +The following transaction format is used to transfer tokens from one or more token holding UTXO(s) to new token holding UTXO(s). +The UTXOs associated with unspent tokens will be used within the transaction input and, just like the BCH attached to these UTXOs, will be considered totally spent after this transaction is accepted by the blockchain. +Tokens will be assigned to the outputs with indexes 1 to 19 as indicated within the OP_RETURN statement. +Any number of additional BCH-only outputs will be allowed. +A BCH-only output can come before token outputs, but a token quantity of 0 must be specified for this output. + +**Transaction inputs**: Any number of inputs or content of inputs, in any order, but must include sufficient tokens coming from valid token transactions of matching `token_id`, `token_type` (see [Consensus Rules](/protocol/slp/slp#Consensus-Rules)). + +**Transaction outputs**: + +| vout | ScriptPubKey ("Address") | BCH amount | Implied token amount (base units) | +|-|-|-|-| +| 0 | OP_RETURN
<lokad id: 'SLP\x00'> (4 bytes, ascii)
<token_type: 1> (1 to 2 byte integer)
<transaction_type: 'SEND'> (4 bytes, ascii)
<token_id> (32 bytes)
<token_output_quantity1> (required, 8 byte integer)
<token_output_quantity2> (optional, 8 byte integer)
...
<token_output_quantity19> (optional, 8 byte integer)
| any | 0 | +| 1 | Receiver 1 | any | token_output_quantity1 | +| ... | ... | any | ... | +| N | Receiver N (N = number of token_output_quantities provided) | any | token_output_quantityN | +| ... | Any | any | 0 | diff --git a/protocol/slp/slp.md b/protocol/slp/slp.md new file mode 100644 index 0000000..ede6bc0 --- /dev/null +++ b/protocol/slp/slp.md @@ -0,0 +1,79 @@ +# Simple Ledger Protocol + +Simple Ledger Protocol is a token system for the Bitcoin Cash network. +It allows users to create, issue, and transfer digital tokens that enjoy the same security model and network of Bitcoin Cash. +Users can associate the created tokens with assets and values, and thus, utilize the [Blockchain](/protocol/blockchain) as the public ledger to achieve transparency and integrity for their transactions. + + +## The intent of token systems + +The Blockchain provides an open ledger with transparency and integrity to document transactions. +However, to utilize this ledger, one has to devise rules and security models for the transactions, as well as the computational power to support a network that complies with the rules. +The above costs make such applications prohibitively expensive for most individual users, while also hindering the emergence of coins for specific applications and transactions. +Such needs drive the creation of various token systems on Bitcoin Cash. +Token systems are additional layers of protocols on Bitcoin Cash, that allow the creation, issuance, and transfer of tokens on the Bitcoin Cash network. +Users and creators of the tokens can utilize the computational power and other benefits of the Bitcoin Cash network for their own token transactions. + + +## The design of Simple Ledger Protocol + +Simple Ledger Protocol (SLP) is one of the most prevalent token systems on Bitcoin Cash. +SLP employs a “colored coins” design that associates token amounts with BCH [transaction](/protocol/blockchain/transaction) outputs. +An SLP transaction will utilize a [data output](/protocol/blockchain/transaction/locking-script#data-output) to include a message in one of four predefined formats to annotate the SLP transaction information associated with each transaction output in the same transaction. +The predefined formats include: [GENESIS](/protocol/slp/genesis), [MINT](protocol/slp/mint), [SEND](/protocol/slp/send), and [COMMIT](/protocol/slp/commit). +The GENESIS message defines the SLP token and issues the first batch of tokens. +The MINT message issues further batches of tokens. +The SEND message denotes the number of tokens sent to each output. +The COMMIT message is proposed to allow periodical commits of all transaction hashes on the token. + + +## Consensus rules + +In all cases of SLP transactions, there must be an [output script](/protocol/blockchain/transaction/locking-script#data-output) that begins with OP_RETURN (opcode 0x6a) within the first output (vout=0). +The data output should be an SLP message that conforms to the predefined format. + + +For transfer transactions (SEND), the sum of token outputs specified OP_RETURN may not exceed the sum of valid token inputs. +Valid token inputs are transaction inputs where the previous transactions are known to conform to SLP consensus rules. +The values of valid token inputs are as listed in SLP messages of the transactions that create the transaction outputs. +Inputs of differing token types or token IDs are ignored. + +For issuance transactions (GENESIS/MINT), Genesis transactions are self-evidently valid or invalid, and MINT transactions require the baton input for the token being issued. +The baton is either directly from the Genesis transaction that created it, or indirectly via the previous Mint transaction. +Inputs of differing token types or token IDs are ignored. +Token inputs are also ignored. + + +## Validation of the SLP transactions + +The “colored coins” design ensures that any transaction that attempts to double-spend SLP token outputs will also double-spend the BCH outputs, and thus, will be rejected by the network. +However, invalid SLP token transactions will be accepted by the network and included in the Blockchain if they are contained within valid BCH transactions. +Therefore, validation of an SLP transaction requires a directed acyclic graph (DAG), with transactions as its vertices and transaction inputs as its edges, that originates from the transaction that is being validated and terminates at the Mint or Genesis transaction. +Full nodes can construct the DAG proof for an SLP transaction by recursively iterating through the inputs of the said transaction to trace their ancestor transactions. + + +Several optimizations have been made to this process. +Vertices of transactions that provide zero tokens can be pruned, so are the input edges of known valid transactions. +Otherwise, DAG proof for SLP transactions can be cached to accelerate the proof of future SLP transactions if pruning is not employed. +The process can also stop before the full DAG is constructed when the sum of proved valid inputs exceeds the output sum, or when the sum of possibly valid inputs goes below the output sum. + +Without DAG proofs, other validation methods are also available. +Users can trust SLP transactions with incomplete DAG proofs. +However, such proofs can be exploited since an attacker can "bury" their invalid transaction by forging another transaction that seems to be valid by itself and spend the output of the invalid transaction. +This process can be repeatedly applied, resulting in a chain of transactions on top of the invalid transaction. +In such cases, the incomplete DAG may only capture the seemingly valid chain of transactions and thus, may produce a false proof. +Users can also rely on third-party API or block explorer for validation. +If checkpoints are available for the token, users can also use DAG proofs that terminate at transactions included the checkpoints to validate transactions of the said token. + + +## Advantages and disadvantages of SLP + +SLP is non-invasive, such that it does not make any change to Bitcoin Cash protocols. +Therefore, transactions that carry SLP tokens can be accepted and validated in the same way as typical BCH transactions by the network. +Meanwhile, the “colored coins” design allows SLP tokens to utilize the same security model of BCH since any attempts to double-spend SLP tokens will also double-spend the associated BCH transaction outputs, which will be rejected by the network. +However, since tokens are considered spent once their associated output is spent, token inputs of valid BCH transactions will always be spent, even if the token transactions within the messages are invalid or no token transaction is included. +Therefore, there is a risk that if wallet applications are not aware of the SLP tokens associated with certain BCH UTXOs or submitted invalid SLP transactions, due to bugs or unexpected errors, users may lose their SLP tokens with no possible remedies. +Also due to the “colored coins” design, SLP transactions must still obey the consensus rules of BCH transactions. +Therefore, outputs with SLP tokens would need to be above the dust threshold, and if the total BCH satoshis of the inputs with SLP tokens cannot afford the satoshis of the outputs, additional BCH satoshis input must be included. +Thus, users of SLP tokens may have to possess BCH satoshis in addition to the “colored coins” to facilitate their SLP transactions. +Such inconvenience, however, may be resolved through Postage services.