# Work Package Execution Flow in Polkadot JAM

⚠️ This doc is still a WIP - don't take it as 100% correct or final truth. Comments are very welcome. For more details, read the [Graypaper](https://graypaper.com)

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

### **Key Roles:**
1. **End Users / Applications** → Initiate requests that require computation or state updates.
2. **Builders** → Construct Work Packages (WPs) based on external inputs.
3. **Validators** → Perform guaranteeing, auditing, assuring, and authoring roles as part of consensus.
4. **Guarantors (Validators)** → Fetch required data, execute computations, and publish reports to DA.
5. **Auditors (Validators)** → Verify Work Reports before allowing finalization.
6. **Accumulation (State Transition Function - STF)** → On-chain process that applies Work Reports to state.
7. **Finalization (GRANDPA)** → Occurs only after the Auditing is complete.

---

## **📌 Step 1: End User Interaction**
### **How Does the End User Interact with JAM?**
- End users interact with **applications (dApps, external software, or other off-chain systems)** that initiate computation requests.
- The request is translated into a **Work Package (WP)** by a **Builder**.
- The Work Package includes:
- **User Input Data** (payload, extrinsics, etc.)
- **Authorization & Context** (ensuring execution follows JAM’s security rules)
- **Dependencies (Imported Segments)** that link to previous execution results.

### **How Does the User Receive a Response?**
- Users **do not interact with validators directly** but rely on:
✅ **Application Notifications** → dApps or off-chain systems track execution results via APIs.
✅ **Smart Contracts or On-Chain Listeners** → On-chain components track finalized state changes.
✅ **Indexers / Off-Chain Systems** → External systems monitor execution and notify users.

---

## **📌 Step 2: Work Package Creation (Builders)**
### **Who Creates Work Packages?**
- Work Packages (WPs) are created by **Builders**, specialized off-chain entities responsible for structuring execution requests.
- JAM does not define how Builders operate, but they construct WPs according to protocol rules.

### **What Does a Work Package Contain?**
- **Work Items** → Units of computation.
- **Context & Authorization** → Defines execution constraints.
- **Imported Segments (`i`)** → References to prior exported segments.
- **Gas Limits (`g, a`)** → Constraints for execution.
- **Exported Segments (`e`)** → Number of segments produced by execution.

---

## **📌 Step 3: Submission to Guarantors**
### **Who Submits Work Packages?**
- The Builder submits the WP to **Validators**, who act as Guarantors for execution.

### **What Do Guarantors Do at This Stage?**
1. **Fetch Data for Imports (`i`)**
- **Imported segments are not sent by the Builder.** Instead, Guarantors **fetch** them from the availability system using JAMNP-S protocols (CE 137, 139, 140).
- If a segment reference is in `H⊞` (work-package hash), they resolve it to `H` (segment-root).

2. **Validate Authorization & Share WP**
- Guarantors must verify that **the WP is valid** before sharing it with other Guarantors on the same core (CE 134).
- Only after verification and **import retrieval** can the WP move to execution.

---

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

### **What Happens During Execution?**
- Transform **Work Packages**/**Work Items** into **Work Report**/**Work Results**.
- During execution, Guarantors fetch required data on demand ("lazy fetching") as needed.
- Produces:
- **Exported Segments (`e`)** → Outputs that future WPs may use.
- **Data published to DA** → So that Auditors can verify execution correctness.

---

## **📌 Step 5: 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?**
- **Imported Segments + Proofs** → Shows that all required inputs were retrieved.
- **Execution Result** → The output of computation.
- **Segment Root Lookups** → Ensures imported data validity.
- **Paged Proofs** → Justifications for exported segments.
- **Work Reports are distributed to all validators (CE 135).**
- **Validators may request missing Work Reports from other nodes (CE 136).**

---

## **📌 Step 6: Availability Checking**
### **Why Is This Step Important?**
- Before execution, the system verifies that **all necessary data is available**.
- This includes checking **erasure-coded shards** to ensure that missing data can be reconstructed.
- Availability must be confirmed before execution proceeds.

### **Who Performs This Step?**
- Validators collectively assure that **data retrieval is possible**.
- If availability assurance cannot be made, execution is **delayed and eventually rejected**.

---

## **📌 Step 7a: Assurance & Accumulation (State Transition Function - STF)**
### **How Do Assurance & Accumulation Work?**
- **Assurance is an on-chain process** where validators confirm that **Work Reports are available** before they are applied to state.
- After enough assurances are placed, the Work Report is considered **available**.
- **Work Reports may time out**—if they do, another Work Report may replace them before accumulation.
- **Accumulation is the final on-chain step** that applies **fully audited Work Reports** to the blockchain state.
- The **State Transition Function (STF) updates the blockchain state** based on the results of validated Work Reports.
- Ensures that:
✅ **Only correctly executed work is reflected in the blockchain state.**
✅ **Exported segments are stored properly for future work.**
✅ **Dependencies are resolved before execution continues.**

---

## **📌 Step 7b: Auditing by Validators (in parallel with Assurance)**

### **Who Audits Work Reports?**
- **Auditors (Validators)** check Work Reports **before** accumulation.
- **JAM auditing is equivalent to ELVES’ approval phase**.

### **Why Is Auditing Required?**
- Work Reports **cannot be accumulated** unless auditing is complete.
- Auditors verify:
✅ **Segment availability** (erasure-coded shards are retrievable)
✅ **Execution correctness** (Does the report match the DA publication?)
✅ **Imported data integrity**
✅ **Paged segment justifications** for exported data.
✅ **Auditors request audit shards before verifying execution (CE 138).**

### **Auditing Happens in Tranches**
- Validators announce which Work Reports they **intend to audit**.
- **Later tranches audit Work Reports that were not verified earlier**.
- If an auditor fails to submit a judgment, **later tranches step in**.

### **Judgments & Disputes**
- **Every audited Work Report results in a judgment**: valid or invalid.
- **Negative judgments are critical** → they must be **broadcasted immediately**.
- **Positive judgments may be deferred**, unless a negative judgment appears.

---

## **📌 Step 8: Finalization (GRANDPA)**

### **How Does Finalization Work?**
- **Finalization is NOT an execution step.**
- It occurs **after accumulation is complete**.
- Only **fully audited and accumulated Work Reports** can be considered for finalization.
- **Negative judgments may trigger disputes**, delaying finalization.
- This aligns with ELVES & Polkadot’s **Approval Checking** mechanism.

---

# **✅ Key Takeaways (Updated with JAMNP-S Protocols)**
1. **Work Packages are submitted over JAMNP-S (CE 133).**
2. **Guarantors fetch imported segments separately before execution (CE 137, 139, 140).**
3. **Work Packages are shared between Guarantors after validation (CE 134).**
4. **Work Reports are distributed to all validators (CE 135).**
5. **Validators can request missing Work Reports before auditing (CE 136).**
6. **Auditors request audit shards before verifying execution (CE 138).**
7. **Accumulation happens on-chain before finalization.**