Fluence Network

The Fluence Labs Developer Hub

Welcome to the Fluence Labs developer hub. You'll find comprehensive guides and documentation to help you start working with Fluence Labs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Should you have any questions, feel free to join our Discord or Telegram!

Get Started

Built-in services

API provided by every Fluence node

Each node provides a set of "built-in" services that can be called from AIR scripts.

All built-in services are divided into four namespaces:

  1. dht – functions related to Kademlia or DHT
  2. srv – management and information about services on a node
  3. dist – distribution and inspection of modules and blueprints
  4. op – basic operations such as data transformation, network topology manipulation, and node infomation

Below is the reference documentation for all the existing built-in services. Please refer to the JS SDK documentation to learn how to easily use them from the JS SDK.

dht resolve

Used to perform DHT.get, i.e., to read a value for the given key from DHT.

Argument: key – a 160-bit string.
Returns: value – an array of byte arrays, i.e., [[u8]].

Example of service call:

(call node ("dht" "resolve") [key] value)

In this example, we instruct node to call dht.resolve(key) and put the result to value.

dht neighborhood

Used primarily for aliasing services and network exploring.

Instructs the node specified in the service call to query the Kademlia network.

Argument: key – the peer ID (PeerId) of the node.
Returns: peers – an array of PeerIds of the nodes that are in the Kademlia neighborhood for the given hash(key).

Comment: This service involves computations of O(log n) complexity. Use it with care.

Example of service call:

(call node ("dht" "neighborhood") [key] peers)

dht add_provider

Used in service aliasing.

Stores the specified service provider (provider) in the internal storage of the node indicated in the service call and associates it with the given key (key). After executing add_provider, the provider can be accessed via the get_providers service using this key.

Arguments:

  • key – a string; usually, it is a human-readable service alias.
  • provider – the location of the service. It is an object of the following structure:
{
  "peer": "123D...", // PeerId of some peer in the network
  "service_id": "uuid-1234-..." // Optional service_id of the service running on the peer specified by `peer`
}

Example of service call:

(call node ("dht" "add_provider") [key provider])

dht get_providers

Used in service aliasing.

Retrieves providers for the given key.

Argument: key – a string; usually, it is a human-readable service alias.
Returns: an array of objects of the following structure:

