Introduction
This document provides a detailed walkthrough of an off-chain task’s complete lifecycle, from initial submission by an actor through execution by runners and payment to the actor’s callback.Note: Descriptions are principle-level (non‑normative). Final interfaces and usage should follow the SDK and Developer Guide; normative behavior follows the Off‑chain architecture and related CIPs (primarily CIP‑2, with deferred execution per CIP‑1).
Complete Lifecycle (Conceptual)
- Task Submission (Block N): Actor submits a task with mandatory
result_schema, payment is locked, and snapshots of VRF seed and active runner list are recorded; an event is emitted for runner detection. - Runner Detection (Block N): Runners independently determine selection using the VRF snapshot and active list at submission.
- Off-Chain Execution (Blocks N+Δ): Selected runners execute off-chain, optionally producing proofs/attestations.
- Result Submission (Blocks N+Δ): Selected runners submit results on-chain; submissions are validated (selection, size/format per
result_schema, proof/attestation if requested) and stored. - Payment Distribution (Same block): Upon collecting N valid results, the chain verifies them, pays the runners whose results it accepted from the job’s escrow, returns any unused escrow, and finalizes the task.
- Deferred Callback Trigger (Same block): A deferred transaction is created and scheduled via the scheduler (CIP‑1) to invoke the actor’s callback with the verified result.
- Callback Execution (Blocks N+Δ): The actor’s callback receives the verified result. It has nothing to settle.
Phase-by-Phase Breakdown
Phase 1: Task Submission
Actor responsibilities (conceptual):- Define task and mandatory
result_schema(size/format bounds) - Specify callback handler,
num_runners,timeout_blocks, andproof_type_requested - Persist task ID for tracking in application state
- Lock funds and snapshot VRF seed and active runner list
- Persist task record with submission/timeout blocks
- Emit submission event for runner detection
Phase 2: Runner Detection & Selection
Runners (conceptual):- Monitor submission events; compute selection from VRF seed snapshot and the active list at submission time (CIP‑2)
- If selected and willing, execute; otherwise promptly call
skip_taskto advance selection
Phase 3: Off-Chain Execution
Execution (conceptual):- Prepare inputs → run computation → (optional) produce proof/attestation → submit result
- Track execution metrics locally for runner‑side pricing/acceptance heuristics (off‑chain concern)
Phase 4: Result Submission
Submission checks (conceptual):- Verify runner selection and prevent duplicates
- Validate result payload against
result_schema(size/format) - Verify requested proof/attestation
- Store result and update task state; when N results collected, schedule deferred callback
Phase 5: Payment Distribution
The chain (conceptual):- Verify the results under the job’s verification mode
- Pay the runners whose results it accepted from the job’s escrow, and return any unused escrow
- Mark the task as finalized, so a result can’t be paid twice
Phase 6: Deferred Callback Trigger
Deferred callback (conceptual):- Construct a deferred transaction targeting the actor’s callback handler and schedule it under scheduler budget (CIP‑1)
- Non‑blocking: Result submission isn’t stalled by callback execution
- Separate metering: Callback is metered independently
- Predictable scheduling: Executed under a fixed per‑block scheduler budget
- Deterministic inclusion: Scheduler handles inclusion based on its rules
Phase 7: Callback Execution
Actor callback responsibilities (conceptual):- Receive the verified result
- Apply it according to application logic
- Success/failure of the callback is recorded; application state is updated accordingly
Alternative Paths
Timeout
- If N results are not collected by
timeout_blocks, the task is finalized as timed out (CIP‑2) - Late submissions are invalid; the actor/application may resubmit or adjust parameters for a new task
Runner Skip
- If a selected runner cannot or will not execute, it SHOULD call
skip_task(task_id)to advance selection to the next runner per deterministic order
Monitoring & Events (Conceptual)
Actors and observers can track task progress via:- Task fields: status (e.g., PENDING, COMPLETED, FINALIZED, TIMEOUT), submission/timeout blocks, selected/submitted/skipped runners, number of results submitted vs. requested
- Events: TaskSubmitted, ResultSubmitted, CallbackScheduled, CallbackExecuted/Failed, TaskFinalized
Best Practices (Principle‑Level)
- Set
timeout_blocksappropriate to expected off‑chain duration and verification mode - Choose
num_runnersandproof_type_requestedto balance reliability, cost, and security - Validate result structures against
result_schemastrictly; ignore outliers for quorum modes - Encourage runners to
skip_taskquickly when they cannot execute to reduce overall latency
Next Steps
Off-Chain Overview
High-level introduction to off-chain compute
Callback & Timeout
Handling edge cases and failures
CIP-2 Specification
Complete formal specification
Developer Examples
Real-world integration examples