Add Your Own Builtins

Some service functionalities have ubiquitous demand making them suitable candidates to be directly deployed to a peer node. The Aqua distributed hash table (DHT) is an example of builtin service. 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 and
script initialization and scheduling
Note that the deployment process is a fully automated workflow requiring you to merely submit your service assets, i.e., Wasm modules and configuration scripts, in the appropriate format as a PR to the Fluence repository.
At this point you should have a solid grasp of creating service modules and their associated configuration files.
Our first step is fork the Fluence 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:
cd fluence
git checkout -b MyBranchName
In our new branch, we create a directory with the service name in the deploy/builtin directory:
cd deploy/builtins 
mkdir my-new-super-service
cd my-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.
Requirements
In order to deploy a builtin service, we need
the Wasm file for each module required for the service
the blueprint file for the service
the optional start and scheduling scripts
Blueprint
Blueprints capture the service name and dependencies:
// example_blueprint.json
{
  "name": "my-new-super-service", 
  "dependencies": [
    "name:my_module_1",
    "name:my_module_2",
    "hash:Hash(my_module_3.wasm)"
  ]
}
Where
name specifies the service's name and
dependencies list the names of the Wasm modules or the Blake3 hash of the Wasm module
In the above example, my_module_i refers to ith module created when you compiled your service code
The easiest way to get the Blake3 hash of our Wasm modules is to install the b3sum utility:
cargo install b3sum
b3sum my_module_3.wasm
If you decide to use the hash approach, please use the hash for the config files names as well (see below).
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 data for on_start.air
{
    "variable1" : "some_string",
    "variable2" : 5,
}
Scheduling Script
Scheduling scripts allow us to decouple service execution from the client and instead can rely on a cron-like scheduler running on a node to trigger our service(s).
Directory Structure
Now that we got our requirements covered, we can populate the directory structure we started to lay out at the beginning of this section. As mentioned above, service deployment as a builtin is an automated workflow one our PR is accepted. Hence, it is imperative to adhere to the directory structure below:
-- 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
        -- Hash(module2_name.wasm).wasm
        -- Hash(module2_name.wasm)_config.json
        ...
For a complete example, please see the aqua-dht builtin:
fluence
    --deploy
        --builtins
            --aqua-dht
                 -aqua-dht.wasm
                 -aqua-dht_config.json
                 -blueprint.json
                 -scheduled
                 -sqlite3.wasm # or 558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e.wasm 
                 -sqlite3_config.json # or 558a483b1c141b66765947cf6a674abe5af2bb5b86244dfca41e5f5eb2a86e9e_config.json
which is based on the eponymous service project.
cUrl As A Service
Research, Papers And References
Last modified 5mo ago
Copy link
On this page
Requirements
Blueprint
Start Script
Scheduling Script
Directory Structure