Carol is a serverless computing service that runs user uploaded programs. At the moment the programs run on only one machine but in the end goal is to have the programs be run between federations of carol nodes. The purpose of Carol is not to "outsource" computing to the cloud like in traditional compute providers. A user asks Carol to run their program so that others can have confidence that the program will be run faithfully.
First, make sure you've got the WASM target installed:
rustup target add wasm32-unknown-unknown
carlo
(optional)cargo install --path crates/carol
Otherwise you have to run cargo run -p carlo
form the project directory instead of running carlo
:
There are example guest machine definitions in example-guests
. Let's copy one
of them and run it on a temporary machine:
cd .. # move above project directory
cp -r carol/example-guests/bitmex_oracle my_machine
cd my_machine
carlo run
if you're using cargo
from the project directory, use: cargo run -p carlo -- run -p ../my_machine
from the project directory.
You should see a few urls in the output for the machine. Try visiting the machine's HTTP url to see it's HTML landing page.
After developing a machine we want to deploy we can run it on a public carol server:
carlo create --carol-url https://carol.computer
This will output a url to the machine you just created.
First clone the repository and then cd
into it and run:
cargo install --path crates/carol
carol --help
..or it can be run from the project directory:
cargo run -p carol -- --help
Then generate a config file.
carol --cfg carol.yml config-gen
This will generate a default configuration (along with some secret keys!) and put them in carol.yml
.
carol --cfg carol.yml run &
To compile a standalone WASM binary. Here we just compile one of the examples in example-guests
(must be run in project directory).
wasm_output_file=$( carlo build -p bitmex_oracle )
Then upload it to carol:
carol_url=http://localhost:8000
binary_id=$( carlo -q upload --carol-url "${carol_url}" --binary "${wasm_output_file}" )
Note this id
is just a hash of the binary. In general it's intended for client software to
generate it locally and check it against what's returned rather than just blindly trusted the carol
server.
Carol machines are created from a binary and a parameterization array. Most machines will have an empty parameterization for now so we make an empty POST request to t
machine_id=$( carlo -q create --carol-url "${carol_url}" --binary-id "${binary_id}" )
Note this id
is a hash of the binary and the (empty) parameterization vector. In general it's
intended for client software to generate it locally and check it against what's returned rather than
just blindly trusted the carol server.
The machine we've created has a few ways of activating it as defined the code we compiled to the binary. At the time of writing it's:
attest_to_price_at_minute
bit_decompose_attest_to_price_at_minute
We can actual inspect the binary for its activation methods with:
carlo api -p bitmex_oracle
(this just displays the names of them for now)
Let's send a HTTP request to the machine which will activate the attest_to_price_at_minute
which will fetch the price of the symbol we ask for at the time we ask for.
curl -vG "${carol_url}/machines/${machine_id}/http/attest_to_price_at_minute" \
-d time=2023-04-16T12:30:00Z \
-d symbol=.BXBT
which at the time of writing returns:
{
"Ok": {
"price": 30264,
"signature": "8d737860c57c0463ab532127359c0a7fbc9fa1bf56b120ad3b724637fb3a3c08d621ce5afe20de25889d14c7e23a0a4a19961cc08596f2c82fd84b9b00fa24b5fc4e67226300d855f6e51176d7ef73525e37d7baad6dae701271a0ede593000d"
}
}
The first milestone is to have carol functioning as a programmable BLS-based DLC oracle for the protocol described in Cryptographic Oracle-Based Conditional Payments. To do this it doesn't need state and it doesn't need to communicate with other carol nodes.
At some point we want to allow programs to store state that they can access when they are re-activated as well as generate secret keys for secp256k1
, bls12_381
Finally, we want programs to be able to store state on multiple carol nodes working as a federation. Secret keys would be Shamir secret shared across these nodes as well.