Changelog
Release v1.6
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 v1.6 (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 v1.6 roadmap.
Step 3: Upgrade to SDK v1.6
Once you have migrated your code to the new interfaces using the v1.5 SDK, you are ready to upgrade to the v1.6 SDK, which removes all interfaces deprecated in v1.5.
If you install the v1.6 SDK and your application performs as expected, you have successfully migrated to v1.6.
If you install the v1.6 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 v1.6-rc2 (v1.6 release candidate 2)
April 16, 2018
This is the second release candidate for v1.6, which affects individual SDKs as follows:
- Java: Change
Action|ActionSum.tags
type fromObject
toMap<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 akey_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 theactions()
scope), you will instead filter ontags
.
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:
- Query the earmarked contracts by reference data
- Create a separate action for each contract you want to transact
- 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 createdfilter
andfilter_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
orasset_id
when creating transactions, you will instead provide aflavor_id
. - Where you provide an
asset_alias
orasset_id
in a filter when querying transactions or actions, you will instead provide aflavor_id
. - Where you provide
asset_tags
in a filter when querying transactions or actions, you will instead providesnapshot.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 providesnapshot.flavor_tags
. - Where you provide
source_account_tags
in a filter when querying transactions or actions, you will instead providesnapshot.source_account_tags
. - Where you provide
destination_account_tags
in a filter when querying transactions or actions, you will instead providesnapshot.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 thecode
field) and target the newSEQXXX
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 theid
field, you do not need to do anything. - If you are currently providing an
alias
, start proving anid
instead and ensure that your code no longer references thealias
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 thealias
andid
, 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.