Metadata Service
The MeshKit metadata routes that stock IPFS nodes do not provide.
MeshKit production workflows need metadata beside encrypted provider bytes. A stock IPFS node can store and retrieve bytes, but it does not automatically provide MeshKit proofs, capsules, mailboxes, sync jobs, vaults, capabilities, logs, or policy state.
The metadata service is the part of a provider boundary that stores those MeshKit-specific records.
Why Raw IPFS Is Not Enough
| Workflow | Needs encrypted bytes | Also needs metadata |
|---|---|---|
| Read by CID | Yes | Proof and envelope metadata |
| Share content | Yes | Capsule and revocation state |
| Send messages | Yes | Mailbox records |
| Sync offline work | Sometimes | Durable sync job records and checkpoints |
| Use vaults or capabilities | Yes | Vault and capability records |
| Audit provider behavior | Yes | Logs, health checks, proof summaries |
If you only configure raw byte storage, some workflows will store content but fail later when they need MeshKit metadata.
Boundary Diagram
The byte store and metadata service can be implemented by the same provider or by coordinated services. The important requirement is that your app reads from the same boundary that wrote the object.
What The Metadata Service Stores
- Proof records
- Share capsules
- Revoked capsule IDs
- Message mailbox entries
- Sync jobs and checkpoints
- Vault records
- Capability records
- Provider logs
- Health check results
Metadata can reveal operational relationships even when content is encrypted. Treat it as sensitive application data.
Production Checklist
Before production:
- Decide which service stores encrypted bytes.
- Decide which service stores MeshKit metadata.
- Ensure both services use the same environment, tenant, and retention model.
- Keep provider and metadata tokens out of source control.
- Run write, read, proof, share, message, sync, and cleanup validation for the workflows you ship.
- Record which validation output proves the environment is ready.
Common Failures
| Symptom | Likely cause | Action |
|---|---|---|
| Bytes exist but read fails | Proof or envelope metadata missing | Check metadata service routing and retention |
| Share capsule missing | Capsule was never written or metadata store differs | Recreate or migrate capsule metadata |
| Message inbox empty | Provider does not support mailbox records | Use a provider with mailbox support |
| Sync unsupported | Provider lacks sync job storage | Configure a provider with durable sync queues |
| Local works, Kubo fails | Kubo stores bytes but no MeshKit metadata API is configured | Add a MeshKit-compatible metadata service |