Filecoin Pay Explorer

Monorepo for the Filecoin Pay ecosystem: subgraph, shared types/configs, UI library, and frontend apps.

Monorepo layout

• apps/
  • explorer/ — Explorer app (README)
  • metrics/ — Metrics dashboard (README)
• packages/
  • ui/ — Shared UI library (Tailwind v4, shadcn, theming) (README)
  • subgraph/ — The Graph subgraph (README)
  • types/ — Shared TypeScript types (README)
  • configs/ — Shared TS/base configs

Prerequisites

• Node >= 22
• pnpm >= 9

Getting Started

Follow these steps to set up and run the applications:

1. Install Dependencies

Install all dependencies for the monorepo:

pnpm install

2. Configure Environment Variables

Set up environment variables for the apps you want to run. You'll need the subgraph URLs for your Filecoin Payments Subgraph. If you need to deploy your own subgraph, see the subgraph deployment guide.

For Explorer app:

cd apps/explorer
cp .env.example .env

Edit apps/explorer/.env and configure:

NEXT_PUBLIC_SUBGRAPH_URL_MAINNET=https://api.goldsky.com/api/public/project_xxx/subgraphs/filecoin-pay-mainnet/version/gn
NEXT_PUBLIC_SUBGRAPH_URL_CALIBRATION=https://api.goldsky.com/api/public/project_xxx/subgraphs/filecoin-pay-calibration/version/gn

Replace the placeholder URL with your actual Filecoin Payments Subgraph endpoint.

⚠️ Note: Both NEXT_PUBLIC_SUBGRAPH_URL_MAINNET and NEXT_PUBLIC_SUBGRAPH_URL_CALIBRATION are required for the Explorer app to function.

For Metrics app:

cd apps/metrics
cp .env.example .env

Edit apps/metrics/.env and configure:

VITE_GRAPHQL_ENDPOINT=https://api.thegraph.com/subgraphs/name/your-username/filecoin-payments

Replace the placeholder URL with your actual Filecoin Payments Subgraph endpoint.

Note: VITE_GRAPHQL_ENDPOINT has a default fallback (http://localhost:8000/subgraphs/name/filecoin-payments) but should be configured for production use.

Return to root directory:

cd ../..

3. Build Shared Packages

⚠️ Important: You must build the required shared packages before running any app:

• Explorer app depends on: @filecoin-pay/types and @filecoin-pay/ui
• Metrics app depends on: @filecoin-pay/types

Build all shared packages (recommended):

pnpm build --filter @filecoin-pay/types --filter @filecoin-pay/ui

Or build only what you need:

# For Explorer only
pnpm build --filter @filecoin-pay/types --filter @filecoin-pay/ui

# For Metrics only
pnpm build --filter @filecoin-pay/types

This step is required for both development and production environments.

4. Run the Applications

Development Mode

Run all apps:

pnpm dev

Run Explorer only:

pnpm dev --filter @filecoin-pay/explorer

Run Metrics only:

pnpm dev --filter @filecoin-pay/metrics

Production Mode

1. Build the application(s):

# Build everything (recommended)
pnpm build

# Or build specific apps
pnpm build --filter @filecoin-pay/explorer
pnpm build --filter @filecoin-pay/metrics

2. Start the production server(s):

# Start Explorer (runs on http://localhost:3000)
pnpm start --filter @filecoin-pay/explorer

# Start Metrics (runs on http://localhost:4173)
cd apps/metrics
pnpm preview
cd ../..

Common Scripts

• Build all: pnpm build
• Build specific app: pnpm build --filter @filecoin-pay/explorer or pnpm build --filter @filecoin-pay/metrics
• Lint: pnpm lint
• Format: pnpm format
• Type check: pnpm type-check
• Test: pnpm test
• Clean: pnpm clean (removes build artifacts and node_modules)

Architecture

Components

• apps/explorer/ — The Explorer app: a statically-built Next.js frontend for browsing Filecoin Pay rails, accounts, and deal activity. This is the primary focus of the repo.
• apps/metrics/ — A Vite-based metrics dashboard. Not a current focus.
• packages/subgraph/ — A The Graph subgraph hosted on Goldsky that indexes Filecoin Pay contract events on mainnet and Filecoin calibration testnet. See the subgraph architecture guide for its data model and Explorer integration.
• packages/ui/, packages/types/, packages/configs/ — Shared libraries consumed by the apps.

Hosting

• Static site — The Explorer is statically built and deployed to Vercel. Vercel is used for convenience; there is no server-side logic that requires it.
• Subgraph — Hosted publicly on Goldsky with no proxy layer. It is intended to be consumed only by the deployed static frontend.

Deployments

Static site and subgraph deployments are separate. See the release checklist for post-deploy verification and production promotion.

• Static site changes deploy automatically via the Vercel GitHub App on merge to main.
• Subgraph releases run through the Release Please workflow. Merging its Release PR creates the tag and GitHub Release, deploys both Goldsky networks, and opens a tracking issue.

Monitoring

Uptime monitoring for the static site and subgraph is managed via FilOzone/infra and visible at status.filoz.org.

Releasing

Subgraph releases are automated with Release Please:

1. Give every PR a Conventional Commit title, such as feat:, fix:, or chore:. The PR title check enforces this because squash merges use the PR title as the commit on staging.
2. When releasable subgraph changes reach staging, Release Please opens or updates a Release PR targeting staging. That PR bumps the subgraph version and updates packages/subgraph/CHANGELOG.md.
3. Merge the Release PR to create the tag and GitHub Release, deploy calibration and mainnet to Goldsky, tag both as staging, and open a release tracking issue. Do not create the release tag manually.
4. Use the tracking issue to confirm indexing and smoke-test the Explorer on staging.
5. Merge the promotion PR (staging → main). This applies the prod tag on Goldsky automatically, switching pay.filecoin.cloud to the new fully-indexed subgraph.

See release-please-config.json and .release-please-manifest.json for version tracking configuration.

Contributing

• Use Node/pnpm versions from root package.json engines.
• Use Conventional Commits for PR titles (e.g., feat:, fix:, chore:).
• Run pnpm lint, pnpm format, and pnpm type-check before committing.
• See per-package READMEs for details.

Related repositories

• Contracts: https://github.com/FilOzone/filecoin-pay
• Explorer: https://github.com/FilOzone/filecoin-pay-explorer

License

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