mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Breaking changes to data model
This commit is contained in:
parent
9b5d1f323e
commit
9cb6904c4e
99
docs/upgrade-guides/v0.10-->v1.0.md
Normal file
99
docs/upgrade-guides/v0.10-->v1.0.md
Normal file
@ -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.
|
||||||
|
|
||||||
|
|
Loading…
x
Reference in New Issue
Block a user