Репозиторій на GitHub — це перше, що бачить журі після відкриття вашого submission. Якщо код не запускається, а README не пояснює, що перед ними, навіть найкраща ідея залишиться без уваги. Нижче — чітка схема оформлення, яка працює на хакатонах у екосистемі Solana.

Структура репозиторію, яку очікує журі

Журі перевіряє десятки подань. Якщо учасникові доводиться шукати смарт-контракт серед трьох рівнів вкладених папок — це вже мінус. Використовуйте плоску та передбачувану структуру:

  • /programs — смарт-контракти на Rust або Anchor. Кожна програма в окремій підпапці з власним Cargo.toml.
  • /app або /frontend — клієнтська частина (React, Next.js, Svelte тощо).
  • /scripts — утиліти для розгортання, ініціалізації, створення тестових акаунтів на Devnet.
  • /tests — інтеграційні тести для смарт-контрактів.
  • .env.example — файл-шаблон із переліком потрібних змінних середовища (RPC-ендпоінт, гаманець, API-ключі) без реальних значень.
  • Anchor.toml (якщо використовуєте Anchor) — конфігурація робочого середовища на верхньому рівні.

Головне правило: журі має знайти точку входу за три кліки. Якщо ваш проєкт складається з одного смарт-контракту без фронтенду — не створюйте порожні папки «для краси». Два файли на верхньому рівні кращі, ніж п'ять порожніх директорій.

Що обов'язково має бути в README

README — це не опис того, як ви старалися. Це інструкція для людини, яка вперше бачить ваш код і хоче його запустити.

Назва, опис та проблема, яку розв'язує проєкт

Перші три-чотири рядки: назва проєкту, одне речення про те, що він робить, і одне речення про проблему. Без вступів на кшталт «У сучасному світі блокчейн-технології стрімко розвиваються». Журі читає сотні таких вступів — пишіть конкретно.

Приклад: «StreamPay — протокол рекурентних платежів на Solana. Дозволяє підпискам автоматично списувати SOL щомісяця без повторного підписання транзакцій користувачем.»

Інструкція запуску (local та Devnet)

Це найважливіший блок. Без нього ваш проєкт вважається незавершеним. Обов'язково розділіть на два сценарії:

Локальний запуск (localnet):

  1. Передумови: вказані версії Node.js, Rust, Anchor, Solana CLI.
  2. Кроки: clone, install dependencies, build, deploy, run frontend.
  3. Очікуваний результат: що користувач має побачити після запуску.

Запуск на Devnet:

  1. Де взяти Devnet SOL (посилання на faucet — без реєстрацій, якщо це можливо).
  2. Які змінні середовища треба встановити (.env.example).
  3. Чи потрібен розгортання смарт-контракту на Devnet, чи достатньо вказати готовий program ID.

Кожна команда має бути перевірена на чистій машині. Якщо ви писали «npm install» аж на п'ятому кроці, а на другому забули «anchor build» — журі зупиниться і перейде до наступної команди.

Технологічний стек

Короткий перелік без обґрунтувань чому саме цей стек. Формат — список:

  • Смарт-контракти: Anchor, Rust
  • Фронтенд: Next.js, TypeScript, Tailwind CSS
  • Інтеграція з Solana: @solana/web3.js, @coral-xyz/anchor
  • Інше: якщо використовуєте специфічні бібліотеки (наприклад, для MEV-захисту чи роботи з RWA-активами), вкажіть їх

Відео demo або посилання на нього

Журі не завжди має час запускати код. Додайте вбудоване відео або пряме посилання на запис (YouTube, Loom тощо). Відео має показувати реальну взаємодію: підпис транзакції, виклик смарт-контракту, результат на екрані. Не замінюйте відео слайдами з описом — це різні речі.

Типові помилки в оформленні репозиторію

  • Захищені гілки без доступу. Якщо єдиний код лежить у гілці, яку журі не може навіть переглянути без запиту — це відмова. Переконайтеся, що репозиторій публічний, а потрібна гілка відкривається без додаткових кроків.
  • .env у комітах. Навіть якщо це тестові ключі, це показує відсутність базової гігієни. Додайте .env до .gitignore і залиште лише .env.example.
  • Залежності, що не встановлюються. Приватні пакети без токену, зламані посилання в package.json, залежності від локальних файлів, яких немає в репозиторії.
  • Абсолютні шляхи замість відносних. Якщо в коді або скриптах прописані шляхи на кшталт /Users/yourname/project/, на машині журі це не спрацює.
  • README з іншого проєкту. Залишені назви шаблонів (boilerplate), згадки про інший хакатон, невідповідність між описом і реальним кодом.
  • Величезні бінарні файли в репозиторії. Відео, зображення, збірки фронтенду — усе це має бути в .gitignore. Використовуйте зовнішні сервіси для медіа.
  • Відсутність Anchor.toml або Cargo.toml на очікуваному місці. Якщо журі клікає на programs/my-program і не бачить Cargo.toml — це вважається неповним поданням.

Як перевірити, що репозиторій відкривається та запускається

Зробіть фінальну перевірку за чек-листом перед submission:

  1. Інкогніто-тест. Відкрийте посилання на репозиторій у режимі інкогніто. Переконайтеся, що він публічний, README рендериться, а гілка з кодом доступна без авторизації.
  2. Чиста машина. Запросіть teammate або друга, який не брав участі в розробці, виконати інструкцію з README крок за кроком. Не підказуйте — фіксуйте, де він застряг.
  3. Devnet-перевірка. Запустіть проєкт на Devnet і виконайте мінімальний сценарій: ініціалізація, одна транзакція, читання стану. Переконайтеся, що program ID у коді збігається з тим, що задеплоєний на Devnet.
  4. Фронтенд без бекенду. Якщо смарт-контракт ще не задеплоєний, перевірте, що фронтенд хоча б завантажується і показує інтерфейс (навіть з помилками підключення).
  5. Посилання в README. Перевірте кожне посилання: на відео, на faucet, на документацію. Мертві посилання — це сигнал, що ви не перевірили власне подання.

Якщо після чистої перевірки щось не запустилося — виправте саме це, а не додавайте новий функціонал. Робочий проєкт із меншим scope завжди виграє в незапускаємого монстра.

Наступний крок: запис demo

Коли репозиторій оформлений і перевірений, наступний етап — запис технічного demo. Це окремий формат, який відрізняється від простої скрінкасти: він має показувати роботу смарт-контракту, взаємодію з блокчейном і реальний користувацький сценарій. Перейдіть до інструкції з запису технічного demo, щоб підготувати відео, яке доповнить ваш репозиторій і посилить подання.

Джерела