Updating from BigchainDB v0.10 to v1.0

BigchainDB v1.0 stands for backwards compatibility. This means that all following minor 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
HTTP API
WebSocket Event Stream API

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) 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 introducing the change or at our updated Handcrafting Transactions document.

Update to Crypto-Conditions version 2

Earlier this year the IETF Interledger working group released an updated draft 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
js-crypto-conditions
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:

{
    "details": {
        "type": "threshold-sha-256",
        "threshold": 2,
        "subconditions": [
            {
                "public_key": "<new owner 1 public key>",
                "type": "ed25519-sha-256",
            },
            {
                "public_key": "<new owner 2 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
New

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

// 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
New

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

// 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
New

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
New

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
New

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:

// Old
[
    "../transactions/2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e/outputs/0"
]

// New
[
    {
        "output_index": 0,
        "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
    }
]

In the future, we're planning to upgrade this endpoint further to meet the requirements of our users.

`GET /api/v1/statuses?tx_id`

Documentation:

Old
New

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=

// Old
{
    "status": "valid",
        "_links": {
            "tx": "/transactions/04c00267af82c161b4bf2ad4a47d1ddbfeb47eef1a14b8d51f37d6ee00ea5cdd"
        }
}

// New
{
    "status": "valid",
}

`GET /api/v1/statuses?block_id`

Documentation:

Old
New

Changes:

All notion of _links was removed. The response object now only contains a single key value pair named status

// Old
{
    "status": "valid",
        "_links": {
            "tx": "/transactions/04c00267af82c161b4bf2ad4a47d1ddbfeb47eef1a14b8d51f37d6ee00ea5cdd"
        }
}

// New
{
    "status": "valid",
}

`GET /api/v1/blocks?tx_id`

Documentation:

Old
New

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.

// Old
{
    "tx_id": "<sha3-256 hash>",
    "asset_id": "<sha3-256 hash>",
    "block_id": "<sha3-256 hash>"
}

// New
{
    "transaction_id": "<sha3-256 hash>",
    "asset_id": "<sha3-256 hash>",
    "block_id": "<sha3-256 hash>"
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v0.10-v1.0.md

v0.10-v1.0.md

Updating from BigchainDB v0.10 to v1.0

A note upfront

Syntactical changes

`tx`, `txid` and `tx_id` becomes `transaction_id`

Breaking Changes to the Data Model

Output amount is now a string

Input `fulfills.txid` is now `transaction_id`

Input `fulfills.output` is now `output_index`

Signing payload is now the transaction body

Update to Crypto-Conditions version 2

Revamp of Crypto-Conditions signing details

Transaction version is now 1.0

Breaking Changes to the HTTP API

`GET /`

`GET /api/v1`

`GET /api/v1/transactions/{tx_id}`

`POST /api/v1/transactions`

`GET /api/v1/outputs`

`GET /api/v1/statuses?tx_id`

`GET /api/v1/statuses?block_id`

`GET /api/v1/blocks?tx_id`

Breaking Changes to the WebSocket Event Stream API

Files

v0.10-v1.0.md

Latest commit

History

v0.10-v1.0.md

File metadata and controls

Updating from BigchainDB v0.10 to v1.0

A note upfront

Syntactical changes

tx, txid and tx_id becomes transaction_id

Breaking Changes to the Data Model

Output amount is now a string

Input fulfills.txid is now transaction_id

Input fulfills.output is now output_index

Signing payload is now the transaction body

Update to Crypto-Conditions version 2

Revamp of Crypto-Conditions signing details

Transaction version is now 1.0

Breaking Changes to the HTTP API

GET /

GET /api/v1

GET /api/v1/transactions/{tx_id}

POST /api/v1/transactions

GET /api/v1/outputs

GET /api/v1/statuses?tx_id

GET /api/v1/statuses?block_id

GET /api/v1/blocks?tx_id

Breaking Changes to the WebSocket Event Stream API

`tx`, `txid` and `tx_id` becomes `transaction_id`

Input `fulfills.txid` is now `transaction_id`

Input `fulfills.output` is now `output_index`

`GET /`

`GET /api/v1`

`GET /api/v1/transactions/{tx_id}`

`POST /api/v1/transactions`

`GET /api/v1/outputs`

`GET /api/v1/statuses?tx_id`

`GET /api/v1/statuses?block_id`

`GET /api/v1/blocks?tx_id`