A simple, easy-to-understand demo showing how to use filecoin-pin to upload files to Filecoin. This single-page React + TypeScript app demonstrates the core upload workflow with progress tracking and wallet integration.

This app demonstrates the complete filecoin-pin upload workflow:

• Create CAR files from user files
• Check upload readiness
• Execute uploads to Filecoin
• Track progress through each step
• Verify CID indexing via IPNI

The core integration logic is in src/hooks/use-filecoin-upload.ts and src/context/filecoin-pin-provider.tsx. Everything else is UI components. See CONTRIBUTING.md for detailed file structure.

• Vite for dev server and bundling
• React 19 with the modern JSX runtime
• TypeScript with strict settings
• Biome for formatting, linting, and import hygiene

• Node.js 18.0+ (Vite supports the active LTS releases)
• npm 9+ (bundled with Node)

npm install
npm run dev

Visit http://localhost:5173 to see the demo.

Available Scripts:

• npm run dev – Start development server
• npm run build – Build for production
• npm run lint – Check code quality
• npm run lint:fix – Fix linting issues

For environment setup and detailed project structure, see CONTRIBUTING.md.

This demo supports deployment with a shared session key, allowing multiple users to safely upload files using the same wallet.

How it works:

• Session key authentication – Uses VITE_WALLET_ADDRESS + VITE_SESSION_KEY instead of exposing the wallet's private key
• Per-user data sets – Each user gets their own data set ID, stored in browser localStorage
• Data set persistence – Returning users automatically reconnect to their existing data set
• Upload history – Users can view their uploaded files (fetched from their data set on-chain)

User isolation:

• All users share the same wallet (via session key)
• Each user's browser stores their unique data set ID
• Users only see pieces from their own data set

Important: This approach relies on browser localStorage for user identity, which is fine for demos but not suitable for production. For production applications, use a backend database to track user → data set mappings with proper authentication.

During the launch window we hardcode a small allowlist of “known good” storage providers and randomly pick from it when a provider is not specified via the providerId debug parameter. This is an expedient, temporary measure to smooth out early network volatility while we gather feedback and improve automated provider discovery. Expect this allowlist to grow then disappear entirely once Calibration stabilizes; outside the launch period you should remove the hardcoded IDs and rely on normal provider selection logic (inside filecoin-pin and underlying synapse-sdk) instead.

For detailed information on:

• Environment configuration (authentication options)
• Project structure and file organization
• Coding guidelines and conventions
• Pull request workflow

See CONTRIBUTING.md.