Filecoin Deals

MeshKit's Filecoin CLI commands talk to the configured Filecoin HTTP persistence bridge. They do not run a Filecoin node and they do not make MeshKit a direct Filecoin client.

Use this page when you need to inspect deal status, request renewal, or retrieve content through that bridge from an operator shell or CI job.

Configure Persistence

Use environment variables for quick checks:

MESHKIT_FILECOIN_ENDPOINT=https://filecoin-bridge.example.com \
MESHKIT_FILECOIN_TOKEN=redacted \
npx -p @meshkit/cli meshkit deals status <deal-id> --json

For repeatable environments, configure persistence in meshkit.config.json:

{
  "version": 1,
  "appId": "my_app",
  "provider": {
    "type": "local-dev"
  },
  "persistence": {
    "type": "filecoin-http",
    "endpoint": "https://filecoin-bridge.example.com",
    "tokenEnv": "MESHKIT_FILECOIN_TOKEN",
    "timeoutMs": 15000
  }
}

The provider block still controls MeshKit storage and metadata. The persistence block adds Filecoin bridge operations.

Check Deal Status

npx -p @meshkit/cli meshkit deals status <deal-id> --json

Use status checks to answer operational questions such as whether the bridge knows the deal, what CID it associates with the deal, and whether the deal has moved into a retrievable state.

Renew A Deal

npx -p @meshkit/cli meshkit deals renew <deal-id> --duration-days 180 --json

--duration-days is optional, but when present it must be a positive integer. The bridge decides whether renewal is accepted and what final persistence proof it returns.

Retrieve Deal Content

npx -p @meshkit/cli meshkit deals retrieve <deal-id> --output artifacts/payload.bin --json

The CLI writes retrieved bytes to the output path and returns a summary containing the network, deal ID, CID, output path, byte count, content type, source, and retrieval time.

Review the output location before running this in CI. Retrieved bytes may be sensitive even when the original MeshKit object was encrypted.

What Filecoin Status Means

Observation	Meaning	Caveat
Deal exists in bridge status	The bridge recognizes the deal ID.	It may not prove the original app workflow can decrypt the content.
Deal is active	The bridge reports active persistence.	Active persistence is not the same as guaranteed low-latency retrieval.
Retrieval succeeds	The bridge returned bytes and the CLI wrote them locally.	The caller still needs MeshKit metadata and keys to open encrypted MeshKit content safely.
Renewal succeeds	The bridge accepted a renewal request.	Your app should still store the returned proof or status for audit.

Common Failures

Error	Cause	Fix
`persistence_not_configured`	No Filecoin persistence provider is configured.	Set `MESHKIT_FILECOIN_ENDPOINT` or add a `persistence` block.
`missing_deal_id`	The command needs a deal ID.	Pass the deal ID returned by the SDK persistence workflow.
`invalid_duration_days`	`--duration-days` is not a positive integer.	Pass a value such as `180` or omit the flag.
`missing_output_path`	Retrieval needs a local destination.	Add `--output <path>`.
Bridge HTTP error	Endpoint, token, or bridge state failed.	Check endpoint health, token scope, and the bridge logs.

Production Notes

Store deal IDs, CIDs, and persistence proof summaries in your application database when later audit or retrieval matters.
Keep Filecoin bridge tokens in the environment or a secret manager.
Treat Filecoin as a persistence layer behind MeshKit, not as a substitute for MeshKit metadata, identity, or proof checks.
Document retrieval expectations separately from storage guarantees.

On this page