Lilypad
Lilypad is a distributed compute network for web3 based on Bacalhau. It currently enables the running of Bacalhau jobs from smart contracts.
🍃 What is Lilypad?
Full Documentation
Vision
Lilypad is aiming to build an internet-scale trustless distributed compute network for web3. Creating the infrastructure for use cases like AI inference, ML training, DeSci and more.
Overview
Lilypad (v0) currently enables users to access verifiable, distributed off-chain compute directly from smart contracts. Lilypad is at v0 and is a Proof of Concept project operating as an integration layer between Bacalhau compute jobs and solidity smart contracts. This integration enables users to access verifiable off-chain decentralised compute from DApps and smart contract projects, enabling interactions and innovations between on-chain and off-chain compute. Lilypad v0 does not charge for compute jobs, outside of network running fees (ie. the cost of transactions on the blockchain network it is deployed to). It operates on the Bacalhau public compute network (which is free to use), though it is worth noting that there are no reliability guarantees given for this network (which is something future versions of this protocol will be working to improve\
Lilypad Roadmap
v0: September 2022 - Lilypad Bridge POC for triggering and returning Bacalhau compute jobs from a smart contract
v2: September 2023 - A more robust trustless distributed testnet
v3: tbd - Lilypad Mainnet
Lilypad v0 Reference
Architecture
Overview
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:
FVM Hackerbase Video
Lilypad v0 Quick Start
Prefer Video?
Note: Since this video was released some changes have been made to the underlying code, but the process and general architecture remains the same.
Quick Start Guide
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 successfullylilypadCancelled
- 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 ofLilypadEvents
by passing the public contract address on the network you are using (see deployed network details) to theLilypadEvents
constructor.Call the LilypadEvents contract function
runLilypadJob()
passing in the following parameters.
Name | Type | Purpose |
---|---|---|
|
| The address of the calling contract, to which success or failure will be passed back. You should probably use address(this) from your contract. |
|
| A Bacalhau job spec in JSON format. See below for more information on creating a job spec. |
| 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. |
Implement the LilypadCaller Interface in your contract
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 successfullylilypadCancelled
- a callback function that will be called when the job fails
Add a Spec compatible with Bacalhau
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.
Add the Lilypad Events Address & Network Fee
You can do this by either passing it into your constructor or setting it as a variable
Call the LilypadEvents runLilypadJob function
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.
Lilypad v0 Integrated Networks
Deployed Network Details
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:
Lilypad v0 Deployed Networks
Chain Name | LilypadEvents Contract Address | RPC | ChainID | BlockExplorer | Faucet |
Filecoin Calibration Net (testnet) | 0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820 | 314159 (0x4cb2f) | |||
Filecoin Mainnet | 0xc18879C0a781DdFa0258302467687413AaD5a4E6 | 314 (0x13a) | Requires Filecoin token See docs | ||
Mantle Testnet | 0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820 | 5001 (0x1389) | |||
Sepolia Testnet | 0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820 | 11155111 (0xaa36a7) | |||
Polygon Mumbai | 0xdC7612fa94F098F1d7BB40E0f4F4db8fF0bC8820 | 80001 (0x13881) | |||
Polygon Mainnet (coming soon) | 137 (0x89) | Requires MATIC tokens | |||
Optimism (coming soon) | 10(0xa) | Requires OP tokens | |||
Arbitrum One (coming soon) | 42161 (0xa4b1) | Requires ARB tokens |