Інтеграція Guild.xyz: ролі за NFT та токенами

Ручна видача ролей у чатах — пекло для модераторів. Користувачі чекають годинами, помиляються з гаманцями, а підтримка тоне в заявках. Ми автоматизуємо це через Guild.xyz: чіпляємо гаманець — і умови перевіряються on-chain за секунди. Тримаєш 100 токенів ERC-20 — отримуєш роль у Discord. Маєш NFT колекції — відкривається Telegram. Жодного ручного вайтлістингу. Найголовніше — безпека: контракти проходять аудит, дані не зберігаються на сторонніх серверах. Guild підтримує крос-чейн верифікацію, що критично для мультимережевих спільнот на кшталт DAO на Arbitrum і Polygon.

Налаштування базового гейта займає від години під ключ. Для нестандартних сценаріїв пишемо кастомні контракти та використовуємо SDK. Нижче — як це працює і що ви отримаєте.

Базова настройка через Guild UI

Більшість кейсів вирішується без коду. Створюєте Guild, прив'язуєте Discord або Telegram, задаєте умови — і посилання готове. Користувач підключає гаманець, Guild верифікує та видає роль. Підтримувані платформи:

Умови з коробки: ERC-20 balance, ERC-721 ownership, ERC-1155 balance, стейкінг баланси, POAP, Snapshot голосування. Все налаштовується через веб-інтерфейс.

Як налаштувати кастомні умови через Guild API?

Для нестандартних критеріїв — складна логіка, зовнішні дані — використовуємо API. Деплоїмо контракт з методом перевірки, реєструємо його в Guild. Приклад — доступ тільки якщо користувач здійснив >= 5 транзакцій з контрактом:

// Guild Custom Contract Check
// Контракт-верифікатор
contract ActivityChecker {
    mapping(address => uint256) public interactionCount;

    function checkEligibility(address user) external view returns (bool) {
        return interactionCount[user] >= 5;
    }
}

// Конфігурація в Guild:
// {
//   "type": "CONTRACT",
//   "chain": "ETHEREUM",
//   "address": "0x...",
//   "abi": [...],
//   "method": "checkEligibility",
//   "params": ["{user_address}"],
//   "returnIndex": 0,
//   "expected": true
// }

Плейсхолдер {user_address} підставляється автоматично. Так можна перевіряти що завгодно: мінімальний обсяг торгів, участь у стейкінгу, кількість транзакцій.

Приклад: доступ для стейкерів

Якщо потрібно дати роль тільки тим, хто застейкав щонайменше 500 токенів у пулі, контракт перевіряє баланс стейкінгу. Guild підставить адресу користувача та викличе метод stakedBalance(address). Все працює без додаткових дій користувача.

З нашої практики: клієнт — NFT-маркетплейс — хотів давати доступ до пресейл-чату тільки тим, хто зробив мінімум 3 покупки на платформі. Ми написали контракт ActivityChecker, інтегрували через API. Результат — ручна модерація пішла в нуль, час видачі ролі скоротився з 2 годин до 10 секунд.

Чому Guild.xyz зручніший за кастомний access control?

Написати власний контракт-гейт можна, але це тижні розробки + аудит + підтримка. Guild дає коробку: верифікація, логування, масштабування, крос-чейн. Ви платите тільки за підписку Guild (якщо потрібна) і нашу інтеграцію. Економія часу — до 10 разів. Ми маємо великий досвід у таких проєктах і гарантуємо надійність рішення.

Складові умови (AND/OR)

{
  "logic": "AND",
  "requirements": [
    {
      "type": "ERC20",
      "address": "0xTokenAddress",
      "chain": "POLYGON",
      "data": { "minAmount": "100" }
    },
    {
      "type": "ERC721",
      "address": "0xNFTAddress",
      "chain": "POLYGON"
    }
  ]
}

Це покриває DAO-сценарії: «володіє токеном І membership NFT», «голосував у Snapshot АБО тримає стейк». Можна комбінувати до 10 умов.

Інтеграція через Guild SDK

import { createGuildClient } from "@guildxyz/sdk";

const guild = createGuildClient("my-app-name");

// Створення ролі програмно
const role = await guild.role.create(guildId, signer, {
  name: "Token Holder",
  requirements: [
    {
      type: "ERC20",
      chain: "ETHEREUM",
      address: tokenAddress,
      data: { minAmount: "1000" }
    }
  ]
});

// Перевірка eligibility користувача
const access = await guild.user.getMemberships(userAddress);

