omnilayer / spec Goto Github PK
View Code? Open in Web Editor NEWOmni Protocol Specification (formerly Mastercoin)
License: The Unlicense
Omni Protocol Specification (formerly Mastercoin)
License: The Unlicense
To eliminate misinterpretation of dates, I propose dates be written as:
<4 digit year>
so today's date would be written as
19 Mar 2014
The Document History section already uses this format. We could use:
19-Mar-2014
I have a few issues with the Data Feed and CFD spec is written today. Would someone care to submit a pull request and fix these issues? :
We should define how this is calculated and tracked in the various ledgers. This should be done in the RoleBasedBounty.md document.
Suppose we hire an Hourly Bounty on an $40 hourly rate, allocate $1000 to them as an "hour bank", and add $500 for external expenses.
We need a decision on these matters, and to have these codified in the spec.
FYI - this is not targeted at the current March 15 DEx launch, but for a future version.
As a user, I want to create multiple buy/sell offers at various prices. I understand how the spec can be simplified by disallowing them, but I think this is over-simplifying things.
I think that this is an essential piece of creating a good volume on the exchange - if I have 1000 MSC at an address, I might want to sell 100 of them at 0.2 BTC, 100 at 0.21 BTC, 100 at 0.22 BTC etc...
The spec currently has the Property type field overloaded to represent both the type (divisible or indivisible) and the action (new/replace/append). These two data items should be in separate message fields, the same way we have an Action field for sell offers and a Response sub-action (future).
Any data feed provider can potentially:
(Either by choice, or by coercion e.g. from their government).
We need to understand, document, and possibly counteract this scenario via some change to the protocol.
For CFDs, all CFDs have a time period. It makes sense for each Feed Provider to declare a minimum amount of time that they promise Feed Data will keep being published ... a sort of TOS. Then CFDs that go beyond this date will have some risk premium.
Other ways of dealing with that is, possibly, allowing a majority of MSC holders to transfer control of a Feed to another party under certain conditions. I think discussing the exact solution is out of scope, you
(originally in #93)
Unforeseen changes could drive an investor to want to do that. He can increase his investment with additional Investment Sends. We'd want some mechanism, e.g. a penalty fee, to discourage malicious reductions in investment amounts.
The following parts of "Purchase Mastercoins for Bitcoins" seems contradicting:
If you send less than the correct amount of bitcoins, your purchase will be adjusted downwards. The remaining coins will be added back to those available in the Sell Offer if it’s still active.
Please note that the buyer is allowed to send multiple bitcoin payments between the Purchase Offer and expiration block which are accumulated and used to adjust the Purchase Offer accordingly.
So does an underpayment finalize/close an "accept offer" or does it remain open until filled completely or the time expires?
the current field for investment send, do not qualify the transaction for the specific property for which the investment send is being made.
for example, if one address issues two properties, House A and House B, the protocol does not describe who to determine which property the investment send should belong to.
I know J.R. is refining the smart property creation transactions based on last week's dev group meeting, but I believe revisiting this restriction is still worthwhile:
"A MSC address may only have one fundraiser active at any given time, preventing the need for investors to specify which fundraiser they are investing in when they invest."
This constraint isn't necessary. It can be accommodated by adding a field for the fundraiser's currency id to the Investment Send (tx 1) message. That id is known as soon as the tx 51 message is confirmed. This approach forces the sender to explicitly identify the fundraiser, which eliminates the possibility of the investment being applied to a succeeding fundraiser by the same address, potentially caused by a delay in processing the tx 1 message (or a re-org???).
This issue is related to an issue I will create shortly, about the need to enable the cancellation of a tx 51 fundraiser.
What happens to the fundraiser (tx 51) that's still under way? What does it mean for that fundraiser or the fundraiser that replaces/appends it?
Needs to be defined; type/byte size. Was discussion during last call that this may be dropped, please confirm direction (drop or define).
Thanks
Zathras
Mastercoins being the first example of a coin using Master Protocol, have a built in inflation or vesting feature (sorry couldn't figure out what else to call it) were the incremental units beyond the ones created in the fundraiser are assigned back to the issuer to use for development funding using a mathematical function.
I propose that the fundraiser smart property should also have the ability to define a mathematical function for the issuance of additional token over time. Given that there is limited space in the blockchain, the protocol would need to define an upper limit of total units that the function can create.
PR #97 says:To indicate that the issuer is abandoning a property entirely:
What about the other fields, e.g. the strings, fundraiser-related fields? Do they matter, are they validated? The Property URL and Property Data fields could provide additional info for the user about the abandonment.
Perhaps I missed this somewhere, but there appears to be no place in the spec identifying the protocol for assigning ID numbers.
Also are "property ID" and "currency ID" equivalent?
If it is, which one takes precedence - particularly if the property was already abandoned (can a property be un-abandoned)? Are they cumulative or only the last one is counts?
As a complement to tx 20 (Sell MSC for BTC), shouldn't there be a Buy MSC for BTC transaction where people can post offers of what they're willing to pay - to find a willing seller?
Using TMSC this transaction 3500c4a2d4443a99a853bf73ed6150562804525daa4bee671a6ed79b702622ed was not confirm by the blockchain for several hours after sending payment. The payment was eventually confirm after the time limit had expired but the test MSC are stocked in reserve.
payment transaction id:b2ed08b91e66ee48224c7e2bc22792ec283a368e82bf8681d6347af868806a26
This issue has rather an impact on MSC related applications than the specification itself, but as the dust limit is explicitly mentioned as 5430 satoshi, it's probably worth to discuss.
When first introduced, the dust transaction threshold was falsely advertised as 5430 satoshi, but in fact it's 5460 satoshi. (see: fix comment about dust logic #2760)
To quote the reference implementation of Bitcoin:
bool IsDust(int64_t nMinRelayTxFee) const
{
// "Dust" is defined in terms of CTransaction::nMinRelayTxFee,
// which has units satoshis-per-kilobyte.
// If you'd pay more than 1/3 in fees
// to spend something, then we consider it dust.
// A typical txout is 34 bytes big, and will
// need a CTxIn of at least 148 bytes to spend,
// so dust is a txout less than 54 uBTC
// (5460 satoshis) with default nMinRelayTxFee
return ((nValue*1000)/(3*((int)GetSerializeSize(SER_DISK,0)+148)) < nMinRelayTxFee);
}
Source: https://github.com/bitcoin/bitcoin/blob/master/src/core.h#L151 (or main.cpp in earlier versions)
As a direct result any transaction with an output value lower than 5460 satoshi gets rejected with the message "TX rejected (code -22)".
As secondary result this allows zero confirmation double spends where one transaction is broadcasted via a client that accepts such transactions and one that does not (e.g. via https://blockchain.info/pushtx and bitcoind).
After some testing it furthermore became clear that semi-dust transactions have a significant longer confirmation time compared to those that are accepted by the Bitcoin core client.
https://github.com/mastercoin-MSC/spec#investment-send
is it possible to do a fundraiser with currency ID that does not equal 1 (aka mastercoin)? For example with currency ID 0?
TL;TR: I propose to introduce a new transaction field to make the use of reference addresses obsolete. This completes the seperation of transportation and data layer and allows to pack multiple transactions into one.
The Master protocol was created to allow a rich set of new transaction types and is build upon the Bitcoin protocol.
Some transactions use an additional output to reference an address ("reference address"). It is furthermore permitted to use an output for the remainder of the input ("change").
Using multiple, additional outputs such as "change" and "reference" output requires to implement rules to determine the role of an output due to the potential ambiguousness and creates several limitations, such as:
When seeing the Master protocol as combination of modular layers such as a transportation and data layer, the usage of an output as some kind of source of information appears to be an overlap between the layers.
I therefore propose to treat "reference addresses" as what they are - a part of transaction data. I furthermore propose to introduce a new data field which acts as substitute for the "reference address" output.
This completes the seperation of data and paves the way to consider different layers of the Master protocol as something modular.
But most important in my opinion: it also paves the way to make use of the several thousand byte data storage capacity of class B transactions.
Without the limitation of one "reference field" per Mastercoin transaction, it could be possible to chain transactions within one transaction. This allows in particular multiple sends without creating new transaction types.
Transactions could be chained by either treating additional data after the first complete parse of a transaction as a new transaction which would require to use fixed length data fields or the usage of data field length properties, or by using "transaction seperators".
This all is of course not to be considered as final proposal, but intended to start a discussion. Input is very welcomed. Cheers!
According to @dacoinminster, currently it is not possible to do a simple send that combines multiple inputs (possibly only for inputs with different addresses - J.R can you clarify this point?).
This means that a user that have multiple inputs in his wallets with different balances, he would need to create multiple send operations (and pay more fees) in order to send these funds. Also the recipient will then have multiple inputs himself, and will have to spend more fees to move them.
I think this should be addressed at the spec level first, and then added in the various wallets.
Not sure where to place this in a PR
But something like:
MSC for BTC Buy Offers entail a two-step process.
Step 1: The Matching MSC Sell Offer Submission and Acceptance
Posts acceptance of an offer to sell Mastercoins for bitcoins. All or some of the coins offered can be purchased with this transaction. Once enough confirmations occur for the matching Buy Offer to statistically ensure that no other submission has priority for matching should an orphan chain occur, there is a final BTC send transaction that needs to occur in order to fund the the matched transaction.
At this point the portion of the Sell Offer that is matched is in accepted status.
Step 2: Funding Event and Balance Adjustments
Send the appropriate amount of bitcoins before the time limit expires to complete the purchase. Mastercoin balances are updated to reflect the new balances for the two addresses involved in the transaction.
tx 21 Sell Master Protocol Coins for Another Master Protocol Currency is required in order to publish & accept offers to sell smart properties outside of fundraisers (tx 51).
Without tx 21, users can only send SP tokens/coins (with tx 0).
I suggest to temporarily insert a line in the spec that Mastercoin data packages should be in order within an output:
Sender's pubKey
Mastercoin data-package 1
Mastercoin data-package 2
It appears that data-packages are only parsed correctly, if this order is given and allowing unordered data packages is probably not trivial. See the discussion here: https://bitcointalk.org/index.php?topic=292628.msg5646781#msg5646781 (and a few posts earlier)
Edit: to cover transactions that are already out which don't fit exactly in the schema "sender-pubKey, data 1, data 2", I suggest to specify the handling of data-packages with something like "use the longest sequence of MSC data-packages within a transaction's output with ascending sequence numbers, starting from 01 and in the case that multiple multisig outputs are available, the same should apply, but starting from last-seq-num + 1", example:
Output 1:
Pos 0: junk
Pos 1: junk, seq num 01 (appearingly)
Pos 2: junk
Pos 3: Mastercoin data-package, seq num 01
Pos 4: Mastercoin data-package, seq num 02
Pos 5: junk
Longest sequence is pos 3 + pos 4, so take them.
Output 2:
Pos 6: junk
Pos 7: Mastercoin data-package, seq num 03
Pos 8: Mastercoin data-package, seq num 04
Pos 9: Mastercoin data-package, seq num 05
The longest sequence starting with a sequence number of 2 + 1 = 03 starts at pos 7 and ends with pos 9. So the actual data-stream is within pos 3, 4, 7, 8, 9. Of course it's a somewhat unrealistic example, but to give you an idea.
Edit 2: more or less done, see: https://bitcointalk.org/index.php?topic=292628.msg5652293#msg5652293 for the minimal changes.
I’m proposing an improvement to the way we distinguish between production and test environments. The spec identifies currency id 2 as Test MSC. Some transactions (e.g. for creating smart properties) also have an ecosystem field (1 for tradable within Mastercoin ecosystem, 2 for Test MSC).
The values in the currency id and ecosystem fields can conflict with each other, such that the intention is not clear, e.g. currency id 2 (Test MSC) with ecosystem 1 (MSC ecosystem) and vice versa.
I propose that we simplify this and eliminate the potential for conflict by making the following changes:
This change makes sense because it will associate the environment with the transaction as opposed to being implied by the data in the transaction. It separates the transaction data from environment identification. The client will process transactions and maintain a transaction history and balance for each (environment, address, currency id) tuple. Transactions in each environment will be isolated from transactions in other environments.
To maintain backward compatibility, Test MSC used in existing transactions will be processed into the new test environment data structure. New test transactions will not use TMSC as such (because they won’t exist), but rather MSC in transactions in the test environment. These will be called TMSC.
Applications will let the user select the environment, on a transaction-by-transaction basis if desired. Users do this now by choosing the particular currency (MSC/TMSC) to transact with. Presentation of MSC in the production and test environments can remain as it is now.
This change also makes it easy for new currency id's to be processed in a test environment - without having to create a shadow test currency.
This new approach will work in any bitcoin network (mainnet, testnet, regtest). And, it's now easy for a client to have separate transaction definitions for test and production. I expect this will be particularly useful when bug fixes are being implemented. The existing, production, version of a transaction can remain untouched, while the candidate transaction code can be included and tested without disrupting production. The developer/tester just has to set the application to use the test environment when exercising the candidate transaction code. Everything else will function as it did.
We should make this change ASAP to eliminate any design/development involving the ecosystem field and to reduce the amount of rework to accommodate this upgrade.
There are several possible reasons why a user might want to cancel a New Property Creation via Fundraiser, including insufficient funds are raised, an unforeseen change in circumstances or valuation. Canceling a fundraiser protects both the creator and the investors.
Based upon the current tx 50 message definition, the fundraiser should be cancelable until the Deadline has passed. When it's canceled, all invested funds will be released back to each investor and the tokens purchased will be destroyed. I realize this requires us to keep the restriction that funds and tokens are locked until after the Deadline has passed. We could provide a way for a Smart Property creator to specify that the fundraiser is not cancelable, eliminating the lock on funds raised and tokens issued.
This begs the question - should an investor be able to reduce the amount of his investment (to zero, possibly) before the Deadline expires? Again, unforeseen changes could drive an investor to want to do that. He can increase his investment with additional Investment Sends. We'd want some mechanism, e.g. a penalty fee, to discourage malicious reductions in investment amounts.
If the amount to transfer exceeds the number owned by the sending address, this indicates the user is transferring all of them.
All three implementations are currently in consensus that a spend that exceeds the balance is invalidated (see: https://bitcointalk.org/index.php?topic=292628.msg5613383#msg5613383).
Can divisible be replaced/appended with indivisible, and vice versa?
Does the ecosystem have to be the same as for the existing property?
Market making charges a fee from people making Market orders, and transfers that fee to people making Limit orders. This way people are incentived to keep the order full.
The idea to add this followed a discussion we had with Yoni Assia from eToro, and seeing CoinMKT implement this.
However, I am not confident that this makes sense in our system. It makes sense in a system where a limit order is atomically counted as either a NEW limit order or matching an EXISTING limit order. In such a system the reward is received when the atomicity condition is fullfilled, and the system decided if an order is NEW or fills an EXISTING order.
In the Master Protocol, (if I'm not mistaken in my interpretation), there isn't really a built-in order matching engine - rather, the client needs to decide whether it tries to match an existing order, or place a new one. So instead of adding such a fee, any client that decides to place a new order, can just price in the market making fee.
So - in my understanding - I am not sure there really is a place for such a feature. Leaving the issue here for discussion, if I don't see convincing arguments in favor then I'll close the issue.
https://github.com/mastercoin-MSC/spec#marking-an-address-as-savings
Appears to use days. As has been discussed for launch of the DEx there might be issues with using the time stamp from the miner machine.
If block number should be used for the DEX, it should also be used for this.
Appendix E - Understanding the cost of Master protocol messages
has "the dust threshold (0.00005430 as of 6/2/14)". The threshold is 0.00005460 BTC.
@zathras - does your code use the correct value?
There are approximately πE7 seconds in a year. If you don't take into account leap years and partial days, you get:
60 x 60 x 24 x 365 = 31,536,000 seconds in a year.
The mistake is on the line:
Doesn't seem Property ID field is defined, link doesn't lead anywhere, is it multivariable? 2 byte?
TX affected: https://github.com/mastercoin-MSC/spec#new-property-creation-with-fixed-number-of-tokens
https://github.com/mastercoin-MSC/spec#field-property-id
Also, I highly recommend a more concrete definition of the multi-variable field, much like the other fields are defined, for clarity for implementers.
Special Considerations to Avoid Invalid Transactions starts with:
"Not every bitcoin wallet lets you choose which address bitcoins come from when you make a payment, and Mastercoin transactions must all come from the address which holds the Mastercoins. If a bitcoin wallet contains bitcoins stored in multiple addresses, the wallet must first consolidate the bitcoins by sending ALL of them to the address which is going to initiate a Mastercoin transaction. Then, any Mastercoin-related bitcoin transactions will be sent from that address. Of course, mastercoin wallets hide this complexity from the user."
In order to make it easier to parse "Class A" transactions Zathras suggested we use P&D by default and make it clear in which order to decode these type of transactions. The following is my suggestion, after comments I can merge edit this into the original spec.
One of the main questions I have at this point is whether to give precedence to Level 3 over Level 2. Level 2 assumes a typo on the output value which is a very common error. See this transaction for instance. On the other hand if there are three exact output values with the same value as Exodus then it should be safe to assume that the owner of said transaction meant the third one to be the recipient address. Please let me know your opinions whether we should do Level 3 or Level 2 first after Level 1.
Decoding "Class A" transactions
In order to support as much Class A transactions as possible we will use a method called "Peek & Decode" (P&D) as standard decoding method. P&D decoding should happen as follows.
Level 1
Take all the outputs that have the same value as the value to the Exodus address. The first thing we want to do is locate the data address. In order to do this decode each address and look for the following byte checks:
If one of these addresses is found get the sequence number of this address and add one to it. Go through the other Exodus equal output values and look for this sequence number. If the sequence number is found this is the recipient address.
Level 2
If the sequence number can't be found you can expand the searching range to include all outputs, not just the ones that have an equal Exodus amount. Repeat the steps from Level 1 in according with the outputs and see if a valid sequence number can be found this way.
Level 3
If a valid sequence number still can't be found we can try finding the correct address by ruling out the other addresses. This method is only valid if all output values are equal in size and if there are three outputs of these type of outputs total. This method is simple deduction. Collect all outputs and remove the data address and the Exodus output. The remaining output is the recipient address.
Notes: If multiple valid looking data addresses are found the transaction gets invalidated.
I think we should add an (optional?) field to the creation of smart property: The SHA256 of a contract that the issuer of a SP agrees to.
E.g. such a contract can be the string:
"The issuer, 'BitHasing LTD', hereby commits to pay monthly dividends equivalent to the product of 1 GHZ of mining power, to each holder of this coin - BitHashingCoin".
While the contract itself shouldn't be included in the blockchain verbatim, I believe it's important to include the hash of the contract.
We want to make sure that if we ran the latest codebase from scratch, it would be consistent with the known history - as a way to make sure no bugs are introduced. Here is one proposal of doing that:
@dacoinminster can you head this standardization effort, and when it's implemented hand-off to Adam for implementing the Daily Build that checks that?
Smart property for the first time requires us to encode non-numerical data into packets. Methodology needs to be defined - assuming from the byte counts associated with each field in the spec (one byte per character) that dictates we go ASCII?
"Properties are awarded currency identifiers in the order in which they are created."
Rather than relying on creation order to determine a new currency id, is it possible to use the content of the tx message and meta-data (e.g. message timestamp) to deterministically generate a new currency id? This eliminates the possibility that 2 clients could generate different currency id's for the same messages if the clients happen to receive them in a different order.
A sell order for X coins should always be interpreted to mean "I want to sell min(X, my current balance at this address)".
Currently the spec disallows doing simple sends that lower the balance below the amount specific in an outstanding sell order. I think this limitation is artificial and should be removed. I can't think of a reason not to have various different outstanding sell offers from an address (#56) without any relation to the amount of funds currently available at that address - the two thing should not be related. As long as parsers/clients also know to only consider the coins as "really up for sale" if there is enough available balance, there shouldn't be any problems there.
Due to the way Dev MSC distribution is defined, our bounties are much larger than they appear. This applies to all different bounties (one time, hourly, role based).
E.g. if we put a $500 bounty on a specific task:
Shouldn't we move to a sort of fixed bounty system, where whatever amount we paid is paid in both BTC/MSC, but the dollar amount of the bounty is fixed? This might make sense at least for some of the bounty types.
David, I would appreciate your thoughts specifically on this.
There are separate sequences for currency id's in the MSC and Test MSC ecosystems, so the currency id by itself is not unique. Simple Send, and all transaction messages that have a currency id, need some way to identify the ecosystem.
"Archive" should be the noun being described by the adjective "Metadata". Otherwise, we're guilty of incorrect grammar usage as "Metadata Archival" is an adjective describing an adjective.
Thanks to /user/puck2 for the correction.
reddit discussion: http://www.reddit.com/r/mastercoin/comments/203efv/when_did_master_become_an_acronym_for_metadata/
There is a race condition when a sell order is changed without cancelling the existing one first. You can end up accidentally broadcasting a new order instead of changing the old one.
There are a several competing pull requests attempting to solve this: #38 #39 #40 #41.
I'm just creating this issue for documentation purposes, it will be closed then the winner of the above pull requests is chosen (See discussion on dev@)
See the fourth paragraph of the Smart Property section.
"...Set the number of properties to zero when replacing a property (Property Type 65 or 66) to indicate that the issuer is abandoning that property entirely. ..."
There's no mechanism to update the details of an existing property.
https://github.com/mastercoin-MSC/spec#purchase-mastercoins-with-bitcoins doesn't explicitly say when the purchaser takes possession of purchased MSC. I see 3 possibilities:
Devs - what does your code do?
I noticed that in the original white paper there is a section on Distributed Exchange which seems to be missing in this spec. Is it somewhere else?
this is the text I found:
Distributed Exchange
• Someone who is holding MasterCoins (or a currency derived from them) can simply broadcast a
message that they are for sale, and a price in another currency (such as bitcoins).
• Someone wishing to buy some coins which are for sale can broadcast their intention to buy
some or all of them.
• When a buyer is confirmed in the block chain to be the first to broadcast this intention, they
may then transfer the offered price to the seller, and they are then recognized as the new
owner of the MasterCoins.
• If an offer has not yet been accepted, the seller may broadcast that the coins are no longer for
sale
Is this scenario intentionally missing? Say for example you want to do a fundraiser just the same as type 51, but you want to sell 1000 tokens for 1 MSC each and stop there.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.