Getting started with the client contract

[trruckerfling]

Data + FVM: Getting Started with the Client Contract

👀 Refer to [this document](https://www.notion.so/Data-FVM-234b7f4c17624cd8b972f92806732ca9?pvs=21) to learn more about aggregator-driven approaches to creating storage deals on FVM, RaaS, and dapps and DAOs!

Quickstart: Upload Your First 🐕 Onto Filecoin via FVM

🌌 These instructions operate on the [Hyperspace testnet](https://docs.filecoin.io/networks/hyperspace/details/). You can use the [Filfox explorer](https://hyperspace.filfox.info/en) to view the activity on this testnet.

[Adopted from https://www.tldraw.com/r/v2_c_M7QpjoG42dpa5c2E4N2hG](https://res.craft.do/user/full/1a0bac4f-3e4f-5fb0-1242-ed52acd856c3/doc/135a6e08-8bb4-870e-4715-495775efb1cb/3fdd6e7d-4c8a-4a28-888e-21d0a327d2d2)

Adopted from https://www.tldraw.com/r/v2_c_M7QpjoG42dpa5c2E4N2hG

Step 0: Get a Great 🐕 Pic!

Make sure you get a dog image you love! It may last on Filecoin / FVM for a long time! 😃

Step 1: Upload onto the FVM Data Depot

👉 The data depot is here: [https://data.lighthouse.storage/](https://data.lighthouse.storage/)

Think of the data depot as a dog shelter – a temporary place for the dog to sit on the internet while it finds its new home on the Filecoin network.

In addition to acting as temporary storage, the data depot prepares the image for upload to Filecoin. Concretely, it packages the file using content-addressing magic, so that Storage Providers (SPs) can later prove to the Filecoin network that your image is correctly stored by them.

Once the image is prepared, the data depot will give you a link to the package (a CAR file), as well as some additional metadata. You will supply this link and the metadata to deal client smart contract, from where the Storage Provider (SP) will read it.

⬆️ Go and upload an image now!

After you have uploaded the image, you should have:

(A1) An https URL to the prepared package containing your image (CAR file) (carLink) (eg this)

(A2) The size of your image in bytes (pieceSize)

(A3) The size of the CAR file that represents A in bytes (carSize)

(A4) The piece CID of A (commP)

Step 2a: Deploy your own Deal Client Contract

The deal client contract coordinates the handshaking required on FVM to find and download your dog into the Filecoin network.

You can deploy your own simple CC by running yarn hardhat deploy on the fevm-hardhat-kit.

This will happen at the end, when Deploying DealClient... is reached.

You can get the address of your CC by looking at the output to DealClient deployed to:.

Now that it is deployed, you have a powerful agent you own on the FVM blockchain, ready to do your bidding to upload all kinds of data onto FVM.

Say the address of your CC is 0xf4E0C74D76Bf324293bB3B3DA184d164d06F7664. You will need to update this address on your dapp frontend before step 2b.

Step 2b: Deal Proposal Payload

Run the dapp frontend locally on your browser. Now enter the four outputs from Step 1 (A1-A4) and press submit. Wait until you have a Deal ID with a link to the Filfox block explorer. (Fair warning – you may have to wait a few minutes.)

Step 3: Deal Publication and Activation

Now you can follow along over the next hours as the deal that got published on Filfox gets activated! We will walk through how this happens in more detail later.

However, you now have a provable way to store your data on Filecoin through FVM!

---

Concepts

Data Preparation

One big thing the data depot takes care of above is what we call data preparation. This is converting the file you want to a format that is usable by the Filecoin protocol for making deals. Data preparation is done as follows, if you wanted to do it yourself:

https://res.craft.do/user/full/1a0bac4f-3e4f-5fb0-1242-ed52acd856c3/doc/135a6e08-8bb4-870e-4715-495775efb1cb/e8de392d-7283-4258-85bf-e1aefccd9416

In order to do this yourself, you could potentially use the [generate-car go utility.](https://github.com/tech-greedy/generate-car)

Follow the directions here for more details. These should also generate A1 through A4 just as the data depot would do for your above.

Datacap

Datacap is allocation that a user can have to make verified deals on Filecoin. SPs strongly prefer deals with Datacap (e.g. verified deals) and the vast majority of deals made on Filecoin currently are made with Datacap. Read more ➡️

Filecoin plus

Fortunately – you ARE able to use Datacap to make deals using the client contract! You can do this in one of two ways:

1. For deals <32GB, you can use the Glif notary. This can award f4 addresses datacap automatically. Datacap here can be reallocated every month for every Github account per month.

GLIF Verify

1. For deals >32GB, you can apply here. This can award larger storage deals and projects datacap. There is a manual approval process here.

Filecoin Plus

Note that once you have received datacap, you should set [verifiedDeal here](https://github.com/filecoin-project/fvm-starter-kit-deal-making/blob/main/frontend/src/components/Inputs.js#L91) to be true. The rest of the approach in the Quickstart can be followed as-is.

Miner Actor Handshake (authenticateMessage and dealNotify)

Note that there is some complexity with how the client contract does its handshake with the Boost SP that you can see here:

https://res.craft.do/user/full/1a0bac4f-3e4f-5fb0-1242-ed52acd856c3/doc/135a6e08-8bb4-870e-4715-495775efb1cb/6ec648e6-3d68-4157-8c44-2b6f02653903

Note that Step 5 can only complete once the client gets to authorize that the storage deal is as it originally intended. The functions authenticateMessage and [dealNotify](https://github.com/filecoin-project/fvm-starter-kit-deal-making/blob/main/client-contract/src/DealClient.sol#L253) in the client contract are both callbacks from the market actor into the contract that are a strict prerequisite before PublishStorageDeal message is sent to the network.

The former function holds the the deal proposal from the miner, which needs to be validated by the contract in accordance with the deal request it made and the contract's own policies. The latter function holds the previously approved deal proposal and the dealID.

The successful completion of both callbacks marks the success of PublishStorageDeals and the true completion of Step 5.

Deal Status

Note that the client contract also allows you to review the status of your deal! Based on the commP, the contract allows anybody to look up:

• The Boost SP powering the deal ([pieceProviders](https://github.com/filecoin-project/fvm-starter-kit-deal-making/blob/main/client-contract/src/DealClient.sol#L98))
• The deal ID of the deal ([pieceDeals](https://github.com/filecoin-project/fvm-starter-kit-deal-making/blob/main/client-contract/src/DealClient.sol#L99))
• The status of the deal ([pieceStatus](https://github.com/filecoin-project/fvm-starter-kit-deal-making/blob/main/client-contract/src/DealClient.sol#L100)), which can be any one of:
  • RequestSubmitted
  • DealPublished
  • DealActivated
  • DealTerminated

However, this information cannot be provided to the user async at the moment. It must be polled for in dapps. Check out how the dapp frontend polls for deal status in this manner (see line 11 in particular):

const dealIDHandler = async () => {
    setDealID("Waiting for acceptance by SP...");
    cid = new CID(commP);
    var refresh = setInterval(async () => {
        console.log(cid.bytes);
        if (cid === undefined) {
          setDealID("Error: CID not found");
          clearInterval(refresh);
        }
        console.log("Checking for deal ID...");
        const dealID = await dealClient.pieceDeals(cid.bytes);
        console.log(dealID);
        if (dealID !== undefined && dealID !== "0") {
          // If your deal has already been submitted, you can get the deal ID by going to <https://hyperspace.filfox.info/en/deal/><dealID>
          // The link will show up in the frontend: once a deal has been submitted, its deal ID stays constant. It will always have the same deal ID.
          setDealID("<https://hyperspace.filfox.info/en/deal/>" + dealID);
          clearInterval(refresh);
        }
      }, 5000
    );
  };

We are considering adding in ***async methods*** for the client contract to be notified about changes in deal state in the future. In the meantime, you can if you Stay tuned!

FAQs

What about retrievals?

You may be wondering – how do I get my dog.jpg back from the SP that stored it?

Once the SP has activated the deal, you will be able to retrieve your image using Lassie:

Basic retrieval

Note that not all SPs offer online and immediate retrievals. However, if you’ve made the deal with Datacap, you are likely fine, as most FIL+ SPs offer retrieval as part of their enhanced service.

Vision and Roadmap

We see a bright future with the development of the client contract standard to enable a variety of deal making modalities in the future.

The interface defined in the client contract is a powerful building block. The reference implementation is a simple example, but a lot more is possible. We see it powering DataDAOs, perpetual storage workers, repair and renewal workers, and so much more.

We separate our goals into what we have DONE, what we want to accomplish SOONER, and what we want to accomplish SOON. There is no "later" in FVM-land, since we move fast :)

✅ **DONE**

• Enable client contracts to use Datacap
• Enable paid deals from the client contract
• Enable adding to and removing from the market actor escrow for the client contract
• Track deal state in the client contract (including deal publication, activation, and termination)

☀️ **SOONER**

• Adopt the proposed FRC standard for 1-1 deals, eg deals where you know your SP ahead of time
• Adopt the proposed FRC standard for SP ordering, so that different SPs don't inadvertently frontrun deals offered on FVM.
• More robust error handling & better developer ergonomics (such as datacap extension and deal activation status in dispatch functions)

☁️ **SOON**

• Enable "client of client" contracts, where the end user and the client contract deployer don't need to the be the same user (this is valuable for paid deals)
• Add 1-N deals to the FRC standard
• Enable the development of a new standard for decentralized aggregators of storage deals, so that deals don't have to be made directly with SPs

Resources

Resource	Notes
	Use this repo to deploy your first deal with your client contract
	Hardhat kit repo with several contracts (including a deal-making client contract) you can deploy on FVM
https://www.youtube.com/watch?v=LK9QjOJIPkQ&t=2784s	Matt’s awesome localnet deal making demo as part of IPFS Thing 2023 (April 25 2023)
https://www.notion.so/FVM-Starfleet-Internal-a15a9245fc914b29b4abb285c7b3649f?pvs=21	Our recently proposed deal making FRC to encode all on-chain interactions of the client contract with a deal-making SP.

Note: this proposed design differs in some key ways from the flow described in this document, and encoded in the first two repos referenced in this table. These changes are meant to counter known problems with SP frontrunning, as well as enable 1-1 deal-making between SPs and client contracts that made offchain arrangements around deal proposal. We welcome your comments and review! |
| https://boost.filecoin.io/experimental-features/fvm-contract-deals | This page describes how an SP running Boost can get started accepting deals on FVM. |