Due to continued research, we have made several changes to the protocol and implementation for the upgrade to version 0.1.0. Ideally these will be the last breaking changes.
- Integration with the new envelope system.
- Messages are now encoded using protobuf.
- Support for BitCoin locking scripts other than P2PKH has been added.
- Changes to code to improve, simplify, and remove dependencies.
While upgrading your implementations to support the changes to the new specification implementation you may run into several required changes. Here are some tips to help the migration go smoother.
The protocol package previously contained all the specification code. Now the actions, assets, and messages have been separated into separate schemas. Each is now in its own package under protocol. Protocol still contains the common code, but anything specific to actions, assets, or messages will be in a new package.
You may see compiler issues like “undefined protocol.ContractOffer” which should now be “actions.ContractOffer”
We received feedback that our sizes in the protocol definition were not clear. If you work with specification implementation this will affect you. Previously there was one “size” value that represented different things in different contexts. It was the object size in bytes most of the time, but with a list or variable size type it was the size in bits of the integer used to encode the number of items in the list or the size of the variable size object. Now size only specifies the size in bytes of the object, mostly for numbers, and fixed binary and text. In part because we are using protobuf to encode the sizes of objects and lists, we now use two new values to specify sizes. “varSize” and “listSize” can have the following values. These values now simply represent the maximum valid value for the variable size or list size.
- “tiny” up to 256 bytes or items. (28)
- “small” up to 65,535 bytes or items. (216)
- “medium” up to 4,294,967,295 bytes or items. (232)
- “large” up to 1.8x1019 bytes or items. (264)
Public Key Hashes Replaced
Previously all addresses were required to be P2PKH, so we only had to maintain the PKHs (Public Key Hashes) to reference any address in the protocol or code. Now support for other locking scripts, address types, has been added. In the protocol, these will now be variable size byte arrays. To serialize and use them we use a new class called RawAddress (smart-contract/pkg/bitcoin) which contains a type and the data required by that type. RawAddresses can be converted into an Address, by adding the network ID, that can be encoded as a commonly known bitcoin address string.
This means the class protocol.PublicKeyHash no longer exists and is replaced with bitcoin.RawAddress in code and byte in the protocol.
The Protobuf compiler uses pointers to objects more than our previous implementation, which is good in practice. It allows objects to be nil instead of an empty object.
This means you may have to add some checks for nil before using objects and you may get compiler errors saying that you are using something as a pointer to an object rather than the object and you may need to add * or & some places in front of variables.
We are trying to clean up our serialize interface, the functions used to serialize objects. Previously there were Read and Write functions as well as Serialize and Deserialize. Now, for the most part, there is Serialize/Deserialize which write/read objects in buffers as well as a Bytes function that returns a byte array containing the serialized object.
Other Interface Changes
To make the code more consistent with naming within the general data schema some of the names within the code have been updated.
- protocol.OpReturnMessage is now actions.Action and on those objects, what was previously Type() is now Code().