Labels: documentation, enhancement
The window.swarm provider has no published specification. A dApp author's only source of truth is the implementation: src/main/swarm/swarm-provider-ipc.js (1491 lines) plus the renderer shim in src/renderer/lib/swarm-provider.js.
git ls-files turns up no provider document, and window.swarm appears in tracked markdown only in CHANGELOG.md. The surface itself is KNOWN_METHODS (swarm-provider-ipc.js:79-95), fifteen methods:
swarm_requestAccess swarm_getCapabilities swarm_getSigningIdentity
swarm_publishData swarm_publishFiles swarm_getUploadStatus
swarm_publishChunk swarm_readChunk
swarm_createFeed swarm_updateFeed swarm_listFeeds
swarm_writeFeedEntry swarm_readFeedEntry
swarm_writeSingleOwnerChunk swarm_readSingleOwnerChunk
Why the code isn't a substitute
Most of a provider API is guessable from method names. The parts that aren't are exactly the parts that are only in the source:
- Which methods need consent, and which don't.
swarm_readChunk is permission-free (:716), and swarm_readFeedEntry is too, with the reasoning in a comment — "no permission required. Feeds are public Swarm" (:282). A caller cannot infer that, so they'll either gate reads behind a consent prompt they don't need or assume writes are free.
- Error codes. The provider is JSON-RPC-shaped with codes like
INVALID_PARAMS: -32602 and INTERNAL_ERROR: -32603 (:75-77), plus semantic reasons raised from the services (e.g. chunk_not_found, chunk_type_mismatch in chunk-service.js). Callers need these to distinguish "retry" from "give up" from "ask the user."
- Cross-origin isolation rules. Tag ownership is tracked per origin so
getUploadStatus can't be used to snoop other origins' tags (:97-99). That's a deliberate security property no consumer would know to rely on.
- Signing identity model.
feed-store.js supports three identity kinds — bee-wallet, app-scoped (derived at m/44'/73406'/{index}'/0/0), and ethereum-wallet — and identity survives permission revocation. A dApp that writes feeds needs to know which key it's getting and whether it's stable.
What I'd propose
docs/swarm-provider-api.md covering, per method: params, return shape, permission tier, and error codes; plus a short section on the identity model and the origin-isolation guarantees.
I'm happy to draft it as a PR generated from the IPC surface rather than filing this and leaving it — a spec is more useful as a patch than a request. I'd extract it from swarm-provider-ipc.js and its test file (swarm-provider-ipc.test.js, 1900 lines, which pins much of the behaviour) and mark anything I'm inferring rather than reading, for a maintainer to correct.
Note
Per the project-state notes in canopy's docs/STATE.md, a docs/radicle-provider-api.md was written for the sibling radicle provider on a local branch. Nothing like it is in this tree for either provider, so I'm citing that as evidence the intent exists, not as an existing precedent to match.
Related: I'd use this to add window.swarm coverage to swarm-quickstart-skills, whose dApp-building guide currently doesn't mention the provider at all — the two gaps are each other's fix.
Labels: documentation, enhancement
The
window.swarmprovider has no published specification. A dApp author's only source of truth is the implementation:src/main/swarm/swarm-provider-ipc.js(1491 lines) plus the renderer shim insrc/renderer/lib/swarm-provider.js.git ls-filesturns up no provider document, andwindow.swarmappears in tracked markdown only inCHANGELOG.md. The surface itself isKNOWN_METHODS(swarm-provider-ipc.js:79-95), fifteen methods:Why the code isn't a substitute
Most of a provider API is guessable from method names. The parts that aren't are exactly the parts that are only in the source:
swarm_readChunkis permission-free (:716), andswarm_readFeedEntryis too, with the reasoning in a comment — "no permission required. Feeds are public Swarm" (:282). A caller cannot infer that, so they'll either gate reads behind a consent prompt they don't need or assume writes are free.INVALID_PARAMS: -32602andINTERNAL_ERROR: -32603(:75-77), plus semantic reasons raised from the services (e.g.chunk_not_found,chunk_type_mismatchinchunk-service.js). Callers need these to distinguish "retry" from "give up" from "ask the user."getUploadStatuscan't be used to snoop other origins' tags (:97-99). That's a deliberate security property no consumer would know to rely on.feed-store.jssupports three identity kinds —bee-wallet,app-scoped(derived atm/44'/73406'/{index}'/0/0), andethereum-wallet— and identity survives permission revocation. A dApp that writes feeds needs to know which key it's getting and whether it's stable.What I'd propose
docs/swarm-provider-api.mdcovering, per method: params, return shape, permission tier, and error codes; plus a short section on the identity model and the origin-isolation guarantees.I'm happy to draft it as a PR generated from the IPC surface rather than filing this and leaving it — a spec is more useful as a patch than a request. I'd extract it from
swarm-provider-ipc.jsand its test file (swarm-provider-ipc.test.js, 1900 lines, which pins much of the behaviour) and mark anything I'm inferring rather than reading, for a maintainer to correct.Note
Per the project-state notes in canopy's
docs/STATE.md, adocs/radicle-provider-api.mdwas written for the sibling radicle provider on a local branch. Nothing like it is in this tree for either provider, so I'm citing that as evidence the intent exists, not as an existing precedent to match.Related: I'd use this to add
window.swarmcoverage to swarm-quickstart-skills, whose dApp-building guide currently doesn't mention the provider at all — the two gaps are each other's fix.