Skip to content

Latest commit

 

History

History
242 lines (213 loc) · 13.7 KB

README.md

File metadata and controls

242 lines (213 loc) · 13.7 KB
Raw

extend

中文

Filecoin Sector Extension Service

Build

Deployment

Running Tests

make test

Building

make  # or make docker

Running

Before running, ensure you set the FULLNODE_API_INFO environment variable with the necessary permissions:

export FULLNODE_API_INFO="lotus api info"  # Requires 'sign' permission

To start the service:

./extend run   

OPTIONS:
   --listen value    specify the address to listen on (default: "127.0.0.1:8000")
   --db value        specify the database URL to use， support sqlite3, mysql, postgres, https://github.com/xo/dburl?tab=readme-ov-file#example-urls (default: "sqlite3:extend.db")
   --secret value    specify the secret to use for API authentication, if not set, no auth will be enabled
   --max-wait value  [Warning] specify the maximum time to wait for messages on chain, otherwise try to replace them, only use this if you know what you are doing (default: 0s)
   --debug           enable debug logging (default: false)
   --help, -h        show help

Get help

./extend -h

Docker

Run the service using Docker:

docker run -d --name extend \
  -p 8000:8000 \
  -e FULLNODE_API_INFO="lotus api info" \
  -v /path/to/extend:/app \
  ghcr.io/strahe/extend:latest run --listen 0.0.0.0:8000 --db /app/extend.db

Enable authentication (optional)

Enable authentication by starting the service with the --secret option:

./extend run --secret yoursecret

Generating Tokens

Generate a token for API access:

./extend auth create-token --secret yoursecret --user {name} [--expiry optional_expiry_time]

# Example output
Token created successfully:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJsZWUiLJuYmYiOjE3MTU1zExMzgsImlhdCI6MTcxNTU3MTEzOH0.2FinpGB7D07dLNWPAW3jqo703i13nZU8ZCY__wKnQ

Use the token in your requests:

Authorization: Bearer  <token>

Warning

Changing --secret yoursecret will invalidate all previously generated tokens.

Usage

Creating Renewal Requests

Create a renewal request by sending a POST request to /requests:

POST /requests

Request parameters

Parameter Value Required Description
miner f01234 Yes Miner ID
from 2024-05-12T07:34:47+00:00 Yes Start time of the sector expiration range in RFC3339 format
to 2024-05-13T07:34:47+00:00 Yes End time of the sector expiration range in RFC3339 format
extension 20160 No Number of epochs to extend
new_expiration 3212223 No New expiration epoch, overrides extension
tolerance 20160, 7 days, default value No Renewal tolerance for aggregation
max_sectors 500, default value No Maximum sectors per message, up to 25000
max_initial_pledges 0, default value No Maximum cumulative pledge value allowed for sectors to be extended. If the cumulative pledge exceeds this value, the remaining sectors will not be extended. Default is no limit.
dry_run false, default No If true, performs a test run without actual renewal

Request example

{  
    "miner": "f01234", 
    "from": "2024-05-12T07:34:47+00:00", 
    "to": "2024-05-13T07:34:47+00:00", 
    "extension": 20160, 
    "new_expiration": 3212223, 
    "tolerance": 20160, 
    "max_sectors": 500,
    "dry_run": false
}

Response parameters

Parameter Value Description
id 11 Request ID
extension 21000 Extension height specified during creation
from "2024-05-12T07:34:47Z" Start time of the sector expiration range
to "2024-05-13T07:34:47Z" End time of the sector expiration range
new_expiration null New expiration time specified during creation
max_sectors 500 Maximum number of sectors per message
max_initial_pledges 0 Maximum cumulative pledge value allowed for sectors to be extended. If the cumulative pledge exceeds this value, the remaining sectors will not be extended. Default is no limit.
messages null Renewal messages on-chain, array
tolerance 20160 Renewal tolerance specified during creation
miner "t017387" Miner
status "failed" Status: created, pending, failed, partfailed,success
took 526.841994321 Execution time in seconds
confirmed_at null Confirmation time of the message on-chain
dry_run true Indicates if it is a test run
dry_run_result "" Test run result
error "failed to get active sector set: RPCConnectionError" Error message
total_sectors 1000 Number of sectors to be renewed
published_sectors 500 Number of sectors actually published on-chain
succeeded_sectors 0 Number of sectors successfully renewed
created_at "2024-05-11T13:39:40.74831759+08:00" Creation time
updated_at "2024-05-11T13:40:16.237069667+08:00" Update time

Response Example

{  
  "data": { 
    "confirmed_at": null, 
    "created_at": "2024-05-11T13:39:40.74831759+08:00", 
    "dry_run": true, 
    "dry_run_result": "", 
    "error": "failed to get active sector set: RPCConnectionError", 
    "extension": 21000, 
    "tolerance": 20160,
    "max_sectors": 500,
    "max_initial_pledges": 0,
    "from": "2024-05-12T07:34:47Z", 
    "id": 11, 
    "messages": null, 
    "miner": "t017387", 
    "new_expiration": null, 
    "status": "created", 
    "to": "2024-05-13T07:34:47Z", 
    "total_sectors": 0,
    "published_sectors": 0,
    "succeeded_sectors": 0,
    "took": 526.841994321, 
    "updated_at": "2024-05-11T13:40:16.237069667+08:00"
  }
}

Querying Renewal Requests

Query a renewal request by its ID:

GET /requests/{:id}

The response structure is the same as the creation response.

Response Example
{
  "data": {
    "confirmed_at": null,
    "created_at": "2024-05-13T16:44:58.208723388+08:00",
    "dry_run": false,
    "dry_run_result": "",
    "error": "",
    "extension": 21000,
    "from": "2024-05-13T15:18:47+08:00",
    "id": 19,
    "messages": [
      "bafy2bzacecvqxeqlk4z2gugbtbhgjmptdfjpt73jemf2zwtbj7lepxhf4h6r4"
    ],
    "miner": "f017387",
    "new_expiration": null,
    "max_sectors": 500,
    "max_initial_pledges": 0,
    "status": "pending",
    "to": "2024-05-14T15:18:47+08:00",
    "total_sectors": 1000,
    "published_sectors": 500,
    "succeeded_sectors": 0,
    "took": 526.841994321,
    "updated_at": "2024-05-13T16:53:55.942614308+08:00"
  }
}

Speeding Up Requests

Accelerate a renewal request by re-estimating the gas for all messages that are still pending on-chain:

POST /requests/{:id}/speedup

Warning

Only pending requests can be accelerated. This does not guarantee the message will be on-chain. Check the request status again after a while and try multiple times if needed.

Request parameters

Parameter Value Required Description
fee_limit 1FIL No Maximum allowable gas fee; if not provided, the system estimates;

Request Example

{
 "fee_limit": "1FIL"
}

Response Example

 {
  "data": "success"
}

Exceptions

HTTP Status Codes:

  • 400: Bad Request
  • 500: Internal Server Error
  • 401: Unauthorized (if authentication is enabled)
{
  "error": "msg"
}