js-bigchaindb-driver/docs/upgrade-guides/0.3.0.md

<!---
Copyright BigchainDB GmbH and BigchainDB contributors
SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0)
Code is Apache-2.0 and docs are CC-BY-4.0
--->

# Updating js-bigchaindb-driver from v0.1.x to v0.3.0

The latest version of js-bigchaindb-driver contains breaking changes to its
external API. In this document, we enumerate all changes to allow you to make
upgrades efficiently.

Note that upgrading the js-bigchaindb-driver to v0.3.0 was done to enable
functionality included in the latest (v1.0) BigchainDB release.  A full list of
BigchainDB v1.0's breaking changes can be found
[here](https://github.com/bigchaindb/bigchaindb/blob/17913dca682ff105540c0ea73365f1763efc2083/docs/upgrade-guides/v0.10--%3Ev1.0.md).
Note that v1.0 [contains breaking changes to its core data
models](https://github.com/bigchaindb/bigchaindb/blob/17913dca682ff105540c0ea73365f1763efc2083/docs/upgrade-guides/v0.10--%3Ev1.0.md#breaking-changes-to-the-data-model).

This document will just go into the very specific breaking changes affecting
the JavaScript driver.


### Breaking changes to js-bigchaindb-driver's APIs

#### Output amount is now a string

```js
// old
export default function makeOutput(condition, amount = 1) {}

// new
export default function makeOutput(condition, amount = '1') {}
```


#### Update to Crypto-Conditions version 2

All conditions or fulfillments passed manually to the driver now need to comply
with ILP's Crypto-Condition version 2 specification.  For more information,
[see the updated
specification](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02)
or checkout the [latest reference implementation of Crypto-Conditions in
JavaScript](https://github.com/interledgerjs/five-bells-condition).


#### Several `Connection` methods now require positional arguments

##### `Connection.listBlocks`

```js
// old
new Connection(PATH).listBlocks({ tx_id, status })

// new
new Connection(PATH).listBlocks(transactionId, status)
```


##### `Connection.listOutputs`

```js
// old
new Connection(PATH).listOutputs({ public_key, unspent })

// new
new Connection(PATH).listOutputs(publicKey, spent)
```

**NOTE:** The `unspent` flag has been inversed. This is inline [with breaking
changes to BigchainDB
v1.0](https://github.com/bigchaindb/bigchaindb/blob/17913dca682ff105540c0ea73365f1763efc2083/docs/upgrade-guides/v0.10--%3Ev1.0.md#get-apiv1outputs).


##### `Connection.listTransactions`

```js
// old
new Connection(PATH).listTransactions({ asset_id, operation })

// new
new Connection(PATH).listTransactions(assetId, operation)
```


### Newly added endpoints

##### `Connection.searchAsset`

```js
// new
new Connection(PATH).searchAssets(search)
```

A querying interface to text-search all assets in BigchainDB. For more
documentation, [see BigchainDB's HTTP
API](https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html#assets).


### Newly available bundles and CDN hosting

The driver is now bundled automatically each time we publish it to npm.com.  We
now ship packages for `commonjs`, `commonjs2`, `amd`, `umd`, `window` and
node.js. Thanks to unpkg.com, we're also able to provide all these packages on
a CDN. A link to all the bundles can be found
[here](https://unpkg.com/bigchaindb-driver@0.3.0/dist/browser/).


A few notes:

- Adjust version number in link as appropriate
- only include `bigchaindb-driver.*.min.js`, but now everything `bundle.*`.
  This is [a known
  issue](https://github.com/bigchaindb/js-bigchaindb-driver/issues/66).