Sequence

Get Started

Examples

Ledger Objects

Ledger Queries

Reference

Java SDK

Ruby SDK

Node SDK

Changelog

Release v2

April 18, 2018

Version 2 has been released. Thanks to everyone for the invaluable feedback throughout this process!

Migration period

You have until July 1, 2018 to migrate your code from SDK v1.x to v2.

Until this date, all versions of the SDK (with both the new and deprecated interfaces) will continue to work.
After this date, we will drop support for v1.x SDKs (with the deprecated interfaces) and only v2 (with the new interfaces) will work going forward.

Migration steps

You can migrate your code seamlessly without interruption by following these steps:

Step 1: Upgrade to SDK v1.5

The v1.5 SDKs are the last SDK releases before v2. They support both the new interfaces and the deprecated interfaces. Upgrading should have no impact on your application.

Step 2: Migrate to the new interfaces

Using the v1.5 SDK, you can then migrate your code to the new interfaces.

The easiest approach is to follow the migration steps in each release outlined in this document below, starting at the bottom with v1.1 and working your way up to v1.5. You can also view a summary of the changes in the v2 roadmap.

Step 3: Upgrade to SDK v2

Once you have migrated your code to the new interfaces using the v1.5 SDK, you are ready to upgrade to the v2 SDK, which removes all interfaces deprecated in v1.5.

If you install the v2 SDK and your application performs as expected, you have successfully migrated to v2.
If you install the v2 SDK and your application returns an error, you have likely missed a spot in your code that is still using the deprecated interfaces.

If you have any questions, don't hesitate to email us at [email protected].

Release v2-rc2 (v2 release candidate 2)

April 16, 2018

This is the second release candidate for v2, which affects individual SDKs as follows:

Java: Change Action|ActionSum.tags type from Object to Map<String, Object>.
Node: Explicitly disallow providing deprecated parameters or accessing deprecated fields.
Ruby: The interface for iterating results of a query has changed. .[list|sum].all has been removed (and deprecated in a parallel release v1.5.2); the new interface uses Ruby's Enumerable on the result of .[list|sum] e.g. .[list|sum].to_a and .[list|sum].each.

Release v2-rc1 (v2 release candidate 1)

April 11, 2018

This is the first release candidate for v2. All interfaces deprecated in v1.x releases have been removed.

Release v1.5

Mar 16, 2018

1. Filters and Group-By now use language-specific fieldname cases

This release unifies the filter syntax with the fieldnames on the SDK objects.

Previously, if you used Java or Node, your filter would always be snake case:

destination_account_id='alice'

But then you would access the field on the object by the name defined in the SDK (which is camel case):

object.destinationAccountId

Now, you should provide your filter with the same case as the field name of the object in your SDK. So for Java and Node, your filter would be:

destinationAccountId='alice'

Transitioning your code

If you are using the Java or Node SDK, you will need to update your filter and group-by strings to use camel case field names instead of snake case.
If you are using the Ruby SDK, you do not need to make any changes.

2. Deprecate transaction reference data

This release deprecates transaction reference data on the transaction builder and the transaction object.

To record details about a transaction, you should instead use action tags.

3. Key IDs replaces Keys on accounts and flavors

This release simplifies the structure of keys within the account and flavor objects.

A key IDs array has been added to the account and flavor objects. The keys array has been deprecated.

Transitioning your code

If you are using the Ruby or Node SDK:

When creating an account or flavor, where you currently provide a keys array (containing a list of objects), you will now provide a key_ids array (containing a list of strings). For example:
```
// OLD
ledger.accounts.create(
  id: 'alice',
  keys: [{id: 'my_key'}],
  tags: {type: 'checking'}
)

// NEW
ledger.accounts.create(
  id: 'alice',
  key_ids: ['my_key'],
  tags: {type: 'checking'}
)
```
If you are using the Java SDK, you do not need to make any changes.

4. Updated query iterator pattern in Node

This release changes the .all() method on .list() and .sum() queries in Node to return a standard async iterator. The previous callback-based interface has been deprecated.

For example:

// OLD
ledger.accounts.list({
  filter: 'tags.type=$1',
  filterParams: ['checking']
}).all(account => {
  console.log(account)
})

// NEW
let all = client.accounts.list(
  filter: 'tags.type=$1',
  filterParams: ['checking']
).all()

while (true) {
  let { value: account, done: done } = await all.next()
  if (done) { break }
  console.log(account)
}

5. Updated query iterator pattern in Ruby

This release deprecates the .all method on .list and .sum queries in Ruby. The new interface uses Ruby's Enumerable on the result of .list and .sum.

For example:

// OLD
ledger.actions.list(
).all.each do |action|
  puts action.to_json
end

// NEW
ledger.actions.list(
).each do |action|
  puts action.to_json
end

6. Introducing feeds

Feeds allow you to sequentially process actions and transactions as they are added to a ledger, without the need for polling or keeping state in your application. This is helpful for:

Real-time applications, such as notifications or live-updating interfaces
Microservice architectures, where one service creates transactions and another service performs some operation in response

For more information, see feeds.

7. Deprecate contracts array in transaction object

The contracts array in the transaction object has been deprecated. This is no longer needed when operating on tokens.

Release v1.4

Mar 8, 2018

1. Introduce action tags

This release adds action tags to the transaction builder and action object. Reference data has been deprecated.

Transitioning your code

If you currently provide reference data on an action when building a transaction, you will instead provide action tags.
If you currently filter on reference_data when querying actions (or transactions within the actions() scope), you will instead filter on tags.

