Saltar al contenido principal

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​

PaqueteRol
@genkaku/protocolBindings de Solana, facturación del escrow, sidecar libp2p, puente de Ollama
@genkaku/dsh-runtimeEl adaptador que comparten ambos plugins
@genkaku/dsh-worker-plugin@0.5.0-rc.8Sirve modelos locales
@genkaku/dsh-user-plugin@0.5.0-rc.8Consume modelos de la red
@genkaku/seedRelay libp2p y servicio de descubrimiento de pares
@genkaku/adminConsola 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.

CuentaSeedsQué 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​

NombreValorSignificado
FEE_BPS100el reparto del 1%, una constante y no un ajuste
ABSOLUTE_SESSION_CAP100 USDCexposición en el peor caso de una sesión
CLAIM_DELAY_SECS600ventana en la que el usuario todavía puede cerrar
IDLE_CLOSE_SECS86 400tras un día de silencio, cualquiera puede cerrar
MAX_PRICE_PER_MIN1 USDCevita 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:

  1. Directorio en la cadena: una llamada getProgramAccounts devuelve 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.
  2. Relay semilla: https://seed.genkaku.app/seed (staging: staging.genkaku.app/seed) responde a GET /peers con 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úblicoPrivado
Anuncio a la semillasíno
Localizador en la filaescrito cuando hay una dirección globalsiempre vacío
Bandera active11 — open_session rechaza un worker inactivo
Quién puede marcarcualquiera que encuentre el peer idbilleteras 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:

ClaveSignificado
selectedclaves (worker, model), como mucho diez (MAX_SELECTED_MODELS)
seededfalse hasta que la lista se ha materializado una vez
sortuno de seis órdenes; el mismo orden guía el selector
privatePeersworkers 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:

ArchivoSignificado
policy.jsonSpendPolicy: 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.jsonlsesiones 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:

  1. open_session(worker, price, deposit): el USDC del usuario sale de su cuenta de token hacia el vault del escrow,
  2. 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; claim paga 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.