# IMPORTANT

**This doc is being reviewed and should not be considered as a source of truth**

# Work Package Execution Flow in Polkadot JAM

## **Flow of Work Packages: End User → Blockchain State**

### **Key Roles:**
1. **End Users / Services** → Request computations or state updates.
2. **Work Package Creators (Services or Protocols)** → Generate Work Packages based on user inputs.
3. **Guarantors** → Fetch required data, execute computations, and produce justifications.
4. **Validators** → Verify Work Reports and update the blockchain state.
5. **Auditors** → Verify the correctness of past executions.

---

## **📌 Step 1: Work Package Creation**
### **Who Creates Work Packages?**
- Work Packages (WPs) are typically created by **services or protocols**, not end users directly.
- End users interact with **services** (e.g., smart contracts, off-chain apps), which then **build** Work Packages.

### **What Does a Work Package Contain?**
- **Code Hash (`c`)** → Specifies the logic that will be executed.
- **Payload (`y`)** → User-provided data or transaction details.
- **Imported Segments (`i`)** → References to previously exported segments needed for execution.
- **Gas Limits (`g, a`)** → Constraints for execution.
- **Exported Segments (`e`)** → Number of data segments the execution will produce.

---

## **📌 Step 2: Work Package Submission to Guarantors**
### **Who Submits Work Packages?**
- The service or protocol submits the Work Package to **Guarantors**.
- Guarantors are responsible for executing and verifying the WP, transforming them into Work Reports.

### **What Do Guarantors Do at This Stage?**
1. **Fetch Data for Imports (`i`)**
- Retrieve **imported segments** by fetching **erasure-coded chunks** from multiple validators.
- If the segment reference is stored in `H⊞` (work-package hash), they resolve it to `H` (segment-root).

2. **Ensure Data Availability**
- The Guarantor ensures that all **imported segments** are correctly reconstructed and available.

---

## **📌 Step 3: Off-Chain Execution by Guarantors**
### **Who Executes the Work Package?**
- Guarantors execute the Work Package **off-chain**.

### **What Happens During Execution?**
- The Work Package transforms **input data** into a **Work Report**.
- Produces:
- **Exported Segments (`e`)** → Output data that future Work Packages might need.
- **Justifications** → Proofs that the execution was correct.

---

## **📌 Step 4: Work Report Submission to Validators**
### **Who Submits the Work Report?**
- The Guarantor submits a **Work Report** to the **validators**.

### **What Does the Work Report Contain?**
- **Execution Result** → The output of the computation.
- **Justifications** → Proof that execution was performed correctly.

---

## **📌 Step 5: On-Chain Validation by Validators**
### **Who Verifies the Work Report?**
- **Validators** check the submitted Work Report.
- If it is valid, they finalize the state update on-chain.

### **What Do Validators Check?**
1. **Segment Justifications**
- Ensure **H⊞ → H conversions** were correctly reported.

2. **Execution Justifications**
- Confirm that execution followed the **code hash (`c`)** deterministically.

3. **State Update**
- Once verified, the **exported segments (`e`)** are made **available** for future Work Packages.
- The blockchain state is **updated** based on the execution result.

---

## **📌 Step 6: Auditing**
### **Who Audits Work Reports?**
- **Auditors** (independent nodes) check past Work Reports for correctness.

### **Why Are Auditors Needed?**
- Since Work Packages are checked by **only a few validators**, auditing ensures:
- No **collusion** or **fraud** occurred.
- The **execution history is sound**.

### **How Do Auditors Work?**
- Auditors fetch the **Auditable Work Package**, which includes:
- The **original Work Package**.
- The **imported data**.
- A **proof of correctness**.
- Verify Merkle proofs for **imported segments**.

🔹 **Efficiency Note**:
- Auditors check Work Packages **30× more often** than Guarantors process them.
- To save bandwidth, some **data duplication** is allowed between Imports DA and Audits DA.

---

# **🚀 Final Summary: The Full Flow**
| **Step** | **Responsible Party** | **Action** |
|---------|-----------------|------------|
| **1. Work Package Creation** | **Service or protocol** | Forms a WP based on user input. |
| **2. Submission to Guarantors** | **Service → Guarantors** | WP is handed off for processing. |
| **3. Data Fetching** | **Guarantors** | Retrieve imported segments & ensure availability. |
| **4. Off-Chain Execution** | **Guarantors** | Compute outputs, generate justifications. |
| **5. Work Report Submission** | **Guarantors → Validators** | Submit execution result & proof. |
| **6. On-Chain Validation** | **Validators** | Verify proofs, update blockchain state. |
| **7. Auditing (Optional)** | **Auditors** | Verify correctness of Work Reports. |

---

# **✅ Key Takeaways**
1. **End users don’t submit Work Packages directly** → Services handle this.
2. **Guarantors execute Work Packages off-chain** and submit a **Work Report**.
3. **Validators do not re-execute Work Packages** → They verify justifications.
4. **On-chain state updates happen only after validator approval**.
5. **Auditors provide post-execution verification** to prevent fraud.