Open Grant: x402-to-Filecoin Storage Gateway on Cloudflare Workers

# Open Grant Proposal: `x402-to-Filecoin Storage Gateway on Cloudflare Workers`

**Project Name:** x402-to-Filecoin Storage Gateway on Cloudflare Workers

**Proposal Category:** Integrations / Storage / Developer and data tooling

**Individual or Entity Name:** Individual / RFDY working through the public GitHub account `@tolga-tom-nook`

**Proposer:** `tolga-tom-nook`

**Project Repo(s):** A new public repository will be created for grant deliverables if accepted, expected at `https://github.com/tolga-tom-nook/x402-filecoin-worker-gateway`.

**(Optional) Filecoin ecosystem affiliations:** None.

**(Optional) Technical Sponsor:** None yet.

**Do you agree to open source all work you do on behalf of this RFP under the MIT/Apache-2 dual-license?:** Yes.

# Project Summary

This proposal adds a small, reproducible bridge between x402-style HTTP payments and Filecoin/IPFS storage workflows, implemented as a Cloudflare Workers reference gateway. The gateway demonstrates how an agent or application can require payment for storage actions, verify/forward the paid request, mint a short-lived upload/session token, and persist storage metadata so integrators have a concrete starting point instead of piecing together payment middleware, edge runtime constraints, and Filecoin storage APIs from scratch.

The target is intentionally narrow: a developer-facing reference implementation, conformance tests, and documentation that make it easy to run a paywalled storage endpoint at the edge. It will not custody user funds or private keys, will not run production infrastructure for users, and will not introduce trading/speculation behavior.

This is intended as Filecoin-facing developer tooling rather than an IPFS-only example: the deliverable will make the Filecoin/storage-provider adapter boundary explicit, document how paid requests map to storage workflow metadata, and keep the edge gateway generic enough for Filecoin builders to adapt to their preferred provider/API.

## Impact

Filecoin has strong storage primitives, but many AI-agent and API developers now expect payment-native HTTP flows. x402 is emerging as a simple pattern for machine-payable APIs, while Cloudflare Workers is a common deployment target for lightweight edge services. A tested x402-to-Filecoin reference gateway would give builders a concrete path to experiment with pay-per-upload, paid retrieval metadata, and storage-access workflows.

The pain point is integration friction: today a builder needs to understand edge runtime constraints, 402/payment middleware, storage-provider credentials, metadata persistence, and failure handling before they can even prototype a paid storage endpoint. This proposal reduces that to a documented Worker, tests, adapter interface, and example client.

Success means a developer can clone the repo, configure test credentials, run the Worker locally, execute a paid/request-gated upload flow in tests, and understand how to adapt the pattern to real Filecoin-compatible storage backends. This creates reusable demonstration material for Filecoin builders exploring agent commerce and paid storage APIs.

## Outcomes

Final deliverables:

1. **Cloudflare Worker gateway**
- x402-compatible paid endpoint skeleton.
- `402 Payment Required` response path and successful paid-flow path.
- Short-lived upload/session token flow after payment verification.
- Metadata persistence adapter with local/dev mode and documented production boundary.

2. **Filecoin/IPFS storage adapter examples**
- Minimal adapter interface for Filecoin-compatible storage providers.
- Example integration path for storage API calls without committing provider secrets.
- Clear non-custodial boundaries and no private-key handling in the Worker.

3. **Conformance and integration tests**
- Local Worker test harness.
- Payment-required/402 response tests.
- Successful paid-flow simulation tests.
- Metadata persistence tests.
- Adapter contract tests.

4. **Developer documentation and runbook**
- Setup guide for local development and Cloudflare deployment.
- API reference and sequence diagrams.
- Security/non-goals section.
- Example client script for agent or CLI invocation.
- Handoff notes for maintainers and future contributors.

Success metrics:

- `npm test`/CI passes for the Worker and adapter test harness.
- A new developer can run the local demo from README instructions without private credentials.
- The docs clearly separate mock/local mode from production storage-provider integration.
- The gateway returns correct 402 and paid-flow responses in automated tests.

## Data Onboarding

This project is developer tooling and does not itself commit to onboarding production data. It provides the gateway and examples that other teams can use to create paid Filecoin/IPFS storage flows.

Projected data onboarded by this grant directly:

- Month #1: 0 production data; local/mock examples only.
- Month #3: 0 production data committed by this grant; possible demo/test objects only if requested by reviewers.
- Month #6: dependent on downstream adoption.
- Month #12: dependent on downstream adoption.