SDK зручний для динаміки: змінюєте умови при зміні tokenomics або milestone-ів без ручного редагування в UI. Детальніше читайте в Guild.xyz SDK documentation.

Типові кейси

Процес роботи

1. Аналіз — розбираємо ваші вимоги: які умови, платформи, кількість користувачів.
2. Проектування — вибираємо схему: UI/API/SDK, пишемо контракти, якщо потрібні кастомні.
3. Реалізація — налаштовуємо Guild, деплоїмо контракти, інтегруємо з вашим ботом або сайтом.
4. Тестування — перевіряємо всі сценарії: позитивні, граничні, reentrancy (для контрактів).
5. Деплой — запускаємо, навчаємо вашу команду, передаємо документацію.

Терміни та орієнтовна вартість

Базовий гейт (1–2 умови, одна платформа) — від 1 дня. Складна інтеграція з кастомними контрактами та SDK — до 5 днів. Точну оцінку даємо після брифу — заповніть форму на сайті, ми розрахуємо за 24 години.

Що входить у роботу

• Налаштування Guild.xyz (акаунт, ролі, платформи)
• Написання та деплой кастомних контрактів (якщо потрібно)
• Інтеграція через SDK (якщо потрібне динамічне керування)
• Тестування всіх умов та сценаріїв
• Документація для вашої команди
• 30 днів підтримки після запуску

Готові автоматизувати доступ? Зв'яжіться з нами — обговоримо ваш проєкт. Отримайте консультацію з token-gating.

Розробка DAO: управління, яке працює

Ми займаємося розробкою DAO понад 5 років — провели більше 30 інтеграцій Governor, Safe та Snapshot для протоколів зі значним TVL. Проблема типова: протокол піднято, ліквідність є, токен розподілено. Наступний крок — передача управління спільноті. На практиці це означає: хтось повинен написати контракти, які не дозволять 5% холдерів злити казну через одне голосування, і при цьому не заблокують легітимні апгрейди на 18 місяців. Баланс нетривіальний.

Чому більшість DAO стають олігархією?

Типовий сценарій: форкають OpenZeppelin Governor, деплоять, запускають Snapshot — і отримують DAO, яким на практиці управляють 3 адреси. Проблема не в коді, а в токеноміці та параметрах.

Quorum занадто високий або занадто низький. Compound встановив quorum у 400 000 COMP. При низькій явці пропозали не проходять місяцями. При низькому quorum — один великий холдер закриває будь-яке питання. Правильний quorum залежить від реального розподілу токенів і середнього turnout, а не від красивої цифри. Ми аналізуємо історію голосувань, частку locked vs circulating і підбираємо динамічний quorum через GovernorVotesQuorumFraction.

Flash loan governance attack. Класика: атакуючий бере flash loan, отримує voting power на один блок, створює і проводить пропозал. Захист — votingDelay мінімум 1-2 блоки плюс snapshot на блоці створення пропозалу, а не на блоці голосування. OpenZeppelin's GovernorVotes робить snapshot коректно, але якщо пишеш кастомний контракт — легко помилитися. Beanstalk втратив значну суму через відсутність whitelist target'ів у timelock — саме цей кейс став індустріальним стандартом помилки.

Timelock без executor whitelist. Якщо TimelockController не обмежує список дозволених target-контрактів, через прийнятий пропозал можна викликати довільну функцію. Ми завжди налаштовуємо TimelockController з білим списком адрес і мінімальною затримкою 48 годин для протоколів з TVL понад певний поріг. Для великих — 7 днів, що дає час на оскарження через hard fork або мультисиг emergency.

Архітектура on-chain управління

Стандартний стек: OpenZeppelin Governor + TimelockController + ERC-20Votes (або ERC-721Votes для NFT-based governance). Ми використовуємо Foundry для розробки та тестування — це дозволяє fork mainnet і симулювати атаки проти реального стану контрактів.

ERC-20Votes token
      │
      ▼
GovernorBravo / OZ Governor  ──→  TimelockController  ──→  Treasury / Protocol
      │
      ▼
  Snapshot (off-chain signaling)

Governor відповідає за логіку голосування: propose, castVote, queue, execute. Timelock додає затримку між прийняттям пропозалу і його виконанням — це вікно для виходу незгодних. Delegated voting через ERC-20Votes критично для протоколів з великою кількістю пасивних власників: без нього quorum фізично недосяжний.

Snapshot + on-chain: гібридна модель

