fixup! feat: add devnet network support and --skip-ipni flag

Author: rvagg

AGENTS.md

@@ -10,7 +10,7 @@ Bridges IPFS content to Filecoin storage providers with cryptographic guarantees
 
 **Stack**: filecoin-pin → synapse-sdk → FOC contracts (FWSS, FilecoinPay, PDPVerifier, SPRegistry) + Curio.
 
-**Status**: Calibration testnet only. Not production-ready.
+**Status**: Supports Mainnet, Calibration testnet, and local devnet (foc-devnet). CLI defaults to Calibration.
 
 ## Design Philosophy
 
@@ -25,10 +25,12 @@ Bridges IPFS content to Filecoin storage providers with cryptographic guarantees
 ```
 src/
 ├── cli.ts, server.ts              # Commander.js CLI + Fastify server
-├── add/, data-set/                # Command implementations
+├── add/, import/, data-set/       # Command implementations
 ├── core/                          # Published library (see package.json exports)
 │   ├── car/                       # CAR file handling (CARv1 streaming)
 │   ├── payments/                  # Payment setup/status
+│   ├── metadata/                  # Metadata normalization
+│   ├── piece/                     # Piece status queries
 │   ├── synapse/                   # SDK initialization patterns
 │   ├── upload/                    # Upload workflows
 │   ├── unixfs/                    # Helia integration, browser/node variants
@@ -50,13 +52,13 @@ src/
 
 ## Key Patterns
 
-**Synapse SDK**: Initialize with callbacks (onProviderSelected, onDataSetResolved, onPieceAdded), upload returns {pieceCid, pieceId, provider}. See `src/core/synapse/index.ts`, `src/core/upload/synapse.ts`.
+**Synapse SDK**: Initialize via `initializeSynapse()` in `src/core/synapse/index.ts`. Upload via `executeUpload()` in `src/core/upload/index.ts` with progress events (`onStored`, `onPullProgress`, `onCopyComplete`, `onPiecesAdded`, `onPiecesConfirmed`). Returns `{pieceCid, size, copies, failures}`.
 
 **CAR files**: CARv1 streaming, handle 3 root cases (single/multiple/none), use zero CID for no roots. See `src/core/car/car-blockstore.ts`.
 
 **UnixFS**: Helia for directory imports, chunking, CID calculation. See `src/core/unixfs/`.
 
-**Payments**: `checkPaymentStatus()`, `setupPayments()` in `src/core/payments/index.ts`.
+**Payments**: `getPaymentStatus()`, `setMaxAllowances()`, `validatePaymentCapacity()` in `src/core/payments/index.ts`.
 
 ## Biome Linting (Critical)
 
@@ -84,11 +86,13 @@ src/
 
 ## CLI & Environment
 
-**Commands**: `payments setup --auto`, `add <file>`, `payments status`, `data-set <id>`, `server`
+**Commands**: `payments setup --auto`, `add <path>`, `import <car-file>`, `payments status`, `data-set <id>`, `server`
 
-**Required env**: `PRIVATE_KEY=0x...` (with USDFC tokens)
+**Network**: `--network mainnet|calibration|devnet` (default: `calibration`). Devnet reads config from foc-devnet's `devnet-info.json` and auto-resolves private key and RPC URL.
 
-**Optional**: `RPC_URL` (default: Calibration), `PORT`, `HOST`, `DATABASE_PATH`, `CAR_STORAGE_PATH`, `LOG_LEVEL`
+**Required env**: `PRIVATE_KEY=0x...` (with USDFC tokens; not needed for devnet)
+
+**Optional**: `NETWORK`, `RPC_URL`, `FOC_DEVNET_BASEDIR`, `DEVNET_INFO_PATH`, `DEVNET_USER_INDEX`, `PORT`, `HOST`, `DATABASE_PATH`, `CAR_STORAGE_PATH`, `LOG_LEVEL`
 
 **Default data dirs for pinning server**: Linux `~/.local/share/filecoin-pin/`, macOS `~/Library/Application Support/filecoin-pin/`, Windows `%APPDATA%/filecoin-pin/`
 

README.md

@@ -165,7 +165,7 @@ The Pinning Server requires the use of environment variables, as detailed below.
 
 ### Network Selection
 
-Filecoin Pin supports both **Mainnet** and **Calibration testnet**. By default, the CLI uses Calibration testnet during development.
+Filecoin Pin supports **Mainnet**, **Calibration testnet**, and local **devnet** networks. By default, the CLI uses Calibration testnet.
 
 **Using the CLI:**
 ```bash
