appd REST API
Each containerized app running in ROFL runs a special daemon (called
rofl-appd) that exposes additional functions via a simple HTTP REST API. In
order to make it easier to isolate access, the API is exposed via a UNIX socket
located at /run/rofl-appd.sock which can be passed to containers via volumes.
An example using the short syntax for Compose volumes:
services:
mycontainer:
# ... other details omitted ...
volumes:
- /run/rofl-appd.sock:/run/rofl-appd.sock
The following sections describe the available endpoints.
Although the communication with rofl-appd is through UNIX sockets, the REST
service still uses the HTTP protocol. In place of a host name you can provide
any name. In our examples, we stick to the http://localhost/<endpoint_path>
format.
App Identifier
This endpoint can be used to retrieve the app ID.
Endpoint: /rofl/v1/app/id (GET)
Example response:
rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf
Key Generation
Each registered app automatically gets access to a decentralized on-chain key management system.
All generated keys can only be generated inside properly attested app instances and will remain the same even in case the app is deployed somewhere else or its state is erased.
Endpoint: /rofl/v1/keys/generate (POST)
Example request:
{
"key_id": "demo key",
"kind": "secp256k1"
}
Request fields:
-
key_idis used for domain separation of different keys (e.g. a different key id will generate a completely different key). -
kinddefines what kind of key should be generated. The following values are currently supported:raw-256to generate 256 bits of entropy.raw-386to generate 384 bits of entropy.ed25519to generate an Ed25519 private key.secp256k1to generate a Secp256k1 private key.
Example response:
{
"key": "a54027bff15a8726b6d9f65383bff20db51c6f3ac5497143a8412a7f16dfdda9"
}
The generated key is returned as a hexadecimal string.
Authenticated Transaction Submission
An app running in ROFL can also submit authenticated transactions to the chain where it is registered at. The special feature of these transactions is that they are signed by an endorsed ephemeral key and are therefore automatically authenticated as coming from the app itself.
This makes it possible to easily authenticate the transaction origin in smart contracts by simply invoking an appropriate subcall:
Subcall.roflEnsureAuthorizedOrigin(roflAppID);
Endpoint: /rofl/v1/tx/sign-submit (POST)
Example request:
{
"tx": {
"kind": "eth",
"data": {
"gas_limit": 200000,
"to": "1234845aaB7b6CD88c7fAd9E9E1cf07638805b20",
"value": 0,
"data": "dae1ee1f00000000000000000000000000000000000000000000000000002695a9e649b2"
}
}
}
Request fields:
-
txdescribes the transaction content with different transaction kinds being supported (as defined by thekindfield):-
Ethereum-compatible calls (
eth) use standard fields (gas_limit,to,valueanddata) to define the transaction content. -
Oasis SDK calls (
std) support CBOR-serialized hex-encodedTransactions to be specified.
-
-
encryptis a boolean flag specifying whether the transaction should be encrypted. By default this istrue. Note that encryption is handled transparently for the caller using an ephemeral key and any response is first decrypted before being passed on.
Example response:
Inside data the JSON response contains a CBOR-serialized hex-encoded
call result. To investigate it you will need to deserialize it first.
For example:
-
Successful call result:
{
"data": "a1626f6b40"
}deserialized as
{"ok": ''}. -
Unsusccessful call result:
{
"data": "a1646661696ca364636f646508666d6f64756c656365766d676d6573736167657272657665727465643a20614a416f4c773d3d"
}deserialized as
{"fail": {"code": 8, "module": "evm", "message": "reverted: aJAoLw=="}}.