Join our community of builders on Discord!

Canonical Data Sources

Different parts of worker state come from different contracts.
ContractBest used for
CodeHTML
Registration, stake, supported models, eligible sets, jail state
CodeHTML
Sessions, jobs, disputes, releases, worker withdrawals
CodeHTML
Minimum stake, slash settings, dispute settings, model configuration
If you only query contract storage through ABI calls, you will not be able to reconstruct full job and session history.

How To Think About Worker State

A worker is practically assignable when all of the following are true:
  • the worker is registered
  • the worker is not jailed
  • the worker meets the global minimum stake
  • the worker supports the model
  • the model is whitelisted
  • the worker is currently in the eligible set for that model
The actual session-assignment check in
CodeHTML
is:
  • CodeHTML
That makes the eligible set the most important assignment boundary for explorer and dispatcher tooling.

Core Read Functions

These reads are the foundation of a worker explorer.
ContractFunctionMeaning
CodeHTML
CodeHTML
Current registration state
CodeHTML
CodeHTML
Current global stake
CodeHTML
CodeHTML
Registered encryption key
CodeHTML
CodeHTML
Worker-declared support for a model
CodeHTML
CodeHTML
Whether the worker is currently assignable for a model
CodeHTML
CodeHTML
Current eligible worker set for a model
CodeHTML
CodeHTML
In-flight jobs assigned to the worker
CodeHTML
CodeHTML
Jail status
CodeHTML
CodeHTML
Jail expiry timestamp
CodeHTML
CodeHTML
Current offense count
CodeHTML
CodeHTML
Worker-side model whitelist flag
CodeHTML
CodeHTML
Global minimum stake
CodeHTML
CodeHTML
Offenses before jailing
CodeHTML
CodeHTML
Cooldown duration
CodeHTML
CodeHTML
Config-side model flag
CodeHTML
CodeHTML
Consumer nonce used for dispatcher signatures

Eligibility Set Semantics

Each model has an
CodeHTML
eligible set inside
CodeHTML
. Important behavior:
  • workers are appended when added
  • removals use swap-and-pop
  • ordering is not stable
  • list position should never be treated as meaningful
[!TIP] Use
CodeHTML
for reconciliation, not as your only source of history.
For historical views, keep your own indexed cache from events.

What Changes Eligibility

A worker enters a model's eligible set when:
  • the worker is registered
  • the worker calls
    CodeHTML
  • the model is whitelisted in
    CodeHTML
  • the model is enabled in
    CodeHTML
  • the worker's stake is at least
    CodeHTML
A worker leaves that eligible set when:
  • the worker calls
    CodeHTML
  • the worker deregisters
  • slashing drops stake below the minimum
  • the worker is jailed
There is no pause or unpause feature in the current
CodeHTML
design.

Registration, Stake, And Jail Flow

Register

CodeHTML
:
  • requires a non-empty key
  • requires
    CodeHTML
  • stores one global stake amount for the worker

Top Up

CodeHTML
:
  • increases global stake
  • can re-add the worker to supported models if eligibility had been lost due to low stake

Withdraw

CodeHTML
:
  • allows stake withdrawal
  • cannot reduce remaining stake below the minimum if the worker still supports any model

Deregister

CodeHTML
:
  • requires
    CodeHTML
  • removes the worker from all eligible sets
  • returns the remaining stake

Slash And Jail

Only
CodeHTML
can slash a worker. Slash formula:
CodeTEXT
Important consequences:
  • slash size is based on the global minimum stake, not the worker's current stake
  • if the slash exceeds current stake, it is capped at current stake
  • offense count increases on each slash
  • workers can be removed from eligibility when stake falls below minimum
  • workers are jailed when offense count reaches the configured threshold
Unjailing resets offense count and can re-add the worker to supported models if stake is still sufficient.

Model Availability Caveat

Explorers should show both model flags separately:
  • CodeHTML
  • CodeHTML
These are checked in different places.
CodeHTML
requires:
  • whitelist present
  • model enabled
But
CodeHTML
only checks:
  • CodeHTML
A model disabled in config is not automatically removed from the eligible set. For explorer UIs, this means a worker can still look assignable unless you display both model-control layers.

Events You Should Index

Because job and session structs are not publicly exposed through getters, index these events.

Session events

EventMeaning
CodeHTML
New session created
CodeHTML
Worker changed for the session
CodeHTML
Session worker key rotated
CodeHTML
Session closed to new jobs

Job events

EventMeaning
CodeHTML
Job created and escrowed
CodeHTML
Worker accepted the job
CodeHTML
Worker completed the job
CodeHTML
Timeout path executed
CodeHTML
Job moved into dispute
CodeHTML
Dispute resolved
CodeHTML
Payout split recorded
CodeHTML
Job finalized
CodeHTML
Worker withdrew earnings

Reconstructing Job State

A practical event-driven state machine looks like this:
CodeTEXT
Useful implementation notes:
  • CodeHTML
    can release both
    CodeHTML
    and
    CodeHTML
    jobs
  • CodeHTML
    jobs become releasable after the dispute window
  • CodeHTML
    jobs become releasable immediately
  • disputed timeout handling can emit
    CodeHTML
    instead of
    CodeHTML

Earnings And Accounting

Explorer UIs should separate three balances:
  • worker stake in
    CodeHTML
  • worker earnings credited inside
    CodeHTML
  • slashed funds accumulated by the protocol
Current contract limitation:
  • CodeHTML
    is not exposed through a public getter
  • CodeHTML
    is not exposed through a public getter
That means:
  • worker earnings should be reconstructed from
    CodeHTML
    and
    CodeHTML
  • burn totals should be reconstructed from
    CodeHTML

Recommended UI Fields

For a worker detail page, the most useful fields are:
  • registration status
  • current stake
  • encryption key presence
  • supported models
  • eligible models
  • active job count
  • jailed flag
  • jailed-until timestamp
  • offense count
  • slash history
  • earnings history
For a model explorer view, show:
  • CodeHTML
  • CodeHTML
  • eligible worker count
  • eligible worker addresses
  • recent job activity from indexed session and job events

Related Guides

Last updated: March 2026
Previous PagePoliciesNext PageWorker API
Worker Explorer - Worker and model | Lightchain AI Documentation | Lightchain AI Documentation