Breaking changes to data model

docs/upgrade-guides/v0.10-->v1.0.md

@@ -0,0 +1,99 @@
+# Updating from BigchainDB v0.10 to v1.0
+
+BigchainDB v1.0 stands for backwards compatibility. This means that all
+following [minor](http://semver.org/) releases after version 1.0 will always be
+backwards-compatible to previous versions.
+
+For all future releases, we commit to not introduce breaking changes to the
+public interfaces of BigchainDB's:
+
+- [Data
+  model](https://docs.bigchaindb.com/projects/server/en/latest/data-models/index.html)
+- [HTTP
+  API](https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html)
+- [WebSocket Event Stream
+  API](https://docs.bigchaindb.com/projects/server/en/latest/websocket-event-stream-api.html)
+- [official Python driver](https://github.com/bigchaindb/bigchaindb-driver)
+- [official Javascript
+  driver](https://github.com/bigchaindb/js-bigchaindb-driver)
+
+
+As we saw the version bump to v1.0 as our last chance in a while to fix minor
+annoyances, we intentionally did clean up on the above interfaces.  In this
+document, we'd like to give a comprehensive summary of those changes to allow
+you to upgrade efficiently.
+
+The next sections will go over each of the above mentioned interfaces and
+detail the exact changes.
+
+### Syntactical changes
+
+#### `txid` and `tx_id` becomes `transaction_id`
+
+To establish better consistency between external interfaces, all usages of
+`txid` and `tx_id` in data models and HTTP API were renamed to
+`transaction_id`.
+
+
+### Changes to the Data Model
+
+#### Output amount is now a string
+
+BigchainDB transactions may have multiple inputs and outputs, and each output
+has an amount, which is the integral number of the asset being transferred. In
+prior versions of BigchainDB, the amount was encoded as a number, which on the
+face of it is the obvious way to encode an integer. However, as usual the devil
+is in the details; JSON, the encoding of choice for BigchainDB transactions,
+encodes all numbers including integers as floating point. This isn't a problem
+for the majority of circumstances where numbers are small, however in some
+environments and for some use cases\*, the number may lose precision.
+
+In order to safeguard against this, amounts are now encoded as strings, and it
+is recommended to use a decimal math library (such as
+[big.js](https://github.com/MikeMcl/big.js)) when dealing with large numbers in
+Javascript. Additionally, numbers are capped at 9e18 to stay comfortably within
+the boundary of a 64 bit signed integer.
+
+\* Try this in the Chrome developer console: `2**60 == 2**60+1`.
+
+
+#### Input `fulfills.txid` is now `transaction_id`
+
+We renamed a TRANSFER transaction's `inputs.fulfills.txid` to
+`inputs.fulfills.transaction_id`.
+
+
+#### Signing payload is now the transaction body
+
+The signature payload of a BigchainDB transaction is now "just" the JSON
+serialized body of the transaction. This change is invisible to applications
+that do not produce transactions with more than one input. However, prior to
+the 1.0 release, transactions with multiple inputs had a special signing
+protocol, which included reassembly of the transaction. This was identified as
+being unneeded, so now the payload that is signed is always just the serialized
+transaction, minus signatures. More details, take a look at the
+[Pull-Request](https://github.com/bigchaindb/bigchaindb/pull/1225) introducing
+the change or at our updated [Handcrafting
+Transactions](https://docs.bigchaindb.com/projects/py-driver/en/latest/handcraft.html)
+document.
+
+
+#### Update to Cryptoconditions version 2
+
+Earlier the IETF Interledger working group released an [updated
+draft](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02) of their
+Crypto-Conditions specification. To send transactions to BigchainDB v1.0, all
+transaction's inputs and outputs need to comply to this new version.
+
+Several of the language specific implementations have already been updated,
+including:
+
+- [py-crypto-conditions](https://github.com/bigchaindb/cryptoconditions)
+- [js-crypto-conditions](https://github.com/interledgerjs/five-bells-condition)
+- [java-crypto-conditions](https://github.com/interledger/java-crypto-conditions)
+
+
+If you don't find your preferred language in this list, do not despair but
+reach out to us for help on Github/Gitter or product@bigchaindb.com.
+
+