## Adoption, Reach, and Growth Strategies

The target audience is developers building machine-payable APIs, AI agents, storage marketplaces, and edge-hosted demos. The first 10 users are likely Filecoin/x402/Cloudflare developers who can validate the repository locally. The first 100 users would come from documentation, example clients, and references from Filecoin/x402 developer channels if the pattern proves useful.

Adoption work included in this grant is limited to developer-facing assets: a public repo, runnable examples, README, sequence diagrams, and issue templates for feedback. Hosted production operations, marketing campaigns, and ongoing support contracts are out of scope.

## Development Roadmap

No funded work will begin until a grant agreement is signed by both parties. The schedule below is relative to contract signature.

**Milestone 1 — Spec + Worker scaffold + 402 tests — T+7 business days — $2,000**

Functionality after completion:
- Public repo initialized under MIT/Apache-2 dual license.
- Cloudflare Worker skeleton with route structure and documented config.
- x402-style payment-required response path.
- Local test harness and 402/payment-required tests.
- Initial README with architecture and setup.

People/roles:
- 1 developer/maintainer (`@tolga-tom-nook` / RFDY delivery).

**Milestone 2 — Storage adapter + paid-flow simulation — T+17 business days — $3,000**

Functionality after completion:
- Storage adapter interface for Filecoin-compatible providers.
- Local/mock adapter plus documented production adapter boundary.
- Successful paid-flow simulation with metadata persistence.
- Example CLI/client invocation path.
- Adapter contract tests and CI coverage.

People/roles:
- 1 developer/maintainer.

**Milestone 3 — Deployment docs, hardening, and handoff — T+25 business days — $3,000**

Functionality after completion:
- Cloudflare deployment guide.
- Security/non-goals documentation.
- Sequence diagrams and API reference.
- Final CI, README, examples, and maintainer handoff.
- 30-day reasonable bug-fix support window for reproducible issues against documented local harness.

People/roles:
- 1 developer/maintainer.

## Total Budget Requested

| Milestone # | Description | Deliverables | Completion Date | Funding |
|===|===|===|===|===|
| 1 | Spec + Worker scaffold + 402 tests | Public repo, Worker skeleton, 402 tests, initial docs | T+7 business days after signature | $2,000 |
| 2 | Storage adapter + paid-flow simulation | Adapter interface, mock/local adapter, paid-flow simulation, metadata persistence tests, example client | T+17 business days after signature | $3,000 |
| 3 | Deployment docs, hardening, handoff | Cloudflare deploy guide, security docs, sequence diagrams, API reference, CI, support window | T+25 business days after signature | $3,000 |
| **Total** | | | | **$8,000** |

## Maintenance and Upgrade Plans

After final milestone acceptance, I will provide 30 days of reasonable bug-fix support for issues that reproduce against the documented local test harness. Longer-term maintenance would be handled through GitHub issues and can be scoped separately if the Filecoin grants team wants additional adapters, production provider examples, or hosted demos.

# Team

## Team Members

- `@tolga-tom-nook` / RFDY delivery account

## Team Member LinkedIn Profiles

- Not provided publicly in this issue. I can provide additional identity/contact details through the grant agreement process if the proposal enters review.

## Team Website

- Not provided publicly in this issue.

## Relevant Experience

Relevant experience includes building and validating agent-oriented GitHub delivery workflows, Cloudflare-compatible service proposals, x402-style payment/API integration prototypes, and automation tooling with tests, documentation, and public handoff artifacts. This proposal is intentionally scoped to a small, testable developer-tooling package that can be delivered by one developer without requiring custody of funds or production operation of user infrastructure.

## Team code repositories

- GitHub account: https://github.com/tolga-tom-nook
- Deliverable repo, if accepted: `https://github.com/tolga-tom-nook/x402-filecoin-worker-gateway`

# Additional Information

I learned about the Open Grants Program through public GitHub grant/bounty research for developer tooling and web3 infrastructure opportunities.

Best contact path for now: GitHub comments on this issue. If the proposal proceeds to agreement review, I can provide private email/payment/legal details through the grant process rather than posting them publicly.

Additional notes:

- This proposal avoids private-key custody, fund movement, trading, gambling, or speculative behavior.
- The Worker will not store private keys or provider secrets in source control.
- The implementation will separate mock/local development from production provider configuration.
- I am happy to reduce or reshape the scope if reviewers prefer a narrower Filecoin-specific adapter first.