Architecture
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
| Package | Role |
|---|---|
@genkaku/protocol | Solana bindings, campaign billing, libp2p sidecar, Ollama bridge |
@genkaku/dsh-runtime | The adapter both plugins share |
@genkaku/dsh-worker-plugin@0.5.0-rc.8 | Serves local models |
@genkaku/dsh-user-plugin@0.5.0-rc.8 | Consumes network models |
@genkaku/seed | libp2p relay and peer discovery service |
@genkaku/admin | Operator 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.
| Account | Seeds | What 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
| Name | Value | Meaning |
|---|---|---|
FEE_BPS | 100 | the 1% split, a constant rather than a setting |
ABSOLUTE_SESSION_CAP | 100 USDC | worst-case exposure of one session |
CLAIM_DELAY_SECS | 600 | window in which the user can still close |
IDLE_CLOSE_SECS | 86 400 | after a day of silence, anyone may close |
MAX_PRICE_PER_MIN | 1 USDC | keeps 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:
- On-chain directory — one
getProgramAccountscall 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. - Seed relay —
https://seed.genkaku.app/seed(staging:staging.genkaku.app/seed) answersGET /peerswith 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.
| Public | Private | |
|---|---|---|
| Announce to the seed | yes | no |
| Locator in the chain row | written when a globally dialable address exists | always empty |
active flag | 1 | 1 — open_session refuses an inactive worker |
| Who may dial | anyone who finds the peer id | wallets 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:
| Key | Meaning |
|---|---|
selected | (worker, model) keys, at most ten (MAX_SELECTED_MODELS) |
seeded | false until the list has been materialised once |
sort | one of six orders; the same order drives the picker |
privatePeers | paired 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:
| File | Meaning |
|---|---|
policy.json | SpendPolicy: enabled, name, expiry, credit limit, reset cadence, per-session cap, price cap, window spend, lifetime spend, pending reservations |
spend.jsonl | settled 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:
open_session(worker, price, deposit)— the user's USDC leaves their token account for the escrow vault,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;claimpays 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.