Adding assets to hybrix

Introduction

There are three levels of complexity when adding a new asset or coin to hybrix.

1. A token based on an already supported chain.
2. A chain derived from a supported chain.
3. A completely new chain

Tokens

For the first case, if the asset is a token based on an existing base chain, only a simplified Node side module or recipe needs to be defined.

You can also use the online recipe form to add your token without writing any code: add a token.

If you want to write the recipe yourself then you do no have write define any qrtz code (API endpoints definitions) as those will already be defined in the base asset recipe. You can import the base recipe using the import property. See below for an example:

recipes/token.burst.lex.json
{
  "symbol":"burst.lex",
  "name":"Lex4All",
  "module":"quartz",

  "import":"burst",

  "mode":"nxt.burst-token",
  "contract":"2264511436216725766",
  "originator":"BURST-KN9G-WJH6-BGAA-GWLWF",
  "factor":0
}

For more examples check out all recipes in the repository on gitlab.

New chains and derived chains

To add a new crypto currency as asset you will need a Client side module for deterministic cryptography and a Node side module or recipe to handle information requests. For derived chains you may be able to reuse either or both of the client and node side modules.

The Client side module will handle address and key generation and transaction signing. See Client. for more information.

The Node side module defines API endpoints in hybrixd that enables users and wallets to interact with other blockchains by translating and relaying calls to API endpoints from RPC's and block explorers for the given crypto currency. Please see below for instructions.

The following files are associated with the modules:

modules/deterministic/$ASSET/deterministic.js.lmza

The compiled Client side module.

recipes/asset.$ASSET.json

The definition of the asset details and Node side module.

Setup local dev environment

To build client side modules you will need to setup your local hybrix development environment. Including the deterministic modules. See Setup local dev environment.

Grocery List

You will need the following information:

Asset Details

Symbol

The symbol associated with the asset (Bitcoin has btc much like the US dollar has usd)

Factor

The factor determines the nr of digits after the dot. (The precision of the currency)

Fee

The transaction fee that is required as overhead payment for a transaction.

Fee-Symbol

The symbol that is used to pay fees. This is usually the same value as Symbol name.

Fee-Factor

The factor of the fee. This is usually the same value as Factor.

Address Regex

The regex to which an address must comply to be valid.

Hosts

The url's of API endpoints. Searching for '$ASSETNAME block explorer api' , '$ASSETNAME rpc'. The goal is to find API's where we can send requests for balances etc.

API endpoints

Endpoints You will need api endpoints for the following. For example https://nodes.wavesplatform.com

balance

The balance a given address. For example /addresses/balance/$ADDRESS

unspents

The unspents (pre-transactional data) for a given address.

push

To submit a signed transaction to the blockchain.

message/attachement

Retrieve the message, attachement or 'op_return' attached to an transaction.

transaction

To retrieve details about a transaction

history

To retrieve history for a given address.

Javascript library

To create a client side module you will need to wrap a library containing the following functions:

seed to keys

A deterministic function to generate a public private key pair from a seed.

keys to address

A function to retrieve the address belonging to a key pair

create and sign transaction

A function to create and sign (but not yet broadcast) a transaction.

For more details on the API endpoints for assets see: help on asset api.

Client - Node separation

The strict seperation between client and node is to ensure that private keys data always remains on the client side.
The node should never touch this data. To facilitate this the node supplies a 'client code blob' : compressed javascript code that can be executed on the client side.
The client does the signing. The ode handles the logistics.

Node side module

The node side module serves as a relay between APIs.

For example: when you query hybrixd for the balance of your waves address: /asset/waves/$ADDRESS this will be routed to the Node side module defined in recipes/asset.waves.json.
The logic there (written in qrtz) will reformat the request to https://nodes.wavesplatform.com/addresses/balance/details/$YOUR_ADDRESS
it will retrieve the result, extract the required information, reformat that and return the standardized end result.

The Node side module is defined using a json recipe containing the asset properties and the logic implemented in qrtz ("Quartz") .

See Node side modules / Recipes

Client side module

A deterministic module is a client side module for hybrixd. It is used to handle client seeds, keys addresses and signing. As we do not want a client to share their keys all these actions should be performed client side. The node should never touch this data. To facilitate this the node supplies a 'client code blob' : compressed javascript code that can be executed on the client side.

See Client side modules (deterministic)

---