# https://github.com/filecoin-project/filecoin-pin Project Manual Generated at: 2026-06-25 23:16:06 UTC ## Table of Contents - [Overview and System Architecture](#page-overview) - [CLI Command Reference](#page-cli) - [JavaScript Library and Core Modules](#page-library) - [Integrations, Configuration, and Operations](#page-integrations) ## Overview and System Architecture ### Related Pages Related topics: [CLI Command Reference](#page-cli), [JavaScript Library and Core Modules](#page-library), [Integrations, Configuration, and Operations](#page-integrations)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) - [documentation/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/README.md) - [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) - [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts) - [src/core/payments/constants.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/constants.ts) - [src/core/data-set/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/index.ts) - [src/core/data-set/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/types.ts) - [src/core/car/car-storage-backend.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/car/car-storage-backend.ts) - [src/core/utils/format.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/utils/format.ts) - [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) - [src/utils/cli-logger.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-logger.ts) - [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md) - [upload-action/src/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/types.ts) - [upload-action/src/github.js](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/github.js)
# Overview and System Architecture ## Purpose and Scope Filecoin Pin is the reference implementation for uploading content to [Filecoin Onchain Cloud](https://filecoin.cloud). It packages the underlying [Synapse SDK](https://synapse.filecoin.services/) and [Helia](https://helia.io/) into several user-facing affordances that share one well-tested core library, so the same upload behavior is reachable from a terminal, a CI pipeline, a JavaScript application, or a standards-compliant IPFS Pinning Service endpoint. The repository ships four affordances: | Affordance | Entry point | Audience | |---|---|---| | CLI | `npx filecoin-pin` | Operators and power users | | JavaScript library | `import { … } from 'filecoin-pin'` | dApp and tool builders | | GitHub Upload Action | `filecoin-project/filecoin-pin/upload-action@` | CI/CD pipelines | | IPFS Pinning Server (beta) | `filecoin-pin server` | Anyone using `ipfs pin remote` | Source: [README.md:1-60](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) The project targets a predictable workflow: a user authenticates with a private key or session key, tops up the on-chain Filecoin Pay balance, packs input into a UnixFS DAG, ships it as a CAR, and hands the resulting pieces to a Filecoin storage provider. The same core flow backs every affordance so behavior stays consistent across them. ## System Architecture The architecture is layered: thin interface adapters at the top, a shared `src/core/` library in the middle, and the Synapse SDK plus Helia at the bottom. ```mermaid flowchart TB subgraph Affordances CLI["CLI
src/cli, src/data-set, src/payments"] Lib["JavaScript Library
filecoin-pin / filecoin-pin/core/*"] Action["GitHub Upload Action
upload-action/"] Server["IPFS Pinning Server (beta)
filecoin-pin server"] end subgraph Core["src/core/ (shared business logic)"] Syn["core/synapse
SDK init + session keys"] Upload["core/upload
CAR → Synapse"] Payments["core/payments
Filecoin Pay planning"] DataSet["core/data-set
list / show / pieces"] UnixFS["core/unixfs
Helia DAG packing"] CAR["core/car
storage backends"] end subgraph External Synapse["@filoz/synapse-sdk"] Helia["Helia (UnixFS)"] FOC["Filecoin Onchain Cloud
(WarmStorage, PDP, Filecoin Pay)"] SP["Storage Providers"] end CLI --> Core Lib --> Core Action --> Core Server --> Core Syn --> Synapse Upload --> Synapse Payments --> Synapse DataSet --> Synapse UnixFS --> Helia CAR --> Helia Synapse --> FOC FOC --> SP ``` Each affordance imports from `filecoin-pin/core/*` rather than re-implementing the flow. As the maintainers note, this is deliberate: keeping the business logic in one place "makes mocking easier for testing" and lets the surrounding UX layers be forked and remixed independently. Source: [src/core/payments/README.md:1-15](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) The same `initializeSynapse` helper that powers the CLI also boots the upload action, the JS library, and the Pinning Server. It accepts a `privateKey`, an `rpcUrl`, and optional session-key configuration, then returns a `Synapse` instance bound to a logger. Source: [src/core/payments/README.md:60-72](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) ## Core Module Organization The shared library is partitioned by responsibility rather than by feature: - **`core/synapse`** — wraps SDK initialization, WebSocket cleanup, session-key detection, and a reusable service singleton. Source: [src/core/payments/README.md:20-30](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) - **`core/upload`** — accepts a CAR stream plus a root CID, runs it through `uploadToSynapse`, and surfaces progress events for piece addition, confirmation, and metadata association. Source: [src/core/payments/README.md:32-44](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) - **`core/payments`** — wraps Filecoin Pay: FIL gas balance, USDFC wallet and deposit balances, ERC20 approve/deposit, service approvals, and a funding planner that turns a `PaymentStatus` plus an `accountSummary` into a deposit plan with a human-readable reason. Source: [src/core/payments/index.ts:1-60](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts), [src/core/payments/funding.ts:1-50](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts) - **`core/data-set`** — wraps dataset queries and piece inspection. It defines a `PieceStatus` enum covering `ACTIVE`, `PENDING_REMOVAL`, `ONCHAIN_ORPHANED`, and `OFFCHAIN_ORPHANED` so the CLI can surface on-chain vs. provider-side state clearly. Source: [src/core/data-set/index.ts:1-15](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/index.ts), [src/core/data-set/types.ts:20-40](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/types.ts) - **`core/car`** — provides a `CARStorageBackend` interface with `initialize`, `writeBlock`, `readBlock`, `finalize`, and `cleanup`, so memory and filesystem backends stay pluggable. Source: [src/core/car/car-storage-backend.ts:1-55](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/car/car-storage-backend.ts) - **`core/unixfs`** — Helia-based DAG packing that turns a file or directory into a UnixFS root CID plus a CAR. Cross-cutting helpers live under `src/utils/`. `cli-auth.ts` normalizes authentication flags (`--private-key`, `--wallet-address`, `--session-key`, `--view-address`, `--network`, `--rpc-url`, `--provider-id`, `--data-set-id`) and merges the deprecated comma-separated aliases into a single array. Source: [src/utils/cli-auth.ts:1-50](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts). `cli-logger.ts` applies the global `-v/--verbose` flag to `LOG_LEVEL` and switches between Clack's TTY renderer and plain `console.log` for CI environments. Source: [src/utils/cli-logger.ts:1-50](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-logger.ts) ## Affordance Layer ### CLI The CLI is the primary human interface. Commands are grouped for the v1.1.0 release so that `add` and `import` — the two primary upload verbs — are no longer buried mid-list (see [#576](https://github.com/filecoin-project/filecoin-pin/issues/576)). The companion `data-set list` was changed to a compact summary view ([#578](https://github.com/filecoin-project/filecoin-pin/issues/578)), and `piece-status` gained pagination because the original "list everything" approach degraded linearly on large datasets ([#579](https://github.com/filecoin-project/filecoin-pin/issues/579)). A long-standing community request is a `--dry-run` mode for `add` that surfaces packed size and storage cost before any commitment ([#591](https://github.com/filecoin-project/filecoin-pin/issues/591)). ### GitHub Upload Action The action lives in `upload-action/` and is versioned separately ([#527](https://github.com/filecoin-project/filecoin-pin/issues/527)). It composes a build step, a transfer step, and a comment step, posting PR comments, creating check runs via `octokit.rest.checks.update`, and consuming a `CombinedContext` that carries upload results, payment status, optional CDN and provider overrides, and a `dryRun` flag. Source: [upload-action/src/types.ts:1-80](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/types.ts), [upload-action/src/github.js:1-50](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/github.js) The action is deliberately conservative: only same-repo PRs and direct pushes are accepted, and `workflow_run` events with incomplete repository provenance are rejected "before wallet input validation or upload" to prevent non-maintainer PR actors from draining funds. Source: [upload-action/README.md:60-75](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md) ### JavaScript Library and IPFS Pinning Server The library exposes both a curated `filecoin-pin` entry point for most consumers and a lower-level `filecoin-pin/core/*` surface for users who need to remix a single module. The Pinning Server reuses the same core, holding state in memory for the duration of a process. It implements the [IPFS Pinning Service API spec](https://ipfs.github.io/pinning-services-api-spec/) so `ipfs pin remote` works against it; because state is not persisted, the maintainers flag it as beta. Source: [README.md:18-28](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) ## Cross-Cutting Design Notes A few decisions recur across the architecture and are worth knowing for new contributors: - **SkipProvider for termination.** `data-set terminate` calls `synapse.storage.terminateService({ dataSetId, skipProvider: true })`; this is filecoin-pin's explicit choice rather than the SDK default and is being tracked as a long-term confirmation in [#581](https://github.com/filecoin-project/filecoin-pin/issues/581). - **Egress defaults.** The community is converging on making `--egress-provider beam` the default for `add` and `import`, with `--egress-provider none` available to opt out ([#464](https://github.com/filecoin-project/filecoin-pin/issues/464)). - **Retrieval round-trip.** A long-standing gap — no built-in `get` command — is being closed in [#575](https://github.com/filecoin-project/filecoin-pin/issues/575) so the upload-store-retrieve loop stays inside one tool. - **Key handling.** Session keys and view-only addresses are first-class alongside a raw `PRIVATE_KEY`, and support for 1Password/LastPass/Bitwarden secure vaults is under investigation in [#589](https://github.com/filecoin-project/filecoin-pin/issues/589). - **Formatting.** All currency and runway values are rendered through `core/utils/format.ts`, which dynamically widens decimal precision for sub-cent amounts so a non-zero `tFIL` balance is never silently rounded to `0.0000`. Source: [src/core/utils/format.ts:1-25](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/utils/format.ts) ## See Also - [Behind the Scenes of Adding a File](behind-the-scenes-of-adding-a-file.md) — end-to-end walkthrough of an `add` run. - [Content Routing FAQ](content-routing-faq.md) — IPNI caching, providers, and indexer behavior. - [Retrieving Your Data](retrieval.md) — gateways, trustless retrieval, and `/piece` endpoints. - [Progress Events](progress-events.md) — typed `onProgress` unions exposed by the JS library. - [Glossary](glossary.md) — definitions for Filecoin Onchain Cloud, Synapse, PDP, and related terms. --- ## CLI Command Reference ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [JavaScript Library and Core Modules](#page-library), [Integrations, Configuration, and Operations](#page-integrations)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) - [documentation/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/README.md) - [src/utils/cli-options.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options.ts) - [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) - [src/utils/cli-helpers.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-helpers.ts) - [src/utils/cli-logger.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-logger.ts) - [src/utils/cli-options-metadata.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts) - [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) - [src/core/data-set/list-data-sets.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/list-data-sets.ts) - [src/core/data-set/get-detailed-data-set.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/get-detailed-data-set.ts) - [src/core/data-set/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/types.ts) - [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md) - [upload-action/examples/cli-recipe/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/examples/cli-recipe/README.md)
# CLI Command Reference The `filecoin-pin` command-line interface is the primary user-facing affordance of the project. It wraps the [Synapse SDK](https://synapse.filecoin.services/) to provide a one-stop tool for packing local files into IPFS-compatible data, uploading them to [Filecoin Onchain Cloud](https://filecoin.cloud), managing data sets, and operating the payment rail that funds storage. The same business logic exposed by the CLI is also reused by the [upload-action/](upload-action/README.md) composite action and the `filecoin-pin` JavaScript library, ensuring consistent behavior across affordances ([README.md:67-88](README.md)). ## Command Groups The CLI organizes its surface into groups so newcomers can see the typical workflow at a glance — a redesign tracked in [#576](https://github.com/filecoin-project/filecoin-pin/issues/576) and shipped in v1.1.0 ([v1.1.0 release notes](https://github.com/filecoin-project/filecoin-pin/releases/tag/v1.1.0)). The primary groups are **Uploads** (`add`, `import`), **Data Sets** (`data-set list`, `data-set show`, `data-set terminate`, `piece-status`), **Payments** (`payments setup`, `payments status`, `deposit`, `withdraw`), and **Server** (`server`). | Command | Purpose | Source / Key Notes | | --- | --- | --- | | `filecoin-pin add ` | Pack a file or directory into a UnixFS CAR and upload it in one step. The recommended entry point for first-time users. | Documented in [README.md:48-50](README.md); command groups introduced in v1.1.0. | | `filecoin-pin import ` | Upload a pre-built CAR file. Useful when CAR generation is decoupled from the upload step (e.g., in custom CI). | Composite example: [upload-action/examples/cli-recipe/README.md](upload-action/examples/cli-recipe/README.md). | | `filecoin-pin data-set list` | List all data sets owned by the wallet. v1.1.0 added a **compact summary** view ([#578](https://github.com/filecoin-project/filecoin-pin/issues/578)) so it no longer dumps every field. | Implementation: [src/core/data-set/list-data-sets.ts](src/core/data-set/list-data-sets.ts). | | `filecoin-pin data-set show ` | Show full details of one data set, including piece-by-piece metadata. | Implementation: [src/core/data-set/get-detailed-data-set.ts](src/core/data-set/get-detailed-data-set.ts). | | `filecoin-pin data-set terminate ` | Terminate a data-set service contract. Filecoin Pin calls `synapse.storage.terminateService({ dataSetId, skipProvider: true })`, an explicit choice tracked in [#581](https://github.com/filecoin-project/filecoin-pin/issues/581). | Default behavior discussion: [#581](https://github.com/filecoin-project/filecoin-pin/issues/581). | | `filecoin-pin piece-status` | Inspect per-piece status. Pagination support is tracked in [#579](https://github.com/filecoin-project/filecoin-pin/issues/579) to avoid unbounded serial fetches. | Status enum: [src/core/data-set/types.ts:25-43](src/core/data-set/types.ts). | | `filecoin-pin payments ...` | Set up and inspect the Filecoin Pay rail. **Must be run before** `add`/`import` so lockup and runway are funded. | Documented in [src/core/payments/README.md:11-25](src/core/payments/README.md). | | `filecoin-pin server` | Run a localhost [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) daemon. State is in-memory. | Beta status noted in [README.md:30-43](README.md). | ### Typical Quick-Start Workflow ```bash # 1. Configure payments (lockup + USDFC top-up) filecoin-pin payments setup --auto-fund # 2. Upload (pack + send in one step) filecoin-pin add ./my-data # 3. Inspect filecoin-pin data-set list filecoin-pin data-set show ``` ## Common Options and Authentication Authentication is shared across every command that signs transactions. The `--private-key` / `--wallet-address` / `--session-key` triplet is registered once via `addAuthOptions` so behavior stays consistent, and every option is bound to a matching environment variable so `--help` shows `[env: PRIVATE_KEY]` etc. ([src/utils/cli-options.ts:31-49](src/utils/cli-options.ts)). The CLI flag wins over the env var when both are set. The `--network` flag selects between `mainnet` (default), `calibration`, and `devnet`. `--network` and `--rpc-url` are mutually exclusive — passing both is a hard error. When `--rpc-url` is supplied, Filecoin Pin probes `eth_chainId` at startup and uses the matching chain ([README.md:96-120](README.md)). The `--metadata key=value` flag is repeatable and accepts an empty value; it is wired through `addMetadataOptions` in [src/utils/cli-options-metadata.ts:27-58](src/utils/cli-options-metadata.ts), which also adds the dataset-metadata variant and the optional `--erc8004-type` for artifact types. A planned `--egress-provider` flag (defaulting to `beam`, with `none` to opt out) is tracked in [#464](https://github.com/filecoin-project/filecoin-pin/issues/464). The global `-v/--verbose` flag maps to `LOG_LEVEL=debug` unless an explicit level is already exported, letting any command emit debug logs ([src/utils/cli-logger.ts:21-27](src/utils/cli-logger.ts)). Spinners and intro/outro prompts are handled by [src/utils/cli-helpers.ts:23-66](src/utils/cli-helpers.ts), which degrades to plain text in non-TTY environments so the CLI is scriptable. ## Cost Estimation, Pagination, and Retrieval — In Flight Several community-driven enhancements are landing alongside the command-group refactor: - **`add --dry-run`**: Pre-upload estimates of packed size and storage cost, surfaced before any on-chain commit. Tracked in [#591](https://github.com/filecoin-project/filecoin-pin/issues/591). - **`piece-status` pagination**: The current implementation fetches piece metadata serially, which scales poorly. Pagination is the proposed fix ([#579](https://github.com/filecoin-project/filecoin-pin/issues/579)). - **`filecoin-pin get `**: A first-class retrieval command that closes the upload-store-retrieve loop, removing the need to switch to Kubo or `curl` after pinning. Tracked in [#575](https://github.com/filecoin-project/filecoin-pin/issues/575). - **Secure-vault key sourcing**: Investigation of 1Password / LastPass / Bitwarden integrations for private-key material, supplementing openwallet flows, is tracked in [#589](https://github.com/filecoin-project/filecoin-pin/issues/589). - **Error-scenario smoke tests**: A regression matrix for CLI error outputs and exit codes, born out of the `CliFatal` sentinel work, is tracked in [#470](https://github.com/filecoin-project/filecoin-pin/issues/470). ## See Also - [Builder Cookbook](https://docs.filecoin.co/builder-cookbook/filecoin-pin) — hands-on CLI and GitHub Action recipes - [Progress Events](documentation/progress-events.md) — typed `onProgress` event unions for library consumers - [Retrieving Your Data](documentation/retrieval.md) — fetching content back from an IPFS Root CID - [Configuration Reference](README.md#configuration) — environment variables and network selection - [upload-action README](upload-action/README.md) — the GitHub Action that wraps the same CLI --- ## JavaScript Library and Core Modules ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [CLI Command Reference](#page-cli), [Integrations, Configuration, and Operations](#page-integrations)
Related Source Files The following source files were used to generate this page: - [package.json](https://github.com/filecoin-project/filecoin-pin/blob/main/package.json) - [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) - [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) - [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts) - [src/core/payments/funding.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts) - [src/core/payments/top-up.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/top-up.ts) - [src/core/data-set/list-data-sets.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/list-data-sets.ts) - [src/core/car/browser.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/car/browser.ts) - [src/core/utils/format.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/utils/format.ts) - [src/utils/cli-options-metadata.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts) - [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts)
# JavaScript Library and Core Modules ## Overview and Purpose `filecoin-pin` is published as a multi-entry-point npm package that exposes the same business logic that drives the CLI and the `upload-action` GitHub Action. The README explicitly recommends two import styles: the high-level `import { ... } from 'filecoin-pin'` for most consumers, and the lower-level `import { ... } from 'filecoin-pin/core/*'` modules for callers who need to assemble their own pipelines (CAR files, payments, Synapse SDK, uploads, UnixFS). Source: [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) The `src/core/` tree is intentionally curated as a *reference implementation* of how to talk to the [Synapse SDK](https://synapse.filecoin.services/). According to the module's own README, "Synapse is abstracted within Filecoin Pin to isolate it as an educational resource, to integrate with our logging system, and to make mocking easier for testing." Source: [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) The library is consumed by three affordances (CLI, GitHub Action, IPFS Pinning Server) plus external dApps, so the design goal is to keep the canonical flows in `core/` while letting each affordance remain thin and easy to fork. ## Package Layout and Export Surface The `exports` field in `package.json` declares the public entry points. The high-level package and several `core/*` subpaths ship with TypeScript types and a JavaScript implementation: | Subpath | Purpose | | --- | --- | | `filecoin-pin` (root, `src/index.ts`) | High-level facade aggregating the affordances for typical consumers | | `filecoin-pin/core` | Re-export hub for all `core/*` modules (Node.js) | | `filecoin-pin/core/synapse` | Synapse SDK initialization and lifecycle | | `filecoin-pin/core/upload` | CAR-to-Filecoin upload patterns | | `filecoin-pin/core/payments` | Filecoin Pay (USDFC) balance, deposit, approval, capacity checks | | `filecoin-pin/core/unixfs` | UnixFS packing helpers | | `filecoin-pin/core/utils` | Formatting, validation, and shared helpers | | `filecoin-pin/core/car` | CAR blockstore utilities | | `filecoin-pin/core/car/browser` | Browser-safe CAR exports (no Node.js deps) | | `filecoin-pin/read-telemetry-config-from-env` | Reads the telemetry env vars documented in `documentation/events-and-metrics.md` | | `filecoin-pin/version-check` | Version compatibility helpers | Source: [package.json](https://github.com/filecoin-project/filecoin-pin/blob/main/package.json) The `bin` field registers a single `filecoin-pin` executable that dispatches to the CLI. A separate browser-only entry (`src/core/car/browser.ts`) re-exports a CAR blockstore plus `carInputError`, `INPUT_IS_CAR`, and `isCar` helpers so that browser bundles do not pull in Node-only modules. Source: [src/core/car/browser.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/car/browser.ts) ## Core Module Reference ### `core/synapse` — SDK Initialization and Lifecycle Provides SDK configuration (network, RPC URL, private key), storage context creation, progress callbacks, WebSocket cleanup, and a service-singleton pattern for reuse across multiple operations. The CLI's authentication helpers share these conventions, including handling of private key, session key, and view-only address modes. Source: [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) ### `core/upload` — Data Upload Patterns The unified upload interface accepts either pre-built CAR files or paths that the UnixFS layer will pack first. It surfaces typed progress events for upload, piece addition, and confirmation, links the IPFS Root CID to the resulting Filecoin piece, and reports the provider's direct-download URLs. This is the same pipeline that `filecoin-pin add` and `filecoin-pin import` invoke under the hood. ### `core/payments` — Filecoin Pay Operations This is the most fully documented module. The README enumerates four capability buckets: native FIL balance checking for gas fees; ERC20 (USDFC) balance management; the two-step approve-then-deposit flow; and service-approval configuration for storage operators. Source: [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) The payments module exports a `planFilecoinPayFunding` function (and a pure counterpart `calculateFundingPlan`) that classifies the reason for any required deposit. The reason codes — `none`, `piece-upload`, `runway-insufficient`, `runway-with-piece`, `target-deposit`, `withdrawal-excess` — map to localized strings via `formatFundingReason`. This classification powers the `filecoin-pin payments deposit` UX so users can see *why* they are being asked to top up. Source: [src/core/payments/funding.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts) Deposits can be safely clamped to a user-supplied balance ceiling through `clampDepositToLimit`, which returns one of three outcomes (`passthrough`, `already-at-limit`, `clamped`) with an explanatory message. Source: [src/core/payments/top-up.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/top-up.ts) ### `core/data-set` — Data Set Management Provides listing, summarization, and inspection helpers. `listDataSets(synapse, options)` returns `DataSetSummary[]` and optionally filters by address, marking entries that were created through Filecoin Pin (via the `DEFAULT_DATA_SET_METADATA` sentinel). This is the underlying source for the `filecoin-pin data-set list` command, whose output was compacted in v1.1.0 to make scanning easier (community issue [#578](https://github.com/filecoin-project/filecoin-pin/issues/578)). Source: [src/core/data-set/list-data-sets.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/list-data-sets.ts) ### `core/unixfs`, `core/car`, `core/utils` These support the upload pipeline: `unixfs` turns files and directories into CAR-shaped block graphs via Helia; `car` provides CAR blockstore utilities (with a Node-only and a browser-only entry point); `utils` exposes formatting helpers used across all affordances. For example, `formatFIL(amount, isTestnet, decimals)` automatically widens the displayed precision when the raw value rounds to zero, and `formatRunway(days, hoursRemainder)` produces human strings such as "1 year(s) 2 month(s)" for storage runway output. Source: [src/core/utils/format.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/utils/format.ts) ## Usage Patterns and Conventions ### High-level vs. low-level API Most consumers should import from the package root. Callers building their own workflows — for example a custom dApp that needs to deposit USDFC, pack a CAR, and upload without the CLI's argument parsing — should prefer the `core/*` subpaths. Both share the same logger (pino) and event conventions, so telemetry and progress reporting remain consistent. Source: [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) ### Metadata and authentication flags The CLI registers metadata flags (piece-level, dataset-level, and optional ERC-8004 artifacts) through a single helper, `registerMetadataOptions`, which enforces `key=value` syntax, rejects duplicate keys, and normalizes ERC-8004 configuration. Source: [src/utils/cli-options-metadata.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts) Authentication flags (`--private-key`, `--wallet-address`, `--session-key`, `--view-address`, `--network`, `--rpc-url`, `--provider-id`, `--data-set-id`) are collected by `parseAuthOptions`, which merges the canonical repeatable flags with their deprecated comma-separated aliases and forwards the result to `initializeSynapse`. Source: [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) ### Telemetry and versioning The package re-exports `read-telemetry-config-from-env` and `version-check` so library consumers can honor the same disable mechanisms the CLI and GitHub Action support (see `documentation/events-and-metrics.md`). Telemetry is on by default for the affordances but never collects PII, and every emission goes through the same event names used by the CLI. ## Architecture at a Glance ```mermaid flowchart LR Consumer["dApp / external code"] -->|"filecoin-pin"| Facade["src/index.ts
(high-level facade)"] Consumer -->|"filecoin-pin/core/*"| Core["src/core/* modules"] Facade --> Core Core --> Synapse["@filoz/synapse-sdk"] Synapse --> FOC["Filecoin Onchain Cloud
(smart contracts, SPs)"] Core --> Helia["Helia
(UnixFS packing)"] Helia --> CAR["CAR v1 blocks"] CAR --> Synapse CLI["CLI (bin: filecoin-pin)"] --> Facade Action["upload-action"] --> Facade Server["Pinning Server (beta)"] --> Facade ``` ## Failure Modes and Community Considerations Several community issues map directly to library behavior: - A `--dry-run` mode (issue [#591](https://github.com/filecoin-project/filecoin-pin/issues/591)) would let `core/upload` report packed size and cost before any on-chain call. Today the same information is exposed only after the upload begins; library consumers wanting an estimate must call `synapse.storage.getPriceList()` themselves. - The `data-set terminate` flow hard-codes `skipProvider: true` when calling `synapse.storage.terminateService` (issue [#581](https://github.com/filecoin-project/filecoin-pin/issues/581)). Library consumers should be aware that this is a Filecoin Pin choice rather than an SDK default. - A planned `filecoin-pin get` retrieval command (issue [#575](https://github.com/filecoin-project/filecoin-pin/issues/575)) is intended to close the upload-store-retrieve loop; once shipped, the underlying logic will be added to a `core/retrieve` module so that library consumers can fetch content programmatically. - `piece-status` and `data-set show` currently fetch piece metadata serially, causing both latency and output overflow on large datasets (issue [#579](https://github.com/filecoin-project/filecoin-pin/issues/579)). Library consumers hitting the same problem should switch to `listDataSets` (now compact in v1.1.0) or paginate manually until the upstream fix lands. ## See Also - [Builder Cookbook](https://docs.filecoin.io/builder-cookbook/filecoin-pin) — practical guides for the CLI, GitHub Action, library, and dApp demo - [Behind the scenes of adding a file](behind-the-scenes-of-adding-a-file.md) — deep dive into the `add` flow - [Progress Events](progress-events.md) — typed `onProgress` event conventions - [Events & Metrics](events-and-metrics.md) — telemetry event names and tags - [Retrieval](retrieval.md) — fetching content back by IPFS Root CID - [Content Routing FAQ](content-routing-faq.md) — IPNI caching and provider management - [API Reference](https://filecoin-project.github.io/filecoin-pin/) — TypeDoc-generated reference --- ## Integrations, Configuration, and Operations ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [CLI Command Reference](#page-cli), [JavaScript Library and Core Modules](#page-library)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) - [documentation/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/README.md) - [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) - [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) - [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts) - [src/core/payments/funding.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts) - [src/core/payments/constants.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/constants.ts) - [src/core/payments/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/types.ts) - [src/core/data-set/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/index.ts) - [src/core/data-set/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/types.ts) - [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md) - [upload-action/src/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/types.ts)
# Integrations, Configuration, and Operations Filecoin Pin is distributed as a single package that exposes several integration surfaces — a CLI, a programmatic JavaScript library, a GitHub Action, and a Pinning Service daemon — all sharing one core module built on top of the [Synapse SDK](https://synapse.filecoin.services/). This page documents how those surfaces are wired together, how authentication and network selection are configured, and how day-to-day operational workflows (payments funding and data-set management) are expressed across surfaces. ## Integration Surfaces The repository ships four user-facing affordances that all share the same `filecoin-pin/core/*` library, ensuring consistent behavior across interfaces. Source: [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md). | Surface | Entry point | Primary use case | |---|---|---| | CLI | `npx filecoin-pin ` | Manual uploads, payments, data-set inspection | | JavaScript library | `import { … } from 'filecoin-pin'` | Programmatic uploads in dApps and services | | GitHub Action | `filecoin-project/filecoin-pin/upload-action@` | CI/CD pinning on push or PR | | Pinning Server (beta) | `npx filecoin-pin server` | localhost IPFS Pinning Service API daemon | The library has two import levels: a high-level API (`filecoin-pin`) for most consumers, and a `core/*` namespace exposing CAR files, payments, Synapse SDK, uploads, and UnixFS primitives for advanced integrators. Source: [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md). ## Authentication and Network Configuration Every CLI command that touches the chain funnels its options through a shared `CLIAuthOptions` interface, which is then normalized into a `SynapseSetupConfig` for SDK initialization. Source: [src/utils/cli-auth.ts:23-48](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts). ```typescript export interface CLIAuthOptions { privateKey?: string walletAddress?: string sessionKey?: string viewAddress?: string network?: string rpcUrl?: string providerIds?: string[] dataSetIds?: string[] } ``` Key operational notes: - **Four signing modes** are supported: a direct private key, a session key paired with a wallet address, a view-only address, and MetaMask-style session keys. The `isSessionKeyMode` helper detects which mode the caller is using. Source: [src/core/payments/index.ts:22-23](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts). - **Network selection** resolves through `NETWORK_CHAINS` and `getRpcUrl`, which also support an RPC URL override and a local devnet configuration via `resolveDevnetConfig`. Source: [src/utils/cli-auth.ts:7-8](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts). - **Provider and data-set overrides** accept both a canonical repeatable `--provider-id` flag and a deprecated comma-separated `--provider-ids` alias; both are merged into the `providerIds` array at parse time so downstream code only sees one shape. Source: [src/utils/cli-auth.ts:39-48](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts). - **GitHub Action** consumers configure a `PaymentConfig` that pins `minStorageDays` and (optionally) `filecoinPayBalanceLimit` directly in workflow files; both are passed in via the `with:` block of `action.yml`. Source: [upload-action/src/types.ts:60-65](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/types.ts). The GitHub Action additionally enforces a two-workflow pattern that rejects artifacts from forks, even those flowing through `workflow_run`, to prevent non-maintainer PR actors from draining funds. Source: [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md). ## Payment and Funding Operations Filecoin Pin uses Filecoin Pay (USDFC) for storage payments and FIL for gas. The `core/payments` module is the integration point and exposes balance checks, ERC20 approve/deposit helpers, service approvals, and a pure-calculator `planFilecoinPayFunding` function for both runway-based and target-deposit-based funding. Source: [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md). ```mermaid flowchart LR CLI[filecoin-pin payments] -->|CLIAuthOptions| Setup[initializeSynapse] Setup -->|Synapse SDK| Status[getPaymentStatus] Status --> Plan[planFilecoinPayFunding] Plan -->|deficit| Approve[USDFC approve] Approve --> Deposit[USDFC deposit] Deposit --> Service[WarmStorage service approval] Service --> Ready[Ready to upload] ``` The funding planner reasons about distinct reason codes — `none`, `piece-upload`, `runway-insufficient`, `runway-with-piece`, `target-deposit`, and `withdrawal-excess` — and returns a human-readable explanation per code so the CLI can print *why* a top-up is required rather than only *how much*. Source: [src/core/payments/funding.ts:18-44](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts). Operationally relevant constants live alongside the module: `MIN_FIL_FOR_GAS = 0.1 FIL`, `DEFAULT_LOCKUP_DAYS` derived from `synapse-core`, and `MAX_RATE_ALLOWANCE`/`MAX_LOCKUP_ALLOWANCE` set to `maxUint256` so wallets display "Unlimited". Source: [src/core/payments/constants.ts:14-31](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/constants.ts). ## Data-Set Operations The `core/data-set` module wraps Synapse SDK primitives to provide a single API for listing, enriching, and inspecting data sets. Source: [src/core/data-set/index.ts:1-22](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/index.ts). Exported entry points include `listDataSets`, `getDataSetPieces`, `getDetailedDataSet`, `calculateActualStorage`, and `resolveByMetadata`. They operate on a `DataSetSummary` shape that augments the SDK's `EnhancedDataSetInfo` with a `dataSetId` alias for `pdpVerifierDataSetId`, optional provider enrichment, computed totals, optional piece lists, a `createdWithFilecoinPin` flag, and structured warnings. Source: [src/core/data-set/types.ts:60-92](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/types.ts). Piece health is reported through a `PieceStatus` enum — `ACTIVE`, `PENDING_REMOVAL`, `ONCHAIN_ORPHANED`, and `OFFCHAIN_ORPHANED` — where the orphaned states are surfaced explicitly because, while unexpected, they have been observed in practice and must be logged for operators. Source: [src/core/data-set/types.ts:27-39](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/types.ts). `data-set terminate` deliberately calls `synapse.storage.terminateService({ dataSetId, skipProvider: true })`. The `skipProvider: true` is an explicit Filecoin Pin choice — not the SDK default — and is tracked as a deliberate operational policy. Source: [issue #581](https://github.com/filecoin-project/filecoin-pin/issues/581). ## Operational Tooling Community work has steadily added affordances for safe day-to-day operations: a reorganized `--help` with command groups ([#576](https://github.com/filecoin-project/filecoin-pin/issues/576)), a compact summary view for `data-set list` ([#578](https://github.com/filecoin-project/filecoin-pin/issues/578)), pagination for `data-set show` and `piece-status` ([#579](https://github.com/filecoin-project/filecoin-pin/issues/579)), a `--dry-run` flag for `filecoin-pin add` to estimate packed size and cost ([#591](https://github.com/filecoin-project/filecoin-pin/issues/591)), and a `filecoin-pin get` retrieval command so users do not need to leave the tool to fetch what they just stored ([#575](https://github.com/filecoin-project/filecoin-pin/issues/575)). The upload-action is also being prepared for extraction into its own repository for independent versioning ([#527](https://github.com/filecoin-project/filecoin-pin/issues/527)). ## See Also - [Behind the Scenes of Adding a File](behind-the-scenes-of-adding-a-file.md) - [Glossary](glossary.md) - [Retrieving Your Data](retrieval.md) - [Progress Events](progress-events.md) - [Content Routing FAQ](content-routing-faq.md) --- --- ## Pitfall Log Project: filecoin-project/filecoin-pin Summary: Found 28 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/575 ## 2. Runtime risk - Runtime risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/579 ## 3. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: Add CLI error-scenario smoke test matrix for devs - User impact: Developers may expose sensitive permissions or credentials: Add CLI error-scenario smoke test matrix for devs - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/470 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/470 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/527 ## 6. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: Extract upload-action into a standalone repository for independent versioning - User impact: Developers may fail before the first successful local run: Extract upload-action into a standalone repository for independent versioning - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/527 ## 7. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: feat: add compact summary view to `data-set list` - User impact: Developers may fail before the first successful local run: feat: add compact summary view to `data-set list` - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/578 ## 8. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.22.1 - User impact: Upgrade or migration may change expected behavior: v0.22.1 - Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.1 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.23.2 - User impact: Upgrade or migration may change expected behavior: v0.23.2 - Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.2 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/578 ## 11. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v0.22.3 - User impact: Upgrade or migration may change expected behavior: v0.22.3 - Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.3 ## 12. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v0.23.0 - User impact: Upgrade or migration may change expected behavior: v0.23.0 - Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.0 ## 13. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v1.0.1 - User impact: Upgrade or migration may change expected behavior: v1.0.1 - Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v1.0.1 ## 14. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/576 ## 15. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/filecoin-project/filecoin-pin ## 16. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this runtime risk before relying on the project: feat: add pagination to `piece-status` - User impact: Developers may hit a documented source-backed failure mode: feat: add pagination to `piece-status` - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/579 ## 17. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: v0.21.0 - User impact: Upgrade or migration may change expected behavior: v0.21.0 - Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.21.0 ## 18. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: v0.22.0 - User impact: Upgrade or migration may change expected behavior: v0.22.0 - Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.0 ## 19. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin ## 20. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/filecoin-project/filecoin-pin ## 21. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/filecoin-project/filecoin-pin ## 22. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: data-set terminate: confirm skipProvider as the default termination path - User impact: Developers may hit a documented source-backed failure mode: data-set terminate: confirm skipProvider as the default termination path - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/581 ## 23. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: feat: add `--dry-run` flag to `filecoin-pin add` for pre-upload cost estimates - User impact: Developers may hit a documented source-backed failure mode: feat: add `--dry-run` flag to `filecoin-pin add` for pre-upload cost estimates - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/591 ## 24. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: feat: reorganize `--help` output with command groups and quick-start example - User impact: Developers may hit a documented source-backed failure mode: feat: reorganize `--help` output with command groups and quick-start example - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/576 ## 25. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys - User impact: Developers may hit a documented source-backed failure mode: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/589 ## 26. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this conceptual risk before relying on the project: feat: add `filecoin-pin get` retrieval command - User impact: Developers may hit a documented source-backed failure mode: feat: add `filecoin-pin get` retrieval command - Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/575 ## 27. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin ## 28. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin