foc-platform is a draft specification and planning workspace for embedding Filecoin Onchain Cloud (FOC) inside a normal platform product.
The core idea is that a SaaS platform, creator tool, AI product, marketplace, enterprise app, or similar service can expose a simple upload API to its users while handling the FOC details behind the scenes. Users should not need to understand wallets, USDFC deposits, datasets, providers, or payment rails in order to store files through the platform.
A typical workflow could look like this:
- A platform user clicks “upload” or calls the platform’s API.
- The platform accepts the request through its normal product/backend flow.
- An upload client or FOC Storage Coordinator moves the file bytes and performs the FOC storage action, for example through tools like Synapse SDK.
- The platform pays FOC through a managed wallet, smart account, contract treasury, or another supported payment model.
- Platform Contracts record the relevant policy, accounting, ownership, quota, billing, and receipt information onchain.
The platform remains a normal API/product service. Platform Contracts do not replace the application, move file bytes, or remove the need for an upload/coordinator path. Instead, they provide an onchain record of who caused a storage action, what was stored, what it cost, and how the platform should account for that usage.
The purpose of this project is to make FOC easier to embed inside larger applications without every platform needing to rebuild its own custom storage accounting, quota, and receipt system from scratch.
A platform could manage FOC usage entirely with traditional backend infrastructure: store upload metadata in Postgres, track billing in Stripe, and keep FOC transaction receipts in an offchain database.
This repository explores a more onchain-native design for that platform layer:
- platform-specific contracts can track storage requests, object ownership, usage, quotas, billing events, and receipts,
- the platform can keep its normal API and product experience,
- offchain services can focus on uploading bytes, coordinating FOC execution, and finalizing results,
- FOC execution can still happen through tools like Synapse SDK,
- the chain can become a durable audit log and shared system of record for platform storage activity.
The goal is not to remove all offchain infrastructure. File bytes still need to be uploaded, transferred, and coordinated by software outside the smart contracts. The goal is to define a reusable pattern where Platform Contracts handle policy and accounting while the platform and its coordinators handle the product experience and storage execution.
This repository is currently a draft specification and planning workspace.
See spec.md.
The design is not production-ready, but it now selects a v1 implementation path to validate: platform EOA/KMS payer, FOC session-key coordinator, hosted coordination, and onchain request/object/usage/receipt state. Future payment and coordinator modes remain compatibility-gated by Phase 0 evidence.
@filoz/synapse-sdk— core SDK for FOC storage, payments, providers, datasets, and retrieval.foc-cli— CLI and agent-facing operational tooling for FOC.foc-storage-mcp— MCP tools for AI-agent FOC storage workflows.tokenhost-builder— candidate framework for generating onchain platform registry, usage ledger, UI, upload adapters, and sponsored transaction scaffolding.
Together, these projects cover different layers of the FOC developer experience. foc-platform focuses specifically on the platform-integration layer: how a company can offer FOC-backed storage through its own API, billing model, user accounts, and managed payment flow.
The current v1 direction is:
- platform EOA/KMS payer,
- FOC session keys for coordinator execution,
- platform-hosted allowlisted coordinator,
- onchain request, object, usage, and compact receipt state,
- quota/credit-style accounting before contract-custodied user deposits.
Smart-account payers, contract treasury payment, direct browser-to-FOC upload, BYO coordinators, stronger proof models, and Token Host-generated production scaffolding remain compatibility-gated future paths.
The next recommended step is to complete the Phase 0 Filecoin Calibration compatibility report in spec.md, including required transaction hashes, pass/fail answers, SDK gaps, and the final recommended v1 mode.