# 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) 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. ## A note upfront We tried to test this upgrade guide as best as we could by using it to adjust our official drivers. If you still find breaking changes that causes your software to crash, please let us and others reading this guide know by sending over a Pull-Request or notifying us on Gitter. Thank you very much :) ## Syntactical changes #### `tx`, `txid` and `tx_id` becomes `transaction_id` To establish better consistency between external interfaces, all usages of `txid`, `tx` and `tx_id` in data models and HTTP API were renamed to `transaction_id` or `transaction`. ## Breaking 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`. #### Input `fulfills.output` is now `output_index` We renamed a TRANSFER transaction's `inputs.fulfills.output` to `inputs.fulfills.output_index`. #### 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 Crypto-Conditions version 2 Earlier this year 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. #### Revamp of Crypto-Conditions signing details In order to create a correct fulfillment for an output condition in BigchainDB, we include the conditon URI ("ni:///sha-256;..."), to verify the fulfillment against. However, the condition URI does not tell you who may sign in order to create a correct fulfillment. For this, we have the `condition.details` object. This is a recursive data structure which mirrors the n-of-m threshold / ed25519 condition types that we support. An example of the new structure is: ```json { "details": { "type": "threshold-sha-256", "threshold": 2, "subconditions": [ { "public_key": "", "type": "ed25519-sha-256", }, { "public_key": "", "type": "ed25519-sha-256", } ], }, } ``` #### Transaction version is now 1.0 The `version` key in the transaction is now set to `'1.0'`. ## Breaking Changes to the HTTP API In this section, we'll go over each of the endpoints separately and list the changes done to them: ### `GET /` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#bigchaindb-root-url) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#bigchaindb-root-url) Changes: - All notion of `_links` was removed - `api_v1` is now an object including currently only one further object called `v1` - `api.v1` includes links that were originally only available through `/api/v1/` - `api.v1` now also includes links to `assets` (a new endpoint) and `outputs` - `streams_v1`'s link was changed from `streams/valid_tx` to `streams/valid_transactions` - `streams_v1` was renamed to `streams` - Usages of scheme, host and port to API V1's endpoints were removed to allow for configurations of BigchainDB behind reverse proxies - e.g. `http://example.com:9984/api/v1/transactions` ==> `/api/v1/transactions` ```json // Old { "_links": { "api_v1": "http://example.com:9984/api/v1/", "docs": "https://docs.bigchaindb.com/projects/server/en/v0.10.2/" }, "keyring": [ "6qHyZew94NMmUTYyHnkZsB8cxJYuRNEiEpXHe1ih9QX3", "AdDuyrTyjrDt935YnFu4VBCVDhHtY2Y6rcy7x2TFeiRi" ], "public_key": "NC8c8rYcAhyKVpx1PCV65CBmyq4YUbLysy3Rqrg8L8mz", "software": "BigchainDB", "version": "0.10.2" } // New { "api": { "v1": { "docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/http-client-server-api.html", "statuses": "/api/v1/statuses/", "streams": "ws://example.com:9985/api/v1/streams/valid_transactions", "transactions": "/api/v1/transactions/", "assets": "/api/v1/assets/", "outputs": "/api/v1/outputs/" } }, "docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/", "keyring": [ "6qHyZew94NMmUTYyHnkZsB8cxJYuRNEiEpXHe1ih9QX3", "AdDuyrTyjrDt935YnFu4VBCVDhHtY2Y6rcy7x2TFeiRi" ], "public_key": "NC8c8rYcAhyKVpx1PCV65CBmyq4YUbLysy3Rqrg8L8mz", "software": "BigchainDB", "version": "0.11.0.dev" } ``` ### `GET /api/v1` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#api-root-endpoint) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#api-root-endpoint) Changes: - All notion of `_links` was removed - The response object of `/api/v1` now includes links to `assets` (a new endpoint) and `outputs` - `streams_v1`'s link was changed from `streams/valid_tx` to `streams/valid_transactions` - `streams_v1` was renamed to `streams` - Usages of scheme, host and port to API V1's endpoints were removed to allow for configurations of BigchainDB behind reverse proxies - e.g. `http://example.com:9984/api/v1/transactions` ==> `/api/v1/transactions` ```json // Old { "_links": { "docs": "https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html", "self": "http://example.com:9984/api/v1/", "statuses": "http://example.com:9984/api/v1/statuses/", "streams_v1": "ws://example.com:9985/api/v1/streams/valid_tx", "transactions": "http://example.com:9984/api/v1/transactions/" } } // New { "docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/http-client-server-api.html", "statuses": "/api/v1/statuses/", "streams": "ws://example.com:9985/api/v1/streams/valid_transactions", "transactions": "/api/v1/transactions/", "assets": "/api/v1/assets/", "outputs": "/api/v1/outputs/" } ``` ### `GET /api/v1/transactions/{tx_id}` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-transactions-tx_id) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-transactions-transaction_id) Changes: - Previously this endpoint returned transactions from BigchainDB's `BACKLOG` and from blocks marked as `UNDECIDED`. With version 1.0, this endpoint will only return transactions included in blocks marked as `VALID`. ### `POST /api/v1/transactions` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#post--api-v1-transactions) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#post--api-v1-transactions) Changes: - A `Location` HTTP header was included in the endpoint's response to allow users to check the transaction's status more easily via the `/statuses?transaction_id` endpoint ### `GET /api/v1/outputs` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-outputs?public_key=public_key) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-outputs?public_key=public_key) Changes: - Reversed the behavior of the `unspent` query parameter to `spent`, implying the following behavior: - If `?spent=true`, the response is an array of all spent outputs associated with a given public key - If `?spent=false`, response is an array of all NOT YET spent (or "unspent" outputs associated with a given public key - If no ``spent=` filter is present in the request, the response is an array of all outputs associated with a given public key (spent and unspent) Previously the response included a list of relative URLs pointed to transations' outputs: ```json // Old [ "../transactions/2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e/outputs/0" ] // New [ { "output_index": 0, "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e" } ] ``` In the future, we're planning to [upgrade this endpoint further](https://github.com/bigchaindb/bigchaindb/blob/99499b1f8783719a082813912ac9a0d363ae278f/bdb-ip.md#6-a-new-outputs-endpoint) to meet the requirements of [our users](https://github.com/bigchaindb/bigchaindb/issues/1227#issuecomment-307297473). ### `GET /api/v1/statuses?tx_id` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-statuses?tx_id=tx_id) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-statuses?transaction_id=transaction_id) Changes: - All notion of `_links` was removed. In case of querying the status of a transaction already included in a block marked `VALID`, no `_links` object is provided anymore. The response object now only contains a single key value pair named `status` - The query parameter `tx_id` was renamed to `transaction_id`, e.g. `GET /api/v1/statuses?transaction_id=` ```json // Old { "status": "valid", "_links": { "tx": "/transactions/04c00267af82c161b4bf2ad4a47d1ddbfeb47eef1a14b8d51f37d6ee00ea5cdd" } } // New { "status": "valid", } ``` ### `GET /api/v1/statuses?block_id` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-statuses?block_id=block_id) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-statuses?block_id=block_id) Changes: - All notion of `_links` was removed. The response object now only contains a single key value pair named `status` ```json // Old { "status": "valid", "_links": { "tx": "/transactions/04c00267af82c161b4bf2ad4a47d1ddbfeb47eef1a14b8d51f37d6ee00ea5cdd" } } // New { "status": "valid", } ``` ### `GET /api/v1/blocks?tx_id` Documentation: - [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-blocks?tx_id=tx_id&status=UNDECIDED|VALID|INVALID) - [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-blocks?transaction_id=transaction_id&status=UNDECIDED|VALID|INVALID) Changes: - The query parameter `tx_id` was renamed to `transaction_id`, e.g. `GET /api/v1/blocks?transaction_id` ## Breaking Changes to the WebSocket Event Stream API In the event object sent to a listener, `tx_id` was renamed to `transaction_id`. ```json // Old { "tx_id": "", "asset_id": "", "block_id": "" } // New { "transaction_id": "", "asset_id": "", "block_id": "" } ```