Flavors

Each type of value in the ledger is called a flavor. For example, if your application manages multiple currencies, you might create a USD flavor, an EUR flavor, and a CNY flavor.

Once a flavor is created, you can issue tokens of that flavor into an account.

Sequence represents amounts as integers in the range 0 to 2^63 - 1 (9,223,372,036,854,775,807).

It you want to represent an amount outside this range, such as Ethereum's wei, which has amounts in the range 0 to 2^256 we recommend using a smaller unit, such as gwei (aka shannon, nanoether).

ID

A flavor ID is a user-defined, unique identifier. If you do not provide one, one will be automatically generated for you.

Keys & Quorum

When creating a flavor, you provide one or more keys and a quorum. The quorum is the number of keys that must sign a transaction in order to issue tokens of the flavor into the ledger. By default, the quorum is equal to the number of keys provided, but you can choose to require only a subset of keys – for example, 2-of-3.

Flavor Tags

Flavor tags are user-defined key-value pairs associated with the flavor. Flavor tags are useful for grouping different flavors together for the purpose of querying tokens or actions.

For example, if you have three different flavors that all represent points – points earned, points gifted, and points promo, they could all have the tag "type": "point". Then, when you want to query the total amount of all "points" issued, you would provide the following filter to the sum actions query:

type='issue' AND snapshot.flavorTags.type='point'
type='issue' AND snapshot.flavorTags.type='point'
type='issue' AND snapshot.flavor_tags.type='point'

This would return a single aggregate sum of all actions issuing tokens across all three flavors.

Tags snapshot

When a new action is added to a ledger via a transaction, a snapshot of the flavor tags as they exist at that time are added to the snapshot object in the action object.

You can then provide a filter to access the tags snapshot when querying actions. For example:

snapshot.flavorTags.type='point'
snapshot.flavorTags.type='point'
snapshot.flavor_tags.type='point'

Updating tags

You can update flavor tags at any time. These new tags will be added to the snapshot on any new actions going forward. Snapshots on existing actions will not be affected.

Data Structure

Field Descriptions

Field Type Description
id string Unique identifier of the flavor, user-supplied or system-generated.
tags JSON object Arbitrary, user-supplied, key-value data about the flavor.
key ids array A list of ids of the keys that control issuance of the flavor.
quorum integer The number of keys from which signatures are required to issue units of the flavor.

Example Object

{
  id: "...",
  tags: {},
  keyIds: [],
  quorum: 1
}
{
  id: "...",
  tags: {},
  keyIds: [],
  quorum: 1
}
{
  id: "...",
  tags: {},
  key_ids: [],
  quorum: 1
}

SDK Examples

Create a flavor

Flavor usd = new Flavor.Builder()
  .setId("usd")
  .addKeyId(key.id)
  .addTag("type", "currency")
  .create(ledger);
ledger.flavors.create({
  id: 'usd',
  keyIds: [key.id],
  tags: {type: 'currency'}
}).then(usd => ...)
usd = ledger.flavors.create(
  id: 'usd',
  key_ids: [key.id],
  tags: {type: 'currency'}
)

Update flavor tags

new Flavor.TagUpdateBuilder()
  .setId("usd")
  .addTag("type", "fiat")
  .update(ledger);
ledger.flavors.updateTags({
  id: 'usd',
  tags: {type: 'fiat'}
}).then(usd => ...)
ledger.flavors.update_tags(
  id: 'usd',
  tags: {type: 'fiat'}
)

Query flavors

Query all "currency" flavors.

Flavor.ItemIterable flavors = new Flavor.ListBuilder()
  .setFilter("tags.type=$1")
  .addFilterParameter("fiat")
  .getIterable(ledger);
for (Flavor flavor : flavors) {
  System.out.println("flavor": " + flavor.id);
}
let all = ledger.flavors.list({
  filter: 'tags.type=$1',
  filterParams: ['fiat']
}).all()

while (true) {
  let { value: flavor, done: done } = await all.next()
  if (done) { break }
  console.log(flavor)
}
ledger.flavors.list(
  filter: 'tags.type=$1',
  filter_params: ['fiat']
).each do |flavor|
  puts flavor.to_json
end