@@ -177,6 +177,9 @@ filecoin-pin add myfile.txt --network mainnet
 
 # Explicitly specify Calibration
 filecoin-pin add myfile.txt --network calibration
+
+# Use a local foc-devnet (reads config from devnet-info.json, details below)
+filecoin-pin add myfile.txt --network devnet
 ```
 
 **Using environment variables:**
@@ -196,13 +199,30 @@ filecoin-pin add myfile.txt
 3. `--network` flag or `NETWORK` environment variable
 4. Default to Calibration testnet
 
+### Local Development with foc-devnet
+
+When using `--network devnet`, Filecoin Pin reads connection details from a running [foc-devnet](https://github.com/filecoin-project/foc-devnet) instance:
+
+- **Private key**: Automatically resolved from `devnet-info.json` (no `PRIVATE_KEY` needed)
+- **RPC URL**: Read from the devnet chain configuration
+- **Contract addresses**: Resolved from the devnet chain definition
+- **IPNI verification**: Automatically skipped (no IPNI infrastructure on devnet)
+
+**Environment variables for devnet:**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FOC_DEVNET_BASEDIR` | Override the foc-devnet base directory | `~/.foc-devnet` |
+| `DEVNET_INFO_PATH` | Explicit path to `devnet-info.json` (overrides basedir) | `<basedir>/state/latest/devnet-info.json` |
+| `DEVNET_USER_INDEX` | Which user from `devnet-info.json` to use | `0` |
+
 ### Common CLI Arguments
 
 * `-h`, `--help`: Display help information for each command
 * `-V`, `--version`: Output the version number
 * `-v`, `--verbose`: Verbose output
 * `--private-key`: Ethereum-style (`0x`) private key, funded with USDFC (required)
-* `--network`: Filecoin network to use: `mainnet` or `calibration` (default: `calibration`)
+* `--network`: Filecoin network to use: `mainnet`, `calibration`, or `devnet` (default: `calibration`)
 * `--rpc-url`: Filecoin RPC endpoint (overrides `--network` if specified)
 
 Other arguments are possible for individual commands, use `--help` to find out more.
@@ -214,10 +234,10 @@ Other arguments are possible for individual commands, use `--help` to find out m
 PRIVATE_KEY=0x...              # Ethereum private key with USDFC tokens
 
 # Optional - Network Configuration
-NETWORK=mainnet                # Network to use: mainnet or calibration (default: calibration)
+NETWORK=mainnet                # Network to use: mainnet, calibration, or devnet (default: calibration)
 RPC_URL=wss://...              # Filecoin RPC endpoint (overrides NETWORK if specified)
-                                # Mainnet: wss://wss.node.glif.io/apigw/lotus/rpc/v1
-                                # Calibration: wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1
+                               # Mainnet: wss://wss.node.glif.io/apigw/lotus/rpc/v1
+                               # Calibration: wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1
 
 # Optional for Pinning Server Daemon
 PORT=3456                      # Daemon server port

src/add/add.ts

@@ -168,14 +168,14 @@ export async function runAdd(options: AddOptions): Promise<AddResult> {
     }
 
     // Auto-skip IPNI on devnet (no IPNI infrastructure available)
