Pular para o conteúdo principal

Architecture

0.5 preview

Users pay nothing; sponsored placements and tips pay workers. Escrow/session wording elsewhere describes 0.2 and is being retired. See Ads, wallets and languages.

Everything GenKaKu runs in production is either a static site or a peer process. Nothing in the request path is a GenKaKu server.

Packages​

PackageRole
@genkaku/protocolSolana bindings, campaign billing, libp2p sidecar, Ollama bridge
@genkaku/dsh-runtimeThe adapter both plugins share
@genkaku/dsh-worker-plugin@0.5.0-rc.8Serves local models
@genkaku/dsh-user-plugin@0.5.0-rc.8Consumes network models
@genkaku/seedlibp2p relay and peer discovery service
@genkaku/adminOperator console for the seed host

The protocol core has no dependency on DeepSeek Harness. That is deliberate: another adapter should not require touching it.

On-chain​

One program, deployed at the same address on Solana mainnet-beta and Solana devnet. The address is published on the website and in the plugins' netconfig.ts; the site's build refuses to advertise a program id before the deployment has run.

AccountSeedsWhat it holds
RegistryConfig["registry"]owner, pending owner, workers-ever-registered
Worker["worker", wallet]peer id, rate, locator, active, earned, settlements
EscrowConfig["escrow"]owner, treasury, guardian, vault, USDC mint, session cap, next session id, treasury accrued
Session["session", id]user, worker, price, deposit, accrued, minutes, timestamps, status

The escrow's USDC sits in the associated token account of the ["escrow"] PDA. The program checks that account's mint and owner on every transfer instead of deriving an address on chain: the token program is already the authority on both fields, and the binary has to fit in one deployable rent budget.

Accounts are fixed-size byte buffers with an 8-byte discriminator, so a reader needs no IDL — getAccountInfo plus a documented offset. The layout is written down in solana/LAYOUT.md in the repository and mirrored in packages/protocol/src/solana.ts.

Constants in the program​

NameValueMeaning
FEE_BPS100the 1% split, a constant rather than a setting
ABSOLUTE_SESSION_CAP100 USDCworst-case exposure of one session
CLAIM_DELAY_SECS600window in which the user can still close
IDLE_CLOSE_SECS86 400after a day of silence, anyone may close
MAX_PRICE_PER_MIN1 USDCkeeps a mistyped price from being taken seriously

Data plane​

Workers serve these libp2p protocols:

/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

Every handler accepts a relayed connection (runOnLimitedConnection). A session is therefore either direct or relay-carried, and both are first-class. libp2p encrypts the stream, so the relay forwards ciphertext and sees metadata only.

There is no DCUtR / hole punching in this build. A peer behind symmetric NAT uses the relay or is not reachable.

Discovery​

Two independent paths:

  1. On-chain directory — one getProgramAccounts call returns every Worker account. A client filters out inactive rows, verifies that each row's peer id encodes its wallet, and caches the result on disk so a boot with no network still lists something.
  2. Seed relay — https://seed.genkaku.app/seed (staging: staging.genkaku.app/seed) answers GET /peers with the multiaddrs that are true right now, and provides a circuit relay for peers that cannot connect directly.

The seed address is baked into the protocol package but can be overridden with GENKAKU_BOOTSTRAP_SEEDS (comma-separated URLs).

Private workers​

Visibility is a property of the worker, not of the program: every worker account keeps its row, because settlement needs an account to pay.

PublicPrivate
Announce to the seedyesno
Locator in the chain rowwritten when a globally dialable address existsalways empty
active flag11 — open_session refuses an inactive worker
Who may dialanyone who finds the peer idwallets on the allowlist

The gate is checked on the libp2p stream handler with connection.remotePeer — a value the transport authenticated, not a claim in a request. walletOfPeerId() turns it back into the Solana address, which is why one ed25519 key can be a wallet and a PeerId at once. Nothing is signed twice and no bearer token is stored.

Access is granted by a pairing exchange on /genkaku/pair/0:

genkaku1.<base64url({ peerId, wallet, name, addrs, relay, secret, exp })>

The worker keeps only sha256(secret), one entry per code, with an expiry (15 minutes) and a usedAt stamp. Redeeming binds the redeemer's wallet, not the string, so a leaked code is a code, not a key. A used code retried from the wallet that used it succeeds idempotently; from any other wallet it is refused.

Private mode is not anonymous. The relay still carries the circuit, the chain still records payments, and the worker's operator still sees the prompts.

Client preferences​

The user plugin stores what the person chose, never what the network offered:

KeyMeaning
selected(worker, model) keys, at most ten (MAX_SELECTED_MODELS)
seededfalse until the list has been materialised once
sortone of six orders; the same order drives the picker
privatePeerspaired private workers: wallet, peer id, addrs, relay, label

Two more files sit in the same ~/.dsh/genkaku directory and are the client's own policy, not preferences the network can see:

FileMeaning
policy.jsonSpendPolicy: enabled, name, expiry, credit limit, reset cadence, per-session cap, price cap, window spend, lifetime spend, pending reservations
spend.jsonlsettled sessions: time, micro-USDC, model, worker, escrow id, tx; trimmed to the last 1000 lines past 512 KiB

policy.json is deliberately not an on-chain account. The chain enforces the deposit it is given; the client is the only place that knows the ceiling above it, and the only thing a refusal costs is an HTTP 402 before any transaction is built. selected plus seeded is what makes "I unticked everything" survive a restart: an empty list is a choice once seeded is true, and the bridge no longer refills it. The cap is enforced in the bridge as well as the UI, because the bridge is the only writer and an HTTP client is not the UI.

Paired private workers are probed on a background ticker (20 s). A probe that comes back with an empty board is treated as refused, not as online with no models, so the panel never claims a private worker is up when the allowlist says otherwise. Probing never blocks a status request.

Billing model​

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

Rounding happens once, never per tick, so the user never pays more than the quoted hourly price and the worker's unbilled exposure is at most one minute.

A paid session is two transactions:

  1. open_session(worker, price, deposit) — the user's USDC leaves their token account for the escrow vault,
  2. settle(minutes) — signed by the worker: 99% to its claimable balance, 1% to the treasury. The client then closes the session to take back the remainder; claim pays the worker ten minutes after the last settle.

A quote of 0 is served without any session, which is why a free worker can run on a machine with no USDC at all.

Operator surfaces​

  • Panel — the plugin's own UI in DeepSeek Harness: models, price, wallet, claim, payments, manual workers.
  • Status server — a local HTTP surface on 127.0.0.1, first free port in 47821–47826, used by the panel and the client adapter.
  • Seed admin — a separate console on the seed VM behind Caddy at /admin, reading seed statistics and the program's accounts. It holds no wallet keys and moves no money.

What is intentionally absent​

  • No token, no staking, no credit score token.
  • No orchestration server, no database of prompts.
  • No automatic content filter — the protocol has no hook that inspects a prompt before a worker sees it.
  • No on-chain price oracle: a rate is a number the worker publishes, and the user decides whether it is worth paying.