Additional notes

Unlike how action reference data was added to both the resulting action and contract objects, action tags are only added to the action object. For earmarking tokens, see token tags.

2. Timestamp inequalities in filters

This release adds support for timestamp inequalities (<, >, <=, >=) in filters (when querying and building transactions).

RFC3339 timestamp format

In order to be able to filter with inequalities on custom timestamp fields in tags, the value must be a string in RFC3339 timestamp format with timezone Z. For example:

2018-05-02T20:43:57.917Z

Type indicator

When constructing a filter that uses an inequality on a timestamp field, a :time type indicator must be appended to the parameter:

tags.expiration:time > $1

Release v1.3

Mar 1, 2018

1. Token query interfaces

This release introduces the list tokens and sum tokens interfaces.

To query balances in an account, you now sum tokens. Query balances has been deprecated.
To list the tokens in an account, you now list tokens. Query contracts has been deprecated.

2. Earmarking tokens with tags

This release introduces token tags and filters when building transactions as a new way to earmark and transact specific tokens in an account.

Previously, the process was:

To earmark tokens, provide reference data on an action. This reference data was copied to the resulting contract holding the tokens.
To transfer or retire tokens with specific tags:
1. Query the earmarked contracts by reference data
2. Create a separate action for each contract you want to transact
3. If you do not want to transact all of the tokens in the contract, extract the reference data from the contract and set it as the change reference data in the action.

This process is now much simpler:

To earmark tokens, provide token tags when building a transaction.
To transact an amount tokens with specific tags, provide a filter when building a transaction.

You no longer need to handle the underlying contracts.

For examples, see token tags.

3. New fields in the action object

This release adds the following fields to the action object:

snapshot.token_tags - records the token tags provided when the action was created
filter and filter_params - records the filter details provided for selecting tokens when the action was created

4. New pagination interfaces

For the query interfaces (list and sum) for all objects (keys, accounts, flavors, transactions, actions, and tokens) there are now two ways to handle pagination:

Retrieving a page of results at a time – useful for implementing pagination in an end-user application, such as infinite scroll.
Iterating though individual results - useful for processing results in an application, such as generating a report (where pages are incidental).

Release v1.2

Feb 16, 2018

1. Introduce flavors

This release changes the name of Asset to Flavor.

New interfaces and field names for flavors have been added, and existing interfaces and field names for assets have been deprecated.

Transitioning your code

Where you create assets, you will instead create flavors.
Where you provide an asset_alias or asset_id when creating transactions, you will instead provide a flavor_id.
Where you provide an asset_alias or asset_id in a filter when querying transactions or actions, you will instead provide a flavor_id.
Where you provide asset_tags in a filter when querying transactions or actions, you will instead provide snapshot.flavor_tags.

Additional notes

This release does not introduce the flavor syntax on the contract query or balance query interfaces. These will be superseded by the list tokens and sum tokens interfaces in the upcoming release v1.3, which will include only the new flavor syntax. For details, see the roadmap.

2. Introduce snapshot on actions

This release introduces a snapshot field on the action object. The snapshot contains a copy of the associated action_tags, flavor_tags, source_account_tags, and destination_account_tags as they existed at the time of the transaction.

New action object

{
  ...
  "snapshot": {
    "flavor_tags": {...},
    "source_account_tags": {...},
    "destination_account_tags": {...},
  }
  ...
}

The existing asset_tags, source_account_tags, and destination_account_tags fields on the action object have been deprecated.

Transitioning your code

Where you provide asset_tags in a filter when querying transactions or actions, you will instead provide snapshot.flavor_tags.
Where you provide source_account_tags in a filter when querying transactions or actions, you will instead provide snapshot.source_account_tags.
Where you provide destination_account_tags in a filter when querying transactions or actions, you will instead provide snapshot.destination_account_tags.

3. Introduce SEQXXX error codes and deprecate CHXXX error codes

This release changes the name of the error code field (from code to seq_code) and changes the format of the error code value (from CHXXX to SEQXXX).

OLD

{
  "code": "CHXXX"
}

NEW

{
  "seq_code": "SEQXXX"
  "code": "CHXXX"       // deprecated
}

Transitioning your code

If you are not currently operating on a specific error code, you do not need do to anything.
If you are currently operating on a specific error code, you will need to access the seq_code field in the error object (instead of the code field) and target the new SEQXXX format.

Release v1.1

Feb 7, 2018

1. Introduce user-provided id and deprecate alias on keys and accounts

This release deprecates the alias field on the key and account objects. You can instead provide an id when creating a key or account. If you do not provide an id, one will be generated automatically for you.

Transitioning your code

If you are not currently providing an alias on a key or account, and instead operating on the id field, you do not need to do anything.
If you are currently providing an alias, start proving an id instead and ensure that your code no longer references the alias field (for example, when querying or transacting).

Breaking change (if not yet transitioning your code)

If you are currently providing an alias on a key or account, but you are operating on both the alias and id, you will need to reset your ledger by Wed, Feb 14 to continue using your current code.

Additional notes

This release does not affect the asset object, which will be addressed in the next release when flavors are introduced and assets are deprecated.

2. Introduce actions query interfaces

This release introduces two new query interfaces to directly access the action objects that currently only exist within the transaction object.

The list actions query returns a filtered set of actions.
The sum actions query returns an aggregate over the amount fields in a filtered set of actions.

For more information, see actions.