Proofs And CIDs
How MeshKit verifies integrity and records provider operations.
A MeshKit CID identifies encrypted envelope bytes or an encrypted stream manifest. It is not a plaintext hash of your application content.
Proofs record how a provider handled that CID: provider name, byte count, envelope version, algorithms, operations, timestamps, and verification state.
CID Flow
MeshKit verifies the returned bytes before it decrypts. If the bytes do not match the expected CID, the read fails before plaintext is returned.
What A CID Proves
| Claim | Does a CID prove it? | Notes |
|---|---|---|
| These exact encrypted bytes were addressed | Yes | That is the content-addressed property |
| The plaintext has a specific value | Not by itself | MeshKit encrypts before storage |
| The provider is healthy | No | Use doctor checks and provider validation |
| A recipient is authorized | No | Authorization is checked through identity, capsule, policy, vault, or capability state |
| Filecoin retrieval is guaranteed | No | Deal state and retrieval behavior are separate |
Proof Records
Use proofs when you need operational evidence:
const file = await mesh.files.put("report.txt", "private report");
const proof = await mesh.proofs.get(file.cid);
console.log({
cid: file.cid,
provider: proof.provider,
verified: proof.verified,
});Proofs are useful for debugging, audit trails, and validating production environments. Store proof summaries when later audit matters, but do not treat proofs as plaintext evidence.
Gateway Retrieval
Gateways can return bytes for a CID, but MeshKit should still verify the bytes before decrypting. A gateway response is useful only after the returned bytes match the expected CID and the metadata boundary can authorize the open.
Common Mistakes
- Treating a MeshKit CID as a hash of plaintext.
- Copying a CID between environments without copying the required MeshKit metadata.
- Trusting a gateway response before CID verification.
- Treating an active Filecoin deal as a retrieval guarantee.
- Dropping proof summaries when later compliance or support workflows need them.
Failure Modes
| Symptom | Meaning | Action |
|---|---|---|
| CID verification fails | Returned bytes do not match the requested CID | Check provider or gateway integrity |
| Proof missing | Metadata service does not know this CID | Confirm the same MeshKit provider boundary created it |
| Decryption fails after verification | Current identity cannot unwrap the key | Check identity or share capsule |
| Proof exists but read fails | Bytes and metadata are out of sync | Validate storage, gateway, and metadata retention |