@wowok/skills 1.1.12 → 1.2.1

package/examples/Insurance/Insurance.md

@@ -4,6 +4,15 @@ A complete example demonstrating how to create an outdoor accident insurance ser
 
 ---
 
+## ⚠️ 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**: Run all build/setup steps in sequence before testing any claim or order flow. Do not skip steps — each depends on objects created by prior steps.
+- **Prerequisites**: `insurance_provider_v1` with sufficient WOW for gas. All on-chain operations require `env.confirmed: true`.
+
+---
+
 ## Core Requirements & Features
 
 | Requirement | Description | Implementation |
@@ -12,13 +21,17 @@ A complete example demonstrating how to create an outdoor accident insurance ser
 | **Time-Lock Guard** | Prevent premature claim completion | Guard using Order + convert_witness(TypeOrderProgress) to verify clock > progress.current_time + lock_duration |
 | **Supply Chain Integration** | Support sub-order creation by travel service providers | Order can be created by authorized agents (travel_provider) |
 | **Permission Control** | Role-based access for insurance operations | Permission object with custom indexes for claim processing |
+| **Safe Fund Allocation** | Merchant revenue collection without theft risk | 2 alternative allocators with `sharing.who = {"Entity": ...}` (funds flow to fixed Treasury or personal address) |
 
 ### Key Design Decisions
 
-1. **Time-Lock via Witness Conversion**: The Complete node Guard uses `convert_witness: 100` (TypeOrderProgress) to convert the submitted Order ID into its associated Progress object, then queries `progress.current_time` to verify the time-lock condition.
+1. **Time-Lock via Witness Conversion**: The Complete node Guard uses `convert_witness: "OrderProgress"` (TypeOrderProgress) to convert the submitted Order ID into its associated Progress object, then queries `progress.current_time` to verify the time-lock condition.
 2. **Simple Two-Node Workflow**: Insurance claims follow a straightforward Start -> Complete path, keeping the workflow simple and predictable.
 3. **Order ID as Submission**: The Order ID is submitted at runtime (`b_submission: true`) and used for witness conversion.
 4. **Machine Creation Pattern**: Machine can be created with nodes and published in a single transaction (as shown in this example).
+5. **Entity Sharing for Fund Safety**: Order allocators use `sharing.who = {"Entity": "address"}` instead of `{"Signer": "signer"}`. Funds always flow to a fixed address (Treasury or personal) regardless of who triggers the allocation — even if the Guard is somehow bypassed, an attacker cannot redirect funds to themselves. This eliminates the fatal fund-theft risk of Signer sharing.
+6. **Project Binding as Defense-in-Depth**: Each withdraw Guard verifies `order.service == insurance_service_v1` (query 1563) to ensure the submitted Order belongs to this Service, preventing cross-service order theft.
+7. **Permission Consistency**: The Treasury object uses the same Permission (`insurance_permission_v1`) as the Service, ensuring a single consistent permission organization governs all insurance operations.
 
 ---
 
@@ -26,8 +39,9 @@ A complete example demonstrating how to create an outdoor accident insurance ser
 
 This example demonstrates:
 
-- **Insurance Service Setup**: Permission, Guard, Machine, and Service creation
+- **Insurance Service Setup**: Permission, Treasury, Guard, Machine, and Service creation
 - **Time-Lock Guard**: Using Order + convert_witness to access Progress data
+- **Safe Fund Allocation**: Two alternative merchant collection approaches via Entity sharing
 - **Workflow Automation**: Machine-driven claim processing
 
 ---
@@ -49,12 +63,20 @@ This example demonstrates:
 |           |                      |                              |
 |           v                      v                              |
 |  +-----------------+    +-----------------+                     |
-|  |    Machine      |    |    Service      |                     |
-|  | (insurance_     |<---| (insurance_     |                     |
-|  |  machine)       |    |  service)       |                     |
+|  |    Treasury     |    |    Machine      |                     |
+|  | (insurance_     |    | (insurance_     |                     |
+|  |  treasury)      |    |  machine)       |                     |
+|  +--------+--------+    +--------+--------+                     |
+|           |                      |                              |
+|           v                      v                              |
+|  +-----------------+    +-----------------+                     |
+|  | withdraw guards |    |    Service      |                     |
+|  | (treasury +     |<---| (insurance_     |                     |
+|  |  personal)      |    |  service)       |                     |
 |  +-----------------+    +-----------------+                     |
 |                                                                  |
 |  Workflow: Start -> Complete (Time-Lock Guard)                  |
