@wowok/skills 1.1.12 → 1.2.1

package/examples/MyShop/MyShop.md

@@ -4,6 +4,15 @@ A complete e-commerce example demonstrating how to build an online store using W
 
 ---
 
+## ⚠️ Running Principle
+
+> **Run the example in full every time (repeatable).** This example uses `replaceExistName: true` on all object creations — each run generates new objects with new addresses. If you skip build steps, operations may silently act on orphaned objects from previous runs, producing incorrect results. Old objects' configurations do not reflect the current document version.
+
+- **Execution order**: Part 1 (Merchant Setup, Steps 1–7) → Part 2 (Customer Flow, Steps 1–9). Run all build steps in sequence before testing any customer flow. Do not skip steps — each depends on objects created by prior steps.
+- **Prerequisites**: `myshop_merchant` with sufficient WOW for gas and order operations. All on-chain operations require `env.confirmed: true`.
+
+---
+
 ## Core Requirements & Features
 
 | Requirement | Description | Implementation |
@@ -109,8 +118,10 @@ Before starting, ensure you have:
 ```json
 {
   "transfer": {
-    "name_or_address": "myshop_merchant",
-    "amount": 1000000000
+    "name_or_address_to": "myshop_merchant",
+    "amount": 1000000000,
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -137,18 +148,21 @@ First, create a Permission object to manage access control for your store operat
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
 
 ---
 
-### Step 2: Create Machine (Order Workflow)
+### Step 2: Create Machine with Workflow Nodes
+
+Create a Machine to define the order processing workflow. This includes nodes for order confirmation, shipping, delivery, and completion. The Machine must be created with all nodes and published in a single operation — the protocol requires at least one node when publishing a Machine.
 
-Create a Machine to define the order processing workflow. This includes nodes for order confirmation, shipping, delivery, and completion.
+> **Reference**: The complete node configuration is available in [`myshop_machine_nodes.json`](./myshop_machine_nodes.json). The JSON below mirrors that file's content wrapped in an on-chain operation.
 
-**Prompt**: Create a Machine named "myshop_machine_v2" with permission "myshop_permission_v2" for the toy store workflow.
+**Prompt**: Create a Machine named "myshop_machine_v2" with permission "myshop_permission_v2", including all workflow nodes (Order Confirmation, Shipping, In Transit, Completed, Cancelled), and publish it immediately.
 
 ```json
 {
@@ -159,15 +173,115 @@ Create a Machine to define the order processing workflow. This includes nodes fo
       "permission": "myshop_permission_v2",
       "replaceExistName": true
     },
