> For the complete documentation index, see [llms.txt](https://docs.molecule.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.molecule.xyz/technical-deep-dive/data/data-storage.md).
# Data Storage
### How Storage Works
Every file uploaded to a Lab passes through a layered storage pipeline that encrypts, distributes, versions, and references data across multiple decentralised systems. The result is a file that is encrypted before it leaves the researcher's browser, pinned to a content-addressed network for retrieval, persisted permanently independent of any single provider, versioned with full provenance history, and referenced onchain in the Lab's Token Bound Account.
### Upload Flow
When a researcher uploads a file to a Lab, the following sequence occurs:
**Authenticate.** The researcher authenticates with their wallet (Privy JWT) or a service token, establishing a session with the Molecule API that permits uploads to the target Lab.
**Prepare.** The client computes a content hash checksum of the raw file. If the file is confidential (access level Token-Holder or Admin-Only), the client encrypts it client-side before upload, so the bytes that leave the browser are already ciphertext; Public files proceed unencrypted. Either way, the content hash and any encryption metadata travel with the file into the storage pipeline. The client-side encryption and key-management model is documented in [Data Privacy & Access](/technical-deep-dive/data/data-privacy-and-access.md); this page covers what happens to the bytes once they enter the pipeline.
**Upload.** The client initiates the upload through the Molecule API, which reserves an upload slot and returns a pre-signed upload URL. The encrypted file is uploaded directly from the browser to the pre-signed URL with progress tracking.
**Commit.** Once the upload completes, Kamu fetches the file from staging, creates a new version record (recording the timestamp, content hash, author, and data room path), and commits the file to IPFS via the pinning service. IPFS returns a content identifier (CID) derived from the file's contents. The file is also persisted to Arweave for permanent availability. The temporary staging file is deleted.
**Reference.** The CID and associated metadata are written onchain to the Lab's Token Bound Account. This creates a tamper-evident, publicly auditable link between the Lab's onchain identity and the offchain file. The transaction is timestamped and signed, becoming part of the Lab's activity log.
**Record.** Kamu stores the full file record — including the file DID, the Lab identifier, encryption metadata, access level, content hash, and version information — in its provenance database. The Molecule API stores a corresponding application record linking the file to the Lab's data room.
### Content Addressing
Every file stored through the pipeline receives a content identifier (CID) — a cryptographic hash derived from the file's contents using IPFS's multihash format. The CID serves as both the file's address and its integrity proof: requesting a CID from any IPFS node guarantees that the returned content is exactly what was originally stored. If even a single byte of the underlying file changes, the CID changes, and the onchain reference in the Lab's token bound account becomes a mismatch — making tampering immediately detectable.
Because CIDs are deterministic, the same file uploaded by different researchers at different times will always produce the same identifier. This property enables deduplication across the network and allows independent verification of data integrity without trusting any specific storage provider.
### Versioning and Provenance
Kamu maintains a complete, append-only history of every dataset in every Lab. When a file is uploaded, updated, or modified, Kamu creates a new version record that preserves the previous version's CID alongside the new one. No version is ever overwritten or deleted — the full lineage is permanently retrievable.
Each version record includes the content hash, the timestamp, the author's decentralised identifier (DID) linked to their wallet address, the data room path, and a reference to the previous version. This creates a verifiable provenance chain from the current state of any dataset back to its original upload. When a collaborator, funder, or reviewer needs to verify when data was created, who created it, or how it evolved over time, the evidence is in Kamu's version graph.
Kamu also records activity events — file access, metadata changes, announcements, and other Lab actions — providing a broader context for the dataset's history beyond just version changes.
### Permanent Persistence
IPFS provides content-addressed retrieval, but it does not guarantee permanent availability on its own. If every node that pins a file goes offline, the file becomes unreachable — the CID still exists as an address, but nothing answers the request.
Molecule Labs solve this by persisting files to Arweave in addition to IPFS. Arweave is a permanent, pay-once storage network — once a file is written, it remains available indefinitely regardless of whether any individual node or service continues operating. This dual-storage approach means files are retrievable from IPFS for fast, everyday access, and backed by Arweave for permanent, censorship-resistant availability.
Even if a file record is removed from a Lab's data room index, the underlying content persists on both IPFS (as long as it remains pinned) and Arweave (permanently). Because confidential files are encrypted before upload, this persistence does not compromise confidentiality — the ciphertext is publicly retrievable but unreadable without a key release, which is gated by onchain access checks (see [Data Privacy & Access](/technical-deep-dive/data/data-privacy-and-access.md)).
### E2E Upload Flow
### Storage Summary
| Data Type | Where Stored | Managed By | Purpose |
| -------------------------- | ----------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Research files (encrypted) | IPFS + Arweave | Filebase (upload), Kamu (versioning) | Decentralised, permanent, content-addressed |
| Onchain data references | Lab's Token Bound Account | Smart contract | Tamper-evident CID pointers and metadata |
| tokenURI pointer | Onchain (Lab TBA) | Lab smart contract | Permanent reference to the LabNFT's display metadata |
| File versions | Kamu provenance DB | Kamu | Append-only version history and audit trail |
| Encryption metadata | In the file's encryption metadata on Kamu (ODF) | Onchain-Verified Envelope Encryption | Wrapped per-file DEK + access conditions; key custody and decryption rules are covered in [Data Privacy & Access](/technical-deep-dive/data/data-privacy-and-access.md) |
| File provenance | Kamu provenance DB | Kamu | DID-based authorship, timestamps, lineage |
| Activity events | Kamu provenance DB + onchain | Kamu + Lab TBA | Access logs, metadata changes, announcements |