@wowok/skills 1.1.9 → 1.1.11

package/examples/ThreeBody_Signature/ThreeBody_Signature.md

@@ -8,7 +8,7 @@ A complete example demonstrating how to create a service for book signing by the
 
 This example demonstrates:
 
- **Service with Buy Guard**: The buy_guard allows you to define various conditions for users to purchase products, such as identity verification, completing KYC, or being on an allowlist. In this example, only the service creator (author) can purchase this service
+**Service with Buy Guard**: The buy_guard allows you to define various conditions for users to purchase products, such as identity verification, completing KYC, or being on an allowlist. In this example, only the service creator (author) can purchase this service.
 
 ### Key Design Decisions
 
@@ -33,17 +33,45 @@ Before running this example, ensure you have:
 {
   "query_type": "account_balance",
   "name_or_address": "three_body_author",
+  "balance": true,
   "network": "testnet"
 }
 ```
 
-**Actual Result**:
+**Expected Result** (if account has balance):
 ```json
 {
-  "address": "0xda123833e96e734815f2f57d52ad463681635c6678cfe113c77dbeee49d7865c",
+  "address": "0x...",
   "balance": {
     "coinType": "0x2::wow::WOW",
-    "totalBalance": "4904827524"
+    "totalBalance": "1000000000"
+  }
+}
+```
+
+**If no balance, use Faucet**:
+
+**Request**:
+```json
+{
+  "faucet": {
+    "network": "testnet",
+    "name_or_address": "three_body_author"
+  }
+}
+```
+
+**Expected Result**:
+```json
+{
+  "faucet": {
+    "name_or_address": "three_body_author",
+    "result": [
+      {"amount": 1000000000, "id": "0x..."},
+      {"amount": 1000000000, "id": "0x..."},
+      {"amount": 1000000000, "id": "0x..."}
+    ],
+    "network": "testnet"
   }
 }
 ```
@@ -60,10 +88,10 @@ Create a Permission object to manage the service.
   "operation_type": "permission",
   "data": {
     "object": {
-      "name": "three_body_permission_v2",
+      "name": "three_body_permission",
       "replaceExistName": true
     },
-    "description": "Permission for Three-Body Signature Service v2",
+    "description": "Permission for Three-Body Signature Service",
     "table": {
       "op": "add perm by entity",
       "entity": {"name_or_address": "three_body_author"},
@@ -77,12 +105,12 @@ Create a Permission object to manage the service.
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Permission",
-  "object": "0xf939b4be49761ef8c30ff19ee874157e2ba1d83ab3a8de4f310443e588d1df99",
-  "version": "2195623",
+  "object": "0x...",
+  "version": "...",
   "change": "created"
 }]
 ```
@@ -99,7 +127,7 @@ Create a Guard that verifies the buyer is the service creator (author). This ens
   "operation_type": "guard",
   "data": {
     "namedNew": {
-      "name": "three_body_buy_guard_v2",
+      "name": "three_body_buy_guard",
       "tags": ["signature", "book", "buy-guard"],
       "replaceExistName": true
     },
@@ -109,25 +137,22 @@ Create a Guard that verifies the buyer is the service creator (author). This ens
         "identifier": 0,
         "b_submission": false,
         "value_type": "Address",
-        "value": "0xda123833e96e734815f2f57d52ad463681635c6678cfe113c77dbeee49d7865c",
-        "name": "author_address"
+        "value": "three_body_author",
+        "name": "Author address"
       }
     ],
     "root": {
-      "type": "node",
-      "node": {
-        "type": "logic_equal",
-        "nodes": [
-          {
-            "type": "context",
-            "context": "Signer"
-          },
-          {
-            "type": "identifier",
-            "identifier": 0
-          }
-        ]
-      }
+      "type": "logic_equal",
+      "nodes": [
+        {
+          "type": "context",
+          "context": "Signer"
+        },
+        {
+          "type": "identifier",
+          "identifier": 0
+        }
+      ]
     }
   },
   "env": {
@@ -137,12 +162,14 @@ Create a Guard that verifies the buyer is the service creator (author). This ens
 }
 ```
 
-**Actual Result**:
+> **Note**: The Guard uses a `table` to define constant values with identifiers, then references them in the `root` logic using `identifier` node type. The `root` is a direct GuardNode (no wrapper).
+
+**Expected Result**:
 ```json
 [{
   "type": "Guard",
-  "object": "0x2fc0283e55f4322eb602a5370b32e455597e339c74a23ada5d9a4a82f02f7925",
-  "version": "2195993",
+  "object": "0x...",
+  "version": "...",
   "change": "created"
 }]
 ```
@@ -161,11 +188,11 @@ Create a Machine to define the service workflow: Book Delivery → Signature Com
   "operation_type": "machine",
   "data": {
     "object": {
-      "name": "three_body_machine_v2",
-      "permission": "three_body_permission_v2",
+      "name": "three_body_machine",
+      "permission": "three_body_permission",
       "replaceExistName": true
     },
-    "description": "Three-Body signature service workflow v2: Book Delivery -> Signature Completion",
+    "description": "Three-Body signature service workflow: Book Delivery -> Signature Completion",
     "node": {
       "op": "add",
       "nodes": [
@@ -212,18 +239,16 @@ Create a Machine to define the service workflow: Book Delivery → Signature Com
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Machine",
-  "object": "0x8e7e1c3f173c9e2203ca2e1e50b4c634dd1cef06d248ac50e35749adf7499411",
-  "version": "2196424",
+  "object": "0x...",
+  "version": "...",
   "change": "created"
 }]
 ```
 
