Architecture
The chain does three things: it registers Slots, mints coins, and moves money. Everything about who did what happens off the chain, between three parts the Slot operator runs and one program on each participant's machine.
The five parts
| Part | Who runs it | What it holds | What it never has |
|---|---|---|---|
| The chain | the Slot operators, as validators | the Slot records, how much each Slot is owed per period, and the payments made | anything about the work, or about who the participants are beyond a payment address |
| A validator | each Slot operator | one consensus key with voting power 1 | stake: there is none, and no slashing |
| A provider | the Slot operator | the work itself, and a one-line record per unit: account, time, reference | your wallet, your payment address |
| An authorization server | the Slot operator, one per Slot | enrollments, the period calendar, reports and their verification status, the settlement key | the content of any work, prompts or results |
| The client | you, on your machine | the keys, the payment address, and reports not yet sent | nothing that stays running; it exits after each unit |
Slots covers what makes a Slot and who runs one. MINIS is the authorization server in detail. The client for the open Slot is Jevlin's, and its own docs describe it.
Where the code lives
| Part | Repository | What is in it |
|---|---|---|
| The chain | twilight-project/twilight-core | twilightd, the Cosmos SDK app with the coreslot, rewards and mining modules, the protobuf definitions, and the operator guide |
| The authorization server | twilight-project/twilight-minis | minis-server, the minis-scheduler that drives each period, drawverify, the deployment runbooks and the ADRs |
The provider and the client belong to each Slot's operator. For the open Slot they are Jevlin's; see Slots.
What passes between them
- Work. The agent calls the client; the client does the unit through the provider and hands the result back. For the search Slot this is one web search through the router.
- A record, in two places. The provider keeps one line about the unit: which account, when, a reference. The client keeps the same line as a report, and sends it to the authorization server right afterwards.
- Verification. The authorization server asks the provider's verification API whether that reference really happened for that account. If so, the report is verified and the participant is counted in for the period.
- Entitlement. Separately, every block the chain credits each active Slot one block of participation. At the period's close it mints the period's new coins into escrow and writes each Slot's share as an entitlement addressed to the operator's payout address.
- Settlement. The authorization server submits transactions that release the entitlement to participants in chunks, then finalizes. What is not paid to participants goes to the Slot's payout address. Rewards has the rules.
Nothing in steps 1 to 3 touches the chain, and nothing in 4 or 5 touches the work. That separation is the design: the part that sees your work cannot pay you, and the part that pays you cannot see your work. How mining works lays out who sees what.
What the chain records
The chain is a Cosmos SDK Proof-of-Authority chain with the staking, slashing, governance and distribution modules left out. Three modules carry the mechanism.
| Module | Plain words | What it stores |
|---|---|---|
| coreslot | the register of Slots, and the validator set | one record per Slot: operator, consensus key, payout and settlement addresses, status, metadata. The only module that changes the validator set. |
| rewards | the mint | the block subsidy, the halving schedule, the supply cap, and one entitlement per Slot per period |
| mining | the payment desk | one settlement per Slot per period, its chunk cursor, and whether it is finalized. It owns only two transactions: submit a chunk, finalize. |
Everything the chain decides is deterministic and integer-only, and a period's close either fully succeeds or changes nothing. The chain never decides who did work. It decides how much a Slot is owed and enforces that the money can go only to the addresses in a chunk or to the Slot's recorded payout address.
What stays off the chain
- Which account did what. Enrollment binds an installation to a provider account; that binding lives in the authorization server, not on the chain.
- The period calendar as participants see it. Join windows, submission deadlines and verification happen in the authorization server. The chain knows only epochs by block height.
- The split among participants. Under today's distribution mode the authorization server computes it and the chain trusts the chunk it submits, within the chain's caps. A verifiable draw, anchored on chain before the randomness is known, is built and can be checked by anyone; see MINIS.
- Discovery. A client finds a Slot's authorization server by a URL the operator publishes; the server's discovery document names the chain and Slot it serves, and the client refuses one that does not match.
Trust, in one paragraph
A participant trusts the operator for two things: that the provider records work honestly, and that the authorization server pays the eligible set as it says. They do not trust the operator with their keys, their wallet, or their code. The chain limits what a dishonest operator can do with the money: it cannot redirect the remainder, cannot pay anyone outside a submitted chunk, cannot pay more than the entitlement, and leaves a record of every chunk. An operator who stops settling simply forfeits nothing to participants and keeps the entitlement at their payout address, which is visible to everyone.