@wowok/skills 1.1.13 → 1.2.2

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 |
@@ -443,7 +452,7 @@ Before creating the Service, create Guards that validate fund allocation conditi
 
 #### 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.
 
@@ -453,41 +462,91 @@ 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
+            }
+          ]
         }
       ]
     }
@@ -500,14 +559,19 @@ Create a Guard that validates the order's Progress has reached the "Completed" n
 }
 ```
 
-**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.
 
 #### 5.2 Create Refund Guard (Customer Refund)
 
@@ -521,41 +585,88 @@ 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": "logic_equal",
+          "nodes": [
+            {
+              "type": "context",
+              "context": "Signer"
+            },
+            {
+              "type": "query",
+              "query": "order.owner",
+              "object": {
+                "identifier": 0
+              },
+              "parameters": []
+            }
+          ]
         },
         {
-          "type": "identifier",
-          "identifier": 1
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": "order.service",
+              "object": {
+                "identifier": 0
+              },
+              "parameters": []
+            },
+            {
+              "type": "identifier",
+              "identifier": 2
+            }
+          ]
         }
       ]
     }
@@ -568,6 +679,19 @@ Create a Guard for customer refunds when order is cancelled.
 }
 ```
 
+**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 6: Create Service (Store)
@@ -588,9 +712,15 @@ 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.