-
-
 ---
 
 ## Step 4: Create Service (Unpublished)
@@ -236,12 +261,12 @@ Create the Three-Body signature service without publishing. The Service must be
   "operation_type": "service",
   "data": {
     "object": {
-      "name": "three_body_signature_service_v2",
+      "name": "three_body_signature_service",
       "type_parameter": "0x2::wow::WOW",
-      "permission": "three_body_permission_v2",
+      "permission": "three_body_permission",
       "replaceExistName": true
     },
-    "description": "Three-Body author book signature service v2. Provide a message up to 10 characters, and the author will sign your book. Process: 1.Book Delivery 2.Signature Completion. Fee: 888.",
+    "description": "Three-Body author book signature service. Provide a message up to 10 characters, and the author will sign your book. Process: 1.Book Delivery 2.Signature Completion. Fee: 888.",
     "publish": false
   },
   "env": {
@@ -251,12 +276,12 @@ Create the Three-Body signature service without publishing. The Service must be
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Service",
-  "object": "0x140e91943775592736f587e596afce7d28f41fee1593f8dfbc2f04d852e5d45c",
-  "version": "2198123",
+  "object": "0x...",
+  "version": "...",
   "change": "created"
 }]
 ```
@@ -272,8 +297,8 @@ Bind the published Machine to the Service. **Important**: The Service must be un
 {
   "operation_type": "service",
   "data": {
-    "object": "three_body_signature_service_v2",
-    "machine": "three_body_machine_v2"
+    "object": "three_body_signature_service",
+    "machine": "three_body_machine"
   },
   "env": {
     "account": "three_body_author",
@@ -282,24 +307,16 @@ Bind the published Machine to the Service. **Important**: The Service must be un
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Service",
-  "object": "0x140e91943775592736f587e596afce7d28f41fee1593f8dfbc2f04d852e5d45c",
-  "version": "2198329",
+  "object": "0x...",
+  "version": "...",
   "change": "mutated"
 }]
 ```
 
-**Verification** (with no_cache: true):
-```json
-{
-  "machine": "0x8e7e1c3f173c9e2203ca2e1e50b4c634dd1cef06d248ac50e35749adf7499411",
-  "bPublished": false
-}
-```
-
 ---
 
 ## Step 6: Set Buy Guard
@@ -311,8 +328,8 @@ Configure the Buy Guard to restrict purchases to the author only.
 {
   "operation_type": "service",
   "data": {
-    "object": "three_body_signature_service_v2",
-    "buy_guard": "three_body_buy_guard_v2"
+    "object": "three_body_signature_service",
+    "buy_guard": "three_body_buy_guard"
   },
   "env": {
     "account": "three_body_author",
@@ -321,12 +338,12 @@ Configure the Buy Guard to restrict purchases to the author only.
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Service",
-  "object": "0x140e91943775592736f587e596afce7d28f41fee1593f8dfbc2f04d852e5d45c",
-  "version": "2203786",
+  "object": "0x...",
+  "version": "...",
   "change": "mutated"
 }]
 ```
@@ -342,13 +359,13 @@ Set up fund allocation: 100% to the author upon order completion.
 {
   "operation_type": "service",
   "data": {
-    "object": "three_body_signature_service_v2",
+    "object": "three_body_signature_service",
     "order_allocators": {
       "description": "Three-Body signature service fund allocation - 100% to author",
       "threshold": 0,
       "allocators": [
         {
-          "guard": "three_body_buy_guard_v2",
+          "guard": "three_body_buy_guard",
           "sharing": [
             {
               "who": {
@@ -370,12 +387,12 @@ Set up fund allocation: 100% to the author upon order completion.
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Service",
-  "object": "0x140e91943775592736f587e596afce7d28f41fee1593f8dfbc2f04d852e5d45c",
-  "version": "2203787",
+  "object": "0x...",
+  "version": "...",
   "change": "mutated"
 }]
 ```