-    const skipIpni = options.skipIpni || synapse.chain.id === DEVNET_CHAIN_ID
+    const skipIpniVerification = options.skipIpniVerification || synapse.chain.id === DEVNET_CHAIN_ID
 
     const uploadOptions: Parameters<typeof performUpload>[3] = {
       contextType: 'add',
       fileSize: carSize,
       logger,
       spinner,
-      skipIpni,
+      skipIpniVerification,
       ...(pieceMetadata && { pieceMetadata }),
       ...(dataSetMetadata && { metadata: dataSetMetadata }),
       ...(options.count != null && { count: options.count }),

src/add/types.ts

@@ -13,7 +13,7 @@ export interface AddOptions extends CLIAuthOptions {
   /** Data set metadata applied when creating or updating the storage context */
   dataSetMetadata?: Record<string, string>
   /** Skip IPNI advertisement verification after upload */
-  skipIpni?: boolean
+  skipIpniVerification?: boolean
 }
 
 export interface AddResult {

src/common/upload-flow.ts

@@ -61,7 +61,7 @@ export interface UploadFlowOptions {
   metadata?: Record<string, string>
 
   /** Skip IPNI advertisement verification after upload */
-  skipIpni?: boolean
+  skipIpniVerification?: boolean
 }
 
 export interface UploadFlowResult extends SynapseUploadResult {
@@ -318,7 +318,7 @@ export async function performUpload(
     ...(options.dataSetIds != null && { dataSetIds: options.dataSetIds }),
     ...(options.excludeProviderIds != null && { excludeProviderIds: options.excludeProviderIds }),
     ...(options.metadata != null && { metadata: options.metadata }),
-    ...(options.skipIpni && { ipniValidation: { enabled: false } }),
+    ...(options.skipIpniVerification && { ipniValidation: { enabled: false } }),
     onProgress(event) {
       switch (event.type) {
         case 'onStored': {

src/import/import.ts

@@ -214,14 +214,14 @@ export async function runCarImport(options: ImportOptions): Promise<ImportResult
     const carData = await readFile(options.filePath)
 
     // Auto-skip IPNI on devnet (no IPNI infrastructure available)
-    const skipIpni = options.skipIpni || synapse.chain.id === DEVNET_CHAIN_ID
+    const skipIpniVerification = options.skipIpniVerification || synapse.chain.id === DEVNET_CHAIN_ID
 
     const uploadOptions: Parameters<typeof performUpload>[3] = {
       contextType: 'import',
       fileSize: fileStat.size,
       logger,
       spinner,
-      skipIpni,
+      skipIpniVerification,
       ...(pieceMetadata && { pieceMetadata }),
       ...(dataSetMetadata && { metadata: dataSetMetadata }),
       ...(options.count != null && { count: options.count }),

src/import/types.ts

@@ -12,7 +12,7 @@ export interface ImportOptions extends CLIAuthOptions {
   /** Data set metadata applied when creating or updating the storage context */
   dataSetMetadata?: Record<string, string>
   /** Skip IPNI advertisement verification after upload */
-  skipIpni?: boolean
+  skipIpniVerification?: boolean
 }
 
 export interface ImportResult {

src/utils/cli-options.ts

@@ -85,7 +85,8 @@ export function addNetworkOptions(command: Command): Command {
       new Option(
         '--network <network>',
         'Filecoin network to use. "devnet" reads config from foc-devnet ' +
-          '(env: FOC_DEVNET_BASEDIR or DEVNET_INFO_PATH, DEVNET_USER_INDEX)'
+          '(https://github.com/filecoin-project/foc-devnet, ' +
+          'env: FOC_DEVNET_BASEDIR or DEVNET_INFO_PATH, DEVNET_USER_INDEX)'
       )
         .choices(['mainnet', 'calibration', 'devnet'])
         .env('NETWORK')
@@ -96,13 +97,14 @@ export function addNetworkOptions(command: Command): Command {
 }
 
 /**
- * Add upload-specific options (skip-ipni) to a command.
+ * Add upload-specific options to a command.
  * Used by `add` and `import` commands.
  */
 export function addUploadOptions(command: Command): Command {
   return command.addOption(
-    new Option('--skip-ipni', 'Skip IPNI advertisement verification after upload (automatic for devnet)').env(
-      'SKIP_IPNI'
-    )
+    new Option(
+      '--skip-ipni-verification',
+      'Skip IPNI advertisement verification after upload (automatic for devnet)'
+    ).env('SKIP_IPNI_VERIFICATION')
   )
 }