diff --git a/README.md b/README.md index f11a4ed..500e353 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +#### *Please note, the specification is currently not complete, partially outdated and does not entirely reflect the behavior of Omni Layer's reference client [Omni Core](https://github.com/OmniLayer/omnicore).* Omni Protocol Specification (formerly Mastercoin) ======================================================= @@ -27,11 +28,11 @@ We claim that the existing bitcoin network can be used as a protocol layer, on t Our claims are built on the following assumptions: * Alternate block chains compete with bitcoins financially, confuse our message to the world, and dilute our efforts. These barriers interfere with the adoption momentum of bitcoin and the adoption momentum of alternate currencies as well, regardless of how well-conceived their rules may be. -* New protocol layers on top of the bitcoin protocol will increase bitcoin values, consolidate our message to the world, and concentrate our efforts, while still allowing individuals and groups to issue new currencies with experimental new rules. The success of any experimental currency protocol layer will enhance the value and success of the foundational bitcoin protocol. -* Getting consensus and widespread adoption from the bitcoin community is not needed to add protocol layers, since no changes to the foundational bitcoin protocol are required. -* Tiny bitcoin transactions can be encoded into the block chain to support and represent transactions in higher protocol layers. -* A protocol can pay for its own software development, “bootstrapping” itself into existence, utilizing a trusted entity to hold funds and hire developers. -* It is possible to create tools to allow end users to create currency protocol layers which have a stable value, pegged to an external currency or commodity. In this way, users of these currencies can own stabilized virtual currency tied to U.S. Dollars, Euros, ounces of gold, barrels of oil, etc. +* New protocol layers on top of the bitcoin protocol will increase bitcoin values, consolidate our message to the world, and concentrate our efforts, while still allowing individuals and groups to issue new currencies with experimental new rules. The success of any experimental currency protocol layer will enhance the value and success of the foundational bitcoin protocol. +* Getting consensus and widespread adoption from the bitcoin community is not needed to add protocol layers, since no changes to the foundational bitcoin protocol are required. +* Tiny bitcoin transactions can be encoded into the block chain to support and represent transactions in higher protocol layers. +* A protocol can pay for its own software development, “bootstrapping” itself into existence, utilizing a trusted entity to hold funds and hire developers. +* It is possible to create tools to allow end users to create currency protocol layers which have a stable value, pegged to an external currency or commodity. In this way, users of these currencies can own stabilized virtual currency tied to U.S. Dollars, Euros, ounces of gold, barrels of oil, etc. * It is possible for users of these new currencies to exchange between currencies with each other using simple rules and no central exchange. @@ -39,7 +40,7 @@ Our claims are built on the following assumptions: The proposed protocol layers can be visualized as follows, with arrows representing users exchanging between currencies: -![Omni Protocol Layers](images/layers.png) +![Omni Protocol Layers](images/layers.png) Note that all transfers of value are still stored in the normal bitcoin block chain, but higher layers of the protocol assign additional meaning to some transactions. @@ -51,9 +52,9 @@ Note that all transfers of value are still stored in the normal bitcoin block ch 1. Version 0.2 (previously 1.0) released 31 Jul 2013 (Version used during the crowdsale) 1. Version 0.3 (previously 1.1) released 9 Sep 2013 (Smart Property + improvements for easier parsing & better escrow fund health) 1. Version 0.3.5 (previously 1.2) released 11 Nov 2013 (Added "Send To Owners" message, spending limits for savings wallets, contract-for-difference bets, and distributed e-commerce messages. Also added Zathras' new appendix (description of class B and class C methods of storing Omni Protocol data). -1. Version 0.4 released 15 Feb 2014 (defined transaction message fields in a separate section, specified 5 transactions for initial deployment, added transaction version, New/Update/Cancel for sell offers, corrected dust threshold value) +1. Version 0.4 released 15 Feb 2014 (defined transaction message fields in a separate section, specified 5 transactions for initial deployment, added transaction version, New/Update/Cancel for sell offers, corrected dust threshold value) 1. Version 0.4.5 released 20 Feb 2014 (added smart property crowdsale, other improvements to future features) -1. Version 0.4.5.1 released 3 Mar 2014 (clarified Sell MSC for Bitcoins behavior) +1. Version 0.4.5.1 released 3 Mar 2014 (clarified Sell MSC for Bitcoins behavior) 1. Version 0.4.5.2 released 31 Mar 2014 (clarified details of smart property creation) 1. Version 0.4.5.3 released 3 Apr 2014 (corrected details of smart property administration) 1. Version 0.4.5.4 released 10 Apr 2014 (corrected/clarified invalid Simple Sends) @@ -79,9 +80,9 @@ Note that all transfers of value are still stored in the normal bitcoin block ch This terminology is deprecated and the specification will shortly be updated to use the appropriate, new Omni terminology where appropriate. -* The term M.A.S.T.E.R. is an acronym for "Metadata Archival by Standard Transaction Embedding Records" +* The term M.A.S.T.E.R. is an acronym for "Metadata Archival by Standard Transaction Embedding Records" * The term "Master Protocol" applies to the specification and the clients that implement its features. -* The term "MSC Protocol" is used as the abbreviation for "Master Protocol". +* The term "MSC Protocol" is used as the abbreviation for "Master Protocol". # Omni Protocol Design @@ -93,7 +94,7 @@ Perhaps you have heard of the “Genesis Block” which launched the Bitcoin pro Initial distribution of Mastercoins was essentially a kickstarter style period to provide funding to pay developers to write the software which fully implements the protocol. The distribution was very simple, and proceeded as follows: -1. Anyone who sent bitcoins to the Exodus Address before August 31st, 2013 was recognized by the protocol as owning 100x that number of Mastercoins. For instance, if I sent 100 bitcoins to the Exodus Address before August 31st, my bitcoin address owns 10,000 Mastercoins after August 31st. +1. Anyone who sent bitcoins to the Exodus Address before August 31st, 2013 was recognized by the protocol as owning 100x that number of Mastercoins. For instance, if I sent 100 bitcoins to the Exodus Address before August 31st, my bitcoin address owns 10,000 Mastercoins after August 31st. 2. Early buyers got additional Mastercoins. In order to encourage adoption momentum, buyers got an additional 10% bonus Mastercoins if they made their purchase a week before the deadline, 20% extra if they purchased two weeks early, and so on, including partial weeks. Thus, if I sent 100 bitcoins to the exodus address 1.5 weeks before August 31st, the protocol recognized my bitcoin address as owning 11,500 Mastercoins (10000 + 15% bonus). 3. Attempts to send funds to the Exodus Address on or after September 1st 2013 (after block #255365) were not considered Mastercoin purchases, and were refunded to the sender. @@ -110,19 +111,19 @@ Initially, the only valid Omni transaction was a “simple send” (defined late 2. As dev MSC vest, 50% of them are sent out as bonuses to people who won Mastercoin bounties, in proportion to how much bounty money they won (bitcoins). The other 50% are used for expenses such as retention bonuses. Eventually, the Mastercoin Foundation will turn over all remaining funds to a distributed bounty system, with the Omni Protocol paying its own bounties via a proof-of-stake voting system, and the Mastercoin Foundation will no longer need to administer any funds for the project. -Technical notes: +Technical notes: * Any Omni Protocol implementation implementing Exodus balance must recalculate the Development Mastercoin amount on each new block found and use the block timestamp for y. * When calculating the years since the Mastercoin sale we assume a year is 31556926 seconds. * 1377993874 is the Unix timestamp used to define the end-date of Exodus and thus the start date for the Development Mastercoins vesting. -* Current implementations do not have Test MSC which vest alongside dev MSC, but such coins may be recognized at some point in the future if it is deemed desireable +* Current implementations do not have Test MSC which vest alongside dev MSC, but such coins may be recognized at some point in the future if it is deemed desireable ## Embedding Omni Protocol Data in the Block Chain Bitcoin has some little-known advanced features (such as scripting) which many people imagine will enable it to perform fancy new tricks someday. The Omni Protocol uses exactly NONE of those advanced features, because support for them is not guaranteed in the future, and the Omni Protocol doesn't need them to embed data in the block chain. -The Omni Protocol was originally specified to embed data in the block chain using fake bitcoin addresses (Class A), but we've since come up with a more blockchain friendly method which embeds data in a bitcoin multi-signature transaction (Class B). Once bitcoin miners start supporting the new OP_RETURN opcode as part of version 0.9 of the Bitcoin reference client, Omni Protocol will be able to use that opcode to make the Omni Protocol data completely prune-able (Class C) see description here by Gavin Andresen here: https://bitcoinfoundation.org/blog/?p=290 +The Omni Protocol was originally specified to embed data in the block chain using fake bitcoin addresses (Class A), but we've since come up with a more blockchain friendly method which embeds data in a bitcoin multi-signature transaction (Class B). Once bitcoin miners start supporting the new OP_RETURN opcode as part of version 0.9 of the Bitcoin reference client, Omni Protocol will be able to use that opcode to make the Omni Protocol data completely prune-able (Class C) see description here by Gavin Andresen here: https://bitcoinfoundation.org/blog/?p=290 Class C transactions are most preferred due to the Provably Prune-able Outputs avoiding issues of "bloat" and "pollution" of the block chain. @@ -130,7 +131,7 @@ The technical details for both Class A and Class B transactions can be found in ## Special Considerations to Avoid Invalid Transactions -Not every bitcoin wallet lets you choose which address bitcoins come from when you make a payment, and Omni transactions must all come from the address which holds the Mastercoins being used. If a bitcoin wallet contains bitcoins stored in multiple addresses, the user (or Omni Protocol software) must first ensure that the address which is going to send the Omni transaction has sufficient balance in bitcoins to create the transaction. Then, the Omni-related transaction can be sent successfully from that address. +Not every bitcoin wallet lets you choose which address bitcoins come from when you make a payment, and Omni transactions must all come from the address which holds the Mastercoins being used. If a bitcoin wallet contains bitcoins stored in multiple addresses, the user (or Omni Protocol software) must first ensure that the address which is going to send the Omni transaction has sufficient balance in bitcoins to create the transaction. Then, the Omni-related transaction can be sent successfully from that address. Wallets which do not allow you to consolidate to one address and send from that address (such as online web wallet providers) will not work for Omni unless they are modified to do so. For this reason, **attempting to purchase Mastercoins from an online web wallet will likely result in the permanent loss of those Mastercoins.** @@ -138,7 +139,7 @@ Other than for these hosted wallets, a bitcoin address can also be treated as an ## Best Practices for Handling Blockchain Reorganizations -Occasionally the bitcoin blockchain experiences a "reorg", when the current longest chain is replaced by another longer chain. Sometimes this results in recent transactions changing their order, or which transactions are included. +Occasionally the bitcoin blockchain experiences a "reorg", when the current longest chain is replaced by another longer chain. Sometimes this results in recent transactions changing their order, or which transactions are included. The Omni Protocol depends heavily on the order in which transactions appear in the blockchain. Even transactions in the same block can have different meaning or validity depending on the order in which they are recorded. Consequently, wallets and other blockchain parsers which also parse Omni Protocol transactions need to detect these reorganizations and reparse the affected blocks, changing Omni Protocol balances according to the the new ordering of transactions. @@ -152,15 +153,15 @@ Also, in many cases a user may wish to do something with Mastercoins recently se There are two broad categories of transactions which have no fees (other than fees charged by the bitcoin protocol layer): -1. All tokens in the MSC protocol can be sent (using simple send) with no fees. +1. All tokens in the MSC protocol can be sent (using simple send) with no fees. 2. Any transaction which directly uses Mastercoin also has no fees. 3. Creating a property does not carry a fee (we don't want barriers to entry) 4. Property management (changing ownership, issuing new tokens, revoking tokens, etc) does not carry a fee (integral to some business models, which we don't want to discourage) Here are some examples of transactions which have no fee: -* Sending MaidsafeCoin using simple send -* Buying and selling MaidsafeCoin using Mastercoin on the distributed exchange +* Sending MaidsafeCoin using simple send +* Buying and selling MaidsafeCoin using Mastercoin on the distributed exchange * Placing a bet denominated in Mastercoin * Paying Mastercoin to all Mastercoin holders (pay to owners) * Paying Mastercoin to purchase a physical good on the distributed e-commerce platform @@ -217,11 +218,11 @@ This section defines the fields that are used to construct transaction messages. + Description: the currency used in the transaction + Size: 32-bit unsigned integer, 4 bytes + Inter-dependencies: [Ecosystem](#field-ecosystem) -+ Valid values: ++ Valid values: * 1 and 3 to 2,147,483,647 in the real MSC ecosystem (2,147,483,646 unique values) * 1 = Mastercoin * 2 and 2,147,483,651 to 4,294,967,295 in the Test MSC ecosystem (Test MSC currencies and properties have the most significant bit set, values start with 0x80000003, yielding 2,147,483,646 unique values) - * 2 = Test Mastercoin + * 2 = Test Mastercoin ### Field: Ecosystem + Description: Specifies whether a smart property is traded against test MSC or real MSC @@ -297,7 +298,7 @@ This section defines the fields that are used to construct transaction messages. ### Field: Time period in blocks + Description: number of blocks during which an action can be performed + Size: 8-bit unsigned integer, 1 byte -+ Valid values: 1 to 255 ++ Valid values: 1 to 255 ### Field: UTC Datetime + Description: Datetime, assuming UTC timezone (the same timezone used by the bitcoin blockchain) @@ -375,7 +376,7 @@ Each transaction definition has its own version number to enable support for cha Omni Protocol transactions are not reversible except as explicitly indicated by this spec. -Any Omni transaction from any address that attempts to transfer, reserve, commit coins, or put coins in escrow while that address's available balance for that currency identifier is 0 will be invalidated. +Any Omni transaction from any address that attempts to transfer, reserve, commit coins, or put coins in escrow while that address's available balance for that currency identifier is 0 will be invalidated. ## Transferring coins @@ -400,7 +401,7 @@ Say you want to transfer 1 Mastercoin to another address. Only 16 bytes are need | **Field** | **Type** | **Example** | | ---- | ---- | ---- | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 0 | +| Transaction type | [Transaction type](#field-transaction-type) | 0 | |Currency identifier| [Currency identifier](#field-currency-identifier) |1 (Mastercoin)| |Amount to transfer|[Number of Coins](#field-number-of-coins)|100,000,000 (1.0 coins) | @@ -409,7 +410,7 @@ Say you want to transfer 1 Mastercoin to another address. Only 16 bytes are need Description: Transaction type 3 transfers coins in the specified currency from the sending address to the current owners of that currency. The current owners are all the addresses, excluding the sender's address, that have a non-zero balance of the specified currency when the transaction message is processed. The Amount to transfer must be divided proportionally among the current owners based upon each owner's current available balance plus reserved amount, excluding the amount owned by the sender. If there are no owners of the property excluding the sending address, the transaction is invalid. The sending address must be charged a transfer fee for each address that receives coins as a result of this transaction. The fee is: -* 0.00000001 Mastercoins for currencies in the MSC ecosystem, and +* 0.00000001 Mastercoins for currencies in the MSC ecosystem, and * 0.00000001 Test Mastercoins for currencies in the Test MSC ecosystem. See [Currency Identifier](#field-currency-identifier), above. @@ -460,7 +461,7 @@ Say you want to publish an offer to sell 1.5 Mastercoins for 1000 bitcoins. Doin | **Field** | **Type** | **Example** | | ---- | ---- | ---- | | Transaction version |[Transaction version](#field-transaction-version) | 1 | -| Transaction type | [Transaction type](#field-transaction-type) | 20| +| Transaction type | [Transaction type](#field-transaction-type) | 20| |Currency identifier| [Currency identifier](#field-currency-identifier) |1 (Mastercoin) | |Amount for sale|[Number of Coins](#field-number-of-coins)|150,000,000 (1.5 coins) | |Amount of bitcoins desired|[Number of Coins](#field-number-of-coins)|100,000,000,000 (1000.0 coins) | @@ -483,7 +484,7 @@ The change will apply to the balance that has not yet been accepted with a purch The amount reserved from the available balance for this address will be adjusted to reflect the new amount for sale. Note that the amount reserved as a result of the update is based on the available balance at the time of the update plus the existing sell offer amount not yet accepted at the time of the update. -Say you decide you want to change an offer, e.g. the number of coins you are offering for sale, or change the asking price. Send the transaction with the new values and the values that are not changing and Action = 2 (Update) before the whole amount offered has been accepted. Note that while the portion of an offer which has been accepted cannot be changed, sending an update message still has an effect, in that it affects any coins which have not been accepted, and it affects accepted coins if the buyer fails to send payment. +Say you decide you want to change an offer, e.g. the number of coins you are offering for sale, or change the asking price. Send the transaction with the new values and the values that are not changing and Action = 2 (Update) before the whole amount offered has been accepted. Note that while the portion of an offer which has been accepted cannot be changed, sending an update message still has an effect, in that it affects any coins which have not been accepted, and it affects accepted coins if the buyer fails to send payment. #### Cancel a Coin Sell Offer @@ -497,7 +498,7 @@ When canceling a sell offer, the values in the following fields are not tested f The cancel will apply to the amount that has not yet been accepted. The UI must indicate if the cancellation was successful and how many coins were not sold. -If you want to cancel an offer, use Action = 3 (Cancel) and send the transaction before the full amount for sale has been accepted. Note that while the portion of an offer which has been accepted cannot be canceled, sending the cancel message still has an effect, in that it cancels any portion of the offer which has not been accepted, and it prevents accepted coins from being relisted if the buyer fails to send payment. +If you want to cancel an offer, use Action = 3 (Cancel) and send the transaction before the full amount for sale has been accepted. Note that while the portion of an offer which has been accepted cannot be canceled, sending the cancel message still has an effect, in that it cancels any portion of the offer which has not been accepted, and it prevents accepted coins from being relisted if the buyer fails to send payment. ### Purchase Mastercoins with Bitcoins @@ -515,14 +516,14 @@ Please note that the buyer is allowed to send multiple bitcoin payments between In order to make parsing Omni Protocol transactions easier, you must also include an output to the Exodus Address when sending the bitcoins to complete a purchase of Mastercoins. The output can be for any amount, but should be at least as high as the amount which is considered as dust threshold by a majority of Bitcoin nodes so that propagation of the transaction within the network and confirmation by a miner is not delayed. -Other Omni Protocol messages (for instance if the buyer wants to change his offer) are not counted towards the actual purchase, even though bitcoins are sent to the selling address as part of encoding the messages. +Other Omni Protocol messages (for instance if the buyer wants to change his offer) are not counted towards the actual purchase, even though bitcoins are sent to the selling address as part of encoding the messages. Say you see an offer such as the one listed above, and wish to initiate a purchase of those coins. Doing so takes 16 bytes: | **Field** | **Type** | **Example** | | ---- | ---- | ---- | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 22| +| Transaction type | [Transaction type](#field-transaction-type) | 22| |Currency identifier| [Currency identifier](#field-currency-identifier) |1 (Mastercoin) | |Amount to be purchased|[Number of Coins](#field-number-of-coins)|130,000,000 (1.3 coins) | @@ -569,13 +570,13 @@ Notes on rounding, with me (the new order) purchasing from Bob (the existing ord 1. If the amount I would have to pay to buy Bob's tokens at his price is fractional, always round UP the amount I have to pay * This will always be better for Bob. Rounding in the other direction will always be impossible (would violate Bob's required price) * If the resulting adjusted unit price is higher than my price, the orders did not really match (no representable fill can be made) - * Example: if those 8 tokens would cost me 15.1 indivisible tokens, I must pay 16 tokens, or NO SALE + * Example: if those 8 tokens would cost me 15.1 indivisible tokens, I must pay 16 tokens, or NO SALE Note: After a partial fill, the unit price for an order does not change, (this is to avoid orders moving around in the order book). For example, if the initial price was 23 for 100, the price will remain at that ratio regardless of any partial fills. - + It is valid for the purchaser’s address to be the same as the seller’s address. -An existing order matches the new order when all of the following conditions are met: +An existing order matches the new order when all of the following conditions are met: 1. the existing order's Currency id for sale is the same as the new order's Currency id desired 1. the existing order's Currency id desired is the same as the new order's Currency id for sale @@ -595,14 +596,14 @@ Say you want to publish an offer to sell 2.5 Mastercoins for 50 GoldCoins (hypot | **Field** | **Type** | **Example** | | ---- | ---- | ---- | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 21| +| Transaction type | [Transaction type](#field-transaction-type) | 21| |Currency identifier for sale| [Currency identifier](#field-currency-identifier) |1 for Mastercoin| |Amount for sale|[Number of Coins](#field-number-of-coins)|250,000,000 (2.5 coins) | |Currency identifier desired| [Currency identifier](#field-currency-identifier) |3 for GoldCoin | |Amount desired|[Number of Coins](#field-number-of-coins)|5,000,000,000 (50.0 coins) | -| Action | [Metadex Sell Offer sub-action](#field-metadex-sell-offer-sub-action) | 1 (ADD new funds for sale) | +| Action | [Metadex Sell Offer sub-action](#field-metadex-sell-offer-sub-action) | 1 (ADD new funds for sale) | -Although the formatting of this message technically allows trading between any two currencies/properties, we currently require that either the currency id for sale or the currency id desired be Mastercoins (or Test Mastercoins), since those currencies are the universal token of the protocol and the only ones which can be traded for bitcoins on the distributed exchange (and thus exit the Omni ecosystem without trusting a centralized exchange). This provides each currency and property better liquidity than a multi-dimensional order book ever could, and it reduces the complexity of the software. If another currency becomes widely used in the Omni Protocol, we may allow other currencies (such as a USDCoin) to be used in a similar way, with a tiny amount of MSC being automatically purchased and burned with each trade (see the [section on fees](#fees) above) when a trade is completed and neither currency being traded is Mastercoin. +Although the formatting of this message technically allows trading between any two currencies/properties, we currently require that either the currency id for sale or the currency id desired be Mastercoins (or Test Mastercoins), since those currencies are the universal token of the protocol and the only ones which can be traded for bitcoins on the distributed exchange (and thus exit the Omni ecosystem without trusting a centralized exchange). This provides each currency and property better liquidity than a multi-dimensional order book ever could, and it reduces the complexity of the software. If another currency becomes widely used in the Omni Protocol, we may allow other currencies (such as a USDCoin) to be used in a similar way, with a tiny amount of MSC being automatically purchased and burned with each trade (see the [section on fees](#fees) above) when a trade is completed and neither currency being traded is Mastercoin. An offer to sell coins can be changed or cancelled by publishing additional transactions with [Metadex Sell offer sub-action](#field-metadex-sell-offer-sub-action) variations: @@ -613,7 +614,7 @@ An offer to sell coins can be changed or cancelled by publishing additional tran * [Action](#field-metadex-sell-offer-sub-action) = 3 (CANCEL-ALL-FOR-CURRENCY-PAIR) cancels all open orders for a given set of two currencies (one side of the order book). * [Action](#field-metadex-sell-offer-sub-action) = 4 (CANCEL-EVERYTHING) can be used to cancel all open orders for all currencies within one ecosystem, if [Currency identifier for sale](#field-currency-identifier) and [Currency identifier desired](#field-currency-identifier) are within the same ecosystem, otherwise all open orders for all currencies of both ecosystems are cancelled. - + When using [Action](#field-metadex-sell-offer-sub-action) = 3 (CANCEL-ALL-FOR-CURRENCY-PAIR) the validity of the following fields is not tested: * [Amount for sale](#field-number-of-coins) * [Amount desired](#field-number-of-coins) @@ -636,15 +637,15 @@ The Omni Protocol supports the creation of property tokens to be used for titles Properties are awarded currency identifiers in the order in which they are created. Mastercoin is currency identifier 1 (bitcoin is 0), and Test Mastercoins have currency identifier 2. Additional properties and currencies therefore start at ID #3. Properties issued and traded using real MSC are kept completely distinct from those issued and traded using Test MSC, so the ID numbering systems for the two [ecosystems](#field-ecosystem) are independent. Test Mastercoin properties have the most significant bit set to distinguish them from real properties, and they cannot be traded against real Mastercoins nor otherwise interact with non-test properties. Test MSC property IDs also start numbering from 3, but with the most significant bit set. In sandbox environments using only Test MSC, these IDs can be displayed without the MSB set, for easier reading. -Every property has a [Property type](#field-property-type), which defines whether it is divisible or not and whether the property replaces or appends a previous property. To create 1,000,000 units of a divisible currency, choose property type 2 and specify 100,000,000,000,000 for the number of properties (1 million divisible to 8 decimal places). For 1,000,000 indivisible tokens for a company, choose property type 1 and specify 1,000,000 for the number of properties. The difference between divisible and indivisible property types is how they are displayed (i.e. where the decimal point goes) and the range of valid values that can be specified in a transaction message field (see [Number of coins](#field-number-of-coins)). +Every property has a [Property type](#field-property-type), which defines whether it is divisible or not and whether the property replaces or appends a previous property. To create 1,000,000 units of a divisible currency, choose property type 2 and specify 100,000,000,000,000 for the number of properties (1 million divisible to 8 decimal places). For 1,000,000 indivisible tokens for a company, choose property type 1 and specify 1,000,000 for the number of properties. The difference between divisible and indivisible property types is how they are displayed (i.e. where the decimal point goes) and the range of valid values that can be specified in a transaction message field (see [Number of coins](#field-number-of-coins)). The attributes of an existing property cannot be changed. However, a new property can be created to replace or append an existing property. Only the address that issued a property can replace or append that property. Attempts by other addresses are invalid. A replaced property can still be used and traded as normal, but the UI should indicate to the user that a newer version of the property exists and link to it. To indicate that the issuer is abandoning a property entirely: * set Previous Property ID to that property's id, * set Number Properties to zero, and -* use one of the "replace" values for [Property Type](#field-property-type) (see Transaction types [50](#new-property-creation-with-fixed-number-of-tokens) and [51](#new-property-creation-via-crowdsale-with-variable-number-of-tokens), below). +* use one of the "replace" values for [Property Type](#field-property-type) (see Transaction types [50](#new-property-creation-with-fixed-number-of-tokens) and [51](#new-property-creation-via-crowdsale-with-variable-number-of-tokens), below). A property can be replaced and appended multiple times, even abandoning and un-abandoning it more than once. Appended properties must not be treated as the same asset in the UI or protocol parsers (the appended properties have independent values). When displaying a property, the UI should provide links to any related properties. Related properties are the property which was replaced or appended by this property (if there is one) as well as any properties from the same issuer which replace or append this property. - + The Ecosystem for the property must be the same as the ecosystem for the "Currency identifier desired", i.e. both must be in the Mastercoin ecosystem or both must be in the Test Mastercoin ecosystem. Currently only new property creation is supported, and the append/replace property types (65/66/129/130) will be made live at block #TBD. @@ -665,7 +666,7 @@ Description: Transaction type 50 is used to create a new Smart Property with a f If creating a title to a house or deed to land, the number of properties should be 1. Don’t set number of properties to 10 for 10 pieces of land – create a new property for each piece of land, since each piece of land inherently has a different value, and they are not interchangeable. -Once this property has been created, the tokens are owned by the address which broadcast the message creating the property. +Once this property has been created, the tokens are owned by the address which broadcast the message creating the property. In addition to the validity constraints for each message field type, the following conditions must be met in order for the transaction to be valid: * "Previous Property ID" must be 0 when "Property Type" indicates a new property @@ -695,7 +696,7 @@ Description: Transaction type 51 is used to initiate a crowdsale which creates a Effective with version 1 of Transaction type 51 and block #(TBD), a single crowdsale is able to accept multiple currencies, including bitcoins (currency id 0), for purchases of a Smart Property in a single crowdsale. See [Accepting Multiple Currencies in a Crowdsale](#accepting-multiple-currencies-in-a-crowdsale) below. The crowdsale is active until any of the following conditions occurs, which causes the crowdsale to be closed permanently: -* there is a block with a blocktime greater than or equal to the crowdsale's "Deadline" value +* there is a block with a blocktime greater than or equal to the crowdsale's "Deadline" value * the crowdsale is [manually closed](#close-a-crowdsale-manually) * the maximum number of tokens that can be issued by a crowdsale has been credited (92,233,720,368.54775807 divisible tokens or 9,223,372,036,854,775,807 indivisible tokens, see field [Number of Coins](#field-number-of-coins)). @@ -715,7 +716,7 @@ The number of tokens credited to the purchaser is: (1 + (EBpercentage / 100.0) ) * "Number Properties per Unit Invested" value * the number of coins sent by the purchaser -Note: To make it easier for issuers, a client UI could let the user enter an initial early bird bonus percentage and then convert that to the weekly percentage value required by the Transaction type 51 message. For example, an initial early bird bonus percentage of 30% would convert to "Early bird bonus %/week" value = 7 for a 30 day crowdsale. This would be particularly helpful for crowdsale lengths that are not a multiple of 7 days. Similarly, a client UI could do a complementary conversion in order to present the current early bird bonus percentage to prospective crowdsale participants. +Note: To make it easier for issuers, a client UI could let the user enter an initial early bird bonus percentage and then convert that to the weekly percentage value required by the Transaction type 51 message. For example, an initial early bird bonus percentage of 30% would convert to "Early bird bonus %/week" value = 7 for a 30 day crowdsale. This would be particularly helpful for crowdsale lengths that are not a multiple of 7 days. Similarly, a client UI could do a complementary conversion in order to present the current early bird bonus percentage to prospective crowdsale participants. The issuer may choose to receive a number of tokens in proportion to the number of tokens credited for each purchase. The "Percentage for issuer" value is used to calculate the number of *additional* tokens generated and credited to the issuer's address as follows: @@ -772,7 +773,7 @@ While the crowdsale is active, the crowdsale owner's address must be able to cha ### Participating in a Crowdsale Participating in a crowdsale is accomplished by sending coins of one of the desired currencies to the crowdsale owner's address with the [Simple Send](#transfer-coins-simple-send) transaction or a bitcoin Send transaction if the crowdsale accepts bitcoins (currency id 0) for purchases. Use multiple Sends to make multiple purchases in the crowdsale. In order to participate in the crowdsale, the currency id must match one of the "Currency identifier desired" values being accepted in the crowdsale and the Send message must be confirmed before any of the following conditions occurs: -* there is a block with a blocktime greater than or equal to the crowdsale's "Deadline" value +* there is a block with a blocktime greater than or equal to the crowdsale's "Deadline" value * the crowdsale is [manually closed](#close-a-crowdsale-manually) * the maximum number of tokens that can be issued by a crowdsale has been generated (92,233,720,368.54775807 divisible tokens or 9,223,372,036,854,775,807 indivisible tokens, see field [Number of Coins](#field-number-of-coins)). @@ -782,7 +783,7 @@ Note: It is possible for a bitcoin block to have a blocktime earlier than a prev For divisible properties, the sending address will be credited with the number of tokens calculated as the corresponding "Number Properties per unit invested" value multiplied by the number of coins (units) specified in the Send message, plus that number of tokens multiplied by the percentage based on the "Early Bird Bonus %/Week" value, to eight decimal places. -For indivisible properties, the sending address will be credited with the number of tokens calculated as the corresponding "Number Properties per unit invested" value multiplied by the number of coins (units) specified in the Send message, plus that number of tokens multiplied by the percentage based on the "Early Bird Bonus %/Week" value, rounded down to an integer number of tokens (with no fractional portion). +For indivisible properties, the sending address will be credited with the number of tokens calculated as the corresponding "Number Properties per unit invested" value multiplied by the number of coins (units) specified in the Send message, plus that number of tokens multiplied by the percentage based on the "Early Bird Bonus %/Week" value, rounded down to an integer number of tokens (with no fractional portion). The aggregate number of tokens credited in a crowdsale is limited by the maximum allowable number of tokens in a Smart Property (see [Number of coins](#field-number-of-coins)). The UI should accurately display the number of tokens that will be credited to the sending address. @@ -793,11 +794,11 @@ Note these important details: + If the Send transaction is confirmed after the crowdsale is closed or if for any other reason no crowdsale is active, no purchase will be made and no tokens will be credited to the sending address, but the Send itself will complete. + Tokens credited to the sending address and the issuer address are immediately added to the available balance belonging to the respective addresses and can be spent or otherwise used by that address. + The funds received are immediately added to the available balance belonging to the crowdsale owner's address and can be spent or otherwise used by that address. -+ When accepting currencies other than Mastercoin, a small fee will be deducted (see [fees](#fees) above) from the coins issued to crowdsale participants. ++ When accepting currencies other than Mastercoin, a small fee will be deducted (see [fees](#fees) above) from the coins issued to crowdsale participants. ### Promote a property -Say that having created your "Quantum Miner" smart property (which was assigned property ID #8) you now want it to show up higher in the list of properties. You decide to spend 3 Mastercoins to promote your smart property so that it is displayed higher in the list than all the spam/scam/experimental properties. Doing so takes 13 bytes: +Say that having created your "Quantum Miner" smart property (which was assigned property ID #8) you now want it to show up higher in the list of properties. You decide to spend 3 Mastercoins to promote your smart property so that it is displayed higher in the list than all the spam/scam/experimental properties. Doing so takes 13 bytes: 1. [Transaction version](#field-transaction-version) = 0 1. [Transaction type](#field-transaction-type) = 52 @@ -805,7 +806,7 @@ Say that having created your "Quantum Miner" smart property (which was assigned 1. [Property ID](#field-currency-identifier) = 8 1. [Number of Mastercoins](#field-number-of-coins) = 300,000,000 (3.00000000 Mastercoins) -This transaction permanently destroys Mastercoins in exchange for favorable placement of this property in the default sort-ordering of properties on every UI. Protocol parsers accumulate all promotions of a property (which can be done by any address which has Mastercoins), with newer promotions being worth more than older promotions. +This transaction permanently destroys Mastercoins in exchange for favorable placement of this property in the default sort-ordering of properties on every UI. Protocol parsers accumulate all promotions of a property (which can be done by any address which has Mastercoins), with newer promotions being worth more than older promotions. To accomplish this time-weighting, a promotion is worth (# Mastercoins spent) * 3^(years since exodus), where "years since exodus" is the number of years (including partial years) since the Mastercoin crowdsale ended on September 1st 2013, and thus new promotions are always worth 3x as much as year-old promotions and 9x as much as two-year-old promotions if the same number of Mastercoins were spent on each. @@ -822,7 +823,7 @@ It is invalid to attempt to close a crowdsale that is not active. Closing an act | **Field** | **Type** | **Example** | | ---- | ---- | ----: | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 53| +| Transaction type | [Transaction type](#field-transaction-type) | 53| | Property ID | [Currency identifier](#field-currency-identifier) | 9 | Note that attempts to participate in a closed crowdsale will result in no investment in that crowdsale and no tokens from that crowdsale will be credited as a result of these attempts. See [Participating in a Crowdsale](#particpating-in-a-crowdsale) for details. @@ -870,7 +871,7 @@ Say that you have a smart property whose ID is 8 and you have just reached a fun | **Field** | **Type** | **Example** | | ---- | ---- | ----: | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 55| +| Transaction type | [Transaction type](#field-transaction-type) | 55| | Property ID | [Currency identifier](#field-currency-identifier) | 8 | | Number Properties | [Number of coins](#field-number-of-coins) | 1,000 | | Memo (Optional) | [String null-terminated](#field-string-255-byte-null-terminated) | “First Milestone Reached!” (24 byte) | @@ -880,7 +881,7 @@ This feature is supported since block number 323230. Description: Properties issued with a [Property with Managed Number of Tokens](#new-property-with-managed-number-of-tokens) transaction may have tokens voluntarily revoked from the balance of any address that has a positive token balance. -It is invalid to attempt to revoke tokens on any property that was not broadcast as a [Property with Managed Number of Tokens](#new-property-with-managed-number-of-tokens). +It is invalid to attempt to revoke tokens on any property that was not broadcast as a [Property with Managed Number of Tokens](#new-property-with-managed-number-of-tokens). It is invalid to attempt to broadcast a token revoke on any property for an address other than the address that broadcasts the revoke transaction. @@ -891,7 +892,7 @@ Say that your project is finished and you want to start burning tokens in exchan | **Field** | **Type** | **Example** | | ---- | ---- | ----: | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 56| +| Transaction type | [Transaction type](#field-transaction-type) | 56| | Property ID | [Currency identifier](#field-currency-identifier) | 8 | | Number Properties | [Number of coins](#field-number-of-coins) | 1,000 | | Memo | [String null-terminated](#field-string-255-byte-null-terminated) | “Redemption of tokens for Bob, Thanks Bob!” (42 byte) | @@ -916,13 +917,13 @@ Say that you wanted to transfer the Issuer on Record status to another address o | **Field** | **Type** | **Example** | | ---- | ---- | ----: | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 70| +| Transaction type | [Transaction type](#field-transaction-type) | 70| | Property ID | [Currency identifier](#field-currency-identifier) | 13 | # Future Transactions -The transactions below are still subject to revision and therefore are not included in deployments based on this version of the spec. +The transactions below are still subject to revision and therefore are not included in deployments based on this version of the spec. ## Creating a List of Addresses @@ -933,12 +934,12 @@ To create or append a list of addresses, publish the following notification from | **Field** | **Type** | **Example** | | ---- | ---- | ---- | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 32| -| Number of addresses | [Integer one-byte](#field-integer-one-byte) | 4| -| Address 1 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEE | -| Address 2 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BED | -| Address 3 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEC | -| Address 4 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEB | +| Transaction type | [Transaction type](#field-transaction-type) | 32| +| Number of addresses | [Integer one-byte](#field-integer-one-byte) | 4| +| Address 1 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEE | +| Address 2 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BED | +| Address 3 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEC | +| Address 4 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEB | That transaction effectively starts the list (or appends it), and provides a handle to refer to the list (the address which published this message). Note that this transaction could be massive if a lot of addresses are added, and may require large fees in bitcoins. Additionally, 0.00000001 MSC (smallest unit of MSC) are burned for each address added, so the address maintaining the list must have enough MSC and BTC on hand to cover these fees. @@ -950,10 +951,10 @@ To remove addresses from a list, publish the following notification from the add | **Field** | **Type** | **Example** | | ---- | ---- | ---- | | Transaction version |[Transaction version](#field-transaction-version) | 0 | -| Transaction type | [Transaction type](#field-transaction-type) | 33| -| Number of addresses | [Integer one-byte](#field-integer-one-byte) |2| -| Address 1 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEE | -| Address 2 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BED | +| Transaction type | [Transaction type](#field-transaction-type) | 33| +| Number of addresses | [Integer one-byte](#field-integer-one-byte) |2| +| Address 1 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BEE | +| Address 2 | [Bitcoin Address](#field-bitcoin-address) | 010966776006953D5567439E5E39F86A0D273BED | Any referenced addresses are removed from the list. Note that as with the previous transaction type, this transaction could be massive if a lot of addresses are removed, and may require large fees in bitcoins. Additionally, 0.00000001 MSC (smallest unit of MSC) are burned for each address removed, so the address maintaining the list must have enough MSC and BTC on hand to cover these fees. @@ -967,7 +968,7 @@ The Omni Protocol defines some transactions which effectively lock funds from be 1. [Transaction version](#field-transaction-version) = 0 1. [Transaction type](#field-transaction-type) = 10 -1. [Reversibility period](#field-time-period-in-seconds) = 2,592,000 (30 days) +1. [Reversibility period](#field-time-period-in-seconds) = 2,592,000 (30 days) Marking an address as savings is PERMANENT and cannot be undone. If an address is marked as savings, the reversibility rules affect not only Mastercoins, but any Omni Protocol child currency stored at that address. @@ -981,7 +982,7 @@ Say you send funds out of a savings wallet. Doing so requires using a transactio 1. [Transaction version](#field-transaction-version) = 0 1. [Transaction type](#field-transaction-type) = 2 -1. [Currency identifier](#field-currency-identifier) = 1 for Mastercoin +1. [Currency identifier](#field-currency-identifier) = 1 for Mastercoin 1. [Amount to transfer](#field-number-of-coins) = 100,000,000 (1.00000000 Mastercoins) An address marked as savings can only do this "restricted send" transaction type. All other transaction types must be ignored, as they are invalid from a savings address. This transaction type is also used for sending from rate-limited wallets. @@ -1001,7 +1002,7 @@ This transaction must be sent from the guardian address. The reference payment m #### Advantages of the Savings/Guardian Model -The savings/guardian model is intended to allow the user to take extreme precautions against accidental loss of the savings address (for instance, by storing lots of backups, including in the cloud), and extreme precautions against theft of the guardian address. Although reasonable precautions should be taken, if your savings address gets hacked, or the key to your guardian address gets lost or destroyed, the coins can still be recovered. +The savings/guardian model is intended to allow the user to take extreme precautions against accidental loss of the savings address (for instance, by storing lots of backups, including in the cloud), and extreme precautions against theft of the guardian address. Although reasonable precautions should be taken, if your savings address gets hacked, or the key to your guardian address gets lost or destroyed, the coins can still be recovered. This model also facilitates estate planning. You simply give your heir(s) a paper copy to the private key of your savings address, but you keep the guardian address key to yourself. If you die, your heirs can simply transfer the funds out of your savings (they will have to wait for the reversibility period to pass), but they can't steal from you while you are alive since you are the only one with the key to the guardian address and can reverse their transaction if they try. @@ -1014,9 +1015,9 @@ Say you want to enforce a spending limit of 1 Mastercoin per Month on one of you 1. [Transaction version](#field-transaction-version) = 0 1. [Transaction type](#field-transaction-type) = 12 -1. [Currency identifier](#field-currency-identifier) = 1 for Mastercoin +1. [Currency identifier](#field-currency-identifier) = 1 for Mastercoin 1. [Spending Limit](#field-number-of-coins) = 100,000,000 (1.00000000 Mastercoins) -1. [Limitation Reset period](#field-time-period-in-seconds) = 2,592,000 (30 days) +1. [Limitation Reset period](#field-time-period-in-seconds) = 2,592,000 (30 days) Marking an address as rate-limited only affects the specified currency. Other currencies stored in the address are not rate-limited. The limitation reset period begins once the protected address makes a send. Attempting to send beyond the rate limit results in the maximum send possible under the limit. @@ -1024,14 +1025,14 @@ When marking an address as rate-limited, the reference payment must point to a An address marked as savings can only do [Restricted Send](#restricted-send) transactions as described above. All other transaction types must be ignored, as they are invalid from a rate-limited address. - + ### Removing a rate limitation Removing the rate limitation above takes 8 bytes: 1. [Transaction version](#field-transaction-version) = 0 1. [Transaction type](#field-transaction-type) = 14 -1. [Currency identifier](#field-currency-identifier) = 1 for Mastercoin +1. [Currency identifier](#field-currency-identifier) = 1 for Mastercoin This transaction must be sent from the guardian address in charge of the rate limitation. The reference payment must be to the rate-limited address. Removing the limit affects only the specified currency, and not any other rate-limited currencies stored at that address. @@ -1054,11 +1055,11 @@ Say you decide you would like to start publishing the price of Gold in the block 1. [Label](#field-string-255-byte-null-terminated) = “Gold\0” (5 bytes) (if a second “Gold” is registered in this sub-category, it will be shown as “Gold-2”) 1. [Description/Notes](#field-string-255-byte-null-terminated) = “tinyurl.com/kwejgoig\0” (21 bytes) (Please save space in the block chain by linking to your description!) -The reference payment must be to the bitcoin address which will be publishing the data. +The reference payment must be to the bitcoin address which will be publishing the data. Each data stream gets a 4-byte unique identifier, determined by the order in which they were registered. For instance, if your data stream was the third data stream ever registered, your data stream identifier would be 3. Note that data streams in the Test MSC ecosystem are completely independent, and have the most significant bit set to distinguish them from normal data streams. However, in sandbox environments using only Test MSC, these IDs can be displayed without the MSB set, for easier reading. -Since anyone can cheaply register a data stream, and thereby create categories and subcategories, we can assume that there will be a lot of noise. Anyone writing code to display data stream categories should note which data streams are the most actively used, and order categories and subcategories by descending activity, thereby pushing unused categories to the bottom of the list. +Since anyone can cheaply register a data stream, and thereby create categories and subcategories, we can assume that there will be a lot of noise. Anyone writing code to display data stream categories should note which data streams are the most actively used, and order categories and subcategories by descending activity, thereby pushing unused categories to the bottom of the list. If you ever need to change the description/notes for your data stream (for instance, if some poor sport takes down your website), simply re-register it from the same address with the same category, subcategory, and label. When re-registering, you can also change the ticker address by choosing a different address for the reference payment (for instance, if your ticker address gets compromised), or change the display multiplier. @@ -1148,7 +1149,7 @@ By offering $200 against $100, the desired 2:1 odds are implied. Since one addre A "Contract for Difference" (CFD) allows a bettor to temporarily gain bullish or bearish exposure to a price movement, in direct proportion to that movement. A bettor who creates a bullish CFD on Gold with 1x leverage (65536) will receive 10% of the counter-wager funds if Gold rises 10% during the period of the bet. If instead Gold falls 10%, the bettor loses 10% of his own money at stake. As with normal bets, 0.5% of the total pot goes to the creator of the data stream before winnings are determined. -CFD bets store "leverage" in place of the data used by "bet threshold" in other bet types. If a bettor prefers that a 10% price movement means a 20% gain or loss, they may select 2x leverage (65536\*2=131072). Similarly, a 10% price movement could mean a 5% gain or loss using 0.5x leverage (65536\*0.5 = 32768). Just as with normal bets, a CFD bettor can "sweeten the deal" by offering better odds (a lower counter-wager amount). High-leverage bets or big price movements could result in a winnings calculation higher than the amount at stake, in which case the winner simply gets the entire pot. +CFD bets store "leverage" in place of the data used by "bet threshold" in other bet types. If a bettor prefers that a 10% price movement means a 20% gain or loss, they may select 2x leverage (65536\*2=131072). Similarly, a 10% price movement could mean a 5% gain or loss using 0.5x leverage (65536\*0.5 = 32768). Just as with normal bets, a CFD bettor can "sweeten the deal" by offering better odds (a lower counter-wager amount). High-leverage bets or big price movements could result in a winnings calculation higher than the amount at stake, in which case the winner simply gets the entire pot. ### Accepting a Bet @@ -1168,7 +1169,7 @@ Say you see a bet which you would like to accept. Simply publish the inverse bet Note that this bet will be matched against only half of the previous example, because while the odds match (2:1 vs. 1:2), the amount of this bet is for less. This bet is only for $50, so would only win $100 if they win, as opposed to the full $200. Once the bets are matched, the first bet still has $100 available for someone else to bet $50 against. -Once GoldCoins reach a value of 20 or the bet deadline passes, the bet winner gets 99.5% of the money at stake. The other 0.5% goes to the creator of the data stream. When using currencies other than Mastercoin, a small fee will be deducted (see [fees](#fees) above). +Once GoldCoins reach a value of 20 or the bet deadline passes, the bet winner gets 99.5% of the money at stake. The other 0.5% goes to the creator of the data stream. When using currencies other than Mastercoin, a small fee will be deducted (see [fees](#fees) above). ## Distributed E-Commerce @@ -1216,9 +1217,9 @@ The message to accept the offer takes X bytes: 1. [Transaction version](#field-transaction-version) = 0 1. Transaction type = 62 for Accept buyer offer (32-bit unsigned integer, 4 bytes) -2. Which buyer = 2 (3rd offer received) (16-bit unsigned integer, 2 bytes) +2. Which buyer = 2 (3rd offer received) (16-bit unsigned integer, 2 bytes) -Once a buyer has been accepted, the seller may ship the Bible. When using currencies other than Mastercoin, a small fee will be deducted (see [fees](#fees) above). +Once a buyer has been accepted, the seller may ship the Bible. When using currencies other than Mastercoin, a small fee will be deducted (see [fees](#fees) above). ### Leaving Feedback @@ -1249,7 +1250,7 @@ The most important and also the most controversial feature (at least the escrow So how do we drive the value of these GoldCoins to their target value, when demand for them may surge and decline? The price of GoldCoins is decided by the balance of supply and demand. Since we can’t control the demand for GoldCoins, we must control the supply. The key to accomplishing this is to use an escrow fund which holds Mastercoins, as shown below: -![Omni Protocol Layers](images/stability.png) +![Omni Protocol Layers](images/stability.png) The escrow fund operates like a battery on the power grid, charging when there is excess energy then discharging where there isn't enough. When there are too few GoldCoins (GoldCoin price is too high), the escrow fund releases new GoldCoins, and the escrow-battery “charges” by holding Mastercoins in escrow. When there are too many GoldCoins (GoldCoin price is too low), the escrow fund purchases some of the excess GoldCoins, thereby “discharging” the escrow-battery as it releases the stored Mastercoins. @@ -1268,7 +1269,7 @@ Say you want to create the GoldCoin currency described above, using the Gold dat 1. Sale/Transfer Penalty = 100,000 for 0.1% (32-bit unsigned integer, 4 bytes, any time GoldCoins are sold or transferred, 0.1% are destroyed, which improves the health of the escrow fund) -As with properties, currencies are awarded currency identifiers in the order in which they are created. Mastercoin is currency identifier 1 (bitcoin is 0), and Test Mastercoins have currency identifier 2, so if GoldCoin is the first Omni Protocol currency, it will get a currency identifier of 3. +As with properties, currencies are awarded currency identifiers in the order in which they are created. Mastercoin is currency identifier 1 (bitcoin is 0), and Test Mastercoins have currency identifier 2, so if GoldCoin is the first Omni Protocol currency, it will get a currency identifier of 3. The currency held in escrow is the parent currency of the data stream. In this example it is Mastercoins, but it could also be any Omni Protocol currency. For instance, GoldCoins could later be held in escrow to support a currency whose data stream uses GoldCoins as a parent currency. @@ -1298,30 +1299,30 @@ Escrow funds should generally be tuned to act slowly. This will allow arbitrage -# Appendix A – Storing Omni Protocol data in the blockchain -By Zathras, Copyright © 2013 The Mastercoin Foundation +# Appendix A – Storing Omni Protocol data in the blockchain +By Zathras, Copyright © 2013 The Mastercoin Foundation -The following appendix serves to detail the different approaches to storing Omni transaction data in the Bitcoin blockchain along with their validity requirements and use cases. +The following appendix serves to detail the different approaches to storing Omni transaction data in the Bitcoin blockchain along with their validity requirements and use cases. This appendix will not discuss the varying types of Omni Protocol transactions or what the transaction data contains (these are defined in the main body of the Omni Protocol Specification) and will focus solely on transaction data storage. - -For the purposes of a simplified overview, parties wishing to develop Omni software should support the decoding of both Class A and Class B transactions, but only need support encoding of Class B transactions. + +For the purposes of a simplified overview, parties wishing to develop Omni software should support the decoding of both Class A and Class B transactions, but only need support encoding of Class B transactions. Note that for all transaction classes, we have some unused "padding" bytes at the end of most messages. Those bytes are undefined (they are ignored, so they can have any value). -## Class A transactions (also known as the ‘original’ method) +## Class A transactions (also known as the ‘original’ method) -Class A transactions were the first class of Omni Protocol transaction and store data in the blockchain by utilizing fake Bitcoin addresses to encode transaction data. +Class A transactions were the first class of Omni Protocol transaction and store data in the blockchain by utilizing fake Bitcoin addresses to encode transaction data. -The transaction data is encoded into said fake Bitcoin address which is then used as an output in a single Bitcoin transaction satisfying the following requirements: +The transaction data is encoded into said fake Bitcoin address which is then used as an output in a single Bitcoin transaction satisfying the following requirements: * Has a single or the largest pay-to-pubkey-hash or pay-to-script-hash (since block height 322000) input with a valid signature to designate the sending address * Has an output for the recipient address (the 'reference' address) * Has an output for the exodus address * Has an output for the encoded fake address (the 'data' address) -* Should have all output values above the 'dust' threshold (0.00005460 BTC as of Q2 2014) and preferable be equal. +* Should have all output values above the 'dust' threshold (0.00005460 BTC as of Q2 2014) and preferable be equal. * Has exactly two non-Exodus outputs (one of which must be the data address) with a value equal to the Exodus output and/or has exactly one output with a sequence number +1 of the data address for reference output identification -* Additional outputs are permitted for the remainder of the input (the 'change' address) +* Additional outputs are permitted for the remainder of the input (the 'change' address) Further: @@ -1331,38 +1332,38 @@ Further: * Pay-to-script-hash output addresses will be the opaque script-hash address and not assume any decomposition into addresses which may be used in the redemption of such outputs * Pay-to-script-hash is enabled since block height 322000 -NOTE: The sequence number for a given address is defined as a 1 -byte integer stored as the first byte of each 'packet'. Sequence numbers are continuous with 0 following 255 (256=0, 255+1=0). +NOTE: The sequence number for a given address is defined as a 1 -byte integer stored as the first byte of each 'packet'. Sequence numbers are continuous with 0 following 255 (256=0, 255+1=0). NOTE: Should a transaction result in an edge case that provides conflicting reference address values for sequence numbers and equal outputs, the reference address identified via equal outputs will take precedence. -As there is no private key associated with these fake addresses they are inherently unspendable. This creates concerns around blockchain bloat, especially within the UTXO (Unspent Transaction Output) set as each use of a fake address adds an unspent output to the UTXO dataset that will never be redeemed, thus growing (or ‘bloating’) it. +As there is no private key associated with these fake addresses they are inherently unspendable. This creates concerns around blockchain bloat, especially within the UTXO (Unspent Transaction Output) set as each use of a fake address adds an unspent output to the UTXO dataset that will never be redeemed, thus growing (or ‘bloating’) it. -As the UTXO set is designed to be memory resident it is thus in the interests of Bitcoin to avoid UTXO bloat to minimize the memory requirement for client implementations. +As the UTXO set is designed to be memory resident it is thus in the interests of Bitcoin to avoid UTXO bloat to minimize the memory requirement for client implementations. Class B transactions were developed to address this issue by using provably redeemable outputs. Class A transactions are thus considered deprecated and are supported for backwards compatibility only. -NOTE: Class A transactions are restricted to the ‘simple send’ transaction type only. All other Omni transaction types are supported by Class B transactions only. Client implementations should utilize Class B for all transaction types, including ‘simple send’. +NOTE: Class A transactions are restricted to the ‘simple send’ transaction type only. All other Omni transaction types are supported by Class B transactions only. Client implementations should utilize Class B for all transaction types, including ‘simple send’. -## Class B transactions (also known as the ‘multisig’ method) +## Class B transactions (also known as the ‘multisig’ method) Class B transactions attempt to address the UTXO ‘bloat’ issue by storing data in the blockchain by utilizing ‘1-of-n’ multisignature outputs where one of the signatories is the sender or another public key address the sender has designated. By adopting a ‘1-of-n’ approach (credit Tachikoma @ bitcointalk) we can increase n to the number of packets (public keys) needed to store the transaction data while maintaining the ability of the sender or their designated party to redeem the output. -NOTE: The reference client currently supports a maximum value of 3 for n. As one signatory should be the sender for redemption purposes, there is a current limit of 2 data packets per output. A number of multisig outputs can be combined to increase the space available for transaction data as required. On decoding all Omni Protocol packets from all multisig outputs are ordered via their sequence number and evaluated as a continuous data stream. +NOTE: The reference client currently supports a maximum value of 3 for n. As one signatory should be the sender for redemption purposes, there is a current limit of 2 data packets per output. A number of multisig outputs can be combined to increase the space available for transaction data as required. On decoding all Omni Protocol packets from all multisig outputs are ordered via their sequence number and evaluated as a continuous data stream. -Transaction data is encoded into one or a number of compressed public keys which are obfuscated and then should have their last byte manipulated to form a valid ECDSA point. These compressed public keys then can be included as signatories in a multisig output ordered by their sequence number. +Transaction data is encoded into one or a number of compressed public keys which are obfuscated and then should have their last byte manipulated to form a valid ECDSA point. These compressed public keys then can be included as signatories in a multisig output ordered by their sequence number. -The size of an Omni Protocol packet in a compressed public key is thus 31 bytes (33 bytes minus the first and last bytes for the key identifier (02) and ECDSA manipulation byte). The Omni Protocol packet reserves the first byte for the sequence number, providing a total of 30 bytes per packet for Omni Protocol transaction data. The range of sequence numbers in a Class B transaction is 1 to 255, providing for a total 7,650 bytes maximum actual transaction data storage per Omni Class B transaction. +The size of an Omni Protocol packet in a compressed public key is thus 31 bytes (33 bytes minus the first and last bytes for the key identifier (02) and ECDSA manipulation byte). The Omni Protocol packet reserves the first byte for the sequence number, providing a total of 30 bytes per packet for Omni Protocol transaction data. The range of sequence numbers in a Class B transaction is 1 to 255, providing for a total 7,650 bytes maximum actual transaction data storage per Omni Class B transaction. -Sequence numbers are again used to order the packets (again first byte of the packet), however as we no longer need to use sequence numbers to identify the recipient (reference) address we are able to start the sequence at one (we do not start the sequence at zero due to our need for a positive sequence number in obfuscation). +Sequence numbers are again used to order the packets (again first byte of the packet), however as we no longer need to use sequence numbers to identify the recipient (reference) address we are able to start the sequence at one (we do not start the sequence at zero due to our need for a positive sequence number in obfuscation). Obfuscation is performed by SHA256 hashing the sender's address S times (where S is the sequence number) and taking the first 31 bytes of the resulting hash and XORing with the 31 byte Omni packet. Multiple SHA256 passes are performed against an uppercase hex representation of the previous hash. - + EXAMPLE: The following provides example output for an obfuscated Omni packet (where and XX is the last byte reserved for ECDSA point validity manipulation): - + @@ -1372,17 +1373,17 @@ EXAMPLE: The following provides example output for an obfuscated Omni packet (w
REFERENCE ADDRESS{1CdighsfdfRcj4ytQSskZgQXbUEamuMUNF }REFERENCE ADDRESS{1CdighsfdfRcj4ytQSskZgQXbUEamuMUNF }
SHA256 HASH (S TIMES) OF ADDRESS{1D9A3DE5C2E22BF89A1E41E6FEDAB54582F8A0C3AE14394A59366293DD130C }59
-Once the obfuscated Omni packet is prepared, the key identifier (02) is prefixed and a random byte compressed public key is then run across a check to ensure the key is a valid ECDSA point. If the key fails this check, the last byte is simply rotated with a different random byte and tested again until the key forms a valid ECDSA point. +Once the obfuscated Omni packet is prepared, the key identifier (02) is prefixed and a random byte compressed public key is then run across a check to ensure the key is a valid ECDSA point. If the key fails this check, the last byte is simply rotated with a different random byte and tested again until the key forms a valid ECDSA point. -![Omni Protocol Layers](images/classb_obfuscated.png) +![Omni Protocol Layers](images/classb_obfuscated.png) -These compressed public key 'packets' can then be included in one or multiple OP_CHECKMULTISIG output along with the senders public key. A single transaction must be constructed satisfying the following requirements: +These compressed public key 'packets' can then be included in one or multiple OP_CHECKMULTISIG output along with the senders public key. A single transaction must be constructed satisfying the following requirements: * Has a single or the largest pay-to-pubkey-hash or pay-to-script-hash (since block height 322000) input with a valid signature to designate the sending address * Has an output for the recipient address (the 'reference' address) * Has an output for the exodus address * Has one or more n-of-m OP_CHECKMULTISIG outputs each containing at least two public keys whereby the first should be a valid public key address designated by the sender which may be used to reclaim the bitcoin assigned to the output, the second must be Omni 'data package n' and the third may be 'data package n+1' -* Omni 'data packages' appear in order by their sequence number -* Additional outputs are permitted +* Omni 'data packages' appear in order by their sequence number +* Additional outputs are permitted Further: @@ -1401,7 +1402,7 @@ Further: It should be clear by now that the Omni Protocol can be used for activities that may be regulated or even prohibited in certain jurisdictions. Anyone working on an implementation of the Omni Protocol should be very careful to warn users to know and understand the regulatory environment of their jurisdiction and country of residence in order to not break any laws. It is up to the user to know the laws of their country, and not (for instance) engage in sports betting in a jurisdiction / country where sports betting is not a legal activity. -Also, the contributors to this open source specification are not securities experts, and offer no advice or counsel on how to properly comply with securities or other regulations. This protocol is presented as a open source tool on which others can implement clients and build innovative services for the benefit of others. +Also, the contributors to this open source specification are not securities experts, and offer no advice or counsel on how to properly comply with securities or other regulations. This protocol is presented as a open source tool on which others can implement clients and build innovative services for the benefit of others. That said, stable distributed currencies / smart property and the other features of this protocol will be incredibly useful in a huge number of legal applications, and even modest success of this protocol could allow early adopters (and even those who simply hold bitcoins) to greatly benefit. The Omni Protocol and Mastercoins, are just neutral tools, capable of being used for good or for evil. We urge our early adopters to consider how they may use Omni for good, and if they gain from its adoption, to use those funds for good. It will take a lot of work to make the good, outshine bad actors. @@ -1430,10 +1431,10 @@ You supply this URL a currency_id, initially 1 or 2, and it should return an JSO **GET /mastercoin_verify/transactions/#address#?currency_id=#currency_id#** ```json -{address: 1KZmDQGzGJWYmPP9X3b7TA9dY91KBXgaG4, transactions: [{tx_hash: 5f01def181b761f1d03bcd20590c5729a47b11c68955b364add9253d7aec5eb9, valid: true, accepted_amount: nil, bought_amount: nil}, {tx_hash: 130c5175d4f3e9add03bd1d115a87b26e613293fbe3815b970f8fc830f018ebc, valid: false, accepted_amount: nil, bought_amount: nil}, etc..]} +{address: 1KZmDQGzGJWYmPP9X3b7TA9dY91KBXgaG4, transactions: [{tx_hash: 5f01def181b761f1d03bcd20590c5729a47b11c68955b364add9253d7aec5eb9, valid: true, accepted_amount: nil, bought_amount: nil}, {tx_hash: 130c5175d4f3e9add03bd1d115a87b26e613293fbe3815b970f8fc830f018ebc, valid: false, accepted_amount: nil, bought_amount: nil}, etc..]} ``` -This URL takes an address and currency_id as arguments and should return an JSON object with an address and a transactions key for this given address. The transactions key should have an array of all transactions for this address and whether this implementation considers a given transaction valid or not. +This URL takes an address and currency_id as arguments and should return an JSON object with an address and a transactions key for this given address. The transactions key should have an array of all transactions for this address and whether this implementation considers a given transaction valid or not. In all likeliness this will capture most of the discrepancies. If this doesn't proof enough we can supply addional information like the amount transferred per transaction in the future. @@ -1441,11 +1442,11 @@ For Simple Send transactions accepted_amount and bought_amount can be null value Example: -User A has a Selling Offer for 5 MSC. User B sends out a Purchase Offer for 8. It gets added to a block but since User A only had a Selling Offer for 5 the Accepted Amount for User B's Purchase Offer is now 5. +User A has a Selling Offer for 5 MSC. User B sends out a Purchase Offer for 8. It gets added to a block but since User A only had a Selling Offer for 5 the Accepted Amount for User B's Purchase Offer is now 5. The bought amount is the total amount a user actually spends on an open Purchase Offer. -Example: +Example: User B has a valid Purchase Offer to buy 5 MSC from User A. He sends out a transaction that actually purchases 2 MSC. At that point his Purchase Offer has an bought_amount of 2 MSC. If he decides to sent an other 3 MSC later this values gets updated to 5 MSC. @@ -1468,19 +1469,19 @@ The following calculations will demonstrate the perceived cost to the end-user, 0.00006 ($0.04) - Reference Address Output 0.00006 ($0.04) - Data Address Output 0.0001 ($0.07) - Bitcoin Transaction Fee - + Total perceived cost ~$0.18 per transaction. - + **Class B** 0.00006 ($0.04) - Exodus Address Output 0.00006 ($0.04) - Reference Address Output 0.00012 ($0.7) - Per Multisig Output 0.0001 ($0.07) - Bitcoin Transaction Fee - + Total perceived cost ~$0.22 per transaction. Each multisig output in a Class B transaction may contain two Omni Protocol packets of 30 bytes each. Thus we can infer (again at 650 USD per BTC) that for every 60 bytes, we increase perceived transaction cost by ~$0.08. - + The term 'perceived' cost has been applied as the Omni Protocol transaction model does not 'burn' (destroy) these outputs, but rather they are redeemable by the various participants of the transaction (with the exception of the Class A data address, hence its deprecation). In a class A transaction (note class A allows simple send only): @@ -1497,3 +1498,5 @@ As we can see from the above, the true cost of a Omni Protocol message may be le A further consideration relates to how multisig outputs are presented in the bitcoin reference client. It is technically accurate to state that any of the addresses within a Class B multisig output can redeem, however only one of these addresses (the sending address) actually has a known private key. The bitcoin reference client however of course has no way of knowing this and so does not include unspent multisig outputs in the displayed balance. It is envisaged that in future Omni Protocol clients will 'clean up' periodically by redeeming and consolidating unspent multisig outputs. + +#### *Please note, the specification is currently not complete, partially outdated and does not entirely reflect the behavior of Omni Layer's reference client [Omni Core](https://github.com/OmniLayer/omnicore).*