-    "description": "Order processing workflow for MyShop toy store"
+    "description": "Order processing workflow for MyShop toy store",
+    "node": {
+      "op": "add",
+      "nodes": [
+        {
+          "name": "Cancelled",
+          "pairs": [
+            {
+              "prev_node": "",
+              "threshold": 0,
+              "forwards": [
+                {
+                  "name": "Cancel Order",
+                  "weight": 1,
+                  "namedOperator": ""
+                }
+              ]
+            },
+            {
+              "prev_node": "Order Confirmation",
+              "threshold": 1,
+              "forwards": [
+                {
+                  "name": "Cancel Order",
+                  "weight": 1,
+                  "namedOperator": ""
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "Completed",
+          "pairs": [
+            {
+              "prev_node": "In Transit",
+              "threshold": 1,
+              "forwards": [
+                {
+                  "name": "Complete Order",
+                  "weight": 1,
+                  "namedOperator": ""
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "In Transit",
+          "pairs": [
+            {
+              "prev_node": "Shipping",
+              "threshold": 1,
+              "forwards": [
+                {
+                  "name": "Confirm Delivery",
+                  "weight": 1,
+                  "permissionIndex": 1002
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "Order Confirmation",
+          "pairs": [
+            {
+              "prev_node": "",
+              "threshold": 0,
+              "forwards": [
+                {
+                  "name": "Confirm Order",
+                  "weight": 1,
+                  "permissionIndex": 1000
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "Shipping",
+          "pairs": [
+            {
+              "prev_node": "Order Confirmation",
+              "threshold": 1,
+              "forwards": [
+                {
+                  "name": "Ship Goods",
+                  "weight": 1,
+                  "permissionIndex": 1001
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    "publish": true
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
 
+> **Note**: The Machine must be created with nodes and published in a single operation. Creating an empty Machine and then adding nodes/publishing separately will be rejected by the protocol's constraint checker. The "Cancelled" node has two pairs: one with `prev_node: ""` (cancel from initial state) and one with `prev_node: "Order Confirmation"` (cancel after order confirmation).
+
 ---
 
 ### Step 3: Machine Workflow Design
@@ -279,152 +393,11 @@ Before adding nodes, let's understand the order processing workflow:
 
 ---
 
-### Step 4: Add Workflow Nodes
-
-Add the workflow nodes to the Machine for order processing. The initial pair (prev_node: "") defines transitions from the empty starting state.
-
-**Prompt**: Add workflow nodes to "myshop_machine_v2" including Order Confirmation, Shipping, In Transit, Completed, and Cancelled nodes.
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "myshop_machine_v2",
-    "node": {
-      "op": "add",
-      "nodes": [
-        {
-          "name": "Order Confirmation",
-          "pairs": [
-            {
-              "prev_node": "",
-              "threshold": 0,
-              "forwards": [
-                {
-                  "name": "Confirm Order",
-                  "permissionIndex": 1000,
-                  "weight": 1
-                }
-              ]
-            },
-            {
-              "prev_node": "Order Confirmation",
-              "threshold": 1,
-              "forwards": [
-                {
-                  "name": "Ship Goods",
-                  "permissionIndex": 1001,
-                  "weight": 1
-                }
-              ]
-            }
-          ]
-        },
-        {
-          "name": "Shipping",
-          "pairs": [
-            {
-              "prev_node": "Order Confirmation",
-              "threshold": 1,
-              "forwards": [
-                {
-                  "name": "Ship Goods",
-                  "permissionIndex": 1001,
-                  "weight": 1
-                }
-              ]
-            }
-          ]
-        },
-        {
-          "name": "In Transit",
-          "pairs": [
-            {
-              "prev_node": "Shipping",
-              "threshold": 1,
-              "forwards": [
-                {
-                  "name": "Confirm Delivery",
-                  "permissionIndex": 1002,
-                  "weight": 1
-                }
-              ]
-            }
-          ]
-        },
-        {
-          "name": "Completed",
-          "pairs": [
-            {
-              "prev_node": "In Transit",
-              "threshold": 1,
-              "forwards": [
-                {
-                  "name": "Complete Order",
-                  "namedOperator": "",
-                  "weight": 1
-                }
-              ]
-            }
-          ]
-        },
-        {
-          "name": "Cancelled",
-          "pairs": [
-            {
-              "prev_node": "Order Confirmation",
-              "threshold": 0,
-              "forwards": [
-                {
-                  "name": "Cancel Order",
-                  "namedOperator": "",
-                  "weight": 1
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    }
-  },
-  "env": {
-    "account": "myshop_merchant",
-    "network": "mainnet"
-  }
-}
-```
-
-> **Note**: The "Cancel Order" forward is defined on the "Cancelled" node with `prev_node: "Order Confirmation"`. This means cancellation can only happen AFTER the merchant confirms the order (transitions from "Order Confirmation" to "Cancelled"). The "Cancelled" node is a terminal state with no further forwards.
-
----
-
-### Step 5: Publish the Machine
-
-Publish the Machine to make it available for creating orders.
-
-**Prompt**: Publish the Machine "myshop_machine_v2" to enable order creation.
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "myshop_machine_v2",
-    "publish": true
-  },
-  "env": {
-    "account": "myshop_merchant",
-    "network": "mainnet"
-  }
-}
-```
-
----
-
-### Step 6: Create Contact Object for Customer Service
+### Step 4: Create Contact Object for Customer Service
 
 Create a Contact object to enable encrypted communication between customers and the store for after-sales support.
 
-#### 6.1 Enable Merchant Messenger
+#### 4.1 Enable Merchant Messenger
 
 **Prompt**: Enable messenger for the merchant account.
 
@@ -437,7 +410,7 @@ Create a Contact object to enable encrypted communication between customers and
 }
 ```
 
-#### 6.2 Create After-Sales Contact Object
+#### 4.2 Create After-Sales Contact Object
 
 **Prompt**: Create a Contact object named "myshop_aftersales_contact_v2" with permission "myshop_permission_v2" for after-sales support.
 
@@ -463,7 +436,8 @@ Create a Contact object to enable encrypted communication between customers and
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -472,13 +446,13 @@ Create a Contact object to enable encrypted communication between customers and
 
 ---
 
-### Step 7: Create Guards for Fund Allocation
+### Step 5: Create Guards for Fund Allocation
 
 Before creating the Service, create Guards that validate fund allocation conditions. These Guards ensure funds are only released when specific conditions are met.
 
-#### 7.1 Create Withdraw Guard (Merchant Withdrawal)
+#### 5.1 Create Withdraw Guard (Merchant Withdrawal)
 
-Create a Guard that validates the order's Progress has reached the "Completed" node. This Guard uses `convert_witness: 100` (TypeOrderProgress) to query the Order's associated Progress object.
+Create a Guard that validates the order's Progress has reached the "Completed" node. This Guard uses `convert_witness: "OrderProgress"` (TypeOrderProgress) to query the Order's associated Progress object.
 
 **Prompt**: Create a Guard named "myshop_withdraw_guard_v2" that verifies the order is completed before allowing merchant withdrawal.
 
@@ -488,62 +462,118 @@ Create a Guard that validates the order's Progress has reached the "Completed" n
   "data": {
     "namedNew": {
       "name": "myshop_withdraw_guard_v2",
-      "tags": ["order", "completed", "withdraw"],
+      "tags": ["order", "completed", "withdraw", "signer-bound"],
       "onChain": false,
       "replaceExistName": true
     },
-    "description": "Verify order progress is at Completed node for merchant withdrawal",
+    "description": "Verify order progress is at Completed node for merchant withdrawal. RISK ELIMINATION: Three-fold verification - (1) order at Completed node, (2) signer is myshop_merchant (prevents fund theft), (3) order belongs to myshop_service_v2 (prevents cross-service theft).",
     "table": [
       {
         "identifier": 0,
         "b_submission": true,
         "value_type": "Address",
-        "name": "order_address"
+        "object_type": "Order",
+        "name": "order_address (Order object submitted at runtime)"
       },
       {
         "identifier": 1,
         "b_submission": false,
         "value_type": "String",
         "value": "Completed",
-        "name": "completed_node"
+        "name": "Expected Completed node name (case-sensitive)"
+      },
+      {
+        "identifier": 2,
+        "b_submission": false,
+        "value_type": "Address",
+        "value": "myshop_merchant",
+        "name": "Authorized merchant address (prevents fund theft by unauthorized callers)"
+      },
+      {
+        "identifier": 3,
+        "b_submission": false,
+        "value_type": "Address",
+        "value": "myshop_service_v2",
+        "name": "Expected service address (prevents cross-service fund theft)"
       }
     ],
     "root": {
-      "type": "logic_equal",
+      "type": "logic_and",
       "nodes": [
         {
-          "type": "query",
-          "query": 1253,
-          "object": {
-            "identifier": 0,
-            "convert_witness": 100
-          },
-          "parameters": []
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": "progress.current",
+              "object": {
+                "identifier": 0,
+                "convert_witness": "OrderProgress"
+              },
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 1
+            }
+          ]
         },
         {
-          "type": "identifier",
-          "identifier": 1
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "context",
+              "context": "Signer"
+            },
+            {
+              "type": "identifier",
+              "identifier": 2
+            }
+          ]
+        },
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": "order.service",
+              "object": {
+                "identifier": 0
+              },
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 3
+            }
+          ]
         }
       ]
     }
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
 
-**Guard Explanation:**
-- **Table Item 0**: Order address (submitted when activating allocation)
+**Guard Explanation (Three-fold Verification):**
+- **Table Item 0**: Order address (submitted at runtime, typed as Order object)
 - **Table Item 1**: Constant string "Completed" (the target node name)
-- **convert_witness: 100**: TypeOrderProgress - converts Order to its associated Progress
-- **Query "progress.current"**: Returns the current node name of the Progress
-- **logic_equal**: Verifies current node equals "Completed"
-
-> **Note**: The Guard `root` field directly specifies the GuardNode (e.g., `type: "logic_equal"`), not wrapped in a `type: "node"` object.
+- **Table Item 2**: Constant address `myshop_merchant` (authorized merchant)
+- **Table Item 3**: Constant address `myshop_service_v2` (this service's on-chain address)
+- **Condition 1 — Order Completed**: `logic_equal[query("progress.current", witness="OrderProgress"), identifier[1]]` — queries the submitted Order's Progress (via witness "OrderProgress") and verifies the current node is "Completed"
+- **Condition 2 — Signer is Merchant**: `logic_equal[context(Signer), identifier[2]]` — verifies the transaction caller is `myshop_merchant`, **preventing fund theft by unauthorized callers** (R-C3-01/R-C3-06)
+- **Condition 3 — Service Ownership**: `logic_equal[query("order.service"), identifier[3]]` — queries the submitted Order's `service` field and verifies it equals `myshop_service_v2`, **preventing cross-service theft** where someone submits another service's Completed order (R-C3-05)
+- **root**: `logic_and` of all three conditions — all must pass for allocation to proceed
+
+> **Risk Elimination (R-C3-06)**: The allocator uses `"who": {"Signer": "signer"}` (funds go to the caller). This is safe ONLY because Condition 2 binds the Signer to `myshop_merchant`. Without this binding, anyone could submit any Completed order and steal 100% of funds. The three-fold verification ensures only the authorized merchant can trigger withdrawal.
+>
+> **Note**: The Guard `root` field directly specifies the GuardNode (e.g., `type: "logic_and"`), not wrapped in a `type: "node"` object.
 
-#### 7.2 Create Refund Guard (Customer Refund)
+#### 5.2 Create Refund Guard (Customer Refund)
 
 Create a Guard for customer refunds when order is cancelled.
 
@@ -555,61 +585,122 @@ Create a Guard for customer refunds when order is cancelled.
   "data": {
     "namedNew": {
       "name": "myshop_refund_guard_v2",
-      "tags": ["order", "cancelled", "refund"],
+      "tags": ["order", "cancelled", "refund", "signer-bound"],
       "onChain": false,
       "replaceExistName": true
     },
-    "description": "Verify order progress is at Cancelled node for customer refund",
+    "description": "Verify order progress is at Cancelled node for customer refund. RISK ELIMINATION: Three-fold verification - (1) order at Cancelled node, (2) signer is order.owner (dynamic query, prevents fund theft - only order owner can trigger their own refund), (3) order belongs to myshop_service_v2 (prevents cross-service theft).",
     "table": [
       {
         "identifier": 0,
         "b_submission": true,
         "value_type": "Address",
-        "name": "order_address"
+        "object_type": "Order",
+        "name": "order_address (Order object submitted at runtime)"
       },
       {
         "identifier": 1,
         "b_submission": false,
         "value_type": "String",
         "value": "Cancelled",
-        "name": "cancelled_node"
+        "name": "Expected Cancelled node name (case-sensitive)"
+      },
+      {
+        "identifier": 2,
+        "b_submission": false,
+        "value_type": "Address",
+        "value": "myshop_service_v2",
+        "name": "Expected service address (prevents cross-service fund theft)"
       }
     ],
     "root": {
-      "type": "logic_equal",
+      "type": "logic_and",
       "nodes": [
         {
-          "type": "query",
-          "query": 1253,
-          "object": {
-            "identifier": 0,
-            "convert_witness": 100
-          },
-          "parameters": []
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": "progress.current",
+              "object": {
+                "identifier": 0,
+                "convert_witness": "OrderProgress"
+              },
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 1
+            }
+          ]
         },
         {
-          "type": "identifier",
-          "identifier": 1
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "context",
+              "context": "Signer"
+            },
+            {
+              "type": "query",
+              "query": "order.owner",
+              "object": {
+                "identifier": 0
+              },
+              "parameters": []
+            }
+          ]
+        },
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": "order.service",
+              "object": {
+                "identifier": 0
+              },
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 2
+            }
+          ]
         }
       ]
     }
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
 
+**Guard Explanation (Three-fold Verification):**
+- **Table Item 0**: Order address (submitted at runtime, typed as Order object)
+- **Table Item 1**: Constant string "Cancelled" (the target node name)
+- **Table Item 2**: Constant address `myshop_service_v2` (this service's on-chain address)
+- **Condition 1 — Order Cancelled**: `logic_equal[query("progress.current", witness="OrderProgress"), identifier[1]]` — queries the submitted Order's Progress (via witness "OrderProgress") and verifies the current node is "Cancelled"
+- **Condition 2 — Signer is Order Owner**: `logic_equal[context(Signer), query("order.owner")]` — verifies the transaction caller is the Order's owner (dynamic query, not a fixed address), **preventing fund theft by unauthorized callers** (R-C3-01/R-C3-06). Only the customer who placed the order can trigger their own refund.
+- **Condition 3 — Service Ownership**: `logic_equal[query("order.service"), identifier[2]]` — queries the submitted Order's `service` field and verifies it equals `myshop_service_v2`, **preventing cross-service theft** (R-C3-05)
+- **root**: `logic_and` of all three conditions — all must pass for refund allocation to proceed
+
+> **Risk Elimination (R-C3-06)**: Unlike the withdraw Guard (which binds Signer to a fixed merchant address), the refund Guard binds Signer to `order.owner` via a **dynamic query** (query 1562). This is because refunds flow to the customer, and each order has a different customer. Only the order's rightful owner can trigger the refund — an attacker cannot submit another customer's Cancelled order.
+>
+> **Refund Recipient Design**: The allocator uses `"who": {"GuardIdentifier": 0}` (funds go to the Order object's address, not the caller's wallet). This creates an escrow pattern: the refund is held at the Order object's address, and the customer subsequently claims it via a separate withdraw operation. This ensures traceability and audit trail.
+
 ---
 
-### Step 8: Create Service (Store)
+### Step 6: Create Service (Store)
 
 Create the Service object that represents your online store with products. This step binds all previously created components together.
 
 > **Important**: For Service creation, provide a complete configuration including machine, order_allocators with Guards, and products. The Service will be created and published in a single transaction.
 
-#### 8.1 Understanding Order Allocators
+#### 6.1 Understanding Order Allocators
 
 The `order_allocators` configuration defines how order payments are distributed:
 
@@ -621,13 +712,19 @@ The `order_allocators` configuration defines how order payments are distributed:
 | **Threshold** | Minimum amount to trigger allocation |
 
 **Recipient Types:**
-- `{ "Signer": "signer" }` - Transaction sender (merchant)
-- `{ "Entity": { "name_or_address": "..." } }` - Specific address or account name
-- `{ "GuardIdentifier": 0 }` - Address from Guard table
+- `{ "Signer": "signer" }` - Transaction sender (caller). **⚠️ R-C3-06 Risk**: If the Guard does NOT bind the Signer to an authorized address, anyone who passes the Guard can steal 100% of funds. Safe ONLY when the Guard includes a `logic_equal[context(Signer), <authorized_address>]` check.
+- `{ "Entity": { "name_or_address": "..." } }` - Specific address or account name (safest — funds go to a fixed address regardless of caller)
+- `{ "GuardIdentifier": 0 }` - Address from Guard table (e.g., the submitted Order object's address)
+
+> **R-C3-06 Risk Elimination — Guard + Sharing Coupling**: The `order_allocators` scene couples Guard verification (WHO can trigger) with sharing recipient (WHERE funds go). This example uses two risk-elimination strategies:
+> - **Withdraw allocator** (`sharing.who = Signer`): Safe because `myshop_withdraw_guard_v2` binds `context(Signer)` to `myshop_merchant` (identifier 2). Only the merchant can pass the Guard, so funds correctly flow to the merchant.
+> - **Refund allocator** (`sharing.who = GuardIdentifier 0`): Funds go to the Order object's address (escrow), not to the caller. The Guard additionally binds `context(Signer)` to `order.owner` (dynamic query 1562), ensuring only the order's rightful owner can trigger the refund.
+>
+> **Alternative approach**: Instead of Signer binding in the Guard, you can use `sharing.who = Entity` to send funds to a fixed Treasury or personal address. This is even more robust because funds are directed regardless of who passes the Guard. See the Insurance example for this pattern.
 
 > **Design Decision — Refund Recipient**: When using `{ "GuardIdentifier": 0 }` in the refund allocation, the refund is sent to the **Order object's on-chain address** (not the customer's wallet address). This is by design: the Order object acts as an escrow holding the refunded payment at its own address. The customer subsequently claims the refund from the Order object via a separate withdraw operation. This two-step design ensures the refund is traceable on-chain and tied to the specific order, providing better dispute resolution and audit trail.
 
-#### 8.2 Create and Publish Service
+#### 6.2 Create and Publish Service
 
 **Prompt**: Create and publish a Service named "myshop_service_v2" with machine "myshop_machine_v2", order allocation using Guards, after-sales contact, and toy products.
 
@@ -706,7 +803,8 @@ The `order_allocators` configuration defines how order payments are distributed:
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -718,7 +816,7 @@ The `order_allocators` configuration defines how order payments are distributed:
 
 ---
 
-### Step 9: Update Product Pricing (Optional)
+### Step 7: Update Product Pricing (Optional)
 
 To offer promotional pricing, update product prices using the `sales` operation with `op: "set"`:
 
@@ -745,7 +843,8 @@ To offer promotional pricing, update product prices using the `sales` operation
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -778,8 +877,10 @@ Create a customer account:
 ```json
 {
   "transfer": {
-    "name_or_address": "myshop_customer",
-    "amount": 1000000000
+    "name_or_address_to": "myshop_customer",
+    "amount": 1000000000,
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -802,7 +903,7 @@ Customers can query the Service to see available products.
 }
 ```
 
-> **AI Note**: Capture the `wip_hash` from the Service query result for each product. When the customer places an order, pass the captured `wip_hash` in `buy.items[].wip_hash`. This is a dispute-prevention mechanism — the on-chain contract compares `item.wip_hash` against the Service's current `sale.wip_hash` to ensure the product hasn't been swapped between browse and purchase time.
+> **AI Note**: Capture the `wip_hash` from the Service query result for each product. When the customer places an order, pass the captured `wip_hash` in `buy.items[].wip_hash`. **The `wip_hash` field cannot be an empty string** — it must match the hash stored in the Service. This is a dispute-prevention mechanism — the on-chain contract compares `item.wip_hash` against the Service's current `sale.wip_hash` to ensure the product hasn't been swapped between browse and purchase time.
 
 ---
 
@@ -823,7 +924,7 @@ Customer creates an order by purchasing products from the Service.
           {
             "name": "Play Purse Set 35PCS",
             "stock": 1,
-            "wip_hash": ""
+            "wip_hash": "03c18561efa8faf4d75480eb1f732c4a46ffde95599e92eca06167785fc07a5b"
           }
         ],
         "total_pay": {
@@ -846,7 +947,8 @@ Customer creates an order by purchasing products from the Service.
   },
   "env": {
     "account": "myshop_customer",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1010,7 +1112,8 @@ Merchant advances the order from initial state to "Order Confirmation" node.
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1039,7 +1142,8 @@ Merchant ships the order and advances from "Order Confirmation" to "Shipping".
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1068,7 +1172,8 @@ Merchant or delivery service confirms the order has been delivered.
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1097,7 +1202,8 @@ Customer confirms receipt and completes the order.
   },
   "env": {
     "account": "myshop_customer",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1110,7 +1216,7 @@ After order completion, the merchant needs to:
 1. Activate the Allocation by verifying the Guard (order completion status)
 2. Withdraw funds from the Service
 
-#### 9.1 Activate Allocation (Guard Verification)
+#### 7.1 Activate Allocation (Guard Verification)
 
 First, activate the Allocation by submitting the Guard verification with the Order ID.
 
@@ -1151,6 +1257,7 @@ First, activate the Allocation by submitting the Guard verification with the Ord
   "env": {
     "account": "myshop_merchant",
     "network": "mainnet",
+    "confirmed": true,
     "no_cache": true
   }
 }
@@ -1158,7 +1265,7 @@ First, activate the Allocation by submitting the Guard verification with the Ord
 
 > **Note**: Replace the Guard address `0x5af9...1074` and Order address `0xa6db...3d5` with your actual object addresses. Use the full 64-character addresses in actual operations.
 
-#### 9.2 Withdraw Funds from Service
+#### 7.2 Withdraw Funds from Service
 
 After the Allocation is activated, withdraw the funds from the Service.
 
@@ -1173,7 +1280,8 @@ After the Allocation is activated, withdraw the funds from the Service.
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1204,7 +1312,8 @@ Customer can cancel the order after the merchant confirms it. The "Cancel Order"
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1229,7 +1338,8 @@ Customer can cancel the order after the merchant confirms it. The "Cancel Order"
   },
   "env": {
     "account": "myshop_customer",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1273,6 +1383,7 @@ After the order is cancelled, the customer can activate the refund allocation us
   "env": {
     "account": "myshop_customer",
     "network": "mainnet",
+    "confirmed": true,
     "no_cache": true
   }
 }
@@ -1308,7 +1419,8 @@ The Service must have a compensation fund balance ≥ the arbitration indemnity
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1336,7 +1448,8 @@ Create an Arbitration object for handling order disputes.
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1358,7 +1471,8 @@ The merchant unpauses the Arbitration object to enable dispute submissions.
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1379,7 +1493,8 @@ Create a new order for testing the arbitration flow (if you don't have one alrea
         "items": [
           {
             "name": "Tree House Building Set",
-            "stock": 1
+            "stock": 1,
+            "wip_hash": "03c18561efa8faf4d75480eb1f732c4a46ffde95599e92eca06167785fc07a5b"
           }
         ],
         "total_pay": {"balance": 30000000}
@@ -1391,12 +1506,13 @@ Create a new order for testing the arbitration flow (if you don't have one alrea
   },
   "env": {
     "account": "myshop_customer",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
 
-> **Note**: The WIP hash is auto-computed by the SDK from the Service's WIP URL configuration.
+> **Note**: The `wip_hash` must be obtained from the Service query result (Step 1 of Part 2). It cannot be omitted or set to an empty string — the on-chain contract validates it against the Service's current `sale.wip_hash`.
 
 ### Step 5: Customer Submits Dispute
 
@@ -1419,7 +1535,8 @@ The customer submits a dispute against the order, creating an Arb object.
   },
   "env": {
     "account": "myshop_customer",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1444,7 +1561,8 @@ The merchant confirms the dispute materials are valid and sets the voting deadli
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1470,7 +1588,8 @@ The merchant provides the final arbitration result with feedback and indemnity a
   },
   "env": {
     "account": "myshop_merchant",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1494,7 +1613,8 @@ The customer claims the compensation from the Service's compensation fund.
   },
   "env": {
     "account": "myshop_customer",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```
@@ -1573,7 +1693,8 @@ When advancing order workflows, use `operation_type: "progress"` with the `opera
   },
   "env": {
     "account": "operator_account",
-    "network": "mainnet"
+    "network": "mainnet",
+    "confirmed": true
   }
 }
 ```