Skip to content

README.md

Latest commit

 

History

History
70 lines (50 loc) · 4.84 KB

README.md

File metadata and controls

70 lines (50 loc) · 4.84 KB
Raw

Documentation

docs/
├── getting-started/   — quickstart
├── reference/         — derived / how-it-works docs (accurate, not gated)
├── design/            — canonical system design (review-gated)
├── drafts/            — unratified / WIP notes (need triage)
└── filesystems/       — Layer 1 file system interface
  • design/ — the source of truth; changes require design-owner review (see .github/CODEOWNERS).
  • reference/ — accurate but derived material (flow walkthroughs, API refs). Kept in sync with the design, but not itself design-of-record, so it is not review-gated.
  • drafts/ — unratified / WIP notes; treat as provisional. Each needs triage: promote to design/ or reference/, fold into an existing doc, or drop.

Getting started

  • Layer 1 Quick Start — three-terminal setup (chain → provider → demo) plus SDK examples for the file-system and S3 interfaces. The canonical entry point.
  • FILE_SYSTEM_QUICKSTART.md — short version, file-system layer only.
  • CLAUDE.md (repo root) — build/test/run commands and contributor guidelines.

Reference

  • Extrinsics Reference — every pallet extrinsic with parameters, errors, and example workflows.
  • Payment Calculator — payment = price_per_byte × max_bytes × duration, with worked examples.
  • Execution Flows — sequence-by-sequence walkthroughs of the main flows (derived from the design; no design-owner sign-off needed).

Design

The canonical system design. Changes require review (see .github/CODEOWNERS).

  • Scalable Web3 Storage — architecture, economic model, comparisons with Filecoin/IPFS/Arweave, rebuttals to common review concerns.
  • Implementation Details — pallet extrinsics, provider HTTP API, MMR layout, challenge mechanism, replica sync.

Drafts

Unratified / WIP notes. These need triage (#308) — each should be reviewed and either promoted into design/ (design-of-record) or reference/ (accurate derived material), folded into an existing doc, or dropped.

  • Layer 1 Design / Implementation — file-system & S3 provider interfaces on top of Layer 0 (split out of the Layer 0 implementation doc); triage tracked in #51.
  • Smart Contracts — pallet_revive integration, custom precompile ABI, address mapping, payment flow. Candidate for promotion to reference/ (it's API-reference material, not a draft design).
  • Marketplace — provider capacity, discovery, and matching.
  • Checkpoint Protocol — multi-provider checkpoint coordination.
  • Provider-Initiated Checkpoints — extension where providers proactively commit state; removed in #306, archived (design + implementation) for potential re-evaluation.
  • Client-Side Encryption — wire format, cipher choice.
  • S3 Metadata Index — how prefix/delimiter queries are served.
  • Challenge Economics — Extensions — speculative "Capped Split for the general public"; also records that the design's two-tier challenger split isn't implemented yet.

Layer 1 — file system interface

  • Layer 1 README — sub-index for the file-system layer.
  • Architecture — encoding, security, blockchain integration.
  • User Guide — drive creation, file/dir operations, configuration.
  • Admin Guide — operations, monitoring, dispute resolution.
  • API Reference — extrinsics, SDK methods, primitives, events, errors.

Clients

  • Storage Client SDK — Layer-0 Rust client.
  • S3 Interface — Layer-1 S3-compatible Rust client.
  • TypeScript SDK — @web3-storage/sdk at packages/sdk (./fs, ./s3, ./revive subpaths).

External

License

See the repository root README.