Skip to main content

🌐 S3 and IPFS Semantics

S3 is a mutable, path-addressed API. IPFS and Filecoin are immutable, content-addressed storage. Lighthouse S3 bridges the two with a metadata index that maps every (bucket, key) to a CID. Understanding this mapping explains everything that behaves differently from Amazon S3 — and unlocks some things Amazon can't do.

PUT s3://bucket/key  ──▶  index: bucket/key → CID  ──▶  bytes stored on Lighthouse
GET s3://bucket/key  ──▶  look up CID              ──▶  fetch by CID

Every object has a CID​

All object responses carry x-amz-meta-cid — the IPFS content identifier of the stored bytes:

s3 s3api head-object --bucket my-bucket --key photo.jpg --query 'Metadata.cid' --output text
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

You can use it for integrity proofs, cross-referencing with the Lighthouse dashboard and IPFS tooling, or public distribution via IPFS gateways.

Overwrites create new CIDs​

Uploading new content to an existing key updates the mapping to a new CID. The previous content still exists at its old CID — content-addressed data is never modified in place. (An object versioning API exposing this history is planned; the CIDs are already retained.)

Copy is instant​

CopyObject never moves bytes: the destination key simply points at the source's CID. Copying a 5 GB object takes the same few milliseconds as copying a 5 KB one.

⚠️ Delete removes the mapping, not the data​

This is the most important difference from Amazon S3. DeleteObject removes the key → CID mapping, so the object disappears from the S3 API. But:

  • The bytes remain on IPFS/Filecoin for as long as the storage deals persist.
  • Anyone who already knows the CID can still fetch the content from the IPFS network.
  • Since every response exposes the CID, treat CIDs of private objects as capabilities — like presigned URLs that don't expire.
Storing sensitive data?

If you need true deletion semantics, encrypt before upload (client-side, or see Lighthouse's encrypted upload features). Deleting the key of an encrypted object makes the remaining ciphertext permanently unreadable — that's cryptographic erasure, and it's the only kind that content-addressed storage can offer.

Filecoin persistence​

Files uploaded through the S3 API get the same Filecoin deal treatment as any other Lighthouse upload — verifiable, long-term storage backed by the Filecoin network, visible in your Lighthouse dashboard alongside files uploaded via SDK or API.