Перейти к основному содержимому

Архитектура

Всё, что 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_BPS100разделение 1%, константа, а не настройка
ABSOLUTE_SESSION_CAP100 USDCхудший случай экспозиции одной сессии
CLAIM_DELAY_SECS600окно, в котором пользователь ещё может закрыть
IDLE_CLOSE_SECS86 400после суток молчания закрыть может кто угодно
MAX_PRICE_PER_MIN1 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 использует релей или остаётся недоступным.

Обнаружение​

Два независимых пути:

  1. Каталог в блокчейне — один вызов getProgramAccounts возвращает все аккаунты Worker. Клиент отфильтровывает неактивные строки, проверяет, что peer id каждой строки кодирует её кошелёк, и кэширует результат на диске, чтобы даже загрузка без сети что-то показывала.
  2. Seed-релей — https://seed.genkaku.app/seed (стейджинг: staging.genkaku.app/seed) отвечает на GET /peers multiaddr'ами, которые верны прямо сейчас, и предоставляет circuit relay для пиров, которые не могут подключиться напрямую.

Адрес seed зашит в пакет protocol, но его можно переопределить через GENKAKU_BOOTSTRAP_SEEDS (URL через запятую).

Приватные воркеры​

Видимость — свойство воркера, а не программы: каждый аккаунт воркера сохраняет свою строку, потому что расчёту нужен счёт, на который платить.

ПубличныйПриватный
Объявление в seedданет
Локатор в строкезаписывается, когда есть глобально доступный адресвсегда пуст
Флаг active11 — 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)
seededfalse, пока список не материализован один раз
sortодин из шести порядков; тот же порядок ведёт выбор модели
privatePeersсопряжённые приватные воркеры: кошелёк, peer id, addrs, relay, метка

В том же каталоге ~/.dsh/genkaku лежат ещё два файла, которые являются политикой самого клиента, а не настройками, видимыми сети:

ФайлЗначение
policy.jsonSpendPolicy: включена ли, имя, срок, лимит, период сброса, лимит на сессию, ценовой лимит, расход за период, расход за всё время, ожидающие резервации
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

Округление происходит один раз, а не на каждом тике, поэтому пользователь никогда не платит больше объявленной цены за час, а неоплаченная экспозиция воркера составляет не более одной минуты.

Платная сессия — это две транзакции:

  1. open_session(worker, price, deposit) — USDC пользователя уходит с его токен-аккаунта в vault эскроу,
  2. settle(minutes) — подписывает воркер: 99% на его доступный для вывода баланс, 1% в казну. Затем клиент закрывает сессию, чтобы забрать остаток; claim выплачивает воркеру через десять минут после последнего расчёта.

Цена 0 обслуживается вообще без сессии — поэтому бесплатный воркер может работать на машине, где нет ни USDC, ни чего-либо ещё.

Интерфейсы оператора​

  • Панель — собственный UI плагина в DeepSeek Harness: модели, цена, кошелёк, вывод, платежи, ручные воркеры.
  • Сервер статуса — локальная HTTP-плоскость на 127.0.0.1, первый свободный порт в 47821–47826, используется панелью и клиентским адаптером.
  • Seed admin — отдельная консоль на виртуальной машине seed за Caddy по пути /admin, читает статистику seed и аккаунты программы. Она не хранит ключи кошелька и не двигает деньги.

Чего намеренно нет​

  • Ни токена, ни стейкинга, ни токена кредитного рейтинга.
  • Ни сервера оркестрации, ни базы данных промптов.
  • Ни автоматического фильтра контента — в протоколе нет хука, который проверяет промпт до того, как его увидит воркер.
  • Ни оракула цен в блокчейне: ставка — это число, которое публикует воркер, а пользователь решает, стоит ли за неё платить.