Lilypad v0 is a "bridge" for running Bacalhau compute jobs via a smart contracts.
Lilypad is a ‘bridge’ to enable computation jobs from smart contracts. The aim of Lilypad v0 was to create an integration for users to call Bacalhau jobs directly from their solidity smart contracts and hence enable interactions and innovations between on-chain and off-chain compute. Lilypad v0 is a proof of concept bridge which runs off the public (free to use) Bacalhau compute network. As such, the reliability of jobs on this network are not guaranteed.
If you have a need for reliable compute based on this infrastructure - get in touch with us.
A user contract implements the LilypadCaller interface and to call a job, they make a function call to the deployed LilypadEvents contract.
This contract emits an event which the Lilypad bridge daemon listens for and then forwards on to the Bacalhau network for processing.
Once the job is complete, the results are returned back to the originating user contract from the bridge code.
See more about how Bacalhau & Lilypad are related below
Lilypad v0 Quick Start
Deployed Network Details
Lilypad Smart Contracts
Creating your own Jobs
Architecture
Lilypad v0 Integrated Networks
If you have a use case for another network - please get in touch with us!
The Lilypad Events contract - used for triggering compute jobs on Bacalhau, is currently integrated to the following networks on the address specified:
Chain Name
LilypadEvents Contract Address
RPC
ChainID
BlockExplorer
Faucet
Filecoin Calibration Net (testnet)
0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820
314159 (0x4cb2f)
,
Filecoin Mainnet
0xc18879C0a781DdFa0258302467687413AaD5a4E6
, ,
314 (0x13a)
, , ,
Requires Filecoin token
Mantle Testnet
0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820
5001 (0x1389)
Sepolia Testnet
0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820
, , , see
11155111 (0xaa36a7)
, ,
Polygon Mumbai
0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820
see
80001 (0x13881)
,
Polygon Mainnet (coming soon)
see
137 (0x89)
Requires MATIC tokens
Optimism (coming soon)
see
10(0xa)
Requires OP tokens
Arbitrum One (coming soon)
see
42161 (0xa4b1)
Requires ARB tokens
\
Creating Bacalhau Job Spec's
There are several public examples you can try out without needing to know anything about Docker or WASM specification jobs -> see the Bacalhau Docs. The full specification for Bacalhau jobs can be seen here.
You need to supply a Bacalhau job spec. To create a job spec, you can:
Run a Bacalhau job successfully, and then get the job spec back using bacalhau describe <job_id> --format=json
.
Generate a job spec without running anything, using bacalhau docker run --dry-run
.
Writing a job spec by hand, by using our schema as a guide.
What can I do with Bacalhau now? You can:
read from IPFS, Filecoin, or URLs
write into Estuary or IPFS
Bacalhau operates by executing jobs within containers. This means it is able to run any arbitrary Docker jobs or WASM images
Here's an example JSON job specification for a Stable Diffusion job which runs in a Docker container, requires no verification and publishes to Estuary.
Here's an example of using this JSON specification in a solidity smart contract:
Note that since we need to be able to add the user prompt input to the middle of the spec (in the Docker entrypoint), it's been split into 2 parts.
There is a full complement of example jobs you can leverage on the Bacalhau Docs Site
Try out
YOLO
OCR
Video Editing
and many, many more!
The Lilypad v0 Smart Contracts
Create a contract that implements LilypadCallerInterface
. As part of this interface you need to implement 2 functions:
lilypadFulfilled
- a callback function that will be called when the job completes successfully
lilypadCancelled
- a callback function that will be called when the job fails
To trigger a job from your contract, you need to call the LilypadEvents
contract which the bridge is listening to. You will connect to Bacalhau network via this bridge. Create an instance of LilypadEvents
in your own contract by passing the public contract address above to the LilypadEvents
constructor. See Deployed Network Detailsfor address details
To make a call to Bacalhau, call runLilypadJob
from your function. You need to pass the following parameters:
_from
address
The address of the calling contract, to which success or failure will be passed back. You should probably use address(this) from your contract.
_spec
string
A Bacalhau job spec in JSON format. See below for more information on creating a job spec.
_resultType
The type of result that you want to be returned. If you specify CID, the result tree will come back as a retrievable IPFS CID. If you specify StdOut, StdErr or ExitCode, those raw values output from the job will be returned.
This contract is the bridge between the Bacalhau network and smart contracts & does all the heavy lifting.
Note - you cannot deploy your own version of this contract. It will not trigger Bacalhau jobs to run on its own and requires the Lilypad GO Daemon integration. You need to use the address of the deployed LilypadEvents contract within your own smart contract.
To use Lilypad, you only need to take note of one function in this events contract - the runLilypadJob(address _from, string memory _spec, uint8 _resultType)
function which takes the following parameters.\
_from
address
The address of the calling contract, to which success or failure will be passed back. You should probably use address(this) from your contract.
_spec
string
A Bacalhau job spec in JSON format. See docs for more information on creating a job spec.
_resultType
The type of result that you want to be returned - specified in the LilypadCaller Interface. If you specify CID, the result tree will come back as a retrievable IPFS CID. If you specify StdOut, StdErr or ExitCode, those raw values output from the job will be returned.
Open LilypadEvents Contract in Remix -> Click here
This interface ensures that the results of a job run on the Bacalhau network via Lilypad can be returned to the originating contract. This interface needs to be implemented by a smart contract for Lilypad to run.
Open the LilypadCaller Interface in Remix -> Click here
Get Started with Lilypad v0 - Call off-chain distributed compute from your smart contract!
Note: Since this video was released some changes have been made to the underlying code, but the process and general architecture remains the same.
The Lilypad Contracts are not currently importable via npm (though this is in progress), so to import them to you own project, you'll need to use their github links
Using Lilypad in your own solidity smart contract requires the following steps
Create a contract that implements the LilypadCaller interface.
As part of this interface you need to implement 2 functions:
lilypadFulfilled
- a callback function that will be called when the job completes successfully
lilypadCancelled
- a callback function that will be called when the job fails
Provide a public Docker Spec compatible for use on Bacalhau in JSON format to the contract.
To trigger a job from your contract, you need to call the LilypadEvents
contract which the Lilypad bridge is listening to and which connects to the Bacalhau public network. Create an instance of LilypadEvents
by passing the public contract address on the network you are using (see Deployed Network Details) to the LilypadEvents
constructor.
Call the LilypadEvents contract function runLilypadJob()
passing in the following parameters.
_from
address
The address of the calling contract, to which success or failure will be passed back. You should probably use address(this) from your contract.
_spec
string
A Bacalhau job spec in JSON format. See below for more information on creating a job spec.
_resultType
The type of result that you want to be returned. If you specify CID, the result tree will come back as a retrievable IPFS CID. If you specify StdOut, StdErr or ExitCode, those raw values output from the job will be returned.
Create a contract that implements LilypadCallerInterface
. As part of this interface you need to implement 2 functions:
lilypadFulfilled
- a callback function that will be called when the job completes successfully
lilypadCancelled
- a callback function that will be called when the job fails
There are several public examples you can try out without needing to know anything about Docker or WASM specification jobs -> see the Bacalhau Docs. The full specification for Bacalhau jobs can be seen here.
Bacalhau operates by executing jobs within containers. This means it is able to run any arbitrary Docker jobs or WASM images
We'll use the public Stable Diffusion Docker Container located here for this example.
Here's an example JSON job specification for the Stable Diffusion job:
Here's an example of using this JSON specification in solidity:
Note that since we need to be able to add the user prompt input to the spec, it's been split into 2 parts.
See more about how to onboard your Docker Workloads for Bacalhau, Onboard WebAssembly Workloads or Work with Custom Containers in the Bacalhau Docs.
You can do this by either passing it into your constructor or setting it as a variable
Using the LilypadEvents Instance, we can now send jobs to the Bacalhau Network via our contract using the runLilypadJob()
function.
In this example we'll use the Stable Diffusion Spec shown above in #add-a-spec-compatible-with-bacalhau
Note that calling the runLilypadJob() function requires a network fee. While the Bacalhau public Network is currently free to use, gas fees are still needed to return the results of the job performed. This is the payable fee in the contract.