Minka Ledger SDK

An SDK for interacting with the Minka Ledger.

Getting started

Installation

Install this package by running:

npm install @minka/ledger-sdk

Basic usage

First, you need an instance of the LedgerSDK class, you can pass an options object with the required property server pointing to the ledger you want to use.

const ledger = new LedgerSdk({
  server: 'https://minka.inc..',
})

That ledger instance has different Clients and only one status method that returns the status of the ledger.

Note: Most of the methods in the entire SDK are asynchronous, meaning they return a promise you need to wait to be resolved by using async/await(preferred) functions or .then()` at the end of the methods chain.

Clients

Each entity of the ledger has its client, and those clients are properties of the LedgerSDK instance, for example, the client for signer will be returned in sdk.signer if you used the example below to connect to the ledger.

Available clients: ledger, symbol, wallet, intent, signer, effect and bridge.

Common client methods

All clients have common methods for listing (list), fetching (read) and initializing (init) entities

list

The list method allows you to fetch a list of the required entity, it has an optional object of type LedgerListParams as a param to pass pagination and filtering options to it. You can read more about it here

const output = await sdk.signer.list()
// output: MultipleRecordsResponse

read

The read method allows you to fetch a single record of the required entity, it has a required string param that is the handle you want to fetch.

const output = await sdk.signer.read('handle')
// output: SingleRecordResponse

drop

The drop method allows you to delete a single record of the required entity. There are two ways of doing so:

• Passing a string param that is the handle/luid you want to delete. Internally fetches the record to obtain its hash before proceeding with the drop request.

// Initialize a drop record builder for the wallet entity
// Call .hash() to create a new record hash
// Call .sign() to add a signature
const dropWalletRecord = await sdk.wallet.drop('handle').hash().sign([{ keyPair }])
/**
 * Send the DELETE request to the backend.
 */
const response = await dropWalletRecord.send()

• Passing the ledger record you want to delete, in cases where you have fetched it before.

const fetchedWallet: LedgerRecord<LedgerWallet> = {
  hash: '<hash>',
  data: {
    handle: '<wallet-handle>',
    access: [
      {
        action: '<action>',
        signer: {
          public: '<public-key>',
        },
      },
    ],
  },
  luid: '<luid>',
  meta: {
    proofs: [
      {
        custom: {
          moment: '<moment>',
          status: '<status>',
        },
        digest: '<digest>',
        method: '<method>',
        public: '<public-key>',
        result: '<result>',
      },
    ],
    status: '<status>',
    moment: '<moment>',
    owners: ['<owner>'],
  },
}

// Initialize a drop record builder for the wallet
const dropWalletRecord = await sdk.wallet
  .drop(record)
  .hash()
  .sign([{ keyPair: yourKeyPair }])

/**
 * Send the DELETE request to the backend.
 * Optionally, you can pass authParams and headers to the send method.
 */
const response = await dropWalletRecord.send({ authParams, headers })

init

the init method allows you to initialize a new record builder instance. record builders provide a more convenient way to work with the records by implementing methods to hash, sign, test and send them to the ledger. You can optionally pass the initial record to the init method, otherwise, it will be initialized with an empty record.

// Initialize a record builder for the signer entity
const emptySignerRecord = await sdk.signer.init()
/**
 * Send that record to the backend. Note this record will
 * return error because it's empty.
 */
const response = await emptySignerRecord.send()

Keep in mind that methods are chainable, so you can easily create a record as follows;

/**
 * "{}" represents valid data for the record
 * "keyPair" represents a valid key pair
 */
await sdk.signer.init({}).hash().sign([{ keyPair }]).send()