{ 
  "peer": "123D...", // required field
  "service_id": "uuid-1234-..." // optional field

Example of service call:

(call node ("dht" "get_providers") [key] providers)

srv create

Used to create a service on a certain node.

Arguments:

  • blueprint_id – ID of the blueprint that has been added to the node specified in the service call by the dist add_blueprint service.
  • owner_id (optional) – a string containing owner_id. If passed, it will be available for the created service in environment variables.
    Returns: service_id – the service ID of the created service.

Comment: To learn how to use this sevice in the JS SDK, refer to its documentation.

Example of service call:

(call node ("srv" "create") [blueprint_id owner_id] service_id)

srv get_interface

Retrieves the functional interface of a service running on the node specified in the service call.

Argument: service_id – ID of the service whose interface you want to retrieve.
Returns : an object of the following structure:

{
  interface: { function_signatures, record_types }
  blueprint_id: "uuid-1234...",
  service_id: "uuid-1234..."
}

Examples of information returned by the service:
The first example considers a simple service that includes the only function. Its signature is shown in the function signature tab. The output of the srv get_interface service is presented in the interface output tab.

func greeting(name: String): String
{
    "blueprint_id": "fa11257a-58e8-4481-bb94-3de50ddc8d8e",
    "interface": {
        "function_signatures": [
            {
                "arguments": [["name","String"]],
                "name": "greeting",
                "output_types": ["String"]
            }
        ],
        "record_types": []
    },
    "service_id": "232a94c1-8a6b-4ac2-8c01-8adda9cab9f3"
}

The second example considers the chat service, containing 3 modules: history, user-list, and SQLite. The service call is displayed in the AIR tab. The output of the srv get_interface service is presented in the JSON tab.

(click to expand)
[
    {
        "blueprint_id": "9422bcc2-b012-480a-9347-56535695d885",
        "interface": {
            "function_signatures": [
                {
                    "arguments": [
                        [
                            "author",
                            "String"
                        ],
                        [
                            "msg",
                            "String"
                        ]
                    ],
                    "name": "add",
                    "output_types": [
                        "String"
                    ]
                },
                {
                    "arguments": [],
                    "name": "get_all",
                    "output_types": [
                        "Array<Message>"
                    ]
                },
                {
                    "arguments": [
                        [
                            "last",
                            "U64"
                        ]
                    ],
                    "name": "get_last",
                    "output_types": [
                        "String"
                    ]
                }
            ],
            "record_types": [
                {
                    "fields": [
                        [
                            "id",
                            "U32"
                        ],
                        [
                            "author",
                            "String"
                        ],
                        [
                            "body",
                            "String"
                        ]
                    ],
                    "id": 6,
                    "name": "Message"
                }
            ]
        },
        "service_id": "470177ad-a916-4469-88e0-f2f41a39d5ef"
    },
    {
        "blueprint_id": "5e21be04-fe21-4df4-84f0-b075d3c14e44",
        "interface": {
            "function_signatures": [
                {
                    "arguments": [
                        [
                            "user",
                            "String"
                        ],
                        [
                            "relay",
                            "String"
                        ],
                        [
                            "signature",
                            "String"
                        ]
                    ],
                    "name": "change_relay",
                    "output_types": [
                        "String"
                    ]
                },
                {
                    "arguments": [
                        [
                            "user",
                            "String"
                        ],
                        [
                            "relay",
                            "String"
                        ],
                        [
                            "signature",
                            "String"
                        ],
                        [
                            "name",
                            "String"
                        ]
                    ],
                    "name": "join",
                    "output_types": [
                        "String"
                    ]
                },
                {
                    "arguments": [],
                    "name": "get_users",
                    "output_types": [
                        "Array<User>"
                    ]
                },
                {
                    "arguments": [
                        [
                            "user",
                            "String"
                        ],
                        [
                            "signature",
                            "String"
                        ]
                    ],
                    "name": "delete",
                    "output_types": [
                        "String"
                    ]
                },
                {
                    "arguments": [
                        [
                            "user",
                            "String"
                        ]
                    ],
                    "name": "is_exists",
                    "output_types": [
                        "I32"
                    ]
                },
                {
                    "arguments": [
                        [
                            "user",
                            "String"
                        ],
                        [
                            "name",
                            "String"
                        ],
                        [
                            "signature",
                            "String"
                        ]
                    ],
                    "name": "change_name",
                    "output_types": [
                        "String"
                    ]
                }
            ],
            "record_types": [
                {
                    "fields": [
                        [
                            "peer_id",
                            "String"
                        ],
                        [
                            "relay_id",
                            "String"
                        ],
                        [
                            "signature",
                            "String"
                        ],
                        [
                            "name",
                            "String"
                        ]
                    ],
                    "id": 6,
                    "name": "User"
                }
            ]
        },
        "service_id": "6f8d7e99-5a4e-4986-b57b-66bd05c748c0"
    }
]
(call node ("srv" "get_interface") [service_id] interface)

srv get_interfaces

Similar to srv get_interface described above, but returns the information about all services running on the node specified in the service call.

Example of service call:

(call node ("srv" "get_interfaces") [] interfaces)

dist add_module

Used to add modules to the node specified in the service call.

Arguments:

  • bytes – a base64 string containing the .wasm module to add.
  • config – an object of the following structure:
{
  "name": "my_module_name"
}

Comment: To learn how to use this service in the JS SDK, refer to its documentation.

Example of service call:

(call node ("dist" "add_module") [bytes config])

dist add_blueprint

Used to add a blueprint to the node specified in the service call.

Argument: blueprint – an object of the following structure:

{
  "name": "good_service",
  "dependencies": [ "module_name_a", "module_name_b", "facade_module" ]
}

Comment: To learn how to use this service in the JS SDK, refer to its documentation.

Example of service call:

(call node ("dist" "add_blueprint") [args] result)

dist get_modules

Used to get the names of the modules available on the node specified in the service call.

Returns: modules – an array of strings, containing the names of the modules.

Example of service call:

(call node ("dist" "get_modules") [] modules)

dist get_blueprints

Used to get the blueprints available on the node specified in the service call. A blueprint is an object of the following structure:

{
  "id": "uuid-1234-...",
  "name": "good_service",
  "dependencies": [ "module_name_a", "module_name_b", "facade_module" ]
}

Returns: blueprints – an array of the blueprint structures.

Example of service call:

(call node ("dist" "get_blueprints") [] blueprints)

op identity

Acts as an identity function. This service returns exactly what was passed to it. Useful for moving the execution of some service topologically or for extracting some data and putting it into an output variable.

Example of service call:

(call node ("op" "identity") [args] result)

op identify

Used to get information about the node specified in the service call.

Returns: info – an object of the following structure:

{
    "external_addresses": [ "/ip4/1.2.3.4/tcp/7777", "/dns4/stage.fluence.dev/tcp/19002" ]
}

Example of service call:

(call node ("op" "identify") [] info)

Updated a day ago

Built-in services


API provided by every Fluence node

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.