Smart Contract as a Client - Part I

This article will show you how to deploy FEVM-compatible smart contracts as deal clients on the Filecoin network. We will deploy the contract to Hyperspace, a developer-oriented test network. Hold on, you are wondering what is even this FEVM? We will start with some basics!

The Filecoin virtual machine (FVM) is a runtime environment for user-deployed smart contracts, known as actors, on the Filecoin network. You can find more details and its roadmap at https://fvm.filecoin.io. In March, developers can deploy EVM compatible smart contracts on FEVM, and later on any language that compiles to WASM on FVM.

Another question you might have is how does the Filecoin Virtual Machine come into play in today's Filecoin storage market?

The Filecoin Virtual Machine unlocks boundless possibilities, ranging from programmable storage primitives (such as storage bounties, auctions, and more) to data-centric Decentralized Autonomous Organizations (DAOs).

The Lotus team has been working on prototyping smart contracts that can enable storage marketplace primitives, codenamed PeSto. With this project, we want to enable developers to more easily understand the deal-making flow in the Filecoin network, and provide a solid deal client smart contract example that includes perpetual storage capabilities which can be deployed or further developed. The project is still a WIP and there are currently a lot of intermediate steps! You can follow along the journey in this Github repo or the workshop at our Youtube channel! That being said, let´s take a look at how a bare minimum client contract works today by inspecting the deal client contract flow and the flow on the storage provider side.

The Client contract is located in this repo, please go through the README before moving forward...

Now that you know what a client contract is, lets jump right into it by deploying the DealClient contract to the HyperSpace network before we go into the flow of the contract.

You can import the DealClient.sol contract to Remix with this Github-link:

We need to comment out the first import line in DealClient.sol to be able to compile the contract:

Before we can deploy the contract to the Hyperspace network, we need to set up our Metamask wallet to interact with the Hyperspace network. Go to chainlist.wtf, search for the Filecoin Hyperspace, click Connect Wallet, and add the Hyperspace testnet to Metamask.

Once you have your MetaMask set up you can request funds for your wallet address with the Hyperspace faucet. It might take a couple of minutes before testFIL lands in your wallet. Now we are ready to deploy the contract:

Once the message has been included in a block (it can take a couple of minutes) you should see a log of it in your Remix console.

Open the transaction information by clicking on the debug button, copy the transaction hash and paste it into a Hyperspace chain explorer to inspect the contract. Your contract is now live on the Filecoin Hyperspace network ✅.

The CAR format

So what is this CAR thing? CAR stands for Content Addressable aRchives, and it is a format for bundling InterPlanetary Linked Data, IPLD, blocks into a large bundle. On the Filecoin network the majority of data is stored as large IPLD blocks.

You can read more about the CAR format here.

Sectors A sector is the default unit of storage that storage providers submit to the Filecoin network. On the mainnet storage providers can decide if they want to commit 32 GiB or 64 GiB sector sizes when they first initialize their storage provider on-chain. On the Hyperspace test network 512MiB sectors are also supported. A sector can contain data from multiple deals and clients.

PieceCID also known as commP (piece commitment)

The piece content identifier (CID) also known as commP (piece commitment), is the merkle root of the CAR file. We need to store this data in the deal information because it tells us where to find the deal data in a sector, which can be composed of several deals.

Great! Now that we understand those concepts, lets start by generating a .CAR testfile using the car - The CLI tool. You can install the latests version with:

With this tool we can create a CAR test file with the commands:

We now have a CAR-file which we can inspect and get information about:

We can now compute the pieceCID/commP for the testfile using this lotus command:

Before we continue it is also useful to know what the padded piece size of the commP, as we will need to input the padded size into the addCID in the contract. For this we can either use a tool like stream-commp, or manually round it to the next power of 2.

Great, now we have the commP for this testfile. As we can see in our Remix Deployed Contracts dashboard we will have to turn this value into raw bytes:

We can turn the commP into raw bytes using the lotus-shed tool.

Now we are finally ready to add this CID to our contract. Take the output from the ./lotus-shed cid cborSer baga… output, append 0x00 in front of it and paste into cidraw. The size should be the padded size that we found in the step where we generated the CAR file and inspected it:

Great! We have now deployed the contract and added a CID to the contract. We can use the lotus evm stat command to get more information about our contract:

Storage providers have a new command for interacting asynchronously with a client contract: lotus-miner storage-deals async-contract-deal

The command takes in a number arguments commPcommPSize, clientAddr, startEpoch, duration and carFile. When the storage provider executes the command it will start the asynchronous deal making process with the client contract. For the contract example and data in this guide the values would be: commP - baga6ea4seaqnyo6tkwpdme66jelyvyeucbb3a2njnhag5zzyls33otg7ll6bsni

commPSize (unpadded) - 508

clientAddr (ID address of the contract) - t06001

startEpoch (block height) - 47200 - this must be set higher then the current block height, and should also take into account the sealing time as the sector must be sealed before the startEpoch.

duration (in epochs) - 576000 This process includes verification where the contract will authenticate making a deal for the given CID, it will create and publish a PublishStorageDeal (PSD) message which will show the deal details on-chain and it will create or add the data to a sector and seal it. Yes it’s just as easy as your other deal onboarding flow, see the whole flow in the video below if you wanna know more(starting 4’15’’)!

If you wanna try it out, join Hyperspace testnet and run your miner with this branch.

You might have noticed that this article skipped an essential step - How does the the storage provider get the data in the first place?

Going forward we will look at multiple possibilities, but one idea that we are currently exploring is enriching the client contract with more deal information and emitting events on actions like addCID. This would allow an consumer of these event (either an SP or a third party) to subscribe the events and trigger deal creation accordingly.

We are also going to show how you can make client contracts as a verified client so that it can enjoy the cheap storage provided by Filecoin storage providers.

Slack: #fil-lotus-announcements #fil-lotus-dev at filecoin.io/slack

GitHub: https://github.com/orgs/lotus-web3/

Twitter: https://twitter.com/lotus_web3 (follow us!)

Youtube: @lotus_web3 (Subscribe!)