Accounts

IDLink to this section

An account id is a user-defined, unique identifier. If you do not provide one, one will be created for you automatically.

Keys & QuorumLink to this section

When creating an account, you provide one or more keys and a quorum. The quorum is the number of keys that must sign a transaction in order to transfer or retire tokens from the account. 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.

TagsLink to this section

Account tags are a set of user-defined key-value pairs associated with an account. Account tags are useful for grouping different accounts together for the purpose of querying balances.

For example, if one user has three different types of accounts, they could all have a tag containing the same user ID.

Then, when you want to query the balance of each asset across all of the user's accounts, you would provide the following filter to the sum tokens query:

accountTags.userId='123'

accountTags.userId='123'

account_tags.user_id='123'

and set the sum-by parameter as:

accountTags.userId

accountTags.userId

account_tags.user_id

This would return a list of token "balances" across all the accounts for that user.

Tags snapshotLink to this section

When a new action is added to a ledger via a transaction, a snapshot of the source account tags and destination account 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.sourceAccountTags.userId='123'

snapshot.sourceAccountTags.userId='123'

snapshot.source_account_tags.user_id='123'

Updating tagsLink to this section

You can update account 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 StructureLink to this section

Field DescriptionsLink to this section

Example ObjectLink to this section

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

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

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

ExamplesLink to this section

Create an accountLink to this section

Create a checking account for Alice.

Account alice = new Account.Builder()
  .setId("alice")
  .addKeyId(key.id)
  .addTag("type", "checking")
  .create(ledger);

ledger.accounts.create({
  id: 'alice',
  keyIds: [key.id],
  tags: {type: 'checking'}
}).then(alice => ...)

alice = ledger.accounts.create(
  id: 'alice',
  key_ids: [key.id],
  tags: {type: 'checking'}
)

Query accountsLink to this section

Query all checking accounts.

Account.ItemIterable accounts = new Account.ListBuilder()
  .setFilter("tags.type=$1")
  .addFilterParameter("checking")
  .getIterable(ledger);
for (Account account : accounts) {
  System.out.println("account: " + account.id);
}

let all = ledger.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)
}

ledger.accounts.list(
  filter: 'tags.type=$1',
  filter_params: ['checking']
).each do |account|
  puts account.to_json
end