5-Minute Guide

This guide will teach you the basics of interacting with a ledger from an SDK.

Setup

First, you'll need to create a ledger and API credentials.

Create a ledger

To create a ledger, visit your team dashboard and select the "Ledgers" tab in the team navigation bar and click the "New" button.

You will be asked to choose a name composed of letters, numbers and hyphens. The name must be unique within your team. Let's name this ledger development.

Create API Credentials

To access your ledger from an SDK, you'll need an API credential. For development, it's convenient to use a Personal API credential.

You can create a Personal API Credential in your team dashboard:

  1. Click the user account menu in the top right of the navigation bar
  2. Select "Account"
  3. Scroll down to the "API credentials" section
  4. Click the "New" button.

For security, you will only be able to view your new API Credential once, so make sure to copy it for use in your SDK.

Instantiate SDK client

To instantiate the SDK client, you need to specify a ledger name and a credential. Let's specify the development ledger and the credential we just created.

Client ledger = new Client.Builder()
  .setLedgerName("development")
  .setCredential("...")
  .build();
const ledger = new sequence.Client({
  ledgerName: 'development',
  credential: '...'
})
ledger = Sequence::Client.new(
  ledger_name: 'development',
  credential: '...'
)

Create a key

Transactions in the ledger are authenticated by cryptographic keys. To create a key, provide an id (a unique identifier).

Key key = new Key.Builder()
  .setId("my_key")
  .create(ledger);
ledger.keys.create({id: 'my_key'}).then(key => ...)
key = ledger.keys.create(id: 'my_key')

Create a flavor

For each type of token you want to track in a ledger, you first create a flavor. You can then issue tokens of that flavor into an account.

To create a flavor, provide an id (a unique identifier) and one or more keys.

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

Create an account

Accounts represent entities in the ledger and can each hold many different flavors of tokens. To create an account, provide an id (a unique identifier) and one or more keys:

Account alice = new Account.Builder()
  .setId("alice")
  .addKeyId(key.id)
  .create(ledger);
ledger.accounts.create({
  id: 'alice',
  keyIds: [key.id]
}).then(alice => ...)
alice = ledger.accounts.create(
  id: 'alice',
  key_ids: [key.id]
)

Create a second account to interact with the first:

Account bob = new Account.Builder()
  .setId("bob")
  .addKeyId(key.id)
  .create(ledger);
ledger.accounts.create({
  id: 'bob',
  keyIds: [key.id]
}).then(bob => ...)
bob = ledger.accounts.create(
  id: 'bob',
  key_ids: [key.id]
)

Issue tokens

To issue tokens, use the issue action in the transaction builder and provide a flavor, an amount, and a destination account.

The transact method automatically applies any necessary key signatures and submits the transaction to the ledger.

Transaction tx = new Transaction.Builder()
  .addAction(new Transaction.Builder.Action.Issue()
    .setFlavorId("usd")
    .setAmount(100)
    .setDestinationAccountId("alice")
  ).transact(ledger);
ledger.transactions.transact(builder => {
  builder.issue({
    flavorId: 'usd',
    amount: 100,
    destinationAccountId: 'alice'
  })
}).then(tx => ...)
tx = ledger.transactions.transact do |builder|
  builder.issue(
    flavor_id: 'usd',
    amount: 100,
    destination_account_id: 'alice'
  )
end

Transfer tokens

To transfer tokens, use the transfer action in the transaction builder and provide a flavor, an amount, a source account, and a destination account.

Transaction tx = new Transaction.Builder()
  .addAction(new Transaction.Builder.Action.Transfer()
    .setFlavorId("usd")
    .setAmount(10)
    .setSourceAccountId("alice")
    .setDestinationAccountId("bob")
  ).transact(ledger);
ledger.transactions.transact(builder => {
  builder.transfer({
    flavorId: 'usd',
    amount: 10,
    sourceAccountId: 'alice',
    destinationAccountId: 'bob'
  })
}).then(tx => ...)
tx = ledger.transactions.transact do |builder|
  builder.transfer(
    flavor_id: 'usd',
    amount: 10,
    source_account_id: 'alice',
    destination_account_id: 'bob'
  )
end

Retire tokens

To retire tokens, use the retire action in the transaction builder and provide a flavor, an amount, and a source account.

Transaction tx = new Transaction.Builder()
  .addAction(new Transaction.Builder.Action.Retire()
    .setFlavorId("usd")
    .setAmount(5)
    .setSourceAccountId("alice")
  ).transact(ledger);
ledger.transactions.transact(builder => {
  builder.retire({
    flavorId: 'usd',
    amount: 5,
    sourceAccountId: 'alice'
  })
}).then(tx => ...)
tx = ledger.transactions.transact do |builder|
  builder.retire(
    flavor_id: 'usd',
    amount: 5,
    source_account_id: 'alice'
  )
end