IPIP-0526: Historic Bitswap Provider Publishing API

[lidel]

This IPIP

• does not change any existing specifications
• documents the legacy PUT /routing/v1/providers/ endpoint that only accepts signed Bitswap provider records, originally introduced for index-provider/IPNI integration in 2022
• includes CSS styling for historic IPIP state

Why?

I spent multiple days over the years discussing this (e.g. ipni/index-provider#403), and explaining all the background and history always takes most of the time.

Now, there is a PR I can link to + this allows us to close all issues related to abandoned IPIP #378 and point here as a provisional spec reference if anyone needs to use or discuss this API for legacy reasons.

Should the be merged?

I'm fine either way.

The IPIP has a special state "historic" and clearly states is provided only for archival purposes.

• If we are not planning on standardizing this API, but there won't be anything better to replace it any time soon, we could merge it to have SOMETHING people can reference, but also be vary its provisional and limited in scope and support.

• If we are planning to create alternative any time soon (EOY 2026), it might be ok to keep it as a draft indefinitely, and close without merging when a modern replacement is defined by a different IPIP.

For now, I'm marking it as a draft, we can decide its fate in 2026.

cc @aschmahmann @gammazero

[github-actions]

🚀 Build Preview on IPFS ready

• 🔎 Commit: 243f717
• 🔏 CID bafybeiap3vrfudjkfjbuekoouzpug42ncrxoidvaczpdd2axobar4uaxfu
• 📦 Preview:
  • dweb.link
  • w3s.link
  • inbrowser.link

[Rinse12]

Adding a production use case, since the thread notes that nobody stepped up to make the HTTP provide API a real thing.

I maintain pkc-js, a pubsub-based social protocol built on kubo. Each community node publishes an IPNS record, subscribes to a pubsub topic for that community, and serves a large and constantly growing set of content blocks. Our readers are browsers and light nodes that resolve through delegated HTTP routers, so provider records in HTTP routers are what actually make our content retrievable. We have been running Routing.Type=custom with provide mapped to our own HTTP routers in production for a while. It works, with the caveat that maintainers correctly describe that path as experimental and untested: see ipfs/kubo#11089, where it silently regressed for two releases, precisely because there are no tests and no spec.

What we want to end up with is narrow: the DHT carries only the few keys tied to a community's IPNS and its pubsub swarm (the IPNS-over-pubsub rendezvous CID and the current root), and the HTTP routers carry everything else. Announcing every content block to the DHT is work that nothing in our system reads, and it scales with the whole pinset instead of with the handful of keys that need global reach. Kubo cannot express that split today and I have opened ipfs/kubo#11411 about it, but the config side is not really the blocker: the blocker is that HTTP providing has no spec, so it cannot become a supported path that such a feature could be built on.

Points we would like the IPIP to settle, from an implementer's perspective:

1. Batching and limits. How many CIDs per request, and how a server advertises its own limit. Kubo currently assumes 100 by default via MaxProvideBatchSize.
2. Record lifetime and refresh. Whether announcements expire, and if so how a client learns the TTL rather than guessing a reprovide interval. We re-announce on a fixed interval that is a guess, not a contract.
3. Address handling. What the server may do with the multiaddrs in an announcement, in particular whether it is allowed to filter or rewrite them. This has cost us real debugging time: routers that keep only /ip4-rooted addresses drop the /dns4-rooted AutoTLS WSS addresses, which are the only ones a browser can dial, so the announcement survives but becomes useless to exactly the clients we care about. We ended up running a rewriting proxy in front of the router to work around it. Whatever the spec decides here, please make it explicit rather than implementation-defined.
4. Authentication. Whether announcements are authenticated, and how, so operators can run routers that are not open write endpoints.
5. Idempotency and deletion. Whether re-announcing the same CID is a no-op refresh, and whether there is a way to withdraw an announcement.

Happy to be a test deployment for whatever shape this lands in, and to report back with results.