@wowok/skills 1.1.9 → 1.1.11

package/examples/Insurance/Insurance.md

@@ -2,8 +2,6 @@
 
 A complete example demonstrating how to create an outdoor accident insurance service using WoWok protocol. This insurance service is designed to be purchased by travel service providers as part of a travel package (supply chain sub-order).
 
-> **View Actual Execution Results**: See [Insurance_TestResults.md](Insurance_TestResults.md) for real testnet execution results with actual object addresses and transaction outputs.
-
 ---
 
 ## Core Requirements & Features
@@ -20,7 +18,7 @@ A complete example demonstrating how to create an outdoor accident insurance ser
 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.
 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 must be created first, then nodes added separately, then published. Creating machine with nodes and publish in one transaction does not work correctly.
+4. **Machine Creation Pattern**: Machine can be created with nodes and published in a single transaction (as shown in this example).
 
 ---
 
@@ -111,11 +109,13 @@ Before running this example, ensure you have:
 }
 ```
 
+> **Best Practice — `no_cache: true`**: When building multiple interdependent objects in one session, set `"no_cache": true` in the `env` object of every on-chain operation to ensure fresh chain state. The examples below omit it for brevity.
+
 ---
 
 ## Step 1: Create Permission Object
 
-Create a Permission object to manage access control for the insurance service.
+Create a Permission object to manage access control for the insurance service. The Permission must include all permission indexes that will be used in the Machine workflow.
 
 **Prompt**: Create a Permission object named "insurance_permission" for the insurance service.
 
@@ -141,6 +141,13 @@ Create a Permission object to manage access control for the insurance service.
 }
 ```
 
+> **Important**: The `index` array must include all permission indexes used in Machine forwards:
+> - `1000`: for `start_claim` forward (Start node)
+> - `1001`: for `complete_claim` forward (Complete node)
+> - Additional indexes for future operations
+>
+> Without these permissions, advancing Progress will fail with `MoveAbort code: 7`.
+
 ---
 
 ## Step 2: Create Time-Lock Complete Guard
