Add Your Own Builtins

As discussed in the Node section, some service functionalities useful to a large audience and such services and can be directly deployed to a peer node. The remainder of this tutorial guides you through the steps necessary to create and deploy a Builtin service.

In order to have a service available out-of-the-box with the necessary startup and scheduling scripts, we can take advantage of the Fluence deployer feature for Node native Services. This feature handles the complete deployment process including

module uploads,
service deployment,
script initialization and scheduling

Note that the deployment process is a fully automated workflow requiring you to merely submit your service assets in the appropriate structure as a PR to the appropriate GitHub repository. At this point you should have a solid grasp of creating service modules and their associated configuration files. See the Developing Modules And Services section for details.

Our first step is fork the ??? repo by clicking on the Fork button, upper right of the repo webpage, and follow the instructions to create a local copy. In your local repo copy, checkout a new branch with a new, unique branch name:

git checkout -b MyBranchName

In your new branch create a new directory with the service name in the builtin directory:

cd builtins 
mkdir my-new-super-service
cd new-super-service

Replace my-new-super-service with your service name.

Now we can build and populate the required directory structure with your service assets. You should put your service files in the corresponding my-new-super-service directory specified in config as builtins_base_dir

TODO: check if that applies to new repo approach.

Requirements

In order to deploy a builtin service, you need

the Wasm files for each module comprising the service
a blueprint file specifying service dependencies
service start or schedule scripts

Blueprints

Just to recap, blueprints specify the service name and module dependencies:

// blueprint.json
{
  "name": "my-new-super-service",
  "dependencies": [
    "name: module_1",
    "name: module_2"
  ]
}

where module_i is the name of the Wasm module. Note that dependencies can be specified as string literals or hashes:

// blueprint.json
{
  "name": "aqua-dht",
  "dependencies": [
    "hash:558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e",
    "name:aqua-dht"
  ]
}

So modules and configs names should look like this:

-- aqua-dht.wasm
-- aqua-dht_config.json
-- 558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e.wasm
-- 558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e_config.json

Start Script

Start scripts, which are optional, execute once after service deployment or node restarts and are submitted as air files and may be accompanied by a json file containing the necessary parameters.

;; on_start.air
(seq
    (call relay ("some_service_alias" "some_func1") [variable1] result)
    (call relay ("some_service_alias" "some_func2") [variable2 result])
)

and the associated data file:

// on_start.json
{
    "variable1" : "some_string",
    "variable2" : 5,
}

Scheduling Script

Directory Structure

-- builtins
    -- {service_alias}
        -- scheduled
            -- {script_name}_{interval_in_seconds}.air [optional]
        -- blueprint.json
        -- on_start.air [optional]
        -- on_start.json [optional]
        -- {module1_name}.wasm
        -- {module1_name}_config.json
        -- {module2_name}.wasm
        -- {module2_name}_config.json
        ...

3.8 KiB Raw Blame History

Add Your Own Builtins

Requirements

Directory Structure

3.8 KiB

Raw Blame History