아키텍처
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 | 시드 호스트용 운영자 콘솔 |
프로토콜 코어는 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, USDC mint, 세션 상한, 다음 세션 id, 재무 적립액 |
| Session | ["session", id] | 사용자, 워커, 가격, 보증금, 적립액, 분, 타임스탬프, 상태 |
에스크로의 USDC는 ["escrow"] PDA의 연결 토큰 계정에 있습니다. 프로그램은 전송마다 그 계정의
mint와 owner를 검사하며 온체인에서 주소를 도출하지 않습니다. 토큰 프로그램이 이미 두 필드의
권위이고, 바이너리는 배포 가능한 렌트 예산 하나에 들어가야 하기 때문입니다.
계정은 8바이트 discriminator를 가진 고정 크기 바이트 버퍼이므로, 읽는 쪽에 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 뒤의 피어는 릴레이를 쓰거나 도달할 수 없습니다.
발견
두 개의 독립 경로:
- 온체인 디렉터리 — 한 번의
getProgramAccounts호출이 모든 Worker 계정을 반환합니다. 클라이언트는 비활성 행을 걸러 내고, 각 행의 peer id가 그 지갑을 인코딩하는지 검증하며, 결과를 디스크에 캐시하여 네트워크가 없는 부팅에서도 무언가를 나열합니다. - 시드 릴레이 —
https://seed.genkaku.app/seed(스테이징:staging.genkaku.app/seed)는 지금 실제로 유효한 multiaddr을GET /peers로 응답하고, 직접 연결할 수 없는 피어에 circuit relay를 제공합니다.
시드 주소는 protocol 패키지에 박혀 있지만 GENKAKU_BOOTSTRAP_SEEDS(쉼표로 구분된 URL)로
재정의할 수 있습니다.
비공개 워커
가시성은 프로그램이 아니라 워커의 속성입니다. 정산에는 지불할 계정이 필요하므로 모든 워커 계정은 행을 유지합니다.
| 공개 | 비공개 | |
|---|---|---|
| 시드에 알림 | 예 | 아니오 |
| 체인 행의 로케이터 | 전역에서 다이얼 가능한 주소가 있을 때 기록 | 항상 비어 있음 |
active 플래그 | 1 | 1 — open_session은 inactive 워커를 거부 |
| 다이얼할 수 있는 사람 | peer id를 찾은 누구나 | 허용 목록의 지갑 |
게이트는 libp2p 스트림 핸들러에서 connection.remotePeer를 검사합니다. 이것은 요청 안의 주장이
아니라 전송 계층이 인증한 값입니다. walletOfPeerId()가 이를 다시 Solana 주소로 바꾸며, 하나의
ed25519 키가 지갑과 PeerId를 겸할 수 있는 이유가 여기 있습니다. 두 번 서명하지 않고 베어러
토큰도 저장하지 않습니다.
접근은 /genkaku/pair/0의 페어링 교환으로 부여합니다.
genkaku1.<base64url({ peerId, wallet, name, addrs, relay, secret, exp })>
워커는 sha256(secret)만 보관하며 코드마다 한 항목, 만료(15분)와 usedAt 표시를 둡니다.
교환은 문자열이 아니라 교환한 사람의 지갑에 묶이므로, 유출된 코드는 키가 아니라 코드일
뿐입니다. 사용한 코드를 그 지갑에서 재시도하면 멱등적으로 성공하고, 다른 지갑에서는 거부됩니다.
비공개 모드가 익명은 아닙니다. 릴레이는 여전히 회로를 나르고, 체인은 여전히 지불을 기록하며, 워커 운영자는 여전히 프롬프트를 봅니다.
클라이언트 설정
사용자 플러그인은 네트워크가 제공한 것이 아니라 사람이 고른 것을 저장합니다.
| 키 | 의미 |
|---|---|
selected | (worker, model) 키, 최대 10개(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이면
빈 목록은 선택이며 브리지는 다시 채우지 않습니다. 상한은 UI와 브리지 양쪽에서 강제합니다.
브리지가 유일한 기록자이고 HTTP 클라이언트는 UI가 아니기 때문입니다.
페어링된 비공개 워커는 백그라운드 티커(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
올림은 tick마다가 아니라 한 번만 일어나므로, 사용자는 견적된 시간당 가격을 초과해 지불하지 않고 워커의 미청구 노출은 최대 1분입니다.
유료 세션은 두 개의 트랜잭션입니다.
open_session(worker, price, deposit)— 사용자의 USDC가 토큰 계정에서 에스크로 vault로 나갑니다.settle(minutes)— 워커가 서명: 99%는 인출 가능 잔액으로, 1%는 재무로. 그다음 클라이언트가 세션을 닫아 나머지를 돌려받고,claim이 마지막 정산 10분 후 워커에게 지급합니다.
견적 0은 어떤 세션도 없이 제공되며, 그래서 무료 워커는 USDC가 전혀 없는 머신에서도 돌릴 수
있습니다.
운영자 접점
- 패널 — DeepSeek Harness 안의 플러그인 자체 UI: 모델, 가격, 지갑, 청구, 결제, 수동 워커.
- 상태 서버 —
127.0.0.1의 로컬 HTTP 접점. 47821–47826의 첫 번째 빈 포트를 사용하며, 패널과 클라이언트 어댑터가 씁니다. - Seed admin — Caddy 뒤
/admin에 있는 시드 VM의 별도 콘솔. 시드 통계와 프로그램의 계정을 읽습니다. 지갑 키를 보관하지 않고 돈을 옮기지도 않습니다.
의도적으로 없는 것
- 토큰도, 스테이킹도, 신용 점수 토큰도 없습니다.
- 오케스트레이션 서버도, 프롬프트 데이터베이스도 없습니다.
- 자동 콘텐츠 필터가 없습니다. 프로토콜에는 워커가 보기 전에 프롬프트를 검사하는 훅이 없습니다.
- 온체인 가격 오라클이 없습니다. 요율은 워커가 공개하는 숫자이고, 지불할 가치가 있는지는 사용자가 결정합니다.