Arquitectura
Todo lo que GenKaKu ejecuta en producción es un sitio estático o un proceso de par. Nada en la ruta de la petición es un servidor de GenKaKu.
Paquetes
| Paquete | Rol |
|---|---|
@genkaku/protocol | Bindings de Solana, facturación del escrow, sidecar libp2p, puente de Ollama |
@genkaku/dsh-runtime | El adaptador que comparten ambos plugins |
@genkaku/dsh-worker-plugin@0.5.0-rc.8 | Sirve modelos locales |
@genkaku/dsh-user-plugin@0.5.0-rc.8 | Consume modelos de la red |
@genkaku/seed | Relay libp2p y servicio de descubrimiento de pares |
@genkaku/admin | Consola de operador para el host de la semilla |
El núcleo del protocolo no depende de DeepSeek Harness. Es algo deliberado: otro adaptador no debería requerir tocarlo.
En la cadena
Un programa, desplegado en la misma dirección en Solana mainnet-beta y
Solana devnet. La dirección se publica en el sitio web y en el netconfig.ts
de los plugins; la compilación del sitio se niega a anunciar un id de programa
antes de que se haya ejecutado el despliegue.
| Cuenta | Seeds | Qué contiene |
|---|---|---|
| RegistryConfig | ["registry"] | owner, pending owner, workers registrados desde el inicio |
| Worker | ["worker", wallet] | peer id, tarifa, localizador, active, earned, settlements |
| EscrowConfig | ["escrow"] | owner, tesorería, guardian, vault, mint de USDC, tope por sesión, siguiente id de sesión, acumulado de tesorería |
| Session | ["session", id] | usuario, worker, precio, depósito, acumulado, minutos, marcas de tiempo, estado |
El USDC del escrow está en la cuenta de token asociada de la PDA ["escrow"]. El
programa comprueba el mint y el owner de esa cuenta en cada transferencia en lugar
de derivar una dirección en la cadena: el programa de tokens ya es la autoridad
sobre ambos campos, y el binario tiene que caber en un presupuesto de rent
desplegable.
Las cuentas son búferes de bytes de tamaño fijo con un discriminador de 8 bytes,
así que un lector no necesita IDL: getAccountInfo más un desplazamiento
documentado. El diseño está escrito en solana/LAYOUT.md del repositorio y
reflejado en packages/protocol/src/solana.ts.
Constantes del programa
| Nombre | Valor | Significado |
|---|---|---|
FEE_BPS | 100 | el reparto del 1%, una constante y no un ajuste |
ABSOLUTE_SESSION_CAP | 100 USDC | exposición en el peor caso de una sesión |
CLAIM_DELAY_SECS | 600 | ventana en la que el usuario todavía puede cerrar |
IDLE_CLOSE_SECS | 86 400 | tras un día de silencio, cualquiera puede cerrar |
MAX_PRICE_PER_MIN | 1 USDC | evita que un precio mal tecleado se tome en serio |
Plano de datos
Los workers sirven estos protocolos 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
Todos los manejadores aceptan una conexión retransmitida
(runOnLimitedConnection). Por tanto, una sesión es directa o transportada por el
relay, y ambas son de primera clase. libp2p cifra el flujo, así que el relay
reenvía texto cifrado y solo ve metadatos.
En esta versión no hay DCUtR ni perforación de NAT. Un par detrás de un NAT simétrico usa el relay o no es alcanzable.
Descubrimiento
Dos rutas independientes:
- Directorio en la cadena: una llamada
getProgramAccountsdevuelve todas las cuentas Worker. Un cliente filtra las filas inactivas, verifica que el peer id de cada fila codifique su billetera y guarda el resultado en caché en disco para que un arranque sin red siga listando algo. - Relay semilla:
https://seed.genkaku.app/seed(staging:staging.genkaku.app/seed) responde aGET /peerscon las multiaddrs que son ciertas en este momento, y ofrece un relay de circuito para los pares que no pueden conectarse directamente.
La dirección de la semilla está grabada en el paquete de protocolo, pero puede
sobrescribirse con GENKAKU_BOOTSTRAP_SEEDS (URL separadas por comas).
Workers privados
La visibilidad es una propiedad del worker, no del programa: toda cuenta de worker conserva su fila, porque la liquidación necesita una cuenta a la que pagar.
| Público | Privado | |
|---|---|---|
| Anuncio a la semilla | sí | no |
| Localizador en la fila | escrito cuando hay una dirección global | siempre vacío |
Bandera active | 1 | 1 — open_session rechaza un worker inactivo |
| Quién puede marcar | cualquiera que encuentre el peer id | billeteras de la lista de permitidos |
La puerta se comprueba en el handler del stream libp2p con
connection.remotePeer, un valor que autenticó el transporte y no una
afirmación de la petición. walletOfPeerId() lo convierte de vuelta en la
dirección Solana, y por eso una sola clave ed25519 puede ser billetera y PeerId a
la vez. Nada se firma dos veces y no se guarda ningún token portador.
El acceso se concede con un intercambio de emparejamiento en /genkaku/pair/0:
genkaku1.<base64url({ peerId, wallet, name, addrs, relay, secret, exp })>
El worker guarda solo sha256(secret), una entrada por código, con caducidad (15
minutos) y marca usedAt. Canjearlo vincula la billetera de quien lo canjea,
no la cadena, así que un código filtrado es un código, no una clave. Un código
usado reintentado desde la billetera que lo usó tiene éxito idempotente; desde
cualquier otra se rechaza.
El modo privado no es anónimo. El relay sigue llevando el circuito, la cadena sigue registrando pagos y el operador del worker sigue viendo los prompts.
Preferencias del cliente
El plugin de usuario guarda lo que eligió la persona, nunca lo que ofreció la red:
| Clave | Significado |
|---|---|
selected | claves (worker, model), como mucho diez (MAX_SELECTED_MODELS) |
seeded | false hasta que la lista se ha materializado una vez |
sort | uno de seis órdenes; el mismo orden guía el selector |
privatePeers | workers privados emparejados: billetera, peer id, addrs, relay, etiqueta |
En el mismo directorio ~/.dsh/genkaku hay dos archivos más que son política del
propio cliente, no preferencias visibles para la red:
| Archivo | Significado |
|---|---|
policy.json | SpendPolicy: activado, nombre, caducidad, límite de crédito, cadencia de reinicio, tope por sesión, tope de precio, gasto del periodo, gasto total, reservas pendientes |
spend.jsonl | sesiones liquidadas: hora, micro-USDC, modelo, worker, id de escrow, tx; recortado a las últimas 1000 líneas al pasar 512 KiB |
policy.json no es, deliberadamente, una cuenta en la cadena. La cadena hace
cumplir el depósito que recibe; el techo por encima solo lo conoce el cliente, y lo
único que cuesta un rechazo es un HTTP 402 antes de construir la transacción.
selected más seeded es lo que hace que «lo desmarqué todo» sobreviva a un
reinicio: una lista vacía es una elección cuando seeded es true, y el puente ya
no la rellena. El límite se aplica en el puente y en la interfaz, porque el
puente es el único escritor y un cliente HTTP no es la interfaz.
Los workers privados emparejados se sondean en un ticker de fondo (20 s). Un sondeo que vuelve con un tablero vacío se trata como rechazado, no como en línea sin modelos, para que el panel nunca afirme que un worker privado está activo cuando la lista de permitidos dice lo contrario. El sondeo nunca bloquea una petición de estado.
Modelo de facturación
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
El redondeo ocurre una sola vez, nunca por tick, así que el usuario nunca paga más que el precio por hora cotizado y la exposición no facturada del worker es como mucho un minuto.
Una sesión de pago son dos transacciones:
open_session(worker, price, deposit): el USDC del usuario sale de su cuenta de token hacia el vault del escrow,settle(minutes): firmada por el worker, el 99% a su saldo reclamable y el 1% a la tesorería. Después el cliente cierra la sesión para recuperar el resto;claimpaga al worker diez minutos después de la última liquidación.
Una cotización de 0 se sirve sin ninguna sesión, y por eso un worker gratuito
puede correr en una máquina sin nada de USDC.
Superficies de operador
- Panel: la propia UI del plugin en DeepSeek Harness: modelos, precio, billetera, reclamación, pagos, workers manuales.
- Servidor de estado: una superficie HTTP local en
127.0.0.1, primer puerto libre en 47821–47826, usada por el panel y por el adaptador del cliente. - Seed admin: una consola aparte en la VM de la semilla, detrás de Caddy en
/admin, que lee estadísticas de la semilla y las cuentas del programa. No guarda claves de billetera ni mueve dinero.
Lo que falta a propósito
- Sin token, sin staking, sin token de puntuación de crédito.
- Sin servidor de orquestación, sin base de datos de prompts.
- Sin filtro automático de contenido: el protocolo no tiene ningún hook que inspeccione un prompt antes de que lo vea un worker.
- Sin oráculo de precios en la cadena: una tarifa es un número que publica el worker, y el usuario decide si merece la pena pagarlo.