Core concepts

IPFS and content addressing

IPFS stores files by their CID (Content Identifier) — a cryptographic hash of the content itself. The same bytes always produce the same CID, so retrieval is verifiable by design.

Kubo

Kubo is the reference Go implementation of IPFS. Meshkit communicates with Kubo over its HTTP RPC API (default: http://127.0.0.1:5001). You must have Kubo installed and running, or let Meshkit start it for you with localNode: true.

Pinning

By default, Kubo may garbage-collect content it no longer references. Pinning marks a CID as permanent — Kubo will keep it until you unpin it. Always pin content you care about:

await meshkit.pin(cid);

IPNS

IPFS CIDs are immutable — changing the content produces a new CID. IPNS (InterPlanetary Name System) lets you create a stable, mutable pointer (a named key) that can be updated to point to new CIDs over time.

/ipns/<key-id>  →  /ipfs/<cid>  (can change)

Meshkit exposes IPNS through publishName, resolveName, resolveAndRetrieve, generateKey, and listKeys.

Multi-node failover

Meshkit accepts multiple Kubo URLs. At init(), it health-checks every node and builds a priority-ordered list of healthy ones. Every operation is tried on the first available node; if it fails, the next is tried automatically.

const { meshkit } = await init({
  nodes: [
    'http://127.0.0.1:5001',      // primary
    'https://backup.example.com:5001', // failover
  ],
});

meshkit.activeNodes returns the currently healthy URLs in priority order.

Local daemon lifecycle

When localNode: true, Meshkit either spawns a fresh Kubo process or attaches to an existing one on the default port. The returned IPFSNodeHandle tells you:

• handle.managed — true if Meshkit spawned it (you should stop it on shutdown)
• handle.url — the RPC URL
• handle.stop() — stop the daemon (only meaningful when managed: true)

Use setupGracefulShutdown to stop it automatically on SIGINT/SIGTERM.