From 9cb6904c4e2e9b9a397db7fee7cc202fc5dcaecd Mon Sep 17 00:00:00 2001 From: tim Date: Thu, 15 Jun 2017 14:49:22 +0200 Subject: [PATCH 1/9] Breaking changes to data model --- docs/upgrade-guides/v0.10-->v1.0.md | 99 +++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/upgrade-guides/v0.10-->v1.0.md diff --git a/docs/upgrade-guides/v0.10-->v1.0.md b/docs/upgrade-guides/v0.10-->v1.0.md new file mode 100644 index 00000000..f4cc976f --- /dev/null +++ b/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. + + From ac6183475b0dc298908175e32b6227ba3a543c89 Mon Sep 17 00:00:00 2001 From: tim Date: Thu, 15 Jun 2017 16:23:44 +0200 Subject: [PATCH 2/9] First cut HTTP API and WebSocket API changes --- docs/upgrade-guides/v0.10-->v1.0.md | 309 +++++++++++++++++++++++++++- 1 file changed, 303 insertions(+), 6 deletions(-) diff --git a/docs/upgrade-guides/v0.10-->v1.0.md b/docs/upgrade-guides/v0.10-->v1.0.md index f4cc976f..63d01a2c 100644 --- a/docs/upgrade-guides/v0.10-->v1.0.md +++ b/docs/upgrade-guides/v0.10-->v1.0.md @@ -26,16 +26,26 @@ you to upgrade efficiently. The next sections will go over each of the above mentioned interfaces and detail the exact changes. -### Syntactical changes +## A note upfront -#### `txid` and `tx_id` becomes `transaction_id` +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` and `tx_id` in data models and HTTP API were renamed to -`transaction_id`. +`txid`, `tx` and `tx_id` in data models and HTTP API were renamed to +`transaction_id` or `transaction`. -### Changes to the Data Model +## Breaking Changes to the Data Model #### Output amount is now a string @@ -80,7 +90,7 @@ document. #### Update to Cryptoconditions version 2 -Earlier the IETF Interledger working group released an [updated +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. @@ -97,3 +107,290 @@ 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. +## 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": 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": "" +} +``` From babe5311a46684ef7679ec843b1f600a7bceed38 Mon Sep 17 00:00:00 2001 From: tim Date: Thu, 15 Jun 2017 17:04:51 +0200 Subject: [PATCH 3/9] Link to upgrade guides from /docs --- docs/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 5169f871..220569e2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,5 @@ -[Documentation on ReadTheDocs](http://bigchaindb.readthedocs.org/) +- [Documentation on ReadTheDocs](http://bigchaindb.readthedocs.org/) +- [BigchainDB Upgrade Guides](upgrade-guides/) # The BigchainDB Documentation Strategy From b025dd1fed474f497b3dff9dda3d262f99a29d36 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Thu, 22 Jun 2017 22:55:51 +0200 Subject: [PATCH 4/9] added a note about the version change in the transaction --- docs/upgrade-guides/v0.10-->v1.0.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/upgrade-guides/v0.10-->v1.0.md b/docs/upgrade-guides/v0.10-->v1.0.md index 63d01a2c..a5f8ad78 100644 --- a/docs/upgrade-guides/v0.10-->v1.0.md +++ b/docs/upgrade-guides/v0.10-->v1.0.md @@ -107,6 +107,11 @@ 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. +#### 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 From 17913dca682ff105540c0ea73365f1763efc2083 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Fri, 23 Jun 2017 10:10:14 +0200 Subject: [PATCH 5/9] remove drivers from non breaking change promise --- docs/upgrade-guides/v0.10-->v1.0.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/upgrade-guides/v0.10-->v1.0.md b/docs/upgrade-guides/v0.10-->v1.0.md index a5f8ad78..a90b8c1d 100644 --- a/docs/upgrade-guides/v0.10-->v1.0.md +++ b/docs/upgrade-guides/v0.10-->v1.0.md @@ -13,9 +13,6 @@ public interfaces of BigchainDB's: 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 From 1b9fd1b08c8800a7c87196e04b0964c51529455e Mon Sep 17 00:00:00 2001 From: vrde Date: Mon, 26 Jun 2017 17:44:38 +0200 Subject: [PATCH 6/9] Rename upgrade guide --- docs/upgrade-guides/{v0.10-->v1.0.md => v0.10-v1.0.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/upgrade-guides/{v0.10-->v1.0.md => v0.10-v1.0.md} (100%) diff --git a/docs/upgrade-guides/v0.10-->v1.0.md b/docs/upgrade-guides/v0.10-v1.0.md similarity index 100% rename from docs/upgrade-guides/v0.10-->v1.0.md rename to docs/upgrade-guides/v0.10-v1.0.md From 3d99d192c6f4e5174456ebbd99f0d4b6d6473c27 Mon Sep 17 00:00:00 2001 From: Scott Sadler Date: Wed, 28 Jun 2017 00:56:16 +0200 Subject: [PATCH 7/9] add condition details upgrade section --- docs/upgrade-guides/v0.10-v1.0.md | 33 ++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/upgrade-guides/v0.10-v1.0.md b/docs/upgrade-guides/v0.10-v1.0.md index a90b8c1d..3feedc0f 100644 --- a/docs/upgrade-guides/v0.10-v1.0.md +++ b/docs/upgrade-guides/v0.10-v1.0.md @@ -85,7 +85,7 @@ Transactions](https://docs.bigchaindb.com/projects/py-driver/en/latest/handcraft document. -#### Update to Cryptoconditions version 2 +#### 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 @@ -104,6 +104,37 @@ 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'`. From 5442cc1f2f81e06df48c3d8bc3b0b3ad5aee69bb Mon Sep 17 00:00:00 2001 From: libscott Date: Thu, 29 Jun 2017 11:34:45 +0200 Subject: [PATCH 8/9] output -> output_index --- docs/upgrade-guides/v0.10-v1.0.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/upgrade-guides/v0.10-v1.0.md b/docs/upgrade-guides/v0.10-v1.0.md index 3feedc0f..4deecb9d 100644 --- a/docs/upgrade-guides/v0.10-v1.0.md +++ b/docs/upgrade-guides/v0.10-v1.0.md @@ -69,6 +69,10 @@ the boundary of a 64 bit signed integer. 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 From f9c24d8db7a9e84fe925e4a7da10f20bd61f5ee9 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Tue, 4 Jul 2017 16:04:24 +0200 Subject: [PATCH 9/9] Renamed output -> output_index in the outputs endpoint example --- docs/upgrade-guides/v0.10-v1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade-guides/v0.10-v1.0.md b/docs/upgrade-guides/v0.10-v1.0.md index 4deecb9d..63778371 100644 --- a/docs/upgrade-guides/v0.10-v1.0.md +++ b/docs/upgrade-guides/v0.10-v1.0.md @@ -321,7 +321,7 @@ transations' outputs: // New [ { - "output": 0, + "output_index": 0, "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e" } ]