Skip to content

Commit ed335d8

Browse files
committed
Bad first draft for deal renewal 101doc
1 parent 81dd19c commit ed335d8

File tree

2 files changed

+189
-1
lines changed

2 files changed

+189
-1
lines changed

storage-providers/basics/quickstart-guide.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,4 +40,4 @@ Within the Filecoin network there are many [programs and tools](../filecoin-deal
4040

4141
## <img src="../../.gitbook/assets/storage-provider-basics-quickstart-guide-icon.png" alt="" data-size="line"> All about deal renewals
4242

43-
Placeholder text here and link to a dedicated page on this topic.
43+
As a storage provider, you play a passive role in renewing expiring deals. Although it is common for clients to initiate the renewal, it is important to know how the process work to maintain great user experience and even assist clients in the process. Start your [Deal Renewal 101](../filecoin-deals/deal-renewal-101.md) journey here.
Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
description: >-
3+
This page discusses the basic 101-level knowledge of deal renewal for storage providers (and clients).
4+
---
5+
6+
# Deal Renewal 101
7+
8+
Renewing Filecoin storage deals involves a set of steps to ensure that your data remains stored on the Filecoin network as your original storage deal approaches its expiration. Here is an outline of how that process might look like.
9+
10+
We will demonstrate most of the commands with [Lotus](../../nodes/full-nodes/basic-setup.md#basic-setup), but hopefully you can follow along using other alternatives.
11+
12+
## 1. Monitor Deal Expirations
13+
14+
- **Track deal expiration**: Use a tool like Lotus or Filfox (Filecoin Explorer) to monitor the expiration dates of your existing storage deals.
15+
- **Set up alerts**: It’s a good practice to set up notifications or alerts so you are aware when deals are nearing expiration.
16+
17+
Here are basic ways you can track and monitor deals:
18+
19+
### 1.1 Check Deal Expiration Using Lotus CLI
20+
21+
Use the Lotus CLI to query information about your active storage deals:
22+
23+
```bash
24+
lotus client list-deals
25+
```
26+
27+
This will show a list of deals with information like the deal ID, deal state, expiration height, and more.
28+
29+
### 1.2 Create a Script to Check Expiring Deals
30+
31+
You can create a bash or Python script to automatically check for deals nearing expiration and trigger an alert when a deal is about to expire. For example, the script can compare the current block height with the expiration height of the deals.
32+
33+
#### Bash Script Example
34+
35+
```bash
36+
#!/bin/bash
37+
38+
# Get current block height
39+
current_block_height=$(lotus chain head | grep Height | awk '{print $2}')
40+
41+
# List deals and extract expiration information
42+
lotus client list-deals | while read -r deal
43+
do
44+
expiration=$(echo $deal | awk '{print $5}') # Assuming expiration is in the 5th column
45+
if [ $((expiration - current_block_height)) -lt 1000 ]; then # Check if the expiration is within 1000 blocks
46+
echo "Deal with ID $deal is expiring soon!"
47+
# Add custom alert code here, like sending an email or message to your team.
48+
fi
49+
done
50+
```
51+
52+
### 1.3 Set Up a Cron Job
53+
54+
You can automate the script to run periodically using cron (Linux/Mac).
55+
56+
#### Example cron job (runs every 6 hours)
57+
58+
```bash
59+
0 */6 * * * /path/to/your/script.sh
60+
```
61+
62+
This will check for deals expiring within a certain block height window and send a notification.
63+
64+
## 2. Prepare for Renewal
65+
66+
- **Ensure sufficient funds**: Make sure you have enough FIL (Filecoin tokens) in your wallet to renew your storage deal, as renewing will require paying storage miners.
67+
- **Data retrieval (optional)**: If you need to modify or update your stored data, [retrieve it](../../builder-cookbook/data-storage/retrieve-data.md) from the Filecoin network before renewing the deal.
68+
69+
### 3. Choose New Deal Parameters
70+
71+
- **Duration of the new deal**: Decide on the duration for which you want the data to be stored in the renewal period. Filecoin storage deals have a fixed term, so choose how long the new deal will last. Check out the [minimum duration](../../basics/project-and-community/filecoin-faqs.md#whats-the-minimum-time-period-for-the-storage-contract-between-the-provider-and-the-buyer) for a storage deal. Note that durations are in epoches, which are about 30 seconds.
72+
- **Storage providers**: You may renew the deal with the same storage provider or choose a new one depending on pricing and reliability. If you provide top-notched service to assist clients in renewal, chances are they will stay on.
73+
- **Deal pricing**: Storage prices fluctuate based on market conditions and miner offerings. Check the current storage pricing before renewing the deal to ensure you’re getting a competitive rate.
74+
75+
### 4. Submit a New Storage Deal
76+
77+
- **Using Lotus**: To renew, you essentially submit a new storage deal with the same or updated data to the network.
78+
- **Lotus CLI**: If using Lotus, you can use the following command to renew the deal:
79+
80+
```shell
81+
lotus client renew [dealID] [duration]
82+
```
83+
84+
### 5. Verify Deal Renewal
85+
86+
- **Check deal status**: Once the deal is confirmed, you can verify the new deal via the Filecoin explorer (like Filfox or Glif) or through your Lotus client.
87+
- **Ensure data redundancy (Optional)**: It’s recommended to store data with multiple providers to ensure redundancy in case one becomes unavailable.
88+
89+
### 6. Automate Renewals (Optional)
90+
91+
- **Set up automatic renewal**: If you have many deals or want to streamline the process, you can automate the renewal of storage deals by using the following methods:
92+
93+
#### Renew with custom scripts
94+
95+
Write a script in your favorite language to call Lotus API to trigger renewals before the expiration date.
96+
97+
Here is a simple bash script example:
98+
99+
```bash
100+
#!/bin/bash
101+
102+
# Get current block height
103+
current_block_height=$(lotus chain head | grep Height | awk '{print $2}')
104+
105+
duration=18000
106+
107+
# List deals and extract expiration information
108+
lotus client list-deals | while read -r deal
109+
do
110+
expiration=$(echo $deal | awk '{print $5}') # Assuming expiration is in the 5th column
111+
if [ $((expiration - current_block_height)) -lt 1000 ]; then # Check if the expiration is within 1000 blocks
112+
echo "Deal with ID $deal is expiring soon!"
113+
# Automatically call `lotus renew` command
114+
lotus client renew $deal $duration
115+
fi
116+
done
117+
```
118+
119+
Or in Python:
120+
121+
```python
122+
#!/usr/bin/env python3
123+
124+
import subprocess
125+
126+
# Set the duration
127+
duration = 18000
128+
129+
# Function to get the current block height
130+
def get_current_block_height():
131+
result = subprocess.run(["lotus", "chain", "head"], capture_output=True, text=True)
132+
for line in result.stdout.splitlines():
133+
if "Height" in line:
134+
return int(line.split()[1])
135+
return None
136+
137+
# Function to list deals and extract deal information
138+
def list_deals():
139+
result = subprocess.run(["lotus", "client", "list-deals"], capture_output=True, text=True)
140+
return result.stdout.splitlines()
141+
142+
# Function to renew a deal
143+
def renew_deal(deal_id, duration):
144+
subprocess.run(["lotus", "client", "renew", deal_id, str(duration)])
145+
146+
# Main script
147+
def main():
148+
# Get the current block height
149+
current_block_height = get_current_block_height()
150+
151+
if current_block_height is None:
152+
print("Error: Unable to get current block height")
153+
return
154+
155+
# List all deals
156+
deals = list_deals()
157+
158+
# Process each deal
159+
for deal in deals:
160+
deal_info = deal.split()
161+
162+
# Assuming deal_id is in the 1st column and expiration is in the 5th column (0-indexed)
163+
deal_id = deal_info[0]
164+
expiration = int(deal_info[4])
165+
166+
# Check if the expiration is within 1000 blocks
167+
if (expiration - current_block_height) < 1000:
168+
print(f"Deal with ID {deal_id} is expiring soon!")
169+
# Automatically renew the deal
170+
renew_deal(deal_id, duration)
171+
172+
# Run the script
173+
if __name__ == "__main__":
174+
main()
175+
176+
```
177+
178+
#### Renew with smart contracts
179+
180+
To learn how to create a smart contract on Filecoin to automate renewals, head over to a new adventure in [Data replication, renewal, and repair (RaaS)](../../smart-contracts/programmatic-storage/raas.md).
181+
182+
### Key Considerations
183+
184+
- **On-chain costs**: Every storage deal incurs transaction costs on the Filecoin network, so keep track of current gas fees.
185+
- **Data availability**: Ensure that your data remains available during the renewal process by renewing well before the expiration of the current deal.
186+
- **Data retrieval vs renewal**: Depending on your needs, you may choose to retrieve the data from the miner, modify it, and submit it as a new deal or simply renew the deal as-is.
187+
188+
By following these steps, you can ensure that your clients' data stays available on the Filecoin network by renewing the storage deals on time.

0 commit comments

Comments
 (0)