Join our community of builders on Discord!

Model Governance

Model governance in Lightchain AI is split across a small set of contracts. This page explains what can be configured, where the source of truth lives, and which changes take effect immediately versus operationally over time.

What Model Governance Covers

At a high level, governance controls:
  • which models exist
  • whether a model is enabled
  • how jobs are priced
  • how fees are split
  • worker stake and slashing parameters
  • dispute and timeout settings
  • infrastructure limits such as blob counts and timeouts
The main contracts involved are:
ContractRole
CodeHTML
Stores model settings and protocol-wide parameters
CodeHTML
Controls worker support and model whitelist state
CodeHTML
Uses those settings during session creation, job escrow, disputes, and payout

Where Model Status Comes From

Model availability is not controlled by one flag alone.

CodeHTML

CodeHTML
manages:
  • model registration
  • model enabled or disabled state
  • base fee
  • per-byte fee
  • max output tokens
Key read functions:
FunctionMeaning
CodeHTML
Whether the model is enabled in config
CodeHTML
Flat fee component
CodeHTML
Variable fee component
CodeHTML
Output token limit metadata
CodeHTML
Final job fee quote

CodeHTML

CodeHTML
manages:
  • model whitelist state for workers
  • which workers support a model
  • which workers are currently eligible for assignment
A worker can only opt into a model when:
  • the model is whitelisted in
    CodeHTML
  • the model is enabled in
    CodeHTML
  • the worker meets the stake and registration requirements

Model Lifecycle

The current model lifecycle in
CodeHTML
is straightforward:
CodeTEXT
The most important governance functions are:
FunctionPurpose
CodeHTML
Creates and enables a new model
CodeHTML
Marks the model disabled
CodeHTML
Re-enables a configured model
CodeHTML
Updates the flat fee
CodeHTML
Updates the per-byte fee
CodeHTML
Updates the model metadata cap
[!TIP] For a complete operational view of a model, track both
CodeHTML
and
CodeHTML
.

Important Enforcement Caveat

Disabling a model in config does not instantly create a hard stop for session creation.
CodeHTML
checks:
  • CodeHTML
It does not directly check:
  • CodeHTML
This means:
  • disabling a model in
    CodeHTML
    does not automatically remove workers already in the eligible set
  • removing whitelist status in
    CodeHTML
    does not automatically purge workers already in that eligible set
  • CodeHTML
    and
    CodeHTML
    can re-add workers to supported models without re-checking whitelist or
    CodeHTML
If governance needs an immediate hard stop for a model, contract-level config changes alone are not enough. The current implementation also requires operational coordination around worker eligibility.

How Fees Are Governed

Job pricing is model-specific:
CodeTEXT
This fee is used by
CodeHTML
to validate escrow. When a job is released, the fee is split into:
CodeTEXT
Fee distribution is controlled through:
FunctionRule
CodeHTML
The total must equal
CodeHTML
Current defaults:
ShareDefault
worker
CodeHTML
bps
protocol
CodeHTML
bps
burn
CodeHTML
bps
[!NOTE]
CodeHTML
is accounting inside
CodeHTML
.
The contract tracks the burn amount, but it does not send ETH to a separate burn address.

Worker And Slashing Parameters

Some protocol-wide parameters live in
CodeHTML
but directly affect worker operations.
ParameterGetterDefaultWhy it matters
Minimum worker stake
CodeHTML
CodeHTML
Required for registration and eligibility
Jail threshold
CodeHTML
CodeHTML
Number of offenses before jailing
Jail cooldown
CodeHTML
CodeHTML
Cooldown before unjailing
Slash rate defaults:
ParameterGetterDefault
Acknowledgement timeout slash
CodeHTML
CodeHTML
Completion timeout slash
CodeHTML
CodeHTML
Dispute slash
CodeHTML
CodeHTML
Slash amounts are based on the global minimum stake, not the worker's current stake:
CodeTEXT

Dispute And Infrastructure Parameters

Dispute-related parameters include:
ParameterGetterDefault
Dispute bond multiplier
CodeHTML
CodeHTML
Dispute window
CodeHTML
CodeHTML
Resolution timeout
CodeHTML
CodeHTML
Sampling rate
CodeHTML
CodeHTML
Similarity threshold
CodeHTML
CodeHTML
Canary similarity threshold
CodeHTML
CodeHTML
Infrastructure-related parameters include:
ParameterGetterDefault
Blob retention period
CodeHTML
CodeHTML
Max blobs per job
CodeHTML
CodeHTML
Session inactivity timeout
CodeHTML
CodeHTML
Max reassignments
CodeHTML
CodeHTML
Ack timeout
CodeHTML
CodeHTML
Completion timeout
CodeHTML
CodeHTML
[!NOTE]
CodeHTML
,
CodeHTML
, and
CodeHTML
are stored on-chain, but current on-chain job logic does not directly enforce them as threshold comparisons.
They are policy inputs for off-chain services.
[!NOTE]
CodeHTML
is currently stored in
CodeHTML
, but it is not enforced by these three contracts.

Defaults And Validation

The current implementation validates several important invariants:
  • model fees must be valid before registration or update
  • fee distribution must sum to
    CodeHTML
  • slash rates cannot exceed the configured slash bound
  • dispute windows and resolution windows must respect configured minimums
  • CodeHTML
    must remain lower than
    CodeHTML
  • core governance addresses such as dispatcher and disputer must be non-zero
These checks help ensure that governance changes do not create impossible or inconsistent runtime behavior.

What To Show In A Governance Dashboard

For model governance, the most useful fields are:
  • model ID
  • enabled flag from
    CodeHTML
  • whitelist flag from
    CodeHTML
  • base fee
  • per-byte rate
  • max output tokens
  • eligible worker count
  • recent governance events
For protocol-wide operations, also show:
  • minimum worker stake
  • fee split
  • slash rates
  • dispute bond and timing windows
  • ack and completion timeouts
  • dispatcher address
  • disputer address

Related Guides

Last updated: March 2026
Previous PageWorker APINext PageBallot