Task Contracts
🚧 This wiki describes DevNet 2.0, soon to be launched. It follows the contracts and
dinclion thedevelopbranch; the currently running DevNet may still use older contracts and commands. Pre-launch discussion: #102.
While tThe Platform Contracts are deployed once for the whole network,. tThe task contracts are deployed per model, by the model owner:. eEvery model trained on DIN gets its own pair of, DINTaskCoordinator and DINTaskAuditor contracts that, which run the federated-learning lifecycle and the reward pool for that model.
Model owner (Ownable)
├── deploys & drives ──► DINTaskCoordinator ◄──── aggregators (register, commit/reveal T1/T2)
│ │ │
│ delegates │ │ slash() aggregators
│ ▼ ▼
└── deploys ───────────► DINTaskAuditor ──slash() auditors──► DinValidatorStake
▲ │
│ └── reward pool (DIN): settled at GI end, claimed by participants
clients (submit local models) · auditors (register, commit/reveal scores)
├── deploys & drives ──► DINTaskCoordinator ◄──── aggregators (register, submit T1/T2)
│ │ │
│ delegates │ │ slash()
│ ▼ ▼
└── deploys ───────────► DINTaskAuditor DinValidatorStake
▲
clients (submit local models) · auditors (register, score)
Before a model can be registered in DinModelRegistry, both contracts must be authorized as slashers on DinValidatorStake — the model owner requests this from the DIN-Representative (off-chain), who executes addSlasherContract via DinCoordinator after verifying the deployment. This guarantees that any model admitted to the network can hold its validators accountable.
Both contracts must be authorized as slashers on DinValidatorStake before the model can be registered in DINModelRegistry, because both carry out slashes:
- the coordinator slashes aggregators;
- the auditor contract slashes auditors.
The model owner requests authorization from the DIN-Representative off-chain. The DIN-Representative checks the deployment and then runs dincli dinrep add-slasher.
The task contracts are plain Ownable contracts. They are not upgradeable: a new version means a new deployment.
DINTaskCoordinator
The central orchestration contract for a model's training. It drives the 23-state Global Iteration (GI) state machine26-state Global Iteration (GI) state machine, coordinates aggregatorsruns two-tier aggregation, and executes slashingslashes aggregators.
Responsibilities:
- Lifecycle management — every phase of a GI is opened and closed explicitly by the model owner; all other participants can only act while their phase is open.
- Aggregator registration — staked validators register as aggregators for the current GI (permissionless while the phase is open, subject to a minimum stake).
- Two-tier aggregation — forms Tier-1 batches (approved local models split into sub-batches, 3 aggregators per batch) and a single Tier-2 batch that combines the T1 results into the new global model. Aggregators submit result CIDs, and the winning CID per batch is decided by majority vote among the batch's aggregators.
-
Slashing — penalizes registered auditors and aggregators that failed to participate or voted against the majority, by calling
slash()onDinValidatorStake. - Holds the genesis model CID (set once before GI 1) and the finalized global model CID of each iteration.
- Lifecycle. The model owner opens and closes every phase of a GI explicitly. Other participants can act only while their phase is open, and only for the current GI.
-
Aggregator registration. Any active validator can register while the window is open, if:
- its stake is at or above the model's stake floor;
- its stake leaves room under the concurrent-registration cap;
- fewer than 300 aggregators have registered this GI.
-
Batch seeds. Batches are shuffled with a seed taken from a future block hash. The seed is anchored when the previous phase closes, and anyone can lock it once that block is mined (
lockAuditSeed,lockAggSeed). -
Two-tier aggregation.
- Tier-1 batches: 3 aggregators each combine a sub-batch of 3 approved local models.
- Tier-2: one batch of the next 3 shuffled aggregators combines the T1 results into the new global model.
- Commit, then reveal. Aggregators first commit a hash bound to their CID, address, GI, tier and batch, then reveal the CID once the owner opens reveals. So no one can copy a peer's result.
- Choosing the winner. The winning CID per batch is the one revealed most often. At least 2 of 3 aggregators must reveal.
-
Aggregator slashing. Every slash below is capped at the validator's slashable stake.
- Missed submission: an aggregator who doesn't reveal for its batch, including one who committed and never revealed, gets a partial slash (30% of the minimum stake; S2, which escalates under S5).
- Losing CID: an aggregator who revealed a CID other than the winner gets a full minimum-stake slash.
- Aggregation disputes (S4). Within a window after a batch is finalized, any active validator can post a bond and dispute the result. The owner adjudicates. A recomputation that confirms the dispute slashes the original aggregators.
- It holds the genesis model CID (set once before GI 1) and each GI's finalized global model CID.
DINTaskAuditor
The evaluation, quality-control and quality-controlreward contract —: the gatekeeper deciding which client contributions make it intoreach the global model, and who gets paid.
Responsibilities:
- Auditor registration — staked validators register as auditors for the current GI.
- Local Model Submission (LMS) — clients submit the IPFS CID of their locally trained model (one submission per client per GI, capped at 10,000 per GI).
- Audit batch formation — submitted models are assigned to batches of auditors (3 auditors × 3 models per batch by default), with a per-batch test dataset CID supplied by the model owner.
- Scoring & eligibility — each assigned auditor evaluates the models in its batch against the test data and records a score (0–100) plus an eligibility vote.
- Finalization — once quorum is reached, a model's final average score is computed; it is approved for aggregation only if the eligibility majority passed it and its average score meets the pass threshold (default 50). Scoring parameters (auditors per batch, quorums, pass score) are tunable per round.
-
Auditor registration. Active validators register for the current GI, under the same stake floor, concurrency and 300-per-GI caps as aggregators.
-
Local Model Submission (LMS). Clients submit the IPFS CID of their locally trained model. Each client gets one submission per GI, and a GI takes at most 10,000.
-
Audit batches. Submitted models are shuffled, from the locked audit seed, into batches of 3 auditors × 3 models.
-
Encrypted test data. For each batch, the owner publishes:
- an AES-GCM-encrypted test-dataset CID;
- a key for each auditor, encrypted to that auditor's registered X25519 key;
- a commitment to the dataset's content.
Only the batch's auditors can read the test data.
-
Scoring: commit, then reveal. Each auditor evaluates every model in its batch, then commits a hash of its score (0–100) and eligibility vote. The hash is bound to the auditor's address and the slot. The auditor reveals once the owner opens reveals.
-
Finalization. A model is approved for aggregation when at least 2 auditors vote it eligible and its median score is at or above the GI's pass score. The model owner sets the pass score when starting each GI.
-
Auditor slashing.
- Missed vote: an auditor who doesn't reveal a vote, including one who committed and never revealed, gets a partial slash (30% of the minimum stake; S1, which escalates under S5).
- Score deviation: scoring far from the median (S3) is a full slash. It ships disabled (shadow mode).
-
Test-data disputes. An auditor of a batch can dispute its test data by posting a 100 DIN bond, as long as the GI's rewards haven't been settled yet. The owner must answer within the window (7,200 blocks, about one day) by revealing the dataset key.
- The key matches: the bond is forfeited.
- The key doesn't match, or the owner stays silent: the dispute is upheld. The bond is returned, 25% of the GI reward pool is forfeited (no penalty if the GI settled while the dispute was open), and the batch must be reassigned.
Rewards
Each GI has a reward pool in DIN, held by DINTaskAuditor.
-
Funding. The pool must be funded before the GI can start, with
depositRewards(gi, amount). Anyone can fund it, andDinEmissioncan subsidise it. - Settlement. When the owner ends the GI, the pool is split:
| Share | Default | Distributed by |
|---|---|---|
| Clients | 60% | median score of each approved local model |
| Auditors | 20% | number of revealed votes |
| Aggregators | 15% | one unit per assigned aggregator of each finalized batch |
| Treasury | 5% | sent to the protocol treasury |
Rewards are pulled: each participant calls claimReward(gi), then claimRewards() to withdraw. dincli has no commands yet for depositing or claiming rewards; these are direct contract calls for now.
The Global Iteration lifecycle
A GI is one full training round. The coordinator's state machine enforces the order — each transition is an explicit dincli model-owner ... command:order. Owner steps are dincli model-owner … commands; the others belong to the role shown.
Setup (once): set auditor contract → confirm both slashers → submit genesis model
Setup (once): set auditor contract → confirm slasher auth → submit genesis model
│
┌────────────────────────────────────────────────────────────────┘
▼
0. Fund the GI reward pool (depositRewards — required before start)
1. GI started (sets the pass score)
2. Aggregator registration (open → aggregators register → close)
3. Auditor registration (open → auditors register → close)
4. Local Model Submission (open → clients train locally & submit CIDs → close; anchors audit seed)
5. Audit batches (lock audit seed → create batches → assign encrypted test data)
6. Score commit → reveal (auditors commit → owner opens reveal → auditors reveal → close; anchors agg seed)
7. T1/T2 batches (lock aggregation seed → create batches)
8. T1 commit → reveal (aggregators commit → owner opens reveal → aggregators reveal → finalize)
9. T2 commit → reveal (same, producing the new global model)
10. Slashing (slash auditors → slash aggregators)
11. GI ended (reward pool settled; next GI starts from the new global model)
1. GI started
2. Aggregator registration (open → aggregators stake & register → close)
3. Auditor registration (open → auditors stake & register → close)
4. Local Model Submission (LMS) (open → clients train locally & submit CIDs → close)
5. Auditor evaluation (batches created → auditors score & vote → close)
6. T1 aggregation (batches created → aggregators combine sub-batches → finalize)
7. T2 aggregation (T1 winners combined into new global model → finalize)
8. Slashing (non-performing / minority-voting auditors & aggregators)
9. GI ended → next GI starts from the new global model
Only model artifacts move between participants —. rRaw training data never leaves a client's device. All artifacts (the genesis model, local models, aggregated models, and encrypted test datasets) live on IPFS;, and the contracts store and vote on their CIDs.
Deploying a model's task contracts
The model owner deploys and wires upconnects both contracts through dincli:
dincli model-owner deploy task-coordinator --artifact <DINTaskCoordinator.json> dincli model-owner deploy task-auditor --artifact <DINTaskAuditor.json> # also links it to the coordinatordincli model-owner deploy task-auditor --artifact <DINTaskAuditor.json># then: request slasher authorization from the DIN-Representative, # confirm it, submit the genesis model, and register the model
⚠️ Known gap: the DevNet 2.0 task contracts take the model'smodelIdas a constructor argument, butdincli model-owner deploystill passes the older argument list. It has to be updated before model owners can deploy throughdincli(see DINTaskCoordinator.md §10).
The full step-by-step —guide, including the slasher authorization request channels and the manifest/ and services setup —, is in the Model Workflow guide.
Further reading
- Model Workflow — complete per-model walkthrough with all commands
- Model Workflow: the complete per-model walkthrough
- Technical references: DINTaskCoordinator · DINTaskAuditor · DINShared (the GI state enum and shared interfaces)
- DevNet 2.0 mechanism design: the slashing conditions (S1–S6), rewards and scoring
- Platform Contracts: the network-wide layer that authorizes these contracts