Skip to content

readme.md

Latest commit

 

History

History
250 lines (160 loc) · 6.43 KB

readme.md

File metadata and controls

250 lines (160 loc) · 6.43 KB
Raw

Early Repair CLI

NPM

Early repair for faulty service providers and datasets

The repair CLI helps prepare and run repair jobs that move pieces away from a faulty Filecoin service provider and into a target PDP provider. It uses:

  • an indexer Postgres database as the read-only source of providers, datasets, and pieces
  • a local SQLite database to track repair jobs and per-piece operations
  • a configured Filecoin wallet to create datasets and submit on-chain add-piece transactions

Installation

pnpm add -g @filoz/repair-cli

The package exposes the repair binary.

repair --help

Setup

Run setup before using any command that talks to the indexer, local database, or wallet.

repair setup

Setup prompts for:

  • private key for the repair wallet
  • mainnet indexer Postgres URL
  • calibration indexer Postgres URL
  • chain, either Filecoin Mainnet 314 or Filecoin Calibration 314159
  • local SQLite database path

The command stores these values in the CLI config and runs the local SQLite schema migration. It returns the configured wallet address.

Most commands also accept:

--debug

Use --debug when you want extra error output from wallet operations.

Command Reference

repair setup

Interactive configuration and local database setup.

repair setup

Use this whenever you need to initialize the CLI, change the active chain, update indexer URLs, or move the local SQLite database.

repair wallet fund

Funds the configured wallet from the Filecoin Calibration faucet.

repair wallet fund

This command only works on Calibration. It claims faucet tokens, waits for the transaction to be mined, and returns the wallet address and FIL balance.

repair wallet balance

Shows wallet and payment account balances.

repair wallet balance

The output includes the wallet address, FIL balance, USDFC balance, and Filecoin Pay account summary fields such as funds, available funds, debt, lockup rates, lockup totals, runway, and current epoch.

repair wallet deposit <amount>

Deposits USDFC from the configured wallet into the wallet's Filecoin Pay account.

repair wallet deposit 100

amount is a positive USDFC amount. The command submits the deposit and approval transaction, then waits for it to be mined.

repair wallet withdraw <amount>

Withdraws USDFC from the wallet's Filecoin Pay account.

repair wallet withdraw 25

amount is a positive USDFC amount. The command submits the withdraw transaction and waits for it to be mined.

repair providers list

Lists PDP providers from the configured indexer.

repair providers list

By default, the command returns active PDP providers that are approved or endorsed. Each provider includes:

  • id
  • name
  • serviceUrl
  • approved
  • endorsed
  • pieceCount, the number of active indexed pieces for that provider
  • totalSize, the sum of active piece raw sizes formatted in decimal GB

Use --all to include every active PDP provider, even if it is not approved or endorsed.

repair providers list --all

repair datasets list

Lists datasets owned by the configured repair wallet.

repair datasets list

Each dataset includes its ID, CDN/IPFS indexing flags, source, provider URL, PDP end epoch, and piece count.

Filter by provider ID:

repair datasets list --provider-id 123

repair repair create

Creates a local repair plan for a source provider and a target provider.

repair repair create --provider-id 101 --target-provider-id 202

--provider-id is the faulty provider whose pieces should be repaired.

--target-provider-id is the provider that should receive the repaired pieces. It must be different from --provider-id.

The command snapshots the current chain block number, creates a local repair row, scans active pieces for the source provider, deduplicates them by CID, and creates local add_piece operations. Pieces with no alternate provider are marked skipped. The command returns a repairId.

repair repair list

Lists local repair jobs.

repair repair list

Each repair includes:

  • repair ID and status
  • source provider ID
  • target provider ID and target provider URL
  • target dataset ID, when one has been created or found
  • block number used when the repair was created
  • total operations and counts by pending, failed, completed, and skipped

repair repair run <repairId>

Runs a pending repair.

repair repair run 1

The command first ensures the target repair dataset exists for the configured wallet and target provider. If no matching dataset exists, it creates one with IPFS indexing enabled and CDN disabled. Then it processes pending add_piece operations by pulling pieces from alternate providers into the target provider and committing them on-chain.

Options:

  • --concurrency <number> controls how many pull batches run at once. Defaults to 4.
  • --batch-size <number> controls the maximum number of add_piece operations per batch. Defaults to 40.
  • --reset retries failed add_piece operations as well as pending operations.

Example:

repair repair run 1 --concurrency 8 --batch-size 100 --reset

repair repair delete <repairId>

Deletes a local repair and its operations.

repair repair delete 1

This only deletes local SQLite state. It does not delete on-chain datasets or remove pieces from a provider.

Typical Workflow

  1. Configure the CLI.
repair setup
  1. On Calibration, fund the wallet if needed.
repair wallet fund
  1. Check balances and deposit USDFC into the payment account.
repair wallet balance
repair wallet deposit 100
  1. Pick source and target providers.
repair providers list
  1. Create, inspect, and run the repair.
repair repair create --provider-id 101 --target-provider-id 202
repair repair list
repair repair run 1

Contributing

Read contributing guidelines.

Open in GitHub Codespaces

License

Dual-licensed: MIT, Apache Software License v2 by way of the Permissive License Stack.