@@ -391,7 +408,7 @@ Add sales items and publish the service to make it available for orders.
 {
   "operation_type": "service",
   "data": {
-    "object": "three_body_signature_service_v2",
+    "object": "three_body_signature_service",
     "sales": {
       "op": "add",
       "sales": [
@@ -414,12 +431,12 @@ Add sales items and publish the service to make it available for orders.
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Service",
-  "object": "0x140e91943775592736f587e596afce7d28f41fee1593f8dfbc2f04d852e5d45c",
-  "version": "2205976",
+  "object": "0x...",
+  "version": "...",
   "change": "mutated"
 }]
 ```
@@ -435,7 +452,7 @@ Unpause the service to allow order creation.
 {
   "operation_type": "service",
   "data": {
-    "object": "three_body_signature_service_v2",
+    "object": "three_body_signature_service",
     "pause": false
   },
   "env": {
@@ -445,12 +462,12 @@ Unpause the service to allow order creation.
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 [{
   "type": "Service",
-  "object": "0x140e91943775592736f587e596afce7d28f41fee1593f8dfbc2f04d852e5d45c",
-  "version": "2205975",
+  "object": "0x...",
+  "version": "...",
   "change": "mutated"
 }]
 ```
@@ -465,18 +482,18 @@ Query the service to verify all configurations.
 ```json
 {
   "query_type": "onchain_objects",
-  "objects": ["three_body_signature_service_v2"],
+  "objects": ["three_body_signature_service"],
   "no_cache": true,
   "network": "testnet"
 }
 ```
 
-**Actual Result**:
+**Expected Result**:
 ```json
 {
-  "object": "0x140e91943775592736f587e596afce7d28f41fee1593f8dfbc2f04d852e5d45c",
+  "object": "three_body_signature_service",
   "type": "Service",
-  "description": "Three-Body author book signature service v2. Provide a message up to 10 characters, and the author will sign your book. Process: 1.Book Delivery 2.Signature Completion. Fee: 888.",
+  "description": "Three-Body author book signature service. Provide a message up to 10 characters, and the author will sign your book. Process: 1.Book Delivery 2.Signature Completion. Fee: 888.",
   "sales": [
     {
       "name": "Three-Body Book Signature",
@@ -487,12 +504,12 @@ Query the service to verify all configurations.
       "wip_hash": ""
     }
   ],
-  "buy_guard": "0x2fc0283e55f4322eb602a5370b32e455597e339c74a23ada5d9a4a82f02f7925",
-  "machine": "0x8e7e1c3f173c9e2203ca2e1e50b4c634dd1cef06d248ac50e35749adf7499411",
+  "buy_guard": "three_body_buy_guard",
+  "machine": "three_body_machine",
   "bPublished": true,
   "bPaused": false,
   "customer_required": ["phone", "email", "shipping_address"],
-  "permission": "0xf939b4be49761ef8c30ff19ee874157e2ba1d83ab3a8de4f310443e588d1df99"
+  "permission": "three_body_permission"
 }
 ```
 
@@ -509,7 +526,7 @@ The author (`three_body_author`) should be able to purchase the service.
 {
   "operation_type": "service",
   "data": {
-    "object": "three_body_signature_service_v2",
+    "object": "three_body_signature_service",
     "order_new": {
       "buy": {
         "items": [
@@ -524,11 +541,15 @@ The author (`three_body_author`) should be able to purchase the service.
         }
       },
       "namedNewOrder": {
-        "name": "three_body_order_v2",
+        "name": "three_body_order",
         "replaceExistName": true
       },
       "namedNewProgress": {
-        "name": "three_body_progress_v2",
+        "name": "three_body_progress",
+        "replaceExistName": true
+      },
+      "namedNewAllocation": {
+        "name": "three_body_allocation",
         "replaceExistName": true
       }
     }
@@ -540,6 +561,30 @@ The author (`three_body_author`) should be able to purchase the service.
 }
 ```
 
+**Expected Result**:
+```json
+[
+  {
+    "type": "Progress",
+    "object": "three_body_progress",
+    "version": "...",
+    "change": "created"
+  },
+  {
+    "type": "Order",
+    "object": "three_body_order",
+    "version": "...",
+    "change": "created"
+  },
+  {
+    "type": "Allocation",
+    "object": "three_body_allocation",
+    "version": "...",
+    "change": "created"
+  }
+]
+```
+
 ---
 
 ### Test 2: Non-Author Purchase (Should Fail)
@@ -551,7 +596,7 @@ Any other account attempting to purchase should fail with Buy Guard verification
 {
   "operation_type": "service",
   "data": {
-    "object": "three_body_signature_service_v2",
+    "object": "three_body_signature_service",
     "order_new": {
       "buy": {
         "items": [
@@ -568,12 +613,19 @@ Any other account attempting to purchase should fail with Buy Guard verification
     }
   },
   "env": {
-    "account": "myshop_customer",
+    "account": "three_body_customer",
     "network": "testnet"
   }
 }
 ```
 
+**Expected Result** (Error):
+```json
+{
+  "error": "Transaction resolution failed: MoveAbort in 8th command, abort code: 7 (Verify failed), in '0x2::passport::result_for_guard'"
+}
+```
+
 ---
 
 ## Workflow Execution
@@ -589,10 +641,12 @@ The author confirms the book has been delivered.
 {
   "operation_type": "progress",
   "data": {
-    "object": "three_body_progress_v2",
-    "forward": {
-      "forward": "Confirm Delivery",
-      "namedOperator": ""
+    "object": "three_body_progress",
+    "operate": {
+      "operation": {
+        "next_node_name": "Book Delivered",
+        "forward": "Confirm Delivery"
+      }
     }
   },
   "env": {
@@ -602,28 +656,53 @@ The author confirms the book has been delivered.
 }
 ```
 
+**Expected Result**:
+```json
+[{
+  "type": "Progress",
+  "object": "three_body_progress",
+  "version": "...",
+  "change": "mutated"
+}]
+```
+
 ### Node 2: Signature Completed
 
 The author completes the signature.
 
+> **Important**: Use `no_cache: true` in the `env` for sequential Progress operations on the same object. This ensures the SDK reads the latest on-chain state (including the updated `current` node) instead of using a cached version.
+
 **Request**:
 ```json
 {
   "operation_type": "progress",
   "data": {
-    "object": "three_body_progress_v2",
-    "forward": {
-      "forward": "Complete Signature",
-      "namedOperator": ""
+    "object": "three_body_progress",
+    "operate": {
+      "operation": {
+        "next_node_name": "Signature Completed",
+        "forward": "Complete Signature"
+      }
     }
   },
   "env": {
     "account": "three_body_author",
-    "network": "testnet"
+    "network": "testnet",
+    "no_cache": true
   }
 }
 ```
 
+**Expected Result**:
+```json
+[{
+  "type": "Progress",
+  "object": "three_body_progress",
+  "version": "...",
+  "change": "mutated"
+}]
+```
+
 ---
 
 ## Summary
@@ -635,17 +714,17 @@ This example demonstrates:
 3. **WIP Files Optional**: Sales items can use WIP files or empty strings
 4. **Service Configuration**: Complete setup from creation to publication
 
-### Key Object IDs (Actual)
+### Key Objects
 
-| Object | Name | ID | Version |
-|--------|------|-----|---------|
-| Permission | three_body_permission_v2 | `0xf939b4...1df99` | 2195623 |
-| Buy Guard | three_body_buy_guard_v2 | `0x2fc028...f7925` | 2195993 |
-| Machine | three_body_machine_v2 | `0x8e7e1c...99411` | 2196424 |
-| Service | three_body_signature_service_v2 | `0x140e91...e5d45c` | 2205976 |
-| Order | three_body_order_v2 | `0x7684ab...3f35d49` | 2209290 |
-| Allocation | three_body_allocation_v2 | `0xd6f2da...99e00` | 2209290 |
-| Progress | three_body_progress_v2 | `0x97ef34...d935d9` | 2209290 |
+| Object | Name |
+|--------|------|
+| Permission | three_body_permission |
+| Buy Guard | three_body_buy_guard |
+| Machine | three_body_machine |
+| Service | three_body_signature_service |
+| Order | three_body_order |
+| Allocation | three_body_allocation |
+| Progress | three_body_progress |
 
 ---
 
@@ -673,104 +752,18 @@ The two-node workflow provides clear tracking:
 
 Each node transition requires the author's confirmation, ensuring accountability.
 
----
-
-## Execution Experience & Best Practices
-
-### 1. Naming Strategy (Critical!)
-
-**Always establish naming conventions first** :
-
-- **Example**: Use consistent suffixes or no suffixes at all
-  - Good: `three_body_permission_v2`, `three_body_buy_guard_v2`, `three_body_machine_v2`
-  - Good: All names follow the same pattern
-  - Provide naming rules for AI to manage object names automatically; avoid conflicts with other naming conventions such as version/timestamp/random numbers for unique names
-  - Strongly recommend using the `replaceExistName` method in `LocalMarkOperationSchema` to enforce name usage (even if already exists)
-  - All operations use names instead of addresses (much easier!)
-  - Local marks map names to addresses automatically
-  - Easier to read, test, and document
-
-**Recommendation**:
-1. Decide on naming before starting
-2. Stick to it throughout the entire workflow
-3. Document your naming pattern in the test results
-
-### 2. Execution Order Matters (Critical!)
-
-**Publish operations lock objects** - plan carefully:
-
-#### Correct Order (Must Follow!)
-1. **Permission** first - foundation for all other objects
-2. **Machine** - create workflow before service
-3. **Service (unpublished)** - get address for Guards
-4. **Guards** - need Service address for verification logic
-5. **Configure Service** - add machine, buy_guard, order_allocators
-6. **Publish Service** - LAST! Once published, many changes are blocked
-
-### 3. Guard Creation Tips
-
-**Guards often depend on other objects**:
-- Buy Guards: May reference Service address
-- Progress Guards: May need Machine or Service information
-- Order Allocator Guards: Should be created before Service publish
-
-**Best Practice**:
-1. Create empty Service with name first (unpublished)
-2. Create all required Guards using that name
-3. Configure Service with Guards
-4. Publish Service
-
-### 4. Machine Workflow Setup
-
-**Machine nodes require permission indexes**:
-- If you use permissionIndex, make sure they exist!
-- Create permission indexes before adding machine nodes
-
-**Machine Publish**:
-- Must publish Machine before binding to Service
-- Published Machine can still have nodes added/modified
-
-### 5. Service Configuration Flow
-
-**Configure everything before publishing**:
-```
-Service Created (unpublished)
-    ↓
-Add Sales Items
-    ↓
-Bind Machine
-    ↓
-Set Buy Guard
-    ↓
-Configure Order Allocators
-    ↓
-Set Arbitration (if needed)
-    ↓
-PUBLISH (LAST STEP!)
-```
-
-### 6. Testing Strategy
-
-**Test incrementally, not all at once**:
-1. Test each step as you go
-2. Verify object creation with queries
-3. Don't proceed to next step until current one is verified
-4. Keep track of all object IDs in a test results file
-
-### 7. Common Pitfalls to Avoid
-
-1. **Price Units**: WOW tokens use 9 decimals, but testnet examples often use simple numbers (888 tokens)
-2. **Local Marks**: Verify objects exist with `local_mark_list` queries
-3. **Account Balance**: Always check balance before starting - gas fees add up!
+### Best Practices
 
-### 8. Let AI Manage Object Naming for You
+1. **Naming Strategy**: Use consistent naming conventions and `replaceExistName: true` to enforce name usage. All operations use names instead of addresses for readability.
 
-### 9. Query Toolkit is Your Best Friend
+2. **Execution Order Matters**: Publish operations lock objects. Follow this order:
+   - Permission first (foundation)
+   - Machine (create workflow before service)
+   - Service (unpublished)
+   - Guards (need Service address for verification logic)
+   - Configure Service (add machine, buy_guard, order_allocators)
+   - Publish Service (LAST - once published, many changes are blocked)
 
-**Use queries constantly**:
-- Verify objects exist
-- Check configurations
-- Debug issues
-- Confirm state changes
+3. **Use `no_cache: true` for Sequential Operations**: When performing multiple operations on the same object in sequence (especially Progress workflow advancement), always set `no_cache: true` in the `env` to ensure the SDK reads the latest on-chain state.
 
-The `query_toolkit` and `onchain_table_data` are essential for validating every step of the way.
+4. **Query Toolkit is Your Best Friend**: Use queries constantly to verify objects exist, check configurations, debug issues, and confirm state changes.