Mesh
Sign in
Get started

5-Minute Guide

This guide covers the basics of working with a ledger from an SDK: creating a key, defining a type of token, creating accounts, and moving tokens between them.

On this page

SetupLink to this section

First, you'll need a ledger and an API credential.

Create a ledgerLink to this section

Open the Ledgers page in the console and choose New ledger.

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

Get an API credentialLink to this section

An SDK reaches a ledger with an API credential. Open the API keys page in the console, give the key a name, and choose Create key. What one is and what it is allowed to do is covered under personal API credentials.

The part that matters here: a credential is displayed once, when it is created, so copy it then, and keep it out of your source. The samples below read it from the SEQCRED environment variable.

Instantiate SDK clientLink to this section

To instantiate the SDK client, specify a ledger name and a credential. Let's specify the test ledger and the credential we just created.

Client ledger = new Client.Builder()
  .setLedgerName("test")
  .setCredential(System.getenv("SEQCRED"))
  .build();
const ledger = new onyxMesh.Client({
  ledgerName: 'test',
  credential: process.env.SEQCRED,
})
ledger = OnyxMesh::Client.new(
  ledger_name: 'test',
  credential: ENV['SEQCRED'],
)

Create a keyLink to this section

Transactions in the ledger are authenticated by cryptographic keys.

To create a key, provide an id (a unique identifier). If no id is provided, one will be automatically generated.

new Key.Builder().setId("key").create(ledger);
await ledger.keys.create({ id: 'key' })
ledger.keys.create(id: 'key')

Create an assetLink to this section

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

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

new Asset.Builder()
  .setId("usd")
  .addKeyId("key")
  .create(ledger);
await ledger.assets.create({
  id: 'usd',
  keyIds: ['key']
})
ledger.assets.create(id: 'usd', key_ids: ['key'])

Create accountsLink to this section

Accounts represent entities in the ledger and can each hold many different assets of tokens.

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

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

Issue tokensLink to this section

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

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

new Transaction.Builder()
  .addAction(
    new Transaction.Builder.Action.Issue()
      .setAssetId("usd")
      .setAmount(100)
      .setDestinationAccountId("alice")
  ).transact(ledger);
await ledger.transactions.transact(builder => {
  builder.issue({
    assetId: 'usd',
    amount: 100,
    destinationAccountId: 'alice',
  })
})
ledger.transactions.transact do |builder|
  builder.issue(
    asset_id: 'usd',
    amount: 100,
    destination_account_id: 'alice',
  )
end

Transfer tokensLink to this section

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

new Transaction.Builder()
  .addAction(
    new Transaction.Builder.Action.Transfer()
      .setAssetId("usd")
      .setAmount(50)
      .setSourceAccountId("alice")
      .setDestinationAccountId("bob")
  ).transact(ledger);
await ledger.transactions.transact(builder => {
  builder.transfer({
    assetId: 'usd',
    amount: 50,
    sourceAccountId: 'alice',
    destinationAccountId: 'bob',
  })
})
ledger.transactions.transact do |builder|
  builder.transfer(
    asset_id: 'usd',
    amount: 50,
    source_account_id: 'alice',
    destination_account_id: 'bob',
  )
end

Retire tokensLink to this section

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

new Transaction.Builder()
  .addAction(
    new Transaction.Builder.Action.Retire()
      .setAssetId("usd")
      .setAmount(10)
      .setSourceAccountId("bob")
  ).transact(ledger);
await ledger.transactions.transact(builder => {
  builder.retire({
    assetId: 'usd',
    amount: 10,
    sourceAccountId: 'bob',
  })
})
ledger.transactions.transact do |builder|
  builder.retire(
    asset_id: 'usd',
    amount: 10,
    source_account_id: 'bob',
  )
end