Scilla Server API

Scilla-server API description

Introduction

With performance profiling experiments showing that the launch overhead of scilla-runner is about 25-30ms and given chain calls involve multiple executions of scilla-runner, there is a significant overhead to smart-contract execution in just process launch. To avoid this overhead, a persistent (continuously running) Scilla server process (called scilla-server) that accepts contract execution requests and executes the contract, providing output within the server process itself, is introduced. This ensures that the launch overhead is removed since the server is launched only once when the node boots up.

Server API

The server is a JSON-RPC server, providing two methos run and check. The server will serve only one request at a time and is going to be single threaded.

Both method take a single parameter named argv, which will be a JSON array of strings. This parameter will hold all the arguments to be provided for this Scilla execution. The arguments will be identical to the command line arguments of the scilla-runner executable.

Note: we use a single parameter JSON-RPC method, and not have the scilla-runner arguments directly as part of the method arguments because jsonrpccpp does not support optional arguments (https://github.com/cinemast/libjson-rpc-cpp/issues/32)

Example:

./bin/scilla-runner -init tests/runner/helloWorld/init.json -istate tests/runner/helloWorld/state_1.json -o output_1.json -imessage tests/runner/helloWorld/message_1.json -iblockchain tests/runner/helloWorld/blockchain_1.json -i tests/contracts/helloWorld.scilla -libdir src/stdlib “-gaslimit 800

Can be passed via the “scilla-runner” JSON-RPC method as:

{
  "jsonrpc": "2.0", 
  "method": "run", 
  “id” : 3, 
  "params": 
  {
    "argv” : [“-init”, “tests/runner/helloWorld/init.json”, “-istate”, “tests/runner/helloWorld/state_1.json”, “-o”, “output_1.json”, “-imessage”, “tests/runner/helloWorld/message_1.json”, “-iblockchain”, “tests/runner/helloWorld/blockchain_1.json”, “-i”, “tests/contracts/helloWorld.scilla”, “-libdir”, “src/stdlib”, “-gaslimit”, “800”]
  }
}

Return value:

On success

Conforming to the JSON-RPC standard, the response object's result field will be set. This value will again be a JSON, and will be identical to today’s output JSON emitted by scilla-runner/ scilla-checker. The -jsonerrors argument currently passed to the runner / checker is implicitly assumed.

On failure:

Partially conforming to the JSON-RPC standard(see Sec 5.1: Error object), the response-object's error field will be set. However, the message section of this error will not be "limited to a concise single sentence" as specified by the standard. It can either be a string or a JSON object itself. The client will need to handle both cases. In the case that the message is a JSON object, it will be identical to the error JSON emitted by scilla-checker / scilla-runner.

The case of the error's message section being just a string occurs only when an incorrect -argv (i.e., command line parameters through JSON-RPC) is passed. The error returned will be a command line parsing error and will not be a JSON, same as what the runners output today.

Declaration in C++ code

These JSON-RPC method can be declared in jsonrpccpp as

Procedure
("run", PARAMS_BY_NAME, JSON_OBJECT, “argv", JSON_ARRAY, NULL);
Procedure
("check", PARAMS_BY_NAME, JSON_OBJECT, “argv", JSON_ARRAY, NULL);