SecondState has developed a high performance WebAssembly(Wasm) Virtual Machine called SSVM.
\nThis product, called Wasm-Joey allows you to:
\nBelow is an explanation of the list of features, followed by actual endpoint documentation.
\nFirstly, callbacks!
\n--header SSVM_Callback: {hostname ... port ... etc.}{\n \"SSVM_Callback\": {\n \"hostname\": \"dev.rpc.ssvm.secondstate.io\",\n \"path\": \"/api/run/1/say\",\n \"method\": \"POST\",\n \"port\": 8081,\n \"headers\": {\n \"Content-Type\": \"text/plain\",\n \"SSVM_Usage_Key\": \"83f02dd3-6440-482f-983f-78127ed6f943\"\n }\n },\n \"Function_Parameters\": [1, 2, 3, 4]\n}\nThis allows the caller to deal with large files without having to upload/download them. The GET and POST activities take place on the server side. The client stays light.
\ncurl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \\\n--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"SSVM_Fetch\": {\n \"body\": \"body\",\n \"hostname\": \"rpc.ssvm.secondstate.io\",\n \"path\": \"/api/run/1/say\",\n \"method\": \"POST\",\n \"port\": 8081,\n \"headers\": {\n \"Content-Type\": \"text/plain\",\n \"SSVM_Usage_Key\": \"83f02dd3-6440-482f-983f-78127ed6f943\"\n }\n },\n \"function_params\": [1, 2]\n}'\nReturns
\nhello hello \"body\"\ncurl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \\\n--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \\\n--header 'SSVM_Fetch: {\"body\": \"header\",\"hostname\": \"rpc.ssvm.secondstate.io\",\"path\": \"/api/run/1/say\",\"method\": \"POST\",\"port\": 8081,\"headers\": {\"Content-Type\": \"text/plain\",\"SSVM_Usage_Key\": \"83f02dd3-6440-482f-983f-78127ed6f943\"}}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"SSVM_Fetch\": {\n \"body\": \"body\",\n \"hostname\": \"rpc.ssvm.secondstate.io\",\n \"path\": \"/api/run/1/say\",\n \"method\": \"POST\",\n \"port\": 8081,\n \"headers\": {\n \"Content-Type\": \"text/plain\",\n \"SSVM_Usage_Key\": \"83f02dd3-6440-482f-983f-78127ed6f943\"\n }\n },\n \"function_params\": [1, 2]\n}'\nReturns
\nhello hello \"header\"\ncurl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \\\n--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"SSVM_Fetch\": \"https://raw.githubusercontent.com/tpmccallum/test_endpoint2/master/tim.txt\",\n \"function_params\": [1, 2]\n}'\nReturns
\nhello Tim\ncurl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/run/1/say' \\\n--header 'SSVM_Usage_Key: 83f02dd3-6440-482f-983f-78127ed6f943' \\\n--header 'SSVM_Fetch: https://raw.githubusercontent.com/tpmccallum/test_endpoint2/master/tim2.txt' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"SSVM_Fetch\": \"https://raw.githubusercontent.com/tpmccallum/test_endpoint2/master/tim.txt\"\n}'\nReturns
\nhello Tim2\nIf a Wasm executable is for private use, the caller can make Joey generate a couple of keys (at the time when the Wasm executable is uploaded). For example, if the following header (SSVM_Create_Usage_Key) key is set to true in the request, the keys will be generated.
curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/executables' \\\n--header 'Content-Type: application/octet-stream' \\\n--header 'SSVM_Description: Private Wasm File' \\\n--header 'SSVM_Create_Usage_Key: true' \\\n--data-binary '@/Users/tpmccallum/hello_bg.wasm'\nThe above code will return the following response
\n{\n \"wasm_id\": 16,\n \"wasm_sha256\": \"0xfb413547a8aba56d0349603a7989e269f3846245e51804932b3e02bc0be4b665\",\n \"usage_key\": \"a038c28b-0e47-42e3-8686-be4c4d7f729b\",\n \"admin_key\": \"87d6edf0-52de-48fa-a4b2-0d035e5dc70a\"\n}\nNote the usage_key and admin_key.
On the contrary, Wasm executables that are set into the system with no mention of SSVM_Create_Usage_Key are set to public by default. For example, the following request returns the generic zeroed out usage key.
curl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/executables' \\\n--header 'Content-Type: application/octet-stream' \\\n--header 'SSVM_Description: Private Wasm File' \\\n--data-binary '@/Users/tpmccallum/hello_bg.wasm'\n{\n \"wasm_id\": 17,\n \"wasm_sha256\": \"0xfb413547a8aba56d0349603a7989e269f3846245e51804932b3e02bc0be4b665\",\n \"usage_key\": \"00000000-0000-0000-0000-000000000000\",\n \"admin_key\": \"8741ec91-79d4-4718-bce9-d073438ea582\"\n}\nTo make a public Wasm executable private, simply perform the following RESTful (PUT) request
curl --location --request PUT 'https://rpc.ssvm.secondstate.io:8081/api/keys/17/usage_key' \\\n--header 'SSVM_Admin_Key: 8741ec91-79d4-4718-bce9-d073438ea582'\nThe above request will return a fresh key as shown below.
\n{\n \"SSVM_Usage_Key\": \"c031f2c8-dada-4eff-9a92-8bd63011c7c1\"\n}\nThis PUT request is also a great way to refresh keys i.e. change who can access a Wasm executable, after a hackathon or temporary training exercise etc.
To make a private Wasm executable public, simply perform the following RESTful DELETE request
curl --location --request DELETE 'https://rpc.ssvm.secondstate.io:8081/api/keys/17/usage_key' \\\n--header 'SSVM_Admin_Key: 8741ec91-79d4-4718-bce9-d073438ea582'\ncurl --location --request POST 'https://rpc.ssvm.secondstate.io:8081/api/ephemeral_storage' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\"some_json\": \"data_to_store_temporarily\"}'\nReturns
\n{\"key\":\"e09da790-b072-46e9-9e6c-c879d07376fd\"}\ncurl --location --request GET 'https://rpc.ssvm.secondstate.io:8081/api/ephemeral_storage/e09da790-b072-46e9-9e6c-c879d07376fd'\nReturns
\n{\"value\":{\"some_json\":\"data_to_store_temporarily\"}}\ncurl --location --request PUT 'https://rpc.ssvm.secondstate.io:8081/api/ephemeral_storage/e09da790-b072-46e9-9e6c-c879d07376fd' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\"asdf\": \"Update the data\"}'\ncurl --location --request DELETE 'https://rpc.ssvm.secondstate.io:8081/api/ephemeral_storage/e09da790-b072-46e9-9e6c-c879d07376fd'\nNow, as promised, let's look at the individual endpoints.
\nPath structure
\n/api/executables/:wasm_id\nGet a single wasm executable (all fields returned by default)
\n{\"wasm_id\":1,\"wasm_description\":\"Description goes here\",\"wasm_as_buffer\":{\"type\":\"Buffer\",\"data\":[49,49,44,53,44,49,44,52,44,53,44,49,44,49,49,50,44,49,44,49,54,44,49,54,44,53]}}\nPath structure (if using filters)
\n/api/executables/:wasm_id?filterBy=[\"wasm_id\"]\n/api/executables/:wasm_id?filterBy=[\"wasm_description\"]\n/api/executables/:wasm_id?filterBy=[\"wasm_as_buffer\"]\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"wasm_id\"]
\n{\"wasm_id\":1}\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"wasm_sha256\"]
\n{\"wasm_sha256\":\"0x880633dce728eddd3d441f297f43226fd21b9bbac080d70a29407507ca6e004b\"}\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"wasm_description\"]
\n{\"wasm_description\":\"Description goes here\"}\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"wasm_as_buffer\"]
\n{\"wasm_as_buffer\":{\"type\":\"Buffer\",\"data\":[49,49,44,53,44,49,44,52,44,53,44,49,44,49,49,50,44,49,44,49,54,44,49,54,44,53]}}\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"wasm_state\"]
\n{\"wasm_state\":\"state is x\"}\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"wasm_callback_object\"]
\n{\"wasm_callback_object\":{\"returns valid callback object\"}}\nPlease note:\nThese (admin only) performance statistics are deliberately implemented on dev.rpc.ssvm.secondstate... only. Please contact us if you would like a demo.
\nAdmin only features, require the SSVM_Admin_Key. For example, the following \"total_gas_consumed\", \"total_invocations\", \"full_usage_report\" and \"latest_execution_time_in_nanoseconds\" filters will require the \"SSVM_Admin_Key\" in the request header like this.
\nvar settings = {\n \"url\": \"https://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\\\"full_usage_report\\\"]\",\n \"method\": \"GET\",\n \"timeout\": 0,\n \"headers\": {\n \"SSVM_Admin_Key\": \"0000-xxxx-0000-xxxx-0000-xxxx\"\n },\n};\n\n$.ajax(settings).done(function (response) {\n console.log(response);\n});\nThis filter allows you to obtain the time it took to complete the most recent call.\nThe measurement is in nanoseconds, so be sure to convert to suit your needs.\nHere is a complete example, from the dev server.
\nvar myHeaders = new Headers();\nmyHeaders.append(\"SSVM_Admin_Key\", \"0000-xxxx-0000-xxxx-0000-xxxx\");\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\nfetch(\"https://dev.rpc.ssvm.secondstate.io:8081/api/executables/251?filterBy=[\\\"latest_execution_time_in_nanoseconds\\\"]\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));\nThe result
\n{\"latest_execution_time_in_nanoseconds\":\"1742587\"}\nThe SSVM_Admin_Key has been changed, please contact secondstate.io if you would like a demo of how to measure performance statistics.
\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"total_gas_consumed\"]
\n{\"total_gas_consumed\":\"200\"}\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"total_invocations\"]
\n{\"total_invocations\":\"4\"}\nhttps://rpc.ssvm.secondstate.io:8081/api/executables/1?filterBy=[\"full_usage_report\"]
\n{\n \"full_usage_report\": {\n \"1606690637\": 50,\n \"1606690639\": 50\n }\n}\nThe full_usage_report lists each invocation in the format of timestamp: gas. The sum of all gas values i.e. 100 is equivalent to total_gas_consumed and the length of the keys (timestamps) are equivalent to the total_invocations i.e.
my_report = {\n \"full_usage_report\": {\n \"1606690637\": 50,\n \"1606690639\": 50\n }\n}\nObject.keys(my_report.full_usage_report).length;\n// Returns 2\nPath structure
\n/api/executables\nGet all wasm executables (provides wasm_id for each)
\n[{\"wasm_id\":1}, {\"wasm_id\":2}, {\"wasm_id\":3}, {\"wasm_id\":4}]\nPath structure
\n/api/executables\nSet a wasm binary file. You simply have to perform this POST request and add your .wasm executable as the payload, as shown in the example ->
\n{\"wasm_id\":1,\"wasm_sha256\":\"0xfb413547a8aba56d0349603a7989e269f3846245e51804932b3e02bc0be4b665\",\"usage_key\":\"83f02dd3-6440-482f-983f-78127ed6f943\",\"admin_key\":\"00ac9d9b-f611-43fe-bd54-4adc960fd2b8\"}\nPath structure
\n/api/update_wasm_binary/:wasm_id\nHotswap Wasm binary (at specific wasm_id) with a different Wasm binary
\n{\"wasm_id\":1,\"wasm_sha256\":\"0xfb413547a8aba56d0349603a7989e269f3846245e51804932b3e02bc0be4b665\",\"usage_key\":\"83f02dd3-6440-482f-983f-78127ed6f943\",\"admin_key\":\"00ac9d9b-f611-43fe-bd54-4adc960fd2b8\"}\n\nPath structure
\n/api/state/:wasm_id\nUpdate the state object for the wasm executable with wasm_id of 1
The wasm_id of the executable which was just updated
\n{\"wasm_id\":\"1\"}\nDelete a Wasm executable (and all related metadata) where wasm_id equals 19
{\"wasm_id\":\"19\"}\nExecute a function that resides in your Wasm executable.
\nDepending on the particular Rust/Wasm function, the caller will be required to provide the valid JSON in the format that the Rust/Wasm can consume it.
\nPlease note:\nThe Rust/Wasm code could explicitly declare a Struct on which serde_json could use as the data type, when parsing. However, a struct is flat. What this means, is that if you are going to parse and traverse nested data, then Rust will require that you build and maintain multiple complex data structures (which mirror the JSON data). You may want to do this, which is great. However, in some cases this may be too hard to write and maintain and so here is a proposal for an easier solution.
\nInstead of writing complex nested Structs you could use serde_json's generic Value type as demonstrated in the following code. This approach allows for maximum flexiblility. For example if the Rust/Wasm application looks like this
\nuse serde_json;\nuse serde_json::{Value};\n\n#[no_mangle]\nfn process(s: &str){\n let json_as_object: Value = serde_json::from_str(s).unwrap();\n println!(\"{:?}\", json_as_object[\"function_params\"]);\n println!(\"{:?}\", json_as_object[\"function_params\"][\"param_one\"]);\n println!(\"{:?}\", json_as_object[\"function_params\"][\"param_two\"]);\n}\nThen the calling request would create a valid JSON object like the one below, in order to satisfy the Rust/Wasm's parsing of this data
\n{\n \"function_params\": {\n \"param_one\": 1,\n \"param_two\": \"two\"\n }\n}\nThe caller can also issue a callback object which will ensure that once the original request is performed, the second callback request will also be performed. Here is an example of a callback object.
\nIn a case where the user wanted to utilise a callback the original body of the request would be as follows (note that we are using not only the function_params but also the callback object which sits at the top level.)
Please note the callback must be explicitly named SSVM_Callback, as shown below.
{\n \"SSVM_Callback\": {\n \"hostname\": \"gorest.co.in\",\n \"path\": \"/public-api/users\",\n \"method\": \"POST\",\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"Authorization\": \"Bearer 4dWCe0YCGG4IBIbKh1eRoNUdq3Qzv0xxxx\"\n }\n },\n \"function_params\": {\n \"param_one\": 4,\n \"param_two\": 4\n }\n}\nThe api/log endpoint is able to provide details about past execution of wasm functions. The system captures many facets i.e. wasm_executable's state, callback objects in play, timestamp etc. every time an execution takes place. A caller can use this log to diagnose callbacks that did not complete and more. For efficiency sake, Joey allows the caller to filter logs based on any combination of the following parameters.
https://rpc.ssvm.secondstate.io:8081/api/log/1?filterBy=[%22log_id%22]
\n{\"log_id\":1}\nhttps://rpc.ssvm.secondstate.io:8081/api/log/1?filterBy=[%22wasm_executable_id%22]
\n{\"wasm_executable_id\":1}\nhttps://rpc.ssvm.secondstate.io:8081/api/log/1?filterBy=[%22wasm_executable_state%22]
\n{\"wasm_executable_state\":\"asdf\"}\nhttps://rpc.ssvm.secondstate.io:8081/api/log/1?filterBy=[%22execution_timestamp%22]
\n{\"execution_timestamp\":\"2020-06-01T06:33:40.000Z\"}\nhttps://rpc.ssvm.secondstate.io:8081/api/log/1?filterBy=[%22execution_object%22]
\nexecution_object: \"{\"callback_data_payload\": {\"function\": {\"name\": \"new template name\"}}, \"callback_request_options\": {\"path\": \"/api/run/2/my_other_function\", \"port\": 8081, \"method\": \"GET\", \"headers\": {\"Content-Type\": \"application/json\"}, \"hostname\": \"rpc.ssvm.secondstate.io\", \"maxRedirects\": 20}, \"original_wasm_executables_id\": \"1\"}\"\nEvery key must end in an underscore followed by a number i.e. input_1\nThe order of the keys i.e. _1, _2, _3 relates to the order that my_function is expecting the function arguments
Every key must not start with the reserved word fetch unless the caller is specifically wanting Joey to fetch the value from a remote location (upfront) and then pass that fetched value into my_function as an argument. See fetch_input_4 example below
Every key must not start with the reserved word SSVM_Callback unless the caller is specifically wanting Joey to execute a callback at the very end of processing. See SSVM_Callback_6 example below
This shows how a caller can just pass in a simple string as an argument. Joey will just pass this across to my_function verbatim.
This example shows how to pass in JSON string. Data like this will just be passed straight into my_function verbatim. The Rust / Wasm and caller will have already agreed on how to interpret this data.
{\"left_temperature\": 35,\"right_temperature\": 38}}\nAs mentioned above, if a key starts with the reserved word fetch, then the key must be one of two formats
1 - A URL that will return remote data all on its own i.e. a URL which will return raw data or a URL pointing to a remote server's GET request endpoint. Here is an example of a URL that will return remote data all on its own i.e. a URL which will return raw data or a URL pointing to a remote server's GET request endpoint
\nhttps://postman-echo.com/get?foo1=bar1\n2 - A JSON string object which adheres to the fetch_input_4 example below. This JSON data structure is modelled off the native Node.js https.request library which accepts this JSON data as options. See below ...
The caller can create a JSON string object like the one below and pass this in as the value of fetch_input_4. Joey will execute the request as a top priority and then pass the result of this request into the my_function function at wasm_id 1 as, in this case, the 4th function parameter.
{\n \"method\": \"POST\",\n \"hostname\": \"postman-echo.com\",\n \"port\": 80,\n \"path\": \"/post\",\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"data\": {\n \"hand\": \"wave\"\n }\n}\nData from callers file system that will be passed to the function as a Buffer
\nThis object will be executed (after all other processing has taken place, but) right before Joey sends the result back to the original caller.
\nThe callback object must conform to the following structure i.e hostname, path, port, method etc.
\n{\n \"hostname\": \"rpc.ssvm.secondstate.io\",\n \"path\": \"/api/run/46/convert_celsius_to_fahrenheit\",\n \"method\": \"POST\",\n \"port\": 8081,\n \"headers\": {\n \"Content-Type\": \"application/json\"\n }\n}\nStore ephemeral data in Joey (TTL is 1 hour only)
\nReturns unique key like this
\n{\"key\":\"d3e8b5b6-397b-48db-b594-013f1ca5790c\"}\nGet storage at ephemeral location\nReturns the data
\n{\"value\":{\"some_json\":\"data_to_store_temporarily\"}}\nUpdate the data at a specific key location.
\nThis action resets the TTL to 1 hour
\n{\"key\":\"d3e8b5b6-397b-48db-b594-013f1ca5790c\"}\nDelete the data at a specific key
\n{\"key\":\"d3e8b5b6-397b-48db-b594-013f1ca5790c\"}\nUpdate the callback object of a Wasm executable
\nThe default for the callback object is {} i.e. a blank object is created when a new Wasm executable is added to the system.
Using the DELETE verb, when actioning the /api/keys/:wasm_id/usage_keys endpoint, will set the SSVM_Usage_Key to a zeroed out value (publicly available)
\n","urlObject":{"protocol":"https","port":"8081","path":["api","keys","16","usage_key"],"host":["rpc","ssvm","secondstate","io"],"query":[],"variable":[]}},"response":[],"_postman_id":"ae99a59f-5087-49a6-ab79-225dc6683688"},{"name":"https://rpc.ssvm.secondstate.io:8081/api/keys/17/usage_key","id":"0b03fb98-5b80-4758-9d88-5dfff28868da","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"SSVM_Admin_Key","value":"8741ec91-79d4-4718-bce9-d073438ea582","type":"text"}],"url":"https://rpc.ssvm.secondstate.io:8081/api/keys/17/usage_key","description":"Using the PUT verb, when actioning the /api/keys/:wasm_id/usage_key endpoint will generate a new SSVM_Usage_Key which will supersede all previous SSVM_Usage_Key values for that Wasm executable.\nAs with the DELETE verb, to this endpoint, you must pass the SSVM_Admin_Key into the request headers as shown here.
\n","urlObject":{"protocol":"https","port":"8081","path":["api","keys","17","usage_key"],"host":["rpc","ssvm","secondstate","io"],"query":[],"variable":[]}},"response":[],"_postman_id":"0b03fb98-5b80-4758-9d88-5dfff28868da"},{"name":"https://rpc.ssvm.secondstate.io:8081/api/executables/1","id":"0022997f-9ee5-49c9-8af6-eee68c7c061c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://rpc.ssvm.secondstate.io:8081/api/executables/4?filterBy=[\"wasm_as_buffer\"]","urlObject":{"protocol":"https","port":"8081","path":["api","executables","4"],"host":["rpc","ssvm","secondstate","io"],"query":[{"key":"filterBy","value":"[\"wasm_as_buffer\"]"}],"variable":[]}},"response":[],"_postman_id":"0022997f-9ee5-49c9-8af6-eee68c7c061c"}]}