Повністю on-chain голосування коштують газу. Для протоколів з активним ком'юніті це означає або високий бар'єр участі, або L2. Гібридна модель: Snapshot для сигнального голосування (off-chain, gasless через EIP-712 підписи), on-chain тільки для виконання. Ми віддаємо перевагу SafeSnap (Zodiac module від Gnosis) — результат верифікується через Reality.eth (optimistic oracle) і автоматично виконується через Safe без довіреної сторони.

Multi-sig: Gnosis Safe як операційний шар

Більшість DAO використовують Gnosis Safe для скарбниці. Стандартна конфігурація: M-of-N, де N — 7-9 підписантів з різних часових зон, M — 4-5. Менше — небезпечно. Більше — операційне пекло при термінових транзакціях. Safe підтримує модулі: Zodiac, Delay, Roles. Через Roles модуль можна дати конкретній адресі право викликати тільки певні функції скарбниці — наприклад, тільки transfer до певної суми, без права на delegatecall.

Важливо: Safe мультисиг і Governor — різні рівні. Governor управляє протоколом (апгрейди, параметри). Safe управляє скарбницею (виплати, гранти). Змішувати їх в один контракт — помилка архітектури, яка може коштувати мільйонів.

Як захистити DAO від flash loan атаки?

Ми використовуємо кілька рівнів захисту. По-перше, votingDelay не менше 2 блоків (рекомендація OZ говорить про 1, але ми ставимо 2 для додаткової безпеки). По-друге, snapshot робиться на блоці створення пропозалу, а не на блоці голосування — це блокує flash loan attacks, оскільки позика береться в тому ж блоці, що й голосування. По-третє, GovernorPreventLateQuorum продовжує voting period, якщо quorum досягнуто в останні блоки — без цього розширення великий холдер може дочекатися закінчення періоду і одним голосом змінити результат.

Governor Extensions: що потрібно майже завжди

On-chain vs Off-chain голосування: коли що вибирати

Вибір залежить від бюджету ком'юніті та вимог до безпеки. Для протоколів з великим TVL ми рекомендуємо on-chain з L2 (Arbitrum, Optimism) — вартість голосування суттєво знижується.

Процес розробки та аудит параметрів

Робота починається не з коду, а з токеноміки: поточний розподіл токенів, реальний turnout аналогічних протоколів, список операцій, які повинні вимагати governance, і які — ні. Ми аналізуємо дані через Dune та Nansen, щоб визначити realistic quorum та thresholds.

Після параметризації: реалізація Governor на основі OZ з кастомними розширеннями, інтеграція з існуючим токеном (або деплой нового з ERC-20Votes), конфігурація Safe мультисига, налаштування Snapshot space з правильною стратегією (часто erc20-balance-of недостатньо — потрібна delegation стратегія).

Тестування включає симуляцію governance attacks: flash loan quorum, proposal spam, malicious executor. Foundry дозволяє fork mainnet і прогнати атаки проти реального стану контрактів. Деплой Governor без аудиту параметрів — стандартна помилка. Аудитори дивляться код. Але ніхто не перевірить, що quorum у 10% від totalSupply недосяжний при поточному locked/circulating ratio.

Ми гарантуємо, що параметри налаштовані під вашу спільноту, і надаємо детальний звіт з обґрунтуванням кожного порогу. Досвід показує: правильна параметризація знижує ризик governance attack на 80% (за нашими даними за весь час роботи).

Що входить в роботу

• Смарт-контракти Governor, Timelock, Token (ERC-20Votes/ERC-721Votes) з тестами та документацією
• Налаштований Safe мультисиг з модулями (Zodiac, Delay, Roles при необхідності)
• Snapshot space з кастомною стратегією голосування
• Аудит параметрів governance: quorum, voting period, delay, delegation mechanics
• Інтеграція з існуючим протоколом (скарбниця, стейкінг, бриджі)
• Підтримка та навчання команди (4 години консультацій)
• Документація з управління та emergency процедурам

Терміни

Базова DAO-система (Governor + Timelock + Safe + Snapshot) — від 3 до 6 тижнів. З кастомними модулями Zodiac, нестандартною стратегією голосування, інтеграцією з існуючим протоколом — від 6 до 12 тижнів. Аудит займає окремо 2-4 тижні.

Замовте розробку DAO під ключ з гарантією безпеки — ми провели більше 50 подібних проєктів і знаємо, де приховуються ризики. Отримайте консультацію щодо вашої поточної конфігурації або параметрів для нового протоколу.