IPIP-0526: Historic Bitswap Provider Publishing API - #526
Conversation
documents the legacy PUT /routing/v1/providers/ endpoint for signed Bitswap provider records, originally introduced for index-provider/IPNI integration. includes CSS styling for historic IPIP state.
🚀 Build Preview on IPFS ready
|
|
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 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:
Happy to be a test deployment for whatever shape this lands in, and to report back with results. |
Style historic IPIPs through ipseity's variable hooks instead of overriding selectors: the TOC keeps body-text color, links meet WCAG AA (4.8:1), and note/warning borders reuse --note-colour and --warning-colour. Add the missing pre box-shadow override that left a blue sliver next to the brown border, and drop the unused --highlight-colour-faded.
Align the endpoint documentation with boxo v0.35.2 and known deployments, and add reproducible test vectors so existing users have an interoperability reference. - error codes: drop unused 422, add 500 delegate errors, document non-atomic processing and the crash on missing Timestamp/AdvisoryTTL - signature: exact signed bytes (SHA-256 of payload as sent), multibase encoding, identity-multihash key limitation, verification as server policy that some deployments skip - example replaced with a valid Ed25519 signature; signed and unsigned fixtures with reproducible key material in Test fixtures - known users: index-provider (single provider identity) and Bitsocial trackers (previously Plebbit), with pkc-js and pkc-http-router links - request headers, CIDv0 keys, Protocol echo-only, response TTL source
Answer implementer questions from PR review: request limits, refresh cadence, address policy, deletion, and HTTP-level auth are undefined by the API; record the observed Kubo and index-provider behavior for each so servers stop inferring a contract from one deployment.
|
Thanks for these @Rinse12. The honest answer to most of them is "unspecified and left to the server": there are no protocol-level limits, no address-handling rules, no withdrawal, and nothing consumes the returned TTL; authentication is the record signature alone, with enforcement being server policy. Rather than answering at length here, I folded all five into the IPIP: see the new "Unspecified Behavior" section and the updated Signature and Response sections, which record what Kubo and index-provider actually do for each. To be upfront about scope: with the time I have, documenting this API precisely, with test vectors, is as far as I can take it. Fixing the gaps needs an IPIP-378-style successor and someone with bandwidth to drive it; this document is meant to give them a running start, and your list is good input for that. Could you give the IPIP a final review? If it looks sensible and accurate from your side, I'm fine merging it. |
This IPIP
PUT /routing/v1/providers/endpoint that only accepts signed Bitswap provider records, originally introduced for index-provider/IPNI integration in 2022Why?
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