Cowrie Research

bubble-protocol-primary-sources-2026-05-13

3 min read

Bubble Protocol primary sources — 2026-05-13

Project status in this pass

  • Bubble Protocol’s clearest accessible primary materials in this pass were the official site plus the Bubble SDK README, client-library README, server-library README, and the core AccessControlledStorage contract interface.
  • The official whitepaper PDF was downloadable and saved locally as bubble-protocol-whitepaper.pdf, but the strongest directly reviewable signal in this pass came from the SDK and site path.
  • The main reason Bubble matters for the corpus is that it makes an onchain-governed offchain-storage stack unusually legible: permission authorship, request validation, storage execution, content addressing, and encryption can all be analyzed as separate layers.

Primary-source snapshots

1) Official site

  • URL: https://bubbleprotocol.com/
  • Key excerpts/signals:
    • Frames Bubble as Private Off-Chain Data Management with On-Chain Security.
    • Highlights use cases such as private DApp storage, data tokenization, social media, paywalls, and NFT-controlled storage.
    • Says access controls are POSIX-like and held in custom smart contracts.
    • Presents governance only at the project level while the protocol pitch itself is about data control and storage policy.
  • Why it mattered:
    • This page is the clearest concise statement that Bubble is selling onchain-governed data access, not just a hosted storage product.

2) Bubble SDK top-level README

  • URL: https://raw.githubusercontent.com/Bubble-Protocol/bubble-sdk/main/README.md
  • Key excerpts/signals:
    • Describes Bubble Protocol as access-controlled off-chain storage for Web3 applications.
    • Says blockchains can govern private data and that Bubble can add Web3 capabilities to any storage system.
    • Explains the core mechanism: a smart contract controls a bubble, a globally unique content ID names each off-chain item, and application logic stays onchain while storage stays offchain.
    • Defines a bubble as the set of content controlled by a contract implementing AccessControlledStorage.
  • Why it mattered:
    • This README gives the best high-level explanation of Bubble’s separation between policy and storage.

3) AccessControlledStorage interface

  • URL: https://raw.githubusercontent.com/Bubble-Protocol/bubble-sdk/main/contracts/AccessControlledStorage.sol
  • Key excerpts/signals:
    • Any contract implementing the interface can control off-chain storage.
    • getAccessPermissions(address user, uint256 contentId) returns permission bits for a file or directory.
    • Reserved IDs define the root of the bubble and directory semantics.
    • Permission bits are POSIX-like (tdrwax).
  • Why it mattered:
    • This is the simplest and most important source for understanding Bubble’s core policy interface: one permission-check method governs off-chain actions.

4) Server library README

  • URL: https://raw.githubusercontent.com/Bubble-Protocol/bubble-sdk/main/packages/server/README.md
  • Key excerpts/signals:
    • Splits server responsibilities into the Guardian and the DataServer.
    • The Guardian validates bubble requests, checks syntax and structure, confirms user permissions via the contract, and rejects malformed or denied requests.
    • The DataServer is user-defined and can serve data from a filesystem, database, CMS, decentralized storage network, or other infrastructure.
    • Optional subscriptions and notification flows can be layered in through websocket support and notification managers.
  • Why it mattered:
    • This README makes Bubble’s most useful architecture explicit: enforcement middleware is separate from actual storage execution.

5) Client library README

  • URL: https://raw.githubusercontent.com/Bubble-Protocol/bubble-sdk/main/packages/client/README.md
  • Key excerpts/signals:
    • Exposes different interaction layers: ContentManager, Bubble, BubbleFactory, and DeployableBubble.
    • Supports encrypted bubbles, multi-user encrypted bubbles, and user-encrypted bubbles with per-user metadata files.
    • Uses signed requests from local or external wallets to authorize private reads and writes.
    • Defines content IDs as globally unique identifiers containing chain, contract, provider, and optional file fields.
  • Why it mattered:
    • This page shows how Bubble turns the protocol into developer-facing patterns for encryption, deployment, and multi-user access.

Working conclusion

Bubble Protocol is best cataloged as onchain-governed offchain-storage middleware whose main reusable mechanism is the separation of contract-authored permission policy, Guardian-side request validation, pluggable storage backends, stable content IDs, and optional encryption/notification layers. The decisive signal is not merely private storage for Web3, but the way Bubble makes policy authorship and storage enforcement explicit enough to compare against local-first storage stacks, token-gated content systems, and off-chain application backends.

Graph View