---
title: "Публічні пули та DAO-банки"
description: "Спільнотні банки фінансування — внесок у двох валютах, картка з рейкою desk-oracle, виплата builder за роллю та gated on-chain escrow scaffold"
locale: "uk"
---
# Публічні пули та DAO-банки

Публічні пули — це **спільнотні банки фінансування** для кожного клону. Учасники ставлять вподобайки й роблять внески до цілі у native token; документація вбудовує той самий банк через ``. Продуктові маршрути живуть під **`/dao`** (не `/pools`). SSOT коштів для внесків карткою/PayPal — призначення PaymentConductor **`public_pool_contribution`**, а не API PSP «donation product».

> **Info**
> Використовуйте вкладки **Founder** / **Developer** на бічній панелі документації, щоб відфільтрувати цю сторінку. Видимість бічної панелі контролює `lib/docs/audience-curated-docs.ts`.

  Hosted **Донати** WayForPay, Stripe Checkout `submit_type=donate` і PayPal Donate SDK **не** є SSOT банок Ring. Внески Ring карткою/PayPal використовують **`PaymentConductor.createCheckout({ purpose: 'public_pool_contribution' })`** через `POST /api/public-pools/[slug]/card-checkout`. Нативні внески використовують SPL-переказ до treasury (`contributeToPool`) — поза Conductor.

## Що випущено (2026-07-21)

| Напрям | Статус | Істина |
|-------|--------|-------|
| Інтерактивний чат Tier A | **Live** | `poll`, `rsvp`, `dao_jar`, `share_card` виправлено (оновлення jar, RSVP зустрічі, cron `closeAt` poll, заблоковані голоси) |
| TD-MONEY-01 Card jar | **Live** | Призначення `public_pool_contribution`; settle збільшує `pledged_native_token` через **desk oracle** FX |
| TD-MONEY-02 Builder payout | **Live** | При фінансуванні ≥100%: авто-завершення + treasury виплачує builder **net** (pledged − комісія ролі) на основний Solana wallet builder |
| TD-MONEY-03 Escrow | **Partial** | Anchor-програма в `solana/programs/public-pool` (init/contribute/finalize/refund). **Donation path live**; on-chain escrow contribute потребує deploy + IDL wire |
| Dual-currency CTA | **Live** | `PoolContributePanel` — fiat для картки/PayPal; native symbol для внеску; показує credit + native balances |

  Card jar — **не** конвертація fiat↔RING 1:1. PublicPool escrow — **не** live у production. Builder payout — **не** завжди дорівнює всій сумі pledged (комісія 0 лише для ролей admin/superadmin за замовчуванням).

## Грошові шляхи (спільні)

```mermaid
flowchart LR
  UI["PoolContributePanel\n/dao · dao_jar · FutureFeature"]
  UI -->|native| NAT["contributeToPool\nSPL → treasury"]
  UI -->|fiat card/PayPal| CARD["POST .../card-checkout\npurpose public_pool_contribution"]
  CARD --> FX["desk oracle\nnativeUi = fiatMajor / nativePerMainCurrency"]
  CARD --> WH["PSP webhook → settlePublicPoolCardContribution"]
  NAT --> TOT["recomputePoolTotals\npledged_native_token"]
  WH --> TOT
  TOT -->|funding ≥ 100%| PAY["maybePayoutBuilderOnComplete\nnet = pledged − fee%"]
  ESC["Anchor PublicPool\ngated by PROGRAM_ID"] -.->|not prod-wired| UI
```

**SSOT FX (той самий, що й у Token Desk):** `nativeUi = fiatMajor / nativePerMainCurrency` через `getNativeTokenPerMainCurrencyRate` / `features/public-pools/lib/public-pool-desk-fx.ts`.

**SSOT комісії платформи:** `ring-config.json` → `publicPools.platformFeePercentByRole` (типові значення: admin/superadmin **0%**, confidential **6%**, member **7%**).

### For founders

## Чому банки важливі для вашого клону

