Plugins

Plugins

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

Plugin requirements

Each plugin MUST publically expose following fields:

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

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 plugin's README file.

Each plugin package can implement multiple plugin types. Bitstamp plugin is an example 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 Strings 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 be either String or an instance of an Error object,
  • callbackReturnValue is different for each method and will be defined in it's 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 limit orders when price is provided. Lack of limit orders 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 limit orders when price is provided. Lack of limit orders 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:

.getLastTx(address, callback);

Should return 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 - Timestamp when tx was first spotted,
  • confirmations - Integer - Number of confirmations/blocks,
  • amount - Integer - Amount transferred TO the given address,
  • fees - Integer - Fees for miners included in this tx.

.getTxStatus(txHash, callback);

Should return current confirmation status for a given Transaction.

• txHash - String containing hash of checked Transaction,

• callbackReturnValue - an Object with following fields:

  • status - String containing one of the states listed below,
  • confirmations - Integer number of confirmations for a given tx; required only in confirmedDeposit state,
  • confidence - Float number between 0 and 1 indicating confidence level for authorizedDeposit status (1 being very sure).

Possible transaction statuses:

• confirmedDeposit - (required) reported when transaction has at least 1 confirmation,
• authorizedDeposit - (optional) 0-confirmation; Relies on plugin-specific heuristics. Whenever this state is reported, confidence field must be provided as well,
• fullDeposit - (required) reported for 0-conf. txs, when authorizedDeposit was not detected or is not implemented. In this case it's allowed to just call parameterless callback();.