Skip to content

Content structure refactor #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ocnrb merged 1 commit into from
Aug 25, 2026
Merged

Content structure refactor #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 0 additions & 90 deletions docs/concepts/architecture.md
View file
Open in desktop

This file was deleted.

61 changes: 33 additions & 28 deletions docs/concepts/gated-and-paid-channels.md → docs/concepts/channel-access.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,39 @@
---
id: gated-and-paid-channels
title: Gated and paid channels
description: Membership contracts on Polygon — closed allowlists, token and NFT gates, and subscriptions.
id: channel-access
title: Channel access
description: The five access models, and the membership contracts behind closed, gated and paid channels.
---

# Gated and paid channels
# Channel access

Three of Pombo's five channel types put membership in a **contract on Polygon**: Closed, Gated and Paid. They share one mechanism and differ only in the rule the contract enforces.
Every channel has one of five access models, chosen at creation:

| Type | Who gets in |
|---|---|
| **Closed** | Addresses the owner adds to an allowlist |
| **Gated** | Anyone holding a chosen ERC-20 balance, or any token of a chosen ERC-721 |
| **Paid** | Anyone with an active subscription — a price in a chosen ERC-20, per period |
<div className="matrix-table">

## One contract per channel
| | Open | Protected | Closed | Gated | Paid |
|---|---|---|---|---|---|
| Read access | Everyone | Password holders | Allowlisted addresses | Token / NFT holders | Active subscribers |
| Write access | Everyone | Password holders | Allowlisted addresses | Token / NFT holders | Active subscribers |
| Access enforced by | — (open by design) | Client-side encryption | On-chain gate contract | On-chain gate contract | On-chain gate contract |
| Content on the wire | Signed plaintext (Pombo format) | AES-256-GCM ciphertext | AES-256-GCM under a channel key | Same | Same |
| Cost to join | Free | Free | Free (owner pays gas to add you) | Holding the asset | The subscription price |

Creating any of the three deploys a **PomboGate** — a minimal membership contract, one [EIP-1167 clone](https://eips.ethereum.org/EIPS/eip-1167) per channel, from a shared factory. The clone costs a single transaction at creation and then answers two questions for the rest of the channel's life:
</div>

- **Open channels** are public rooms. Anyone can read and write.
- **Protected channels** look public to the network, but every message is encrypted client-side with AES-256-GCM using a key derived from the shared password (PBKDF2, 310,000 iterations). Without the password, the network carries only ciphertext. One caveat: each protected channel publishes a verification challenge that anyone can fetch and test guesses against offline — so the channel is exactly as secret as the password is strong.
- **Closed, Gated and Paid channels** enforce membership *on-chain*, through a small membership contract deployed per channel. This is the only family where access control is enforceable at the protocol level — the network itself refuses messages from authors the contract does not vouch for — and content is encrypted under a channel key that only members obtain. They differ only in the rule the contract enforces: an owner-managed allowlist, holding a token or NFT, or an active subscription. The rest of this page covers the three in detail.
- A channel can also be created **read-only** (announcement style): everyone can read, only the owner posts.

:::note[Terminology]
Pombo's source code calls the pre-contract generation of closed channels *native channels*. Those still work, but can no longer be created: closed, gated and paid channels are all backed by a gate contract.
:::

Who a channel belongs to, and what its owner can do about behaviour inside it, is the subject of [Ownership and moderation](ownership-and-moderation.md).

## The membership contract

Creating a closed, gated or paid channel deploys a **PomboGate** — a minimal membership contract, one [EIP-1167 clone](https://eips.ethereum.org/EIPS/eip-1167) per channel, from a shared factory. The clone costs a single transaction at creation and then answers two questions for the rest of the channel's life:

- **`isValidSignature`** ([ERC-1271]) — *was this author ever a member?* This is what the Streamr Network checks on every message, which is why the clone, not you, is the channel's publisher on the wire.
- **`checkAccess`** — *does this address have access right now?* This drives encryption-key distribution and what the app shows you; it never invalidates messages already published.
Expand All @@ -27,13 +44,13 @@ The consequence worth internalizing: **membership is sticky.** Being removed fro

Because there is one grantee for every stream — the clone — adding or removing a member is a transaction on the gate, never a change to the channel's on-chain stream permissions. A Closed channel created with ten initial members costs one batched transaction, not ten.

## Closed channels
### Closed channels

The owner (or a moderator) adds and removes Ethereum addresses. Members read and write for free; the owner pays the gas for each membership change.

Closed channels are always **unlisted** — they never appear in Explore, and their name and description stay off-chain. This is the type to use for a private group.

## Token and NFT gates
### Token and NFT gates

The gate reads the member's balance at the moment access is checked:

Expand All @@ -46,32 +63,20 @@ Selling has a second effect that is easy to miss. The same live check is what vo

Registering your membership on-chain is the one-transaction opt-in that prevents this: it records you permanently, so the contract keeps vouching for you as an author whatever you later do with the asset. It does not extend your *access* — that ends when you sell either way. Only the standing of what you already wrote.

## Paid channels
### Paid channels

The owner sets a price in an ERC-20 and a period in days. A subscriber pays, and the contract records an expiry timestamp.

- **The payment goes to the channel owner.** The contract transfers the price straight to them; it takes no fee of its own, and Pombo is not a party to the transaction.
- **Renewing early loses nothing** — a renewal extends from the current expiry, not from the moment you pay.
- **There is no grace period.** Access ends at the recorded timestamp. The app warns you in the three days before, and shows an expired state with a renew action after.
- **Payment is first-person.** The contract deliberately refuses third-party payment: paying for someone else would link payer and beneficiary on-chain forever.
- For tokens that support [EIP-2612](https://eips.ethereum.org/EIPS/eip-2612) permits (such as USDC on Polygon), paying is a single transaction; otherwise it is the usual approve-then-pay pair. Gates priced in POL are settled in wrapped POL, and the app wraps the shortfall for you.
- For tokens that support [EIP-2612](https://eips.ethereum.org/EIPS/eip-2612) permits (such as USDC on Polygon), paying is a single transaction; otherwise it is the usual approve-then-pay pair. Prices set in POL are settled in wrapped POL, and the app wraps the shortfall for you.

:::caution[A subscription buys the future, not the past]
New subscribers receive only the channel's **current** encryption key, so history published before they joined does not open for them — including files. This is deliberate: without it, one month's subscription would buy everything the channel ever said. See [Encryption](encryption.md#closed-gated-and-paid-channels).
:::

## Moderation

Bans here are the enforceable kind: the contract stops vouching for the address, and the network stops accepting its messages. This is the difference the whole family exists for — elsewhere a ban is [advisory](channels-and-ownership.md#moderation).

Owners can also appoint **moderators**, who add, remove and ban members but cannot erase history, act on the owner or other moderators, or appoint anyone themselves.

## Discovery

Gated and paid channels are the only private types that can be **listed** in Explore. They show their name, description, image and access marker — the condition or the price — so someone can see what they would be joining before acquiring anything. The conversation itself stays encrypted: a listing is a shop window, not a preview.

Closed channels are never listed, whatever the owner picks. The general rules for discovery and curation are in [Channels and ownership](channels-and-ownership.md#discovery-and-curation).

## Honest limits

- **Revocation is not instant.** Encryption keys rotate on a weekly cadence, so someone who sells the gate asset or lets a subscription lapse can still read new messages until the next rotation — and rotations happen only while the channel's admin is online. The contract cuts them off immediately for everything the *contract* controls; the key layer catches up afterwards.
Expand Down
Loading