Skip to content

Task Contracts

Jump to bottom
umermjd11 edited this page Oct 5, 2026 · 4 revisions

Task Contracts

🚧 This wiki describes DevNet 2.0, soon to be launched. It follows the contracts and dincli on the develop branch; the currently running DevNet may still use older contracts and commands. Pre-launch discussion: #102.

The Platform Contracts are deployed once for the whole network. The task contracts are deployed per model, by the model owner. Every model trained on DIN gets its own pair, DINTaskCoordinator and DINTaskAuditor, 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)

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 26-state Global Iteration (GI) state machine, runs two-tier aggregation, and slashes aggregators.

  • 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 reward contract: the gatekeeper deciding which client contributions reach the global model, and who gets paid.

  • 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, and DinEmission can 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. 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
                                                                    │
   ┌────────────────────────────────────────────────────────────────┘
   ▼
 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)

Only model artifacts move between participants. Raw 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 connects 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 coordinator
# 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's modelId as a constructor argument, but dincli model-owner deploy still passes the older argument list. It has to be updated before model owners can deploy through dincli (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.

Further reading

Introduction

DIN Components

Network Roles

Clone this wiki locally