+|  Allocators: 2 Entity-sharing approaches (first-match-wins)     |
 |                                                                  |
 ------------------------------------------------------------------
 ```
@@ -71,9 +93,32 @@ This example demonstrates:
 **Guard Logic**:
 ```
 clock > progress.current_time + 1000ms
-(progress accessed via Order + convert_witness=TypeOrderProgress)
+(progress accessed via Order + convert_witness="OrderProgress")
 ```
 
+### Fund Allocation Flow (2 Alternative Approaches)
+
+```
+Order reaches Complete
+        |
+        v
+   Allocation triggered
+        |
+   +----+----+
+   |         |
+   v         v
+Approach 1: Approach 2:
+Treasury   Personal
+guard      guard
+   |         |
+   v         v
+Entity:    Entity:
+insurance_ insurance_
+treasury   provider
+```
+
+> **first-match-wins**: Allocators execute the FIRST Allocator whose Guard passes. Listing both approaches in one Service illustrates the 2 design options; in production you would typically pick ONE approach (delete the other allocator).
+
 ---
 
 ## Prerequisites
@@ -150,9 +195,38 @@ Create a Permission object to manage access control for the insurance service. T
 
 ---
 
-## Step 2: Create Time-Lock Complete Guard
+## Step 2: Create Treasury Object
+
+Create a Treasury object to aggregate insurance service revenue (public funds for operations and distribution). The Treasury uses the same Permission as the Service (`insurance_permission_v1`) — this ensures a single consistent permission organization governs both fund collection and service operations.
+
+**Prompt**: Create a Treasury object named "insurance_treasury" for aggregating insurance revenue.
+
+```json
+{
+  "operation_type": "treasury",
+  "data": {
+    "object": {
+      "name": "insurance_treasury_v1",
+      "type_parameter": "0x2::wow::WOW",
+      "permission": "insurance_permission_v1",
+      "replaceExistName": true
+    },
+    "description": "Treasury for aggregating insurance service revenue (public funds for operations and distribution). Uses the same Permission as the Service for consistency."
+  },
+  "env": {
+    "account": "insurance_provider_v1",
+    "network": "testnet"
+  }
+}
+```
+
+> **Important — Permission Consistency**: The Treasury's Permission should match the Service's Permission (`insurance_permission_v1`). Using different Permissions for Treasury and Service means different permission organizations govern fund collection vs service operations — this is a minor design risk. Keep them consistent unless you have a specific reason to separate them.
+
+---
+
+## Step 3: Create Time-Lock Complete Guard
 
-Create a Guard that verifies the time-lock condition for claim completion. The Guard uses the submitted Order ID with `convert_witness: 100` (TypeOrderProgress) to access the associated Progress object and query `progress.current_time`.
+Create a Guard that verifies the time-lock condition for claim completion. The Guard uses the submitted Order ID with `convert_witness: "OrderProgress"` (TypeOrderProgress) to access the associated Progress object and query `progress.current_time`.
 
 **Guard Logic**:
 ```
@@ -170,7 +244,7 @@ clock > progress.current_time + 1000
       "tags": ["insurance", "time-lock", "complete"],
       "replaceExistName": true
     },
