IPNS

Publish mutable pointers, manage named keys, and resolve IPNS names with Meshkit.

IPNS lets you create a stable name that can be updated to point to new CIDs over time, so consumers always resolve to the latest version.

Generate a key

Before publishing, create a named key in the Kubo keystore:

import { init } from '@ipfs-meshkit/meshkit';

const { meshkit } = await init({ localNode: true });

const key = await meshkit.generateKey('latest');
console.log(key.id);   // /ipns/Qm... (use this as the stable name)
console.log(key.name); // "latest"

The built-in "self" key (derived from the node's PeerID) is always available without generating a new one.

Publish a record

import { IPNS_TTL_FAST } from '@ipfs-meshkit/meshkit';

const bytes = new TextEncoder().encode('version 1');
const cid = await meshkit.upload(bytes);
await meshkit.pin(cid); // publishName does not pin — do it yourself

const { name, value } = await meshkit.publishName(cid, {
  key: 'latest',
  ttl: IPNS_TTL_FAST, // "1m" — fast cache hint for resolvers
});

console.log(`/ipns/${name}  →  ${value}`);

Resolve a name

const path = await meshkit.resolveName(`/ipns/${key.id}`);
console.log(path); // /ipfs/Qm...

Resolve and retrieve in one call

const bytes = await meshkit.resolveAndRetrieve(`/ipns/${key.id}`);
console.log(new TextDecoder().decode(bytes)); // version 1

Update the pointer

Republish with the same key to point to a new CID:

const updated = new TextEncoder().encode('version 2');
const newCid = await meshkit.upload(updated);
await meshkit.pin(newCid);

await meshkit.publishName(newCid, { key: 'latest' });
// /ipns/<key.id> now resolves to the new CID

List keys

const keys = await meshkit.listKeys();
// [{ id: '...', name: 'self' }, { id: '...', name: 'latest' }]

TTL constants

Constant	Value	Use
`IPNS_TTL_FAST`	`"1m"`	Frequent updates — short resolver cache
`IPNS_TTL_DEFAULT`	`"1h"`	Stable content — reduce resolution traffic

TTL is a hint to resolvers. It does not guarantee propagation timing.

Publish options

Option	Type	Default	Description
`key`	`string`	`"self"`	Keystore label
`lifetime`	`IpnsDuration`	~48h	Record validity window
`ttl`	`IpnsDuration`	—	Cache hint for resolvers
`resolve`	`boolean`	`true`	Resolve `value` before publishing

On this page