# 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)