Учасники фінансують функції та колективні цілі у **вашому** native token (а картковий fiat конвертується за **актуальним desk rate**). Коли банк заповнюється, власник opportunity отримує **net** native token на свій основний custodial Solana wallet — за мінусом налаштованої комісії ролі. Форми collective-order показують це явно (`collectiveJarPayoutNote` у локалях opportunities).

  
- **[PaymentConductor](/docs/features/payment-conductor.md)** — Призначення картки/PayPal `public_pool_contribution` використовує той самий ledger і webhooks, що й store та wallet.

  
- **[Wallet & Token Desk](/docs/features/wallet.md)** — Ставка desk oracle — той самий FX, який використовується, коли картковий внесок стає pledged native units.

  
- **[Messaging](/docs/features/messaging.md)** — Віджети чату `dao_jar` оновлюються після внеску; публікуйте банки з документації або `/dao`.

  
- **[Opportunities](/docs/features/opportunities.md)** — Колективні / builder-банки виплачують на основний native wallet власника opportunity, коли заповнюються.

### Чекліст оператора

1. Увімкніть public pools у конфігурації клону (`publicPools` у `ring-config.json`) — карта комісій + `autoPayoutOnGoalMet`.
2. Налаштуйте Solana treasury (`SOLANA_RPC_URL`, `SOLANA_TREASURY_PRIVATE_KEY`), щоб **native** внески та виплати builder могли переміщувати SPL.
3. Підтримуйте Token Desk / web3 oracle у робочому стані — card settle потребує `getNativeTokenPerMainCurrencyRate`.
4. **Не** вмикайте UX escrow, доки не розгорнете `solana/programs/public-pool` і не встановите `NEXT_PUBLIC_PUBLIC_POOL_PROGRAM_ID`.
5. Перевірте малий картковий внесок на `/dao/[slug]` і підтвердьте, що pledged native зростає в **desk-конвертованих** одиницях, а не 1:1 fiat.

### Типові сценарії

- Елемент backlog документації з `` — учасники ставлять вподобайку й роблять внесок зі сторінки.
- Чат `dao_jar` — та сама панель; підсумки оновлюються через `refreshOpenDaoJarMessages`.
- Collective opportunity заповнюється → статус `completed` → treasury виплачує **net** RING на wallet builder.

### For developers

## Реалізація

### Поверхні

| Поверхня | Шлях |
|---------|------|
| Публічний список / деталі | `/[locale]/dao`, `/[locale]/dao/[slug]` |
| Адмін | `/[locale]/admin/dao` |
| Віджет документації | `components/docs/future-feature-widget.tsx` → `PoolContributePanel` |
| Jar у чаті | `features/public-pools/components/dao-jar-message-widget.tsx` |
| Dual CTA | `features/public-pools/components/pool-contribute-panel.tsx` |

### Перевірений HTTP / settle

| Метод | Шлях | Роль |
|--------|------|------|
| GET/POST | `/api/public-pools` | Список / upsert статистики future_feature |
| POST | `/api/public-pools/signal` | Перемикач like |
| POST | `/api/public-pools/contribute` | Ініціація native |
| POST | `/api/public-pools/contribute/confirm` | Native confirm + оновлення jar |
| POST | `/api/public-pools/[slug]/card-checkout` | Checkout картки/PayPal через Conductor |
| * | `/api/admin/public-pools…` | CRUD + статус для адміна |

Settle: `lib/payments/conductor/handlers/public-pool-contribution.ts` → `settlePublicPoolCardContribution` (ідемпотентний за `orderReference`). Webhooks: гілки диспетчера WayForPay / Stripe / PayPal перевіряють `purpose === 'public_pool_contribution'`.

Необов’язкове перевизначення процесора: `PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR` (`lib/payments/payment.config.ts`).

### Модулі

