Pinning Service

PinningServiceProvider wraps a backing storage provider with a remote pin lifecycle. MeshKit first stores encrypted bytes through the backing provider, then asks the pinning service to pin the resulting CID.

Pinning improves retention. It does not replace byte storage, MeshKit metadata, identity, sharing, or retrieval validation.

Config

{
  "version": 1,
  "provider": {
    "type": "pinning-service",
    "endpoint": "https://pinning.internal.example",
    "tokenEnv": "MESHKIT_PINNING_TOKEN",
    "storage": {
      "type": "ipfs-http",
      "ipfsApiUrl": "https://ipfs-api.internal.example",
      "metadataApiUrl": "https://meshkit-metadata.internal.example",
      "tokenEnv": "MESHKIT_PROVIDER_TOKEN"
    }
  }
}

Direct construction:

import { createMeshkit, HttpIpfsProvider, PinningServiceProvider } from "@meshkit/core";

const storage = new HttpIpfsProvider({
  ipfsApiUrl: process.env.MESHKIT_IPFS_API!,
  metadataApiUrl: process.env.MESHKIT_METADATA_API!,
  token: process.env.MESHKIT_PROVIDER_TOKEN,
});

const provider = new PinningServiceProvider({
  storage,
  endpoint: process.env.MESHKIT_PINNING_ENDPOINT!,
  token: process.env.MESHKIT_PINNING_TOKEN,
});

const mesh = await createMeshkit({ provider });

What To Validate

• The backing storage provider can write and read encrypted bytes.
• The MeshKit metadata service records proofs and workflow metadata.
• The pinning endpoint accepts the CID and reports expected status.
• Unpin semantics match your retention policy.
• Quota, billing, auth, and rate limits are known.

Common Mistakes

• Treating pinning as a replacement for the backing storage provider.
• Pinning a CID but losing the MeshKit metadata needed to open it.
• Using one token for pinning and storage when the services should have different privileges.
• Assuming a pinned CID means the object is authorized for every identity.

Validation

MESHKIT_LIVE_PINNING=1 MESHKIT_PINNING_ENDPOINT=https://pinning.example MESHKIT_PINNING_TOKEN=... npm run providers:pinning:live

By default, the validator can use local-dev storage to test adapter credentials. Set MESHKIT_PINNING_STORAGE=ipfs-http plus Kubo variables to validate pinning after a real IPFS write.

Next Steps

• Provider model
• Production setup
• IPFS HTTP / Kubo