@@ -163,51 +170,48 @@ 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 + 1000ms (1 second 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=TypeOrderProgress(100).",
+
     "table": [
       {
         "identifier": 0,
         "b_submission": true,
         "value_type": "Address",
-        "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
         "name": "Order ID (submitted at runtime)"
       },
       {
         "identifier": 1,
         "b_submission": false,
         "value_type": "U64",
-        "value": 1000
+        "value": 10000
       }
     ],
     "root": {
-      "type": "node",
-      "node": {
-        "type": "logic_as_u256_greater",
-        "nodes": [
-          {
-            "type": "context",
-            "context": "Clock"
-          },
-          {
-            "type": "calc_number_add",
-            "nodes": [
-              {
-                "type": "query",
-                "query": "progress.current_time",
-                "object": {
-                  "identifier": 0,
-                  "convert_witness": 100
-                },
-                "parameters": []
+      "type": "logic_as_u256_greater",
+      "nodes": [
+        {
+          "type": "context",
+          "context": "Clock"
+        },
+        {
+          "type": "calc_number_add",
+          "nodes": [
+            {
+              "type": "query",
+              "query": 1272,
+              "object": {
+                "identifier": 0,
+                "convert_witness": 100
               },
-              {
-                "type": "identifier",
-                "identifier": 1
-              }
-            ]
-          }
-        ]
-      }
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 1
+            }
+          ]
+        }
+      ]
     }
   },
   "env": {
@@ -221,10 +225,10 @@ clock > progress.current_time + 1000
 
 | identifier | b_submission | value_type | value | Purpose |
 |------------|-------------|-----------|-------|---------|
-| 0 | **true** | Address | 0x0...0 (placeholder) | Order ID submitted at runtime, converted to Progress via convert_witness |
-| 1 | false | U64 | 1000 | Time-lock duration in ms (1 second for testing) |
+| 0 | **true** | Address | (submitted at runtime) | Order ID submitted at runtime, converted to Progress via convert_witness |
+| 1 | false | U64 | 10000 | Time-lock duration in ms (10 seconds for testing) |
 
-> **Important**: `1000` ms (1 second) is for testing only. In production, set to a reasonable duration (e.g., 8 hours = 28800000 ms).
+> **Important**: `10000` ms (10 seconds) is for testing only. In production, set to a reasonable duration (e.g., 8 hours = 28800000 ms).
 
 ---
 
@@ -260,25 +264,22 @@ Create a Guard that allows the insurance provider to withdraw funds after the or
       }
     ],
     "root": {
-      "type": "node",
-      "node": {
-        "type": "logic_equal",
-        "nodes": [
-          {
-            "type": "query",
-            "query": "progress.current",
-            "object": {
-              "identifier": 0,
-              "convert_witness": 100
-            },
-            "parameters": []
+      "type": "logic_equal",
+      "nodes": [
+        {
+          "type": "query",
+          "query": 1253,
+          "object": {
+            "identifier": 0,
+            "convert_witness": 100
           },
-          {
-            "type": "identifier",
-            "identifier": 1
-          }
-        ]
-      }
+          "parameters": []
+        },
+        {
+          "type": "identifier",
+          "identifier": 1
+        }
+      ]
     }
   },
   "env": {
@@ -292,7 +293,12 @@ Create a Guard that allows the insurance provider to withdraw funds after the or
 
 ## Step 4: Create, Configure and Publish Machine
 
-Create a Machine with workflow nodes and publish it in a single transaction. **IMPORTANT**: Machine nodes must be added during creation (in the same transaction) before publishing. Adding nodes after creation in separate transactions may not persist correctly.
+Create a Machine with workflow nodes and publish it in a single transaction.
+
+> **IMPORTANT**: 
+> - Machine nodes are added during creation in the same transaction
+> - Once published, Machine nodes become immutable and cannot be modified
+> - If you need to change nodes after publishing, you must create a new Machine
 
 **Prompt**: Create a Machine named "insurance_machine" with the claim processing workflow and publish it.
 
@@ -364,13 +370,16 @@ Create a Machine with workflow nodes and publish it in a single transaction. **I
 
 ---
 
-## Step 7: Create and Publish Service
+## Step 5: Create and Publish Service
 
 Create the insurance service with machine, order_allocators, sales, and publish in a single transaction.
 
-> **Important**: Service must include `order_allocators` when publishing. After publishing, `machine`, `order_allocators`, and `arbitrations` become immutable.
+> **Important**: 
+> - Service must include `order_allocators` when publishing
+> - After publishing, `machine`, `order_allocators`, and `arbitrations` become immutable
+> - Ensure the Machine is properly configured before creating the Service
 
-**Prompt**: Create and publish a Service named "insurance_service" with machine, order allocation, and insurance product.
+**Prompt**: Create and publish a Service named "insurance_service_v1" with machine, order allocation, and insurance product.
 
 ```json
 {
@@ -422,19 +431,23 @@ Create the insurance service with machine, order_allocators, sales, and publish
 }
 ```
 
+> **Important**: 
+> - `mode: "Rate"` represents Rate allocation mode (valid values: `"Amount"`, `"Rate"`, `"Surplus"`)
+> - `who: {"Signer": "signer"}` represents the transaction signer
+
 ---
 
-## Step 8: Unpause Service
+## Step 6: Unpause Service
 
 Unpause the service to allow order creation.
 
-**Prompt**: Unpause "insurance_service".
+**Prompt**: Unpause "insurance_service_v1".
 
 ```json
 {
   "operation_type": "service",
   "data": {
-    "object": "insurance_service",
+    "object": "insurance_service_v1",
     "pause": false
   },
   "env": {
@@ -446,34 +459,35 @@ Unpause the service to allow order creation.
 
 ---
 
-## Step 9: Verify Service Configuration
+## Step 7: Verify Service Configuration
 
 Query the service to verify all configurations are correct.
 
-**Prompt**: Query "insurance_service" to verify configuration.
+**Prompt**: Query "insurance_service_v1" to verify configuration.
 
 ```json
 {
   "query_type": "onchain_objects",
-  "objects": ["insurance_service"]
+  "objects": ["insurance_service_v1"],
+  "network": "testnet"
 }
 ```
 
 ---
 
-## Step 10: Test Order Creation and Progress
+## Step 8: Test Order Creation and Progress
 
-### 10.1 Create Insurance Order
+### 8.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.
 
-**Prompt**: Create an order on "insurance_service" using account "insurance_provider".
+**Prompt**: Create an order on "insurance_service_v1" using account "insurance_provider_v1".
 
 ```json
 {
   "operation_type": "service",
   "data": {
-    "object": "insurance_service",
+    "object": "insurance_service_v1",
     "order_new": {
       "buy": {
         "items": [
@@ -500,7 +514,18 @@ Create an order on the insurance service using the `order_new` field of the `ser
 }
 ```
 
-### 10.2 Advance Progress: Initial -> Start
+> **Get the Progress ID**: After creating the order, query it to obtain the Progress object ID needed for the next steps:
+> ```json
+> {
+>   "query_type": "onchain_objects",
+>   "objects": ["test_insurance_order_v1"],
+>   "network": "testnet",
+>   "no_cache": true
+> }
+> ```
+> The response includes a `progress` field containing the Progress object ID, and an `allocation` field containing the Allocation object ID.
+
+### 8.2 Advance Progress: Initial -> Start
 
 First, advance the progress from initial state to Start node.
 
@@ -525,11 +550,22 @@ First, advance the progress from initial state to Start node.
 }
 ```
 
-### 10.3 Advance Progress: Start -> Complete
+> **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
+
+### 8.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.
 
-Wait at least 1 second after entering Start node, then advance the progress to Complete with the Order ID as submission.
+> **Two-Phase Submission Loop**: When a forward has a Guard that requires user submission (`b_submission: true`), the MCP server uses a two-phase approach:
+> 
+> **Phase 1**: Call WITHOUT the `submission` field at root level. The server will return a `submission` prompt containing the Guard addresses and submission structure that needs to be filled.
+> 
+> **Phase 2**: Call WITH the `submission` field at root level, populated with the `value` fields from the Phase 1 prompt. The prompt shows which `identifier` expects a value of which `value_type`.
 
-**Prompt**: Advance progress to Complete, submitting the Order ID. Wait 1 second before executing.
+**Phase 1 Prompt**: Call progress operation WITHOUT `submission` field.
 
 ```json
 {
@@ -546,49 +582,141 @@ Wait at least 1 second after entering Start node, then advance the progress to C
   "env": {
     "account": "insurance_provider_v1",
     "network": "testnet"
+  }
+}
+```
+
+The server will return a `submission` prompt like:
+
+```json
+{
+  "type": "submission",
+  "guard": [
+    { "object": "0x1508ded8...", "impack": true }
+  ],
+  "submission": [
+    {
+      "guard": "0x1508ded8...",
+      "submission": [
+        {
+          "identifier": 0,
+          "b_submission": true,
+          "value_type": "Address",
+          "name": "Order ID (submitted at runtime)",
+          "object_type": "Order"
+        }
+      ]
+    }
+  ]
+}
+```
+
+> **Note**: The Phase 1 response returns `value_type` as a numeric enum ID (e.g., `1` = Address). When filling in Phase 2, you can use either the numeric form (`1`) or the string name (`"Address"`) — both are accepted.
+
+**Phase 2**: Fill in the `value` field with the Order ID and resubmit. The `submission` field must be placed at the **root level** of the request (sibling to `operation_type`, `data`, and `env`).
+
+```json
+{
+  "operation_type": "progress",
+  "data": {
+    "object": "<insurance_progress_id>",
+    "operate": {
+      "operation": {
+        "next_node_name": "Complete",
+        "forward": "complete_claim"
+      }
+    }
   },
   "submission": {
     "type": "submission",
     "guard": [
       {
-        "object": "insurance_complete_guard_v1",
+        "object": "0x1508ded8...",
         "impack": true
       }
     ],
     "submission": [
       {
-        "guard": "insurance_complete_guard_v1",
+        "guard": "0x1508ded8...",
         "submission": [
           {
             "identifier": 0,
             "b_submission": true,
             "value_type": "Address",
+            "name": "Order ID (submitted at runtime)",
+            "object_type": "Order",
             "value": "<insurance_order_id>"
           }
         ]
       }
     ]
+  },
+  "env": {
+    "account": "insurance_provider_v1",
+    "network": "testnet"
+  }
+}
+```
+
+> **⚠️ 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.
+> - Both `next_node_name` and `forward` fields are required in the operation object.
+> - Use simple forward name `"complete_claim"` without node prefix.
+
+---
+
+## Troubleshooting
+
+### MoveAbort code: 7 (Guard Verification Failed)
+
+When advancing Progress, if you get `abort code: 7 (Verify failed)`, the Guard condition was not satisfied. For the time-lock Guard:
+- 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
+
+### Forward validation failed
+
+If you see `Connection from current node "" to target node "Complete" does not exist`, use simple forward names without node prefix:
+- ✅ Correct: `"forward": "start_claim"`
+- ❌ Incorrect: `"forward": "Start.start_claim"`
+
+### Missing required field 'next_node_name'
+
+The progress operation requires both `next_node_name` and `forward` fields in the operation object:
+```json
+{
+  "operation": {
+    "next_node_name": "Start",
+    "forward": "start_claim"
   }
 }
 ```
 
-> **Note**: Replace `<insurance_progress_id>` and `<insurance_order_id>` with actual values from step 10.1.
+### Data not found / stale data
+
+If queries return old data after successful transactions:
+- Use `no_cache: true` parameter for critical queries
+- Wait for transaction confirmation before the next operation
+
+### Machine modification failed
+
+Published Machine nodes are immutable (`MoveAbort code: 3`). Create a new Machine with the correct configuration if changes are needed.
 
 ---
 
 ## Execution Checklist
 
-- [ ] Create `insurance_provider` account
-- [ ] Get test tokens for `insurance_provider`
-- [ ] Step 1: Create `insurance_permission`
-- [ ] Step 2: Create `insurance_complete_guard`
-- [ ] Step 3: Create `insurance_withdraw_guard`
-- [ ] Step 4: Create `insurance_machine` (without nodes)
-- [ ] Step 5: Add nodes to Machine (Start, Complete)
-- [ ] Step 6: Publish Machine
-- [ ] Step 7: Create and publish `insurance_service` (with machine, order_allocators, sales)
-- [ ] Step 8: Unpause Service
-- [ ] Step 9: Verify Service configuration
-- [ ] Step 10.1: Create test insurance order
-- [ ] Step 10.2: Advance progress Initial -> Start
-- [ ] Step 10.3: Wait 1s, then advance progress Start -> Complete
+- [ ] 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)