Plugins

Plugins

Plugins are a part of lamassu-server (version 1.0.1 and up) functionality that can be implemented by a 3rd party.

Plugin requirements

Each plugin MUST publicly expose the following fields:

• NAME - String containing a formatted name of the plugin (example)
• SUPPORTED_MODULES - Array containing a list of supported plugin types (example)

All plugins depending on an external configuration (credentials, global currency, etc.) SHOULD expose config(Object config) method (example). Each plugin may specify it's own flat JSON configuration scheme. This scheme should be documented in the plugin's README file.

Each plugin package can implement multiple plugin types. Bitstamp plugin is an example of implementing both Ticker and Trader.

Plugin lifecycle

On server boot, all plugins are loaded (require('plugin-name');) and configured (plugin.config(configObject);). Once plugins configuration changes plugin's .config() method is called, and that may happen any time.

Plugin patterns

• All Bitcoin values are passed in Satoshis as an Integer,

• All fiat values are passed as a String with 2 decimal places,

• All callbacks have the following structure (unless otherwise noted):

  function calback(error, callbackReturnValue) {
    // further processing
  }

  where error and callbackReturnValue are mutually exclusive, and:

  • error can either be a String or an instance of an Error object,
  • callbackReturnValue is different for each method and will be defined in its description.

Plugin types

Wallet

Sends Bitcoins, generates new Bitcoin addresses, returns its current balance.

Plugin type (for SUPPORTED_MODULES array): wallet

Example: lamassu-blockchain

Required methods:

.sendBitcoins(address, satoshis, minersFee, callback);

Creates and broadcasts transaction for a given Bitcoin amount and to a given Bitcoin address.

• address - String containing Bitcoin address in Base58 format,
• satoshis - Integer amount to be sent,
• minersFee - Integer amount to be used as a fee,
• callbackReturnValue - String transaction hash of a sent tx.

.balance(callback);

Returns balance available for sending (funds with at least 1 confirmation).

• callbackReturnValue - Object mapping ALL CAPS currency codes (ex. BTC) to their Integer satoshi values.

.newAddress(info, callback); ** DRAFT! **

Generates and stores private key of a new Bitcoin address.

• info - Object containing two fields (supporting them is optional):

  • label - String should be used to name generated address (if supported),
  • account - String name of wallet account to be used (if supported).

• callbackReturnValue - String containing Bitcoin address in Base58 format,

Ticker

Provides current Bitcoin price for a given currency or currencies.

Plugin type: ticker

Example: lamassu-bitstamp

Required methods:

.ticker(currencies, callback);

Returns current ask and bid prices for a given currency/currencies.

• currencies - String or Array of Strings of currencies to be checked,

• callbackReturnValue - Object mapping ALL CAPS currency codes (ex. USD) to objects with the following structure:

  {
    USD: {
      currency: 'USD',
      rates: {
        ask: String, // two decimal places
        bid: String  // two decimal places
      }
    }
  }

Trader

Conducts instant market buys/sells for a given BTC amount.

Plugin type: trader

Example: lamassu-bitstamp

Required methods:

.balance(callback);

Returns available balance for both virtual and fiat currencies.

• callbackReturnValue - Object mapping ALL CAPS currency codes (ex. BTC or USD) to their values. For their formats see Plugin patterns.

.purchase(satoshis, opts, callback);

MUST by default place market-buy orders and should fall back to a limit order when price is provided. Lack of limit orders support should be noted in repository README file.

• satoshis - Integer amount of satoshis to be purchased,
• opts - Object currently the only allowed parameter here is an optional price.

This method should only return error on failure, no callbackReturnValue is required!

.sell(satoshis, opts, callback);

MUST by default place market-sell orders and should fall back to a limit order when price is provided. Lack of limit orders support should be noted in repository README file.

• satoshis - Integer amount of satoshis to be purchased,
• opts - Object currently the only allowed parameter here is an optional price.

This method should only return error on failure, no callbackReturnValue is required!

Identity Verifier

Verifies users and transactions.

Plugin type: idVerifier

Example: lamassu-identitymind

Required methods:

.verifyUser(rawData, callback);

.verifyTransaction(rawData, callback);

Info ** DRAFT! **

Provides server with public ledger data (ex. tx status, address's txs, address balance)

Plugin type: info

Example: lamassu-chain

Required methods:

.getAddressLastTx(address, callback);

Returns data about last incoming tx for a given address.

• address - String containing Bitcoin address in Base58 format,

• callbackReturnValue - an Object with following fields:

  • txHash - String - Transaction hash,
  • tsReceived - Integer - UNIX timestamp when tx was first spotted,
  • confirmations - Integer - Number of confirmations/blocks,
  • amount - Integer - Amount by which address balance changed,
  • fees - Integer - Fees for miners included in this tx,
  • authorized - Boolean - Should be set when plugin implements own 0-confirmations heuristics,
  • confidence - Flat - Number between 0 and 1 indicating confidence level for authorized status (1 being very sure).

.getTx(txHash, address, callback);

Returns current confirmation status for a given Transaction.

• txHash - String containing hash of checked Transaction,

• address - String containing Bitcoin address in Base58 format,

• callbackReturnValue - the same as in .getAddressLastTx() method.