You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Client Contract allows developers to create storage deals programmatically
4
-
via smart contracts.
3
+
This page covers the client contract, and includes a tutorial on how developers can use the client contract to create storage deals programmatically.
5
4
---
6
5
7
6
# Client contract tutorial
8
7
9
-
In this tutorial, we will cover the background of creating storage deals via smart contracts and how to create storage deals with smart contracts on the FEVM (Ethereum Virtual Machine on top of the Filecoin blockchain). Before continuing, you will need the following software preinstalled on your computer:
8
+
In this tutorial we will cover the background of creating storage deals using smart contracts, and how to create storage deals with smart contracts on the [Filecoin virtual machine](../../reference/general/glossary.md#filecoin-virtual-machine).
9
+
10
+
You can find a video form of this walkthrough on [ETHGlobal’s YouTube Channel](https://www.youtube.com/watch?v=27EV3gQGY9k).
11
+
12
+
## Prerequisites
13
+
14
+
Before continuing, make sure you have the following software installed and prerequisities ready:
10
15
11
16
* Git
12
17
* NodeJS
13
18
* Yarn or NPM (Yarn is used in this tutorial)
14
19
* A code editor such as VS Code
15
20
* A wallet with Calibration testnet FIL
16
21
17
-
You can find a video form of this walkthrough on [ETHGlobal’s YouTube Channel](https://www.youtube.com/watch?v=27EV3gQGY9k).
Before we get started, we recommend reading about programmatic storage with Filecoin here. There are two methods to programmtic storage, which are direct dealmaking and aggregated dealmaking. We will cover direct dealmaking with the client contract tutorial.
22
-
23
-
### Steps <ahref="#steps"id="steps"></a>
22
+
## Steps
24
23
25
-
Let’s now run through how to create storage deals via smart contracts.
24
+
Let’s run through how to create storage deals using smart contracts.
26
25
27
-
####Setup <ahref="#setup"id="setup"></a>
26
+
### Setup
28
27
29
28
First, let’s grab the kit and set up the development environment.
30
29
31
-
1. Clone the Filecoin virtual machine deal-making kit, including all submodules:\
30
+
1. Clone the Filecoin virtual machine deal-making kit, including all submodules:
This will copy the fvm deal-making kit into your current directory and initiate the `go-generate-car` submodule.
40
-
2. Moving into the `fvm-starter-kit-deal-making` directory and grab all the dependencies using `yarn`:\
36
+
This will copy the FVM deal-making kit into your current directory and initiate the `go-generate-car` submodule.
41
37
38
+
2. Move into the `fvm-starter-kit-deal-making` directory and grab all the dependencies using `yarn`:
42
39
43
-
```
40
+
```shell
44
41
cd fvm-starter-kit-deal-making
45
42
yarn
46
43
```
47
44
45
+
3. Now that all the packages are downloaded, you need to create a `.env` file with your private key. This is so the Hardhat kit knows what wallet to use fortransactions. Open up the repoin your code editor of choice and find the file titled `.env.example`. Rename the file to `.env`. You can do this in your terminal by running:
48
46
49
-
3. Now that all the packages are downloaded, we will need to create a `.env` file with your private key. This is so the hardhat kit knows what wallet to use for transactions. Open up the repo in your code editor of choice and find the file titled `.env.example`. Rename the file to `.env`:\
50
-
51
-
52
-
```
47
+
```shell
53
48
mv .env.example .env
54
49
```
55
50
51
+
4. Within the `.env` file, replace the example private key with your actual private key. If you are using Metamask, follow [this tutorial to get your private key](https://support.metamask.io/hc/en-us/articles/360015289632-How-to-export-an-account-s-private-key).
56
52
57
-
4. Replace the example private key with your actual private key. If you are using Metamask, follow [this tutorial to get your private key](https://support.metamask.io/hc/en-us/articles/360015289632-How-to-export-an-account-s-private-key).\
58
-
53
+
{% hint style="info" %}
54
+
Take precautions and never share your private key with anyone! Also make sure to not check your private key into Git. The `.gitignore` of the Hardhat kit is already set to ignore `.env` files.
55
+
{% endhint %}
59
56
60
-
Remember to take precautions to never share your private key with anyone or check it into Git! The `.gitignore` of the hardhat kit is already set to ignore `.env` files.\
57
+
5. Deploy the contracts with `hardhat`:
61
58
62
-
5. Deploy the contracts with `hardhat`:\
63
-
64
-
65
-
```
59
+
```shell
66
60
yarn hardhat deploy
67
61
```
68
62
69
-
\
70
-
This should compile and deploy all the contracts, including the client contract, which is the one we will be interacting with. Copy and take note of the address of the deployed contract for later.
63
+
This should compile and deploy all the contracts, including the client contract, which is the one we will be interacting with. Take note of the address of the deployed contract; we'll be using this later.
71
64
72
-
### Preparing a file for storage <a href="#preparing-a-file-for-storage" id="preparing-a-file-for-storage"></a>
65
+
### Preparing a file for storage
73
66
74
-
Before storing a file with a storage provider, it needs to be prepared by turning it into a `.car` file, and the metadata must be recorded. To do this the Hardhat kit has a tool [which can do this for you](https://github.com/filecoin-project/fevm-hardhat-kit/tree/main/tools). However, to keep things nice and simple, we’re going to use the [FVM Data Depot website](https://data.lighthouse.storage/). This website will automatically convert files to the `.car` format, output all the necessary metadata, and act as an HTTP retrieval point for the storage providers.
67
+
Before storing a file with a storage provider it needs to be prepared by turning it into a `.car` file. The metadata also needs to be recorded. The Hardhat kit has a tool [which can do this for you](https://github.com/filecoin-project/fevm-hardhat-kit/tree/main/tools). However, to keep things nice and simple, we’re going to use the [FVM Data Depot website](https://data.lighthouse.storage/). This website will automatically convert files to the `.car` format, output all the necessary metadata, and act as an HTTP retrieval point for the storage providers.
75
68
76
69
1. Go to the [FVM Data Depot website](https://data.lighthouse.storage/) and create an account.
77
70
2. Click **Upload File** and select a file you wish to upload.
@@ -85,12 +78,12 @@ Before storing a file with a storage provider, it needs to be prepared by turnin
85
78
86
79
We’ll use this information in the next step when invoking the `MakeDealProposal` method.
87
80
88
-
### Invoke the MakeDealProposal method <a href="#invoke-the-makedealproposal-method" id="invoke-the-makedealproposal-method"></a>
81
+
### Invoke the `MakeDealProposal` method
89
82
90
83
Now that we have the `.car` file prepared in the data depot, we can invoke the MakeDealProposal method on the smart contract we deployed earlier. To do this, we will run the `make-deal-proposal` task in Hardhat. There are quite a few parameters to include in this call:
91
84
92
-
* `contract`: the address of your deployed `ClientContract.sol`
93
-
* \`piece-cid: gathered from the previous step.
85
+
* `contract`: the address of your deployed `ClientContract.sol`.
86
+
* `piece-cid: gathered from the previous step.
94
87
* `piece-size`: gathered from the previous step.
95
88
* `car-size`: gathered from the previous step.
96
89
* `start-epoch`: The block number you want the deal to begin on. It should be a block in the future. You can find the current block number on [FilFox Calibration](https://calibration.filfox.info/en).
@@ -99,7 +92,7 @@ Now that we have the `.car` file prepared in the data depot, we can invoke the M
99
92
100
93
When calling the `make-deal-proposal` task in Hardhat, your command will look something like this:
Parameters such as the `collateral` and `price-per-epoch` are set to `0`. On mainnet, these would be determined by storage providers, but since this is on the Calibration testnet, the storage providers should pick up the jobs even with these parameters set to `0`.
122
115
123
-
### Storage provider picks up the job <a href="#storage-provider-picks-up-the-job" id="storage-provider-picks-up-the-job"></a>
116
+
### Storage provider picks up the job
124
117
125
-
Now if you’ve invoked the task with all the correct parameters, the method will execute on-chain and emit an event that Boost storage providers will be listening to. If the deal is well-formed and the parameters are acceptable, they will download the .car file, double-check to ensure the `piece-cid` and `piece-size` match the deal and publish your storage deal! This could take up to a day. Once the deal is published, you can find it on a Calibration testnet block explorer. The client in the deal should be the `t4` address of the smart contract we called `MakeStorageDeal` on.
118
+
Now if you’ve invoked the task with all the correct parameters, the method will execute on-chain and emit an event that Boost storage providers will be listening for. If the deal is well-formed and the parameters are acceptable, they will download the `.car` file, double-check to ensure the `piece-cid` and `piece-size` match the deal, and publish your storage deal! This could take up to a day. Once the deal is published, you'll be able to find it on a Calibration testnet [block explorer](../../networks/calibration/explorers.md). The client in the deal should be the `t4` address of the smart contract we called `MakeStorageDeal` on.
After emitting an event and waiting for storage providers to accept your deal, you can monitor its status on a provided Boost logs dashboard. This feature is only available on the Calibration testnet. [See this guide on GitHub](https://github.com/filecoin-project/community/discussions/659) forhelp diagnosing why deals might not be accepted and adjusting your proposal for re-submission.
During this tutorial, we have shown the significance of making deals using smart contracts and then walked through making a storage deal using the FVM deal-making kit and web3.storage. Developers can make use of this workflow to integrate decentralized storage on Filecoin with their smart contracts and decentralized applications.
2. Use Yarn to install the project’s dependencies:
41
41
42
-
```
42
+
```shell
43
43
yarn install
44
44
45
45
# [1/4] 🔍 Resolving packages...
@@ -51,19 +51,19 @@ yarn install
51
51
# ✨ Done in 16.34s.
52
52
```
53
53
54
-
3.Create an environment variable for your private key. Each wallet has a different process for exporting your private key - check your wallet’s official documentation.
4. Always be careful when dealing with your private key. Double-check that you’re not hardcoding it anywhere or committing it to source control like GitHub. Anyone with access to your private key has complete control over your funds.
64
-
5. Get the addresses associated with the private key from Hardhat:
60
+
{% hint style="info" %}
61
+
Always be careful when dealing with your private key. Double-check that you’re not hardcoding it anywhere or committing it to Git. Remember: anyone with access to your private key has complete control over your funds.
62
+
{% endhint %}
63
+
64
+
4. Get the addresses associated with the private key from Hardhat:
65
65
66
-
```sh
66
+
```shell
67
67
yarn hardhat get-address
68
68
69
69
# Ethereum address (this addresss should work for most tools): 0x11Fc070e5c0D32024c9B63c136913405e07C8c48
@@ -84,7 +84,7 @@ Make sure that your account has funds. You won’t be able to deploy any contrac
84
84
85
85
1. Run `hardhat deploy` to deploy all the contracts. This can take a few minutes:
86
86
87
-
```sh
87
+
```shell
88
88
yarn hardhat deploy
89
89
90
90
# Compiled 18 Solidity files successfully
@@ -98,7 +98,7 @@ yarn hardhat deploy
98
98
99
99
2. Interact with the contracts using the available functions within the `tasks` folder. For example, you can get the balance of the `simple-coin` contract by calling the `get-balance` function:
0 commit comments