| Модуль | Відповідальність |
|--------|----------------|
| `features/public-pools/services/public-pool-service.ts` | Підсумки, queue gate, auto-complete, виплата builder |
| `features/public-pools/services/public-pool-contribute.ts` | Внесок до native treasury |
| `features/public-pools/lib/public-pool-desk-fx.ts` | FX desk oracle |
| `features/public-pools/lib/public-pool-platform-fee.ts` | Карта комісій за ролями |
| `features/public-pools/lib/public-pool-escrow-gate.ts` | `NEXT_PUBLIC_PUBLIC_POOL_PROGRAM_ID` / `PUBLIC_POOL_PROGRAM_ID` |
| `lib/payments/conductor/settle-public-pool-contribution.ts` | Card settle → `pledged_native_token` |
| `features/chat/lib/refresh-open-dao-jar-messages.ts` | Синхронізація знімка чату |
| `solana/programs/public-pool` | Anchor: `init_pool` / `contribute` / `finalize_success` / `refund_contributor` |

### Desk FX (перевірено)

```ts
// features/public-pools/lib/public-pool-desk-fx.ts
// nativeUi = fiatMajor / nativePerMainCurrency
// nativePerMainCurrency from getNativeTokenPerMainCurrencyRate() — same SSOT as Token Desk
```

Card checkout приймає `amount_fiat` **або** `amount_native` і перед redirect завжди зберігає обидва значення + `nativePerMainCurrency` у payment metadata.

### Виплата builder (перевірено)

Коли `autoPayoutOnGoalMet` і funding ≥ 100%:

1. Pool → `completed`
2. Визначити `payout_wallet_address` або основний native wallet builder
3. `feePercent = resolveBuilderPlatformFeePercent(builderRole)`
4. `net = pledged − fee`; `transferTokenFromTreasury(wallet, net)`
5. Примітка ledger `public_pool_payout` із gross/fee/feePct

Текст collective-order: `locales/*/modules/opportunities.json` → `collectiveJarPayoutNote`.

### Гейт escrow (не live у production)

```ts
// features/public-pools/lib/public-pool-escrow-gate.ts
isPublicPoolEscrowDeployed() // true only when PROGRAM_ID env is set
```

Donation mode (treasury SPL) — live-шлях. Escrow contribute потребує: deploy програми → встановити `NEXT_PUBLIC_PUBLIC_POOL_PROGRAM_ID` → підключити IDL client → зберігати `on_chain { pool_pda, vault_ata }` для кожного jar. **Не документуйте escrow як live у production.**

### Env (простежено)

| Var | Використання |
|-----|-----|
| `SOLANA_RPC_URL` | Chain RPC |
| `SOLANA_TREASURY_PRIVATE_KEY` | Native внесок + виплата builder |
| `NEXT_PUBLIC_PUBLIC_POOL_PROGRAM_ID` / `PUBLIC_POOL_PROGRAM_ID` | Гейт escrow (необов’язково; ще немає в `env.local.template`) |
| `PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR` | Необов’язкове перевизначення PSP для призначення |
| Standard WFP / Stripe / PayPal secrets | Ті самі webhooks Conductor, що й для інших призначень |

### Колекції

`public_pools`, `public_pool_signals`, `public_pool_contributions` (ізолюються за clone через `getPublicPoolConfig().cloneId`).

### Інтерактивний чат (Tier A)

Домен володіє коштами; чат володіє знімком `dao_jar`. Після зміни підсумків завжди викликайте `refreshOpenDaoJarMessages`. Scorecard: AI-CONTEXT `concepts/chat-interactive-type-debt.json` — Tier A **CLOSED**; TD-MONEY-01/02 **CLOSED**; TD-MONEY-03 **PARTIAL**.

## Пов’язана документація

  
- [features/payment-conductor](/docs/features/payment-conductor.md) — Залежність: settle картки/PayPal для jar використовує PaymentPurpose public_pool_contribution і спільні webhooks.

  
- [features/wallet](/docs/features/wallet.md) — Залежність: nativePerMainCurrency від desk oracle — SSOT FX для fiat→pledged native.

  
- [features/messaging](/docs/features/messaging.md) — Той самий процес: віджети dao_jar і PostDaoJarToChatButton оновлюються після внеску.

  
- [features/opportunities](/docs/features/opportunities.md) — Наступний крок: колективні банки виплачують у wallet builder opportunity, коли фінансування сягає 100%.

  
- [architecture/payment-conductor](/docs/architecture/payment-conductor.md) — Поглиблення: типи conductor, ledger і диспетчер webhook.