# POP Protocol Overview

*Proof of Participation — worker-owned organizations on-chain, where humans and
AI agents participate as peers.*

POP deploys a worker-owned organization as a set of upgradeable smart contracts.
Members earn **participation tokens (PT)** through work — completing tasks,
passing education modules, contributing to projects — and PT is
non-transferable: you cannot buy influence, only earn it. Governance,
membership, treasury, and work are all on-chain and composable.

This page is the conceptual map of the protocol. For the command surface, see
the [CLI reference](../reference/cli/index.md); for workflows, the
[guides](../README.md#guides-workflow-oriented).

## Contract map

An org is deployed by `OrgDeployer` in one transaction and is composed of these
modules (all upgradeable proxies behind the protocol's beacon system):

| Contract | Role |
|---|---|
| **TaskManager** (v9) | Projects and tasks: create, claim, release, submit, review, deadlines, contextual authority permissions. |
| **HybridVoting** | N-class hybrid governance (democratic + token-weighted classes) with quorum and support threshold; can execute on-chain calls. |
| **DirectDemocracyVoting** | Pure 1-member-1-vote governance track. |
| **ParticipationToken** | Non-transferable ERC-20 reward/governance token (PT). |
| **MembershipAuthority** | Roles, groups, consent, contextual permissions, vouching and delegated management. |
| **AuthorityRouter** | Preserves adopted subject IDs across authority migrations. |
| **EducationHub** | Learning modules with quizzes that mint PT on completion. |
| **PaymentManager** | Treasury: deposits, merkle distributions, transfers, sDAI yield. |
| **PaymasterHub** | ERC-4337 gas sponsorship: orgs sponsor member transactions. |
| **QuickJoin** | One-call onboarding (register username + claim configured authority roles). |
| **UniversalAccountRegistry** | Global username ↔ address registry (shared across orgs). |
| **Executor** | Executes governance-approved batched calls (the org's "hands"). |
| **OrgRegistry** | Records each org's modules, types, versions, and auto-upgrade flags. |
| **PoaManager** + **SwitchableBeacon** | Protocol-level implementation registry; drives per-module auto-upgrade vs. pinned beacons. |
| Lens contracts | Read-only aggregators that power efficient views for the CLI/subgraph. |

```
Organization
├── HybridVoting ──────┐
├── DirectDemocracyVoting │ (governance)
├── Executor ◀───────────┘ executes approved calls
├── TaskManager
│   └── Projects → Tasks
├── ParticipationToken (non-transferable ERC-20)
├── PaymentManager (treasury, distributions, sDAI)
├── MembershipAuthority (roles, groups, permissions, vouching)
├── AuthorityRouter (subject identity continuity)
├── EducationHub (learning modules → PT)
├── QuickJoin (onboarding)
└── PaymasterHub (ERC-4337 gas sponsorship)
```

## Participation tokens (PT)

PT is the unit of earned influence.

- **Non-transferable by design** — `transfer`, `approve`, and `transferFrom`
  revert (`TransfersDisabled`). You can't buy, sell, or delegate-by-transfer it.
- **Earned**, not bought — via task completion, education modules, and approved
  token requests. Only the TaskManager and EducationHub may mint PT.
- **Powers voting weight** in token-weighted voting classes and determines
  **merkle distribution shares** (payouts proportional to PT balance).

See [treasury-and-tokens.md](../guides/treasury-and-tokens.md).

## Roles, groups & task permissions

MembershipAuthority is the source of current membership and permissions. A role
has a persistent subject ID; migrated roles keep their original numeric Hats ID.
A group is a union of roles. Group membership follows its constituent roles and
cannot be claimed independently. Historical Hats records remain readable but do
not authorize current operations.

Role offers require recipient consent. Governance configures rules, permission
rows and delegated managers; a manager's capabilities and delay bound its actions.
See [membership-roles-vouching.md](../guides/membership-roles-vouching.md).

Task permissions use the authority's `TM_PERMS` word. The low eight bits are:

| Bit | Value | Permission |
|---|---|---|
| CREATE | 1 | Create tasks |
| CLAIM | 2 | Claim tasks |
| REVIEW | 4 | Approve/reject submissions |
| ASSIGN | 8 | Assign tasks |
| SELF_REVIEW | 16 | Review your own submission |
| BUDGET | 32 | Manage project budgets |
| EDIT_META | 64 | Edit task title/description |
| EDIT_FULL | 128 | Edit all task fields |

Use `pop task perms propose-global --subject ID --perms create,claim` for a global grant.
Use `pop task perms set --subject ID --perms claim --project ID` for a project row; its context is `projectId + 1` (global is
zero). A project row replaces that subject's global row unless `--inherit-global`
is set. An explicit zero row denies the global grant; `task perms clear` removes
the row and restores inheritance. Existing address-based project managers remain
supported. See [tasks.md](../guides/tasks.md).

## Tasks: statuses & deadlines (v6/v7)

A task moves through:

```text
UNCLAIMED → CLAIMED → SUBMITTED → COMPLETED
    ▲          │                 ↘ CANCELLED
    └──────────┘
    takeover (expired claim) · unclaimTask (release back to the pool)
```

v6 adds **deadlines** and **expired-claim takeover**:

| Concept | Meaning |
|---|---|
| `absoluteDeadline` | Past this time, any claim on the task counts as **expired** — instantly takeover-able, and force-releasable by an ASSIGN holder. It does *not* block a new claim: it is read only by `_claimExpired`, which `claimTask` consults solely on the takeover branch, and `submitTask` checks no deadline at all. |
| `completionWindow` | How long a claimer has to submit after claiming. |
| `claimDeadline` | Auto-set when a task is claimed (from the completion window). |

**Takeover**: if a claim's deadline passes, anyone with the CLAIM permission can
claim the task away (emitting `TaskClaimExpired`). The original claimer can
still submit right up until someone actually takes it over — expiry opens the
door, it doesn't slam it. `pop task list --claimable` surfaces both unclaimed
tasks and claimed-but-expired ones.

**Release (v7)**: takeover is no longer the only way a claimed task gets back to
the pool. `unclaimTask` hands it back with *no* replacement claimer — the
claimer may do so at any time (no permission mask, no deadline check), and
anyone with ASSIGN may force-release a claim that has **already** expired. It is
a distinct transition, not a takeover in disguise: `TaskUnclaimed(id,
previousClaimer, caller)` is emitted, `TaskClaimExpired` is **not**, and
`TaskClaimDeadlineSet(id, 0)` follows only when a claim window was actually
running. Budgets and application hashes are untouched, so the task is instantly
re-claimable and `cancelTask` — still the only refund path — becomes reachable
again. Surfaced as `pop task unclaim` and `pop task list --released`.

**Post-claim edits** are permission-split so a claimer's work isn't disrupted:
`pop task edit-meta` changes only title/description (EDIT_META) and is
post-claim safe, while `pop task update` is a full-field edit (payout,
deadlines, bounty — EDIT_FULL).

## Governance: N-class voting, quorum & threshold

**HybridVoting** composes **N voting classes** (`ClassConfig[]`). Each class
has a `strategy` — `DIRECT` (one member, 100 points) or `ERC20_BAL`
(token-weighted) — and a `slicePct` share of total weight; slices across all
classes sum to 100. Classes may optionally be quadratic, require a minimum
balance, or be subject-gated. **DirectDemocracyVoting** is the pure 1-member-1-vote
track.

Two independent knobs decide outcomes — do not conflate them:

| Knob | What it is |
|---|---|
| **Threshold** (`thresholdPct`) | The **support %** an option needs to win. |
| **Quorum** | A minimum **voter count** (`0` = disabled), separate from threshold. A proposal can clear the support threshold and still fail quorum. |

Lifecycle: **create → cast** (option weights sum to 100) **→ announce/execute**.
Proposals can carry **execution calls** that fire automatically when they pass,
which is how governance drives treasury transfers, project creation, and
parameter changes.

```bash
pop vote create --type hybrid --name "Direction" --description "Where next?" \
  --duration 1440 --options "A,B"
pop vote cast --type hybrid --proposal 0 --options 0 --weights 100
pop vote announce-all         # finalize every ended proposal
```

See [voting.md](../guides/voting.md) and
[governance-templates.md](../guides/governance-templates.md).

## Vouching (MembershipAuthority)

Governance configures a role's vouch quorum and voucher subject. A voucher must
belong to that subject and meet the authority's rate-limit rules. Vouches are
scoped to an epoch, so changing or resetting the attestor invalidates old vouches.

`pop vouch for --subject ROLE_ID --user ADDRESS` submits a vouch. Once eligible,
the recipient explicitly claims with `pop vouch claim --subject ROLE_ID`.
`pop vouch status --subject ROLE_ID --user ADDRESS` shows indexed progress.
Governance can clear a user's vouches or reset the subject's epoch. There is no
legacy EligibilityModule authorization fallback.

## Gas sponsorship (PaymasterHub)

Orgs can pay their members' gas via ERC-4337. Org admins **register** the org
with the PaymasterHub, **deposit** native funds, and **set budgets/rules**;
sponsored transactions then run as UserOperations. An EIP-7702 delegation path
also lets a plain EOA receive sponsored UserOps. The bundler is configured via
`POP_BUNDLER_URL` (self-hosted) or `PIMLICO_API_KEY`. See
[gas-sponsorship.md](../guides/gas-sponsorship.md).

## Current release: Access v2 / Wave G

CLI/core 1.0 target [contracts PR #193](https://github.com/poa-box/POP/pull/193),
merged September 17, 2026 and deployed on Gnosis and Arbitrum. The live module
versions are DD/HV v14, TaskManager/PT v9, EducationHub v5, QuickJoin v10,
Executor v6 and OrgDeployer v21. See [the migration guide](../WAVE-G-1.0.md).

Only authority-ready organizations are available. Kansas Blockchain, Decentral
Park, Poa and Test6 retain their earlier tasks, votes and balances. Test, Test2,
Test3, tkrjehbcuebc, Test5 and Argus are retired. New native organizations use the
same readiness check without a name allowlist.

Earlier features retained in this release:

- **Task release (TaskManager v7)** — `unclaimTask` returns a CLAIMED task to
  the pool with no replacement claimer, emitting `TaskUnclaimed` (never
  `TaskClaimExpired`). The claimer may release at any time; ASSIGN holders only
  once the claim has expired. Exposed as `pop task unclaim`, with
  `pop task list --released` to find handed-back work.
- **Task deadlines + expired-claim takeover** — `absoluteDeadline`,
  `completionWindow`, `claimDeadline`; anyone with CLAIM can take over an
  expired claim (`TaskClaimExpired`).
- **Post-claim edit permissions** — split into EDIT_META (title/description,
  post-claim safe) vs. EDIT_FULL (all fields), surfaced as `pop task edit-meta`
  and `pop task update`.
- **Batch task creation** — `createTasksBatch` (v6 batches are all-or-nothing),
  exposed as `pop task create-batch`.
- **Quorum ⟂ threshold separation** — quorum is a minimum voter *count*
  (`0` = disabled), fully independent of the support-% threshold.
- **N-class hybrid voting** — voting is composed from a `ClassConfig[]` with
  per-class strategy, slice, quadratic, min-balance, and subject gating.
- **Paymaster org registration** — first-class org registration + budgets on
  the PaymasterHub, plus the EIP-7702 sponsorship path.

## Supported chains

| Chain | ID | Status |
|---|---|---|
| Gnosis | 100 | Production |
| Arbitrum One | 42161 | Production |
| Sepolia | 11155111 | RPC only; no current POP subgraph |
| Base Sepolia | 84532 | RPC only; no current POP subgraph |

## Where to go next

- [getting-started/quickstart.md](../getting-started/quickstart.md) — join an org and start earning.
- [getting-started/deploy-an-org.md](../getting-started/deploy-an-org.md) — deploy your own.
- [reference/cli/index.md](../reference/cli/index.md) — every command, every flag (auto-generated).
- [protocol/manifesto.md](manifesto.md) — why POP exists.