-    "description": "Time-lock guard for insurance claim completion. Requires current clock > progress.current_time + 10000ms (10 seconds for TESTING; in production set to reasonable duration like 8 hours). Progress is accessed via Order with convert_witness=TypeOrderProgress(100).",
+    "description": "Time-lock guard for insurance claim completion. Requires current clock > progress.current_time + 10000ms (10 seconds for TESTING; in production set to reasonable duration like 8 hours). Progress is accessed via Order with convert_witness="OrderProgress"(100).",
 
     "table": [
       {
@@ -198,10 +272,10 @@ clock > progress.current_time + 1000
           "nodes": [
             {
               "type": "query",
-              "query": 1272,
+              "query": "progress.current_time",
               "object": {
                 "identifier": 0,
-                "convert_witness": 100
+                "convert_witness": "OrderProgress"
               },
               "parameters": []
             },
@@ -232,52 +306,181 @@ clock > progress.current_time + 1000
 
 ---
 
-## Step 3: Create Withdraw Guard for Order Allocators
+## Step 4: Create Withdraw Guards for Order Allocators
 
-Create a Guard that allows the insurance provider to withdraw funds after the order reaches the Complete node.
+Create **two** withdraw Guards — one for each merchant collection approach. Both Guards share identical root/table logic (order at Complete node + project binding) but differ in `description` to indicate their distinct purposes. Allocators require unique Guard addresses, so two Guard objects are needed.
 
-**Prompt**: Create a Guard named "insurance_withdraw_guard" for order fund allocation.
+**Guard Logic** (identical for both):
+```
+logic_and[
+  query("progress.current") == "Complete",   // order is at Complete node
+  query("order.service") == insurance_service_v1        // order belongs to THIS service
+]
+```
+
+**Risk Elimination**:
+- **Project binding** (query 1563): prevents cross-service order theft — an attacker cannot submit another Service's completed Order to trigger allocation.
+- **Entity sharing** (configured in Step 6): funds flow to a fixed address regardless of caller — no Signer binding needed in the Guard.
+
+### 4.1 Treasury Collection Guard
+
+**Prompt**: Create a Guard named "insurance_withdraw_guard_treasury" for Treasury fund collection.
 
 ```json
 {
   "operation_type": "guard",
   "data": {
     "namedNew": {
-      "name": "insurance_withdraw_guard_v1",
-      "tags": ["insurance", "withdraw"],
+      "name": "insurance_withdraw_guard_treasury_v1",
+      "tags": ["insurance", "withdraw", "treasury"],
       "replaceExistName": true
     },
-    "description": "Allow insurance provider to withdraw funds after order is completed.",
+    "description": "Allow fund allocation to Treasury after order is completed. RISK ELIMINATION: order must be at Complete node AND belong to insurance_service_v1 (prevents cross-service theft). Funds flow to fixed Treasury Entity (safe — no Signer binding needed).",
     "table": [
       {
         "identifier": 0,
         "b_submission": true,
         "value_type": "Address",
-        "name": "order_id"
+        "object_type": "Order",
+        "name": "order_id (Order object submitted at runtime)"
       },
       {
         "identifier": 1,
         "b_submission": false,
         "value_type": "String",
         "value": "Complete",
-        "name": "complete_node"
+        "name": "Expected Complete node name (case-sensitive)"
+      },
+      {
+        "identifier": 2,
+        "b_submission": false,
+        "value_type": "Address",
+        "value": "insurance_service_v1",
+        "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": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": "order.service",
+              "object": {
+                "identifier": 0
+              },
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 2
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "env": {
+    "account": "insurance_provider_v1",
+    "network": "testnet"
+  }
+}
+```
+
+### 4.2 Personal Collection Guard
+
+**Prompt**: Create a Guard named "insurance_withdraw_guard_personal" for personal fund collection.
+
+```json
+{
+  "operation_type": "guard",
+  "data": {
+    "namedNew": {
+      "name": "insurance_withdraw_guard_personal_v1",
+      "tags": ["insurance", "withdraw", "personal"],
+      "replaceExistName": true
+    },
+    "description": "Allow fund allocation to personal collection address after order is completed. RISK ELIMINATION: order must be at Complete node AND belong to insurance_service_v1. Funds flow to fixed personal Entity (safe — no Signer binding needed).",
+    "table": [
+      {
+        "identifier": 0,
+        "b_submission": true,
+        "value_type": "Address",
+        "object_type": "Order",
+        "name": "order_id (Order object submitted at runtime)"
+      },
+      {
+        "identifier": 1,
+        "b_submission": false,
+        "value_type": "String",
+        "value": "Complete",
+        "name": "Expected Complete node name (case-sensitive)"
+      },
+      {
+        "identifier": 2,
+        "b_submission": false,
+        "value_type": "Address",
+        "value": "insurance_service_v1",
+        "name": "Expected service address (prevents cross-service fund theft)"
+      }
+    ],
+    "root": {
+      "type": "logic_and",
+      "nodes": [
+        {
+          "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": "query",
+              "query": "order.service",
+              "object": {
+                "identifier": 0
+              },
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 2
+            }
+          ]
         }
       ]
     }
@@ -289,9 +492,19 @@ Create a Guard that allows the insurance provider to withdraw funds after the or
 }
 ```
 
+**Guard Table** (identical for both guards):
+
+| identifier | b_submission | value_type | value | Purpose |
+|------------|-------------|-----------|-------|---------|
+| 0 | **true** | Address | (submitted at runtime) | Order ID submitted at runtime, converted to Progress via convert_witness="OrderProgress" |
+| 1 | false | String | "Complete" | Expected node name (case-sensitive) |
+| 2 | false | Address | insurance_service_v1 | Expected Service address (project binding — prevents cross-service fund theft) |
+
+> **Why 2 Guards?** Allocators require unique Guard addresses. The 2 Guards have identical root/table logic but different `description` and `tags` to indicate their distinct purposes (Treasury collection vs personal collection). In production you would typically pick ONE approach and delete the other Guard + Allocator.
+
 ---
 
-## Step 4: Create, Configure and Publish Machine
+## Step 5: Create, Configure and Publish Machine
 
 Create a Machine with workflow nodes and publish it in a single transaction.
 
@@ -370,9 +583,9 @@ Create a Machine with workflow nodes and publish it in a single transaction.
 
 ---
 
-## Step 5: Create and Publish Service
+## Step 6: Create and Publish Service
 
-Create the insurance service with machine, order_allocators, sales, and publish in a single transaction.
+Create the insurance service with machine, order_allocators (2 alternative approaches), sales, and publish in a single transaction.
 
 > **Important**: 
 > - Service must include `order_allocators` when publishing
@@ -394,14 +607,24 @@ Create the insurance service with machine, order_allocators, sales, and publish
     "description": "Outdoor accident insurance for Iceland travel. Provides coverage for ice scooting and other outdoor activities.",
     "machine": "insurance_machine_v1",
     "order_allocators": {
-      "description": "Insurance order revenue allocation",
+      "description": "Insurance order revenue allocation — 2 alternative merchant collection approaches (first-match-wins means only the first passing allocator executes)",
       "threshold": 0,
       "allocators": [
         {
-          "guard": "insurance_withdraw_guard_v1",
+          "guard": "insurance_withdraw_guard_treasury_v1",
+          "sharing": [
+            {
+              "who": {"Entity": "insurance_treasury_v1"},
+              "sharing": 10000,
+              "mode": "Rate"
+            }
+          ]
+        },
+        {
+          "guard": "insurance_withdraw_guard_personal_v1",
           "sharing": [
             {
-              "who": {"Signer": "signer"},
+              "who": {"Entity": "insurance_provider_v1"},
               "sharing": 10000,
               "mode": "Rate"
             }
@@ -417,7 +640,7 @@ Create the insurance service with machine, order_allocators, sales, and publish
           "price": 100000000,
           "stock": 1000,
           "suspension": false,
-          "wip": "",
+          "wip": "https://cdn.jsdelivr.net/gh/wowok-ai/docs@main/wip-examples/three_body.wip",
           "wip_hash": ""
         }
       ]
@@ -431,13 +654,19 @@ Create the insurance service with machine, order_allocators, sales, and publish
 }
 ```
 
-> **Important**: 
+> **Important — Fund Allocation Safety**: 
 > - `mode: "Rate"` represents Rate allocation mode (valid values: `"Amount"`, `"Rate"`, `"Surplus"`)
-> - `who: {"Signer": "signer"}` represents the transaction signer
+> - `who: {"Entity": "name_or_address"}` — funds flow to a FIXED address (Treasury or personal). This is the SAFE pattern: even if the Guard is somehow bypassed or an attacker submits a forged Order, funds still go to the fixed Entity — the attacker cannot redirect funds to themselves.
+> - **NEVER use `who: {"Signer": "signer"}` for merchant collection** — this means funds flow to whoever calls the allocation. Combined with a Guard that only checks order status (no Signer binding), anyone can submit any completed Order and steal 100% of funds.
+> - **2 allocators = 2 alternative approaches**: first-match-wins means only the FIRST allocator whose Guard passes will execute. In production, pick ONE approach (Treasury OR personal) and delete the other. Listing both here illustrates the 2 design options.
+> - **Permission consistency**: the Treasury uses `insurance_permission_v1` (same as Service) — keep Permissions consistent unless you have a specific reason to separate them.
+> - `wip_hash: ""` (empty string) means the system will automatically extract and use the hash from within the WIP file (`meta.hash` field). The WIP file at the `wip` URL must be a valid JSON file in WIP format. Do NOT use the SHA-256 of the file bytes as `wip_hash` — it must be the `meta.hash` value inside the WIP JSON, or empty string for auto-extraction.
 
 ---
 
-## Step 6: Unpause Service
+## Step 7: Unpause Service (Optional)
+
+> **Note**: A newly created Service is **not paused by default**. This step is only needed if you explicitly paused the service earlier. You can safely skip this step and proceed to Step 8.
 
 Unpause the service to allow order creation.
 
@@ -459,7 +688,7 @@ Unpause the service to allow order creation.
 
 ---
 
-## Step 7: Verify Service Configuration
+## Step 8: Verify Service Configuration
 
 Query the service to verify all configurations are correct.
 
@@ -475,9 +704,9 @@ Query the service to verify all configurations are correct.
 
 ---
 
-## Step 8: Test Order Creation and Progress
+## Step 9: Test Order Creation and Progress
 
-### 8.1 Create Insurance Order
+### 9.1 Create Insurance Order
 
 Create an order on the insurance service using the `order_new` field of the `service` operation. In production, this would be done by the travel service provider as a supply chain sub-order.
 
@@ -504,6 +733,14 @@ Create an order on the insurance service using the `order_new` field of the `ser
       "namedNewOrder": {
         "name": "test_insurance_order_v1",
         "replaceExistName": true
+      },
+      "namedNewAllocation": {
+        "name": "insurance_test_alloc_v1",
+        "replaceExistName": true
+      },
+      "namedNewProgress": {
+        "name": "insurance_test_progress_v1",
+        "replaceExistName": true
       }
     }
   },
@@ -514,7 +751,9 @@ Create an order on the insurance service using the `order_new` field of the `ser
 }
 ```
 
-> **Get the Progress ID**: After creating the order, query it to obtain the Progress object ID needed for the next steps:
+> **Named Objects**: The `namedNewOrder`, `namedNewAllocation`, and `namedNewProgress` fields assign local names to the created objects. You can reference them by name (e.g., `"test_insurance_order_v1"`, `"insurance_test_alloc_v1"`, `"insurance_test_progress_v1"`) in subsequent operations instead of using raw on-chain IDs.
+>
+> **Optional — Query the Order**: To verify the order or obtain on-chain object IDs:
 > ```json
 > {
 >   "query_type": "onchain_objects",
@@ -523,9 +762,9 @@ Create an order on the insurance service using the `order_new` field of the `ser
 >   "no_cache": true
 > }
 > ```
-> The response includes a `progress` field containing the Progress object ID, and an `allocation` field containing the Allocation object ID.
+> The response includes `progress` and `allocation` fields with the on-chain object IDs.
 
-### 8.2 Advance Progress: Initial -> Start
+### 9.2 Advance Progress: Initial -> Start
 
 First, advance the progress from initial state to Start node.
 
@@ -533,10 +772,10 @@ First, advance the progress from initial state to Start node.
 
 ```json
 {
-  "operation_type": "progress",
+  "operation_type": "order",
   "data": {
-    "object": "<insurance_progress_id>",
-    "operate": {
+    "object": "test_insurance_order_v1",
+    "progress": {
       "operation": {
         "next_node_name": "Start",
         "forward": "start_claim"
@@ -553,9 +792,9 @@ First, advance the progress from initial state to Start node.
 > **Note**: 
 > - Both `next_node_name` and `forward` fields are required in the operation object
 > - Use simple forward name (e.g., `"start_claim"`) without node prefix. The system automatically resolves the path from current node
-> - The Progress object ID can be obtained by querying the Order object (it has a `progress` field) — see Step 8.1
+> - The Progress is advanced via the Order object's `progress` field, using the Order name as reference
 
-### 8.3 Advance Progress: Start -> Complete
+### 9.3 Advance Progress: Start -> Complete
 
 Wait at least 10 seconds after entering Start node, then advance the progress to Complete with the Order ID as submission.
 
@@ -569,10 +808,10 @@ Wait at least 10 seconds after entering Start node, then advance the progress to
 
 ```json
 {
-  "operation_type": "progress",
+  "operation_type": "order",
   "data": {
-    "object": "<insurance_progress_id>",
-    "operate": {
+    "object": "test_insurance_order_v1",
+    "progress": {
       "operation": {
         "next_node_name": "Complete",
         "forward": "complete_claim"
@@ -617,10 +856,10 @@ The server will return a `submission` prompt like:
 
 ```json
 {
-  "operation_type": "progress",
+  "operation_type": "order",
   "data": {
-    "object": "<insurance_progress_id>",
-    "operate": {
+    "object": "test_insurance_order_v1",
+    "progress": {
       "operation": {
         "next_node_name": "Complete",
         "forward": "complete_claim"
@@ -645,7 +884,7 @@ The server will return a `submission` prompt like:
             "value_type": "Address",
             "name": "Order ID (submitted at runtime)",
             "object_type": "Order",
-            "value": "<insurance_order_id>"
+            "value": "test_insurance_order_v1"
           }
         ]
       }
@@ -659,15 +898,126 @@ The server will return a `submission` prompt like:
 ```
 
 > **⚠️ Important**: 
-> - The `submission` field must be at the **root level** of the request (sibling to `operation_type`, `data`, and `env`), NOT nested inside `data` or `operate.operation`.
-> - The `guard` objects in the submission use on-chain addresses (not names), as returned by the Phase 1 response.
-> - Fill in the `value` field with the actual Order ID (or Order name). Keep the other fields (`identifier`, `value_type`, `name`, `object_type`) as returned by Phase 1.
-> - Replace `<insurance_progress_id>` and `<insurance_order_id>` with actual values from step 8.1.
+> - The `submission` field must be at the **root level** of the request (sibling to `operation_type`, `data`, and `env`), NOT nested inside `data` or `progress.operation`.
+> - The `guard` objects in the submission use on-chain addresses (not names), as returned by the Phase 1 response. Replace `0x1508ded8...` with the actual guard address from your Phase 1 response.
+> - The `value` field accepts either an on-chain object ID or a named object reference (e.g., `"test_insurance_order_v1"`). Keep the other fields (`identifier`, `value_type`, `name`, `object_type`) as returned by Phase 1.
+> - The Order is referenced by its name (`"test_insurance_order_v1"`) in the `data.object` field.
 > - Both `next_node_name` and `forward` fields are required in the operation object.
 > - Use simple forward name `"complete_claim"` without node prefix.
 
 ---
 
+## Step 10: Withdraw Funds via Allocation
+
+After the Progress reaches the Complete node, funds can be withdrawn using one of the withdraw Guards. This example uses the Treasury collection Guard (`insurance_withdraw_guard_treasury_v1`). To use the personal collection approach instead, substitute `insurance_withdraw_guard_personal_v1`.
+
+The Guard verifies:
+1. `progress.current == "Complete"` (query 1253) via the submitted Order ID with `convert_witness: "OrderProgress"` (TypeOrderProgress)
+2. `order.service == insurance_service_v1` (query 1563) — project binding prevents cross-service order theft
+
+The Allocation object was created automatically when the Order was placed (Step 9.1). Query the Order to obtain the Allocation object ID — it is in the `allocation` field of the Order object.
+
+> **Fund Flow**: With `sharing.who = {"Entity": "insurance_treasury_v1"}`, 100% of the order amount flows to the Treasury object regardless of who triggers the allocation. The caller cannot redirect funds — this is the safe Entity-sharing pattern.
+
+> **Two-Phase Submission**: The `alloc_by_guard` operation also uses two-phase submission when the Guard has `b_submission: true` fields, just like the Progress operation in Step 9.3.
+
+### 10.1 Phase 1: Request Submission Prompt
+
+Call the allocation operation WITHOUT the `submission` field to obtain the Guard submission structure.
+
+**Prompt**: Withdraw funds from allocation "insurance_test_alloc_v1" using Treasury withdraw guard.
+
+```json
+{
+  "operation_type": "allocation",
+  "data": {
+    "object": "insurance_test_alloc_v1",
+    "alloc_by_guard": "insurance_withdraw_guard_treasury_v1"
+  },
+  "env": {
+    "account": "insurance_provider_v1",
+    "network": "testnet"
+  }
+}
+```
+
+The server will return a `submission` prompt like:
+
+```json
+{
+  "type": "submission",
+  "guard": [
+    { "object": "0xfb8bed2f...", "impack": true }
+  ],
+  "submission": [
+    {
+      "guard": "0xfb8bed2f...",
+      "submission": [
+        {
+          "identifier": 0,
+          "b_submission": true,
+          "value_type": "Address",
+          "name": "order_id (Order object submitted at runtime)",
+          "object_type": "Order"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 10.2 Phase 2: Submit with Order ID
+
+Fill in the `value` field with the Order ID (or Order name) and resubmit. The `submission` field must be placed at the **root level** of the request.
+
+**Prompt**: Withdraw funds from allocation with Order ID submission.
+
+```json
+{
+  "operation_type": "allocation",
+  "data": {
+    "object": "insurance_test_alloc_v1",
+    "alloc_by_guard": "insurance_withdraw_guard_treasury_v1"
+  },
+  "submission": {
+    "type": "submission",
+    "guard": [
+      {
+        "object": "0xfb8bed2f...",
+        "impack": true
+      }
+    ],
+    "submission": [
+      {
+        "guard": "0xfb8bed2f...",
+        "submission": [
+          {
+            "identifier": 0,
+            "b_submission": true,
+            "value_type": "Address",
+            "name": "order_id (Order object submitted at runtime)",
+            "object_type": "Order",
+            "value": "test_insurance_order_v1"
+          }
+        ]
+      }
+    ]
+  },
+  "env": {
+    "account": "insurance_provider_v1",
+    "network": "testnet"
+  }
+}
+```
+
+> **⚠️ Important**: 
+> - Replace `0xfb8bed2f...` with the actual `insurance_withdraw_guard_treasury_v1` address from your Phase 1 response.
+> - The `value` field accepts either an on-chain object ID or a named object reference (e.g., `"test_insurance_order_v1"`).
+> - The `sharing` configuration (`{"Entity": "insurance_treasury_v1"}` at 100% Rate) determines where funds flow. Funds go to the fixed Treasury address regardless of who calls the allocation — this is the safe Entity-sharing pattern that prevents fund theft.
+> - After a successful withdrawal, the Allocation `balance` becomes `0` and a Payment object is created as an immutable record.
+
+---
+
 ## Troubleshooting
 
 ### MoveAbort code: 7 (Guard Verification Failed)
@@ -676,6 +1026,10 @@ When advancing Progress, if you get `abort code: 7 (Verify failed)`, the Guard c
 - Wait longer than the time-lock duration (10000ms = 10 seconds) before advancing to Complete
 - Verify the submitted Order ID is correct and corresponds to the Progress being advanced
 
+For the withdraw Guard:
+- Verify the Order's Progress is at the "Complete" node (case-sensitive — "Complete" ≠ "complete")
+- Verify the Order belongs to `insurance_service_v1` (project binding check via query 1563)
+
 ### Forward validation failed
 
 If you see `Connection from current node "" to target node "Complete" does not exist`, use simple forward names without node prefix:
@@ -711,12 +1065,14 @@ Published Machine nodes are immutable (`MoveAbort code: 3`). Create a new Machin
 - [ ] Create `insurance_provider_v1` account
 - [ ] Get test tokens for `insurance_provider_v1`
 - [ ] Step 1: Create `insurance_permission_v1` with all required indexes
-- [ ] Step 2: Create `insurance_complete_guard_v1`
-- [ ] Step 3: Create `insurance_withdraw_guard_v1`
-- [ ] Step 4: Create `insurance_machine_v1` with nodes and publish
-- [ ] Step 5: Create and publish `insurance_service_v1` (with machine, order_allocators, sales)
-- [ ] Step 6: Unpause Service
-- [ ] Step 7: Verify Service configuration
-- [ ] Step 8.1: Create test insurance order
-- [ ] Step 8.2: Advance progress Initial -> Start
-- [ ] Step 8.3: Advance progress Start -> Complete with submission (wait 10s after Step 8.2)
+- [ ] Step 2: Create `insurance_treasury_v1` (same Permission as Service)
+- [ ] Step 3: Create `insurance_complete_guard_v1` (time-lock)
+- [ ] Step 4: Create `insurance_withdraw_guard_treasury_v1` + `insurance_withdraw_guard_personal_v1` (project binding)
+- [ ] Step 5: Create `insurance_machine_v1` with nodes and publish
+- [ ] Step 6: Create and publish `insurance_service_v1` (with machine, 2 Entity-sharing allocators, sales)
+- [ ] Step 7: Unpause Service (Optional — skip if service was never paused)
+- [ ] Step 8: Verify Service configuration
+- [ ] Step 9.1: Create test insurance order
+- [ ] Step 9.2: Advance progress Initial -> Start
+- [ ] Step 9.3: Advance progress Start -> Complete with submission (wait 10s after Step 9.2)
+- [ ] Step 10: Withdraw funds via Allocation (alloc_by_guard with Treasury or personal withdraw guard)