show navigation

Node side modules (Recipes)

A recipe file is a json file describing the properties of an asset (also token), a (data) source or an engine implementation.

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.

Recipes are stored in the $HYBRIXD/node/recipes folder. View on gitlab

For a token only a basic recipe is required that will import an existing chain's properties.

Example for an asset foo with properties host and cache and quartz program for balance that does something and returns something:

asset.foo.json
{
  "symbol" :"foo",
  "host" : "http://foo.bar",
  "quartz" : {
    "balance" : ["dosomething", "returnsomething"]
  },
  "router" : {
    "balance" : "Does something and then returns something to the user."
  }
}

A recipe defines either an asset/token or a source. For assets (and tokens) a symbol is required, for sources an id.

To facilitate some common standards there are qrtz engines available for Insight and Electrum rpc's. Import these to use their functionality

Filename

For assets the filename is defined as /recipes/asset.$SYMBOL.json or /recipes/token.$SYMBOL.json

For sources the filename is defined as /recipes/source.$TYPE.$ID.json

For engines the filename is defined as /recipes/engine.$NAME.json

Properties

symbol	(Only required for assets) Discription: A string containing the symbol. This is used as the main idenitfier. Format: `"$BASE[.$TOKEN]"` Examples: `"BTC"`, `"ETH.SHIFT"`
source	(Only required for sources) Discription: Examples: `"abe.bitcoin"`, `"insight.litecoin"`, `"deterministic"`
engine	(Only required for engines) Discription: Examples: `"storage"`
name	Discription: A string containing the display name (for pretty printing). Example: `"Bitcoin"`
mode	Discription: A string containing the deterministic mode. Format: `"$DETERMINISTIC_MODULE.$SUBMODE"` Example: `"bitjoinjslib.bitcoin"`
contract	(Only required for token assets) Description: The unique identifier for an asset token
originator	(Only required for token assets) Description: The creator or origin address for an asset token
import	Discription: A string or array of strings containing the id's / symbols of the recipes from which this recipe should inherit properties. Cf Import section below Example: `"btc"`, `["btc","eth"]` , `"btc::host"`
module	Discription: The name of the server/node side code implementation
module-deterministic	(Only required for assets) Discription: The name of the client side code implementation (TODO TO BE RENAMED!)
factor	(Only required for assets) Discription: The number of decimal digits used for this asset.
fee	(Only required for assets) Discription: A number representing the fee associated with transfering assets
fee-symbol	(Optional for assets) Discription: the symbol in which the fee is calculated
host	A string or array of strings containing the hosts [cache] The ammount of time in miliseconds that data should be cached (Defaults to 12000) [throttle] Defaults to 5 [retry] Defaults to 3 [timeout] Defaults to 15000 [interval] Defaults to 2000 The following properties are used to initialize the connection: (cf https://www.npmjs.com/package/node-rest-client#options-parameters ) [user] [pass] [proxy] [connection] [mimetypes] [requestConfig] [responseConfig]
quartz	Defines the Qrtz code. A function is defined by an array of qrtz statements.
router	Defines the routing definitions. Used to expose functions as API endpoints and to generate documentation.

Asset Endpoints

An asset should provide the following endpoints: TODO TODO mention default.qrtz

Endpoint	Description	Expected output
`/balance/$ADDRESS`
`/transaction/$TRANSACTION_ID`
`/validate/$ADDRESS`
`/sample/$ADDRESS`
`/details/$ADDRESS`
`/fee`
`/factor`
`/unspent/$ADDRESS`

qrtz

Browse to https://api.hybrix.io/help/qrtz for more help on qrtz.

$ Operator $PROPERTY

For qrtz commands the $ is used (inspired by posix) to retrieve variables:

Calling /asset/foo/balance/bar on

asset.foo.json
{
  "id" :"foo",
  "a" : 1,
  "b" : 2,
  "quartz" : {
  "balance" : ["dosomething with $a, $b, $0", "returns $1"]
}
}

Results in

asset.foo.json
{
  "id" :"foo",
  "a" : 1,
  "b" : 2,
  "quartz" : {
    "balance" : ["dosomething with 1, 2, balance", "returns bar"]
  }
}

Cross recipe variables $RECIPE::PROPERTY

The $foo::bar notation can be used to reference variables in other (non imported files)

Given

asset.foo.json
{
  "id" :"foo",
  "a" : 1,
}

then

asset.bar.json
{
  "id" :"bar",
  "a" : -1,
  "quartz" : {
    "balance" : ["dosomething with $a, $foo::a", "returnsomething"]
  }
}

Compiles to:

{
  "id" :"bar",
  "a" : -1,
  "quartz" : {
    "balance" : ["dosomething with -1, 1", "returnsomething"]
  }
}

Import

Inheritance using "import":

Given foo.json

asset.foo.json
{
  "id" :"foo",
  "a" : 1,
  "b" : 2,
}

bar.json can inherit foo.json by using

asset.bar.json
{
"id" :"bar",
"a" : -1,
"c" : 3,
"import" : "foo"
}

which compiles to

asset.bar.json
{
  "id" :"bar",
  "a" : -1,
  "b" : 2,
  "c" : 3,
  "import" : "foo"
}

Note that the value of a is retained, bu b is added.

Multi-inheritance

Multi-inheritance can be defined by using:

asset.bar.json
{
  "id" :"bar",
  "a" : -1,
  "c" : 3,
  "import" : ["foo1","foo2","foo3"]
}

They are imported from left to right (values in foo3 overwrite those of foo1 and foo2)

Token inheritance

A token asset, identified by a two part symbol "$BASE.$TOKEN", for example: "eth.shift" will automatically inherit the qrtz code from its base asset "eth".

Javascript modules

To run your javascript code directly you can use the qrtz func method.

To create a helloworld module create a folder in the modules folder with the following files:

modules/
- helloworld/
- - engine.helloworld.json
  - module.js

With the following content:

modules/helloworld/engine.helloworld.json:
{
    "engine":"helloworld"
    "name":"Hello World",
    "module":"helloworld",
    "router":{
      "example" : "Returns the text 'example'",
      "hello" : "Returns the text 'hello world'"
    },
    "quartz": {
      "example" : [
       "done example"
     ],
      "hello" : [
        "func hello"
      ]
    }
}

The router defines the api endpoints and their corresponding api endpoints. With this module you can now call /engine/helloworld/example and /engine/helloworld/hello and view the automatically generated help page on /help/api/engine/helloworld

The qrtz function example returns 'example' immediatly by using qrtz directly. The function hello will call the hello function in de module.js:

modules/helloworld/module.js:

function hello(proc, data){ // proc, the process handle and the data from the data stream are passed (data is unused in this example

  proc.done('hello world'); // pass 'hello world' as output

  // proc.fail('Oops! Someting gone wrong'); // return a failure
  // proc.peek('myVariable'); // retrieve the content of the variable named myVariable
  // proc.poke('myVariable',123); // set the content of the myVariable variable
}

exports.hello = hello; // export the function so it can be used by qrtz func

Check out the existing modules: View on gitlab