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:
dht– functions related to Kademlia or DHTsrv– management and information about services on a nodedist– distribution and inspection of modules and blueprintsop– 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