Open Grant Proposal: Fail-closed Filecoin retrieval matrix

# Open Grant Proposal: Fail-closed Filecoin retrieval matrix

**Project Name:** Fail-closed Filecoin retrieval matrix

**Proposal Category:** Developer and data tooling

**Individual or Entity Name:** Individual. Agreement and payment, if accepted, must be completed by the same individual.

**Proposer:** tzh476

**Project Repo(s):** New public repo to be created under https://github.com/tzh476 (working title `filecoin-retrieval-matrix`). No existing public Filecoin/FVM repo is claimed.

**(Optional) Filecoin ecosystem affiliations:** None. No current work relationship with Protocol Labs, Filecoin Foundation, or FFDW.

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

**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

Filecoin retrieval checks often print success when the local node, deal, or HTTP gateway is missing. That is the same defect class as a CI matrix that prints PASS when the runtime is absent. Developers then ship integrations against a green log that never retrieved a byte.

This project is a small, measured, fail-closed retrieval matrix: a CLI and GitHub Action that pin a CID, a retrieval path, and a first-party check. If lotus, the Calibration endpoint, or the deal is missing, the cell is FAIL with the exact missing dependency. It does not invent a PASS. It does not report a vulnerability in a live service.

I have eight years of professional software engineering experience and professional Filecoin experience from employment. I am not citing a public FVM contract or Filecoin repo, because this account does not have one. Adjacent public work: a fail-closed R compatibility matrix (https://github.com/tzh476/r-compat-matrix) and an evidence-first BNB discovery UI (https://github.com/tzh476/fourproof-bnb).

## Impact

Pain point: tooling and tutorials treat “I called an API” as “the CID is retrievable.” That hides broken deals and missing nodes.

Benefit: a reusable Action that other Filecoin tools can add to CI so a missing lotus binary cannot look like a green retrieval.

Risk of not doing it: new builders copy fake-green examples and waste review time.

Success: the Action is used in at least one external Filecoin repo CI, and the self-test proves FAIL when the node is absent and PASS on one pinned Calibration CID.

## Outcomes

- Public MIT/Apache-2 repo with a CLI (`fil-retrieval-matrix`) and a GitHub Action.
- Manifest format: CID, network (Calibration/mainnet), retrieval method, expected size bound, source pin.
- Self-test: missing-node FAIL; pinned Calibration CID PASS; oversized/unknown CID FAIL.
- README that names the machine, the endpoint, and the limits. No “all tests passed” claim without the log.

Metrics: Action runs on this repo’s CI; one external adoption issue or PR; self-test coverage of the three cells above.

## Data Onboarding

Not applicable. This project does not onboard storage data.

## Adoption, Reach, and Growth Strategies

Target: Filecoin library and tutorial maintainers who already run GitHub Actions.

First 10 users: publish the Action, open one PR or issue against a public Filecoin tooling repo offering the workflow file, and document the copy-paste snippet.

First 100: unlikely in the grant window; the grant is scoped to a working Action and one external adoption attempt, not a growth campaign.

## Development Roadmap

Milestone 1 — Fail-closed CLI (one person, Stephen Smith): spec the manifest; implement `fil-retrieval-matrix` so a missing lotus/API prints FAIL; unit tests for missing-runtime and bound checks. 3 weeks. $4,000.

Milestone 2 — Calibration retrieval cell (one person): one pinned public CID on Calibration; record endpoint, time, and size; GitHub Action wrapping the CLI. 3 weeks. $4,000.

Milestone 3 — Docs and one external offer (one person): README with reproduce steps; open one adoption PR/issue on a public Filecoin tooling repo; do not claim merge. 2 weeks. $4,000.

No work starts until a grant agreement is signed by both parties. Dates below are offsets from that signature.

## Total Budget Requested

| Milestone # | Description | Deliverables | Completion Date | Funding |
|---|---|---|---|---|
| 1 | Fail-closed CLI | CLI + missing-runtime FAIL tests | Signature + 3 weeks | $4,000 |
| 2 | Calibration cell + Action | Pinned CID check + GitHub Action | Signature + 6 weeks | $4,000 |
| 3 | Docs + one external offer | README + one public adoption offer | Signature + 8 weeks | $4,000 |

Total: $12,000 USD.

## Maintenance and Upgrade Plans

After the grant, the repo stays public under MIT/Apache-2. I will merge failing-test regressions and pin-updates. No promise of a company or full-time maintainer after the window.

# Team

## Team Members

- Stephen Smith (GitHub tzh476) — sole implementer

## Team Member LinkedIn Profiles

None provided.

## Team Website

https://github.com/tzh476

## Relevant Experience

Eight years of professional software engineering, including professional Filecoin work that is not a public repository. Public adjacent work shows the same fail-closed habit this grant needs: https://github.com/tzh476/r-compat-matrix and https://github.com/tzh476/fourproof-bnb. I am not claiming a shipped public FVM contract.

## Team code repositories

- https://github.com/tzh476/r-compat-matrix
- https://github.com/tzh476/fourproof-bnb
- https://github.com/tzh476/prov-lock

# Additional Information

Learned about the program from fil.org/grants.

Best email for agreement and next steps: tzh476@gmail.com

This is an Open Grant for new tooling. It is not a FIL Builder Next Step application and does not claim an existing on-chain FVM project.

No existing repository, files, or tests are identified; the proposal says the new repo should contain the fil-retrieval-matrix CLI, a manifest, self-tests, and a GitHub Action. Start by defining the manifest and missing-runtime and bound-check cases described in Milestone 1. Done means the three stated self-test cells produce the required FAIL or PASS results and the README records reproduction details.

Written by the indexing model from the issue text.