Архитектура
Всё, что GenKaKu запускает в продакшене, — это либо статический сайт, либо процесс пира. Ничто в пути запроса не является сервером GenKaKu.
Пакеты
| Пакет | Роль |
|---|---|
@genkaku/protocol | Привязки Solana, биллинг эскроу, сайдкар libp2p, мост Ollama |
@genkaku/dsh-runtime | Адаптер, общий для обоих плагинов |
@genkaku/dsh-worker-plugin@0.5.0-rc.8 | Отдаёт локальные модели |
@genkaku/dsh-user-plugin@0.5.0-rc.8 | Потребляет модели сети |
@genkaku/seed | Релей libp2p и сервис обнаружения пиров |
@genkaku/admin | Консоль оператора для хоста seed |
Ядро протокола не зависит от DeepSeek Harness. Это сделано намеренно: другой адаптер не должен требовать его изменения.
В блокчейне
Одна программа, развёрнутая по одному и тому же адресу в Solana mainnet-beta и
Solana devnet. Адрес опубликован на сайте и в netconfig.ts плагинов; сборка сайта отказывается
рекламировать id программы до того, как развёртывание выполнено.
| Аккаунт | Seeds | Что хранит |
|---|---|---|
| RegistryConfig | ["registry"] | owner, pending owner, число воркеров, когда-либо регистрировавшихся |
| Worker | ["worker", wallet] | peer id, ставка, локатор, active, earned, settlements |
| EscrowConfig | ["escrow"] | owner, казна, guardian, vault, mint USDC, лимит сессии, следующий id сессии, накопленное для казны |
| Session | ["session", id] | пользователь, воркер, цена, депозит, накоплено, минуты, метки времени, статус |
USDC эскроу лежит на связанном токен-аккаунте PDA ["escrow"]. Программа проверяет mint и owner
этого аккаунта при каждом переводе, а не выводит адрес в блокчейне: токен-программа уже является
источником истины для обоих полей, а бинарник должен укладываться в один бюджет ренты, доступный
для развёртывания.
Аккаунты — это буферы байтов фиксированного размера с 8-байтовым дискриминатором, поэтому
читающему не нужен IDL: достаточно getAccountInfo и документированного смещения. Раскладка
записана в solana/LAYOUT.md в репозитории и отражена в packages/protocol/src/solana.ts.
Константы программы
| Имя | Значение | Смысл |
|---|---|---|
FEE_BPS | 100 | разделение 1%, константа, а не настройка |
ABSOLUTE_SESSION_CAP | 100 USDC | худший случай экспозиции одной сессии |
CLAIM_DELAY_SECS | 600 | окно, в котором пользователь ещё может закрыть |
IDLE_CLOSE_SECS | 86 400 | после суток молчания закрыть может кто угодно |
MAX_PRICE_PER_MIN | 1 USDC | не даёт воспринимать цену с опечаткой всерьёз |
Плоскость данных
Воркеры обслуживают эти протоколы libp2p:
/genkaku/open/0 session open
/genkaku/token/0 auth token
/genkaku/receipt/0 signed ledger increments
/genkaku/settle/1 settle the session (the worker signs and sends it)
/genkaku/offers/0 offer board
/genkaku/policy/0 policy document
/genkaku/hello/0 identity, wallet proof, quote
Каждый обработчик принимает соединение через релей (runOnLimitedConnection). Поэтому сессия либо
прямая, либо проходит через релей, и оба варианта полноценны. libp2p шифрует поток, так что релей
пересылает шифротекст и видит только метаданные.
В этой сборке нет DCUtR / пробивки NAT. Пир за симметричным NAT использует релей или остаётся недоступным.
Обнаружение
Два независимых пути:
- Каталог в блокчейне — один вызов
getProgramAccountsвозвращает все аккаунты Worker. Клиент отфильтровывает неактивные строки, проверяет, что peer id каждой строки кодирует её кошелёк, и кэширует результат на диске, чтобы даже загрузка без сети что-то показывала. - Seed-релей —
https://seed.genkaku.app/seed(стейджинг:staging.genkaku.app/seed) отвечает наGET /peersmultiaddr'ами, которые верны прямо сейчас, и предоставляет circuit relay для пиров, которые не могут подключиться напрямую.
Адрес seed зашит в пакет protocol, но его можно переопределить через GENKAKU_BOOTSTRAP_SEEDS
(URL через запятую).
Приватные воркеры
Видимость — свойство воркера, а не программы: каждый аккаунт воркера сохраняет свою строку, потому что расчёту нужен счёт, на который платить.
| Публичный | Приватный | |
|---|---|---|
| Объявление в seed | да | нет |
| Локатор в строке | записывается, когда есть глобально доступный адрес | всегда пуст |
Флаг active | 1 | 1 — open_session отказывает неактивному воркеру |
| Кто может набирать | любой, кто нашёл peer id | кошельки из списка разрешённых |
Шлюз проверяется в обработчике потока libp2p по connection.remotePeer — значению, которое
аутентифицировал транспорт, а не утверждению в запросе. walletOfPeerId() превращает его обратно в
адрес Solana; поэтому один ключ ed25519 может быть и кошельком, и PeerId. Ничего не подписывается
дважды, и bearer-токен не хранится.
Доступ выдаётся обменом сопряжения на /genkaku/pair/0:
genkaku1.<base64url({ peerId, wallet, name, addrs, relay, secret, exp })>
Воркер хранит только sha256(secret), по записи на код, со сроком (15 минут) и отметкой usedAt.
Погашение привязывает кошелёк погасившего, а не строку, поэтому утёкший код — это код, а не
ключ. Использованный код, повторённый с того же кошелька, проходит идемпотентно; с любого другого —
отклоняется.
Приватный режим не анонимен. Relay по-прежнему несёт схему, блокчейн по-прежнему записывает платежи, а оператор воркера по-прежнему видит промпты.
Настройки клиента
Плагин пользователя хранит то, что выбрал человек, а не то, что предложила сеть:
| Ключ | Значение |
|---|---|
selected | ключи (worker, model), не больше десяти (MAX_SELECTED_MODELS) |
seeded | false, пока список не материализован один раз |
sort | один из шести порядков; тот же порядок ведёт выбор модели |
privatePeers | сопряжённые приватные воркеры: кошелёк, peer id, addrs, relay, метка |
В том же каталоге ~/.dsh/genkaku лежат ещё два файла, которые являются политикой
самого клиента, а не настройками, видимыми сети:
| Файл | Значение |
|---|---|
policy.json | SpendPolicy: включена ли, имя, срок, лимит, период сброса, лимит на сессию, ценовой лимит, расход за период, расход за всё время, ожидающие резервации |
spend.jsonl | расчитанные сессии: время, micro-USDC, модель, воркер, escrow id, tx; после 512 KiB обрезается до последних 1000 строк |
policy.json намеренно не является аккаунтом в блокчейне. Блокчейн исполняет только
переданный ему депозит; потолок над ним знает лишь клиент, и отказ стоит всего одного HTTP 402
до сборки транзакции.
selected вместе с seeded — это то, что позволяет «я снял все отметки» пережить перезапуск:
пустой список становится выбором, когда seeded равен true, и мост больше его не заполняет.
Предел проверяется и в мосте, и в интерфейсе, потому что мост — единственный, кто пишет, а
HTTP-клиент — не интерфейс.
Сопряжённые приватные воркеры опрашиваются фоновым тикером (20 с). Опрос, вернувшийся с пустой доской, считается отказом, а не онлайном без моделей, чтобы панель никогда не утверждала, что приватный воркер работает, когда список разрешённых говорит обратное. Опрос никогда не блокирует запрос состояния.
Модель биллинга
pricePerHour : 6-decimal USDC, set by the worker
unit : 1 minute (60 units per hour)
billed : ceil(elapsed / 1min) × ceil(pricePerHour / 60)
deposit : 10 minutes of session time, prepaid, capped at 100 USDC
Округление происходит один раз, а не на каждом тике, поэтому пользователь никогда не платит больше объявленной цены за час, а неоплаченная экспозиция воркера составляет не более одной минуты.
Платная сессия — это две транзакции:
open_session(worker, price, deposit)— USDC пользователя уходит с его токен-аккаунта в vault эскроу,settle(minutes)— подписывает воркер: 99% на его доступный для вывода баланс, 1% в казну. Затем клиент закрывает сессию, чтобы забрать остаток;claimвыплачивает воркеру через десять минут после последнего расчёта.
Цена 0 обслуживается вообще без сессии — поэтому бесплатный воркер может работать на машине, где
нет ни USDC, ни чего-либо ещё.
Интерфейсы оператора
- Панель — собственный UI плагина в DeepSeek Harness: модели, цена, кошелёк, вывод, платежи, ручные воркеры.
- Сервер статуса — локальная HTTP-плоскость на
127.0.0.1, первый свободный порт в 47821–47826, используется панелью и клиентским адаптером. - Seed admin — отдельная консоль на виртуальной машине seed за Caddy по пути
/admin, читает статистику seed и аккаунты программы. Она не хранит ключи кошелька и не двигает деньги.
Чего намеренно нет
- Ни токена, ни стейкинга, ни токена кредитного рейтинга.
- Ни сервера оркестрации, ни базы данных промптов.
- Ни автоматического фильтра контента — в протоколе нет хука, который проверяет промпт до того, как его увидит воркер.
- Ни оракула цен в блокчейне: ставка — это число, которое публикует воркер, а пользователь решает, стоит ли за неё платить.