@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/schemas/guard-templates.json

@@ -0,0 +1,379 @@
+{
+  "$schema": "https://wowok.net/schemas/guard-templates.json",
+  "version": "1.0.0",
+  "description": "Guard creation templates for common validation patterns. Each template is a complete CallGuard_Data object that can be used as-is or customized. Use schema_query action='get_guard_templates' to retrieve these templates.",
+  "templates": [
+    {
+      "name": "signer_verification",
+      "title": "Signer Verification Guard",
+      "description": "Verifies that the transaction signer matches a specific address stored in the Guard table. Simplest possible Guard — use as a starting point.",
+      "use_case": "Only a specific account (e.g., the merchant) can perform an action. Common for Service buy_guard, Machine forward guard, Reward claim guard.",
+      "binding_hint": {
+        "action": "buy",
+        "host_object": "Service",
+        "binding_field": "buy_guard",
+        "rule_sentence": "Only the specified address can perform this action.",
+        "failure_conditions": ["Signer does not match the stored address."],
+        "circular_reference": false
+      },
+      "template": {
+        "namedNew": {
+          "name": "guard_signer_verification",
+          "replaceExistName": false
+        },
+        "description": "Verify signer matches the address stored at identifier 0 in the table.",
+        "table": [
+          {
+            "identifier": 0,
+            "b_submission": false,
+            "name": "allowed_address",
+            "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
+            "value_type": "Address"
+          }
+        ],
+        "root": {
+          "type": "logic_equal",
+          "nodes": [
+            { "type": "context", "context": "Signer" },
+            { "type": "identifier", "identifier": 0 }
+          ]
+        }
+      },
+      "customization": {
+        "table[0].value": "Replace with the allowed address (0x + 64 hex chars).",
+        "namedNew.name": "Set a unique Guard name.",
+        "namedNew.replaceExistName": "Set true to overwrite an existing Guard with the same name."
+      }
+    },
+    {
+      "name": "progress_node_check",
+      "title": "Progress Node Check Guard",
+      "description": "Verifies that an Order's Progress is at a specific node. Uses convert_witness=100 (TypeOrderProgress) to access the submitted Order's Progress data.",
+      "use_case": "Allow an action only when the order is at a specific workflow node (e.g., 'Completed' for refunds, 'Delivered' for reward claims). Common for Allocation guard, Reward claim guard.",
+      "binding_hint": {
+        "action": "allocate",
+        "host_object": "Service",
+        "binding_field": "order_allocators",
+        "rule_sentence": "The order must be at the specified progress node.",
+        "failure_conditions": ["Order is not at the expected progress node."],
+        "circular_reference": false
+      },
+      "template": {
+        "namedNew": {
+          "name": "guard_progress_node_check",
+          "replaceExistName": false
+        },
+        "description": "Verify order progress is at the node name stored at identifier 1.",
+        "table": [
+          {
+            "identifier": 0,
+            "b_submission": true,
+            "name": "submitted_order",
+            "value_type": "Address"
+          },
+          {
+            "identifier": 1,
+            "b_submission": false,
+            "name": "expected_node_name",
+            "value": "Completed",
+            "value_type": "String"
+          }
+        ],
+        "root": {
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": 1253,
+              "object": { "identifier": 0, "convert_witness": 100 },
+              "parameters": []
+            },
+            { "type": "identifier", "identifier": 1 }
+          ]
+        }
+      },
+      "customization": {
+        "table[1].value": "Replace 'Completed' with the expected node name.",
+        "table[0].value_type": "Address — the submitted order address (b_submission=true).",
+        "namedNew.name": "Set a unique Guard name."
+      }
+    },
+    {
+      "name": "order_owner_verification",
+      "title": "Order Owner Verification Guard",
+      "description": "Verifies that the transaction signer is the owner of the submitted Order. Uses query=1562 (order.owner) to dynamically fetch the owner.",
+      "use_case": "Only the order owner can trigger a refund or claim. Prevents fund theft — even if someone else knows the order ID, they cannot claim funds.",
+      "binding_hint": {
+        "action": "allocate",
+        "host_object": "Service",
+        "binding_field": "order_allocators",
+        "rule_sentence": "Only the order owner can trigger this allocation.",
+        "failure_conditions": ["Signer is not the order owner."],
+        "circular_reference": false
+      },
+      "template": {
+        "namedNew": {
+          "name": "guard_order_owner_verification",
+          "replaceExistName": false
+        },
+        "description": "Verify signer is the owner of the submitted order (identifier 0).",
+        "table": [
+          {
+            "identifier": 0,
+            "b_submission": true,
+            "name": "submitted_order",
+            "value_type": "Address"
+          }
+        ],
+        "root": {
+          "type": "logic_equal",
+          "nodes": [
+            { "type": "context", "context": "Signer" },
+            {
+              "type": "query",
+              "query": 1562,
+              "object": { "identifier": 0 },
+              "parameters": []
+            }
+          ]
+        }
+      },
+      "customization": {
+        "namedNew.name": "Set a unique Guard name."
+      }
+    },
+    {
+      "name": "service_belonging_check",
+      "title": "Service Belonging Guard",
+      "description": "Verifies that the submitted Order belongs to a specific Service. Uses query=1563 (order.service) to dynamically fetch the service address.",
+      "use_case": "Prevents cross-service theft — even if an attacker has a valid order from a different service, they cannot claim funds from THIS service's allocation. Combine with order_owner_verification for full security.",
+      "binding_hint": {
+        "action": "allocate",
+        "host_object": "Service",
+        "binding_field": "order_allocators",
+        "rule_sentence": "The order must belong to this specific service.",
+        "failure_conditions": ["Order belongs to a different service."],
+        "circular_reference": false
+      },
+      "template": {
+        "namedNew": {
+          "name": "guard_service_belonging_check",
+          "replaceExistName": false
+        },
+        "description": "Verify the submitted order's service matches the address stored at identifier 1.",
+        "table": [
+          {
+            "identifier": 0,
+            "b_submission": true,
+            "name": "submitted_order",
+            "value_type": "Address"
+          },
+          {
+            "identifier": 1,
+            "b_submission": false,
+            "name": "this_service_address",
+            "value": "0x0000000000000000000000000000000000000000000000000000000000000000",
+            "value_type": "Address"
+          }
+        ],
+        "root": {
+          "type": "logic_equal",
+          "nodes": [
+            {
+              "type": "query",
+              "query": 1563,
+              "object": { "identifier": 0 },
+              "parameters": []
+            },
+            { "type": "identifier", "identifier": 1 }
+          ]
+        }
+      },
+      "customization": {
+        "table[1].value": "Replace with THIS Service's address (0x + 64 hex chars).",
+        "namedNew.name": "Set a unique Guard name."
+      }
+    },
+    {
+      "name": "reward_not_claimed",
+      "title": "Reward Not Claimed Guard",
+      "description": "Verifies that a reward has NOT been claimed yet by the recipient. Uses query_reward_record_exists + logic_not to invert the result.",
+      "use_case": "Prevents double-claiming of rewards. Combined with progress_node_check and order_owner_verification for a complete reward guard.",
+      "binding_hint": {
+        "action": "claim_reward",
+        "host_object": "Reward",
+        "binding_field": "guard",
+        "rule_sentence": "The reward must not have been claimed yet by the recipient.",
+        "failure_conditions": ["Reward already claimed by this recipient."],
+        "circular_reference": false
+      },
+      "template": {
+        "namedNew": {
+          "name": "guard_reward_not_claimed",
+          "replaceExistName": false
+        },
+        "description": "Verify no reward record exists for the submitted recipient (identifier 1) on the submitted reward object (identifier 0).",
+        "table": [
+          {
+            "identifier": 0,
+            "b_submission": true,
+            "name": "submitted_reward_object",
+            "value_type": "Address"
+          },
+          {
+            "identifier": 1,
+            "b_submission": true,
+            "name": "submitted_recipient",
+            "value_type": "Address"
+          }
+        ],
+        "root": {
+          "type": "logic_not",
+          "node": {
+            "type": "query_reward_record_exists",
+            "object": { "identifier": 0 },
+            "recipient": { "identifier": 1 },
+            "where": {}
+          }
+        }
+      },
+      "customization": {
+        "namedNew.name": "Set a unique Guard name."
+      }
+    },
+    {
+      "name": "combined_reward_guard",
+      "title": "Combined Reward Guard (3 conditions)",
+      "description": "Complete Reward Guard combining: (1) order at expected progress node, (2) signer is order owner, (3) reward not claimed. Use logic_and to require ALL conditions.",
+      "use_case": "Production-ready Reward claim guard. Prevents fund theft, ensures workflow completion, prevents double-claiming.",
+      "binding_hint": {
+        "action": "claim_reward",
+        "host_object": "Reward",
+        "binding_field": "guard",
+        "rule_sentence": "Order must be at expected node, signer must be order owner, and reward must not be claimed.",
+        "failure_conditions": [
+          "Order is not at the expected progress node.",
+          "Signer is not the order owner.",
+          "Reward already claimed by this recipient."
+        ],
+        "circular_reference": false
+      },
+      "template": {
+        "namedNew": {
+          "name": "guard_combined_reward",
+          "replaceExistName": false
+        },
+        "description": "Combined Reward Guard: progress node check + order owner verification + reward not claimed.",
+        "table": [
+          {
+            "identifier": 0,
+            "b_submission": true,
+            "name": "submitted_order",
+            "value_type": "Address"
+          },
+          {
+            "identifier": 1,
+            "b_submission": false,
+            "name": "expected_node_name",
+            "value": "Completed",
+            "value_type": "String"
+          },
+          {
+            "identifier": 2,
+            "b_submission": true,
+            "name": "submitted_reward_object",
+            "value_type": "Address"
+          },
+          {
+            "identifier": 3,
+            "b_submission": true,
+            "name": "submitted_recipient",
+            "value_type": "Address"
+          }
+        ],
+        "root": {
+          "type": "logic_and",
+          "nodes": [
+            {
+              "type": "logic_equal",
+              "nodes": [
+                {
+                  "type": "query",
+                  "query": 1253,
+                  "object": { "identifier": 0, "convert_witness": 100 },
+                  "parameters": []
+                },
+                { "type": "identifier", "identifier": 1 }
+              ]
+            },
+            {
+              "type": "logic_equal",
+              "nodes": [
+                { "type": "context", "context": "Signer" },
+                {
+                  "type": "query",
+                  "query": 1562,
+                  "object": { "identifier": 0 },
+                  "parameters": []
+                }
+              ]
+            },
+            {
+              "type": "logic_not",
+              "node": {
+                "type": "query_reward_record_exists",
+                "object": { "identifier": 2 },
+                "recipient": { "identifier": 3 },
+                "where": {}
+              }
+            }
+          ]
+        }
+      },
+      "customization": {
+        "table[1].value": "Replace 'Completed' with the expected node name for your workflow.",
+        "namedNew.name": "Set a unique Guard name."
+      }
+    }
+  ],
+  "query_reference": {
+    "description": "Common Guard query IDs. Use wowok_buildin_info with info='guard instructions' for the complete list.",
+    "queries": [
+      { "id": 1253, "name": "order.progress.node", "returns": "String", "description": "Get current progress node name of an order", "witness": "TypeOrderProgress (100)" },
+      { "id": 1562, "name": "order.owner", "returns": "Address", "description": "Get order owner address" },
+      { "id": 1563, "name": "order.service", "returns": "Address", "description": "Get order service address" },
+      { "id": 1564, "name": "order.payer", "returns": "Address", "description": "Get order payer address" }
+    ],
+    "witness_types": [
+      { "id": 100, "name": "TypeOrderProgress", "description": "Access order progress data" },
+      { "id": 200, "name": "TypeOrder", "description": "Access order data" }
+    ]
+  },
+  "node_return_types": {
+    "logic_bool": ["logic_and", "logic_or", "logic_not", "logic_equal", "logic_as_u256_equal", "logic_as_u256_greater", "logic_as_u256_lesser", "logic_as_u256_greater_or_equal", "logic_as_u256_lesser_or_equal", "logic_string_contains", "logic_string_nocase_contains", "logic_string_nocase_equal", "calc_string_contains", "calc_string_nocase_contains", "calc_string_nocase_equal", "vec_contains_bool", "vec_contains_address", "vec_contains_string", "vec_contains_string_nocase", "vec_contains_number", "query_reward_record_exists"],
+    "calc_numeric": ["calc_number_add", "calc_number_subtract", "calc_number_multiply", "calc_number_divide", "calc_number_mod"],
+    "calc_string": ["calc_string_length", "calc_string_indexof", "calc_string_nocase_indexof"],
+    "conversion": ["convert_number_address", "convert_address_number", "convert_number_string", "convert_string_number", "convert_safe_u8", "convert_safe_u16", "convert_safe_u32", "convert_safe_u64", "convert_safe_u128", "convert_safe_u256"],
+    "query": ["query (depends on query instruction)", "query_reward_record_find", "query_reward_record_count", "query_reward_record_exists", "query_progress_history_find", "query_progress_history_session_find", "query_progress_history_session_forward_find", "query_progress_history_session_count", "query_progress_history_session_forward_count", "query_progress_history_session_forward_retained_submission_count"],
+    "vector": ["vec_length", "vec_contains_bool", "vec_contains_address", "vec_contains_string", "vec_contains_string_nocase", "vec_contains_number"],
+    "context": ["Signer (Address)", "Clock (U64)", "Guard (Address)"]
+  },
+  "best_practices": [
+    "Root node MUST return Bool — always use a logic node (logic_and, logic_or, logic_not, logic_equal) as the root.",
+    "Use logic_and for multiple conditions — most common pattern for combining validations.",
+    "Check node return types: logic nodes expect Bool children; calculation nodes expect numeric children; comparison nodes expect matching types.",
+    "Use identifier references: store constants (addresses, strings, numbers) in the Guard table and reference them by identifier index.",
+    "Use convert_witness when querying object data: set convert_witness to the appropriate witness type (e.g., 100 for TypeOrderProgress) to access the data you need.",
+    "Handle optional fields in where clauses: only include fields you want to filter by; omitting a field means 'don't filter by this field'.",
+    "Guard is IMMUTABLE after creation — test your logic carefully before deploying. Use replaceExistName=true to replace with a corrected version.",
+    "COGNITIVE PRINCIPLE: Guard validation occurs BEFORE the operation. A Guard querying the SAME Progress object it operates on sees the PRE-transition value (source node), not the target node. For post-transition verification, bind the Guard to the Allocator instead."
+  ],
+  "common_errors": [
+    "Type mismatch: comparing incompatible types (e.g., Address with String). Use conversion nodes to align types.",
+    "Missing identifier: referencing an identifier index that doesn't exist in the Guard table.",
+    "Wrong return type: using a non-Bool node as the root or as a child of a logic node.",
+    "Invalid query ID: using a query instruction ID that doesn't exist. Use wowok_buildin_info with info='guard instructions' for the complete list.",
+    "Missing convert_witness: querying object data without setting the appropriate witness type — the query returns empty/null.",
+    "Circular reference: Guard queries the state of the SAME object it validates, seeing pre-transition values instead of post-transition values."
+  ]
+}

package/dist/schemas/guard2file.schema.json

@@ -50,7 +50,7 @@
                 "testnet",
                 "mainnet"
               ],
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             },
             "referrer": {
               "$ref": "#/definitions/guard2file/properties/env/properties/account",

package/dist/schemas/index.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "WoWok MCP Schema Index",
   "description": "Index of all available JSON schemas for WoWok MCP tools",
-  "generatedAt": "2026-07-24T21:15:38.360Z",
+  "generatedAt": "2026-07-29T00:14:19.691Z",
   "tools": [
     {
       "name": "onchain_operations",

package/dist/schemas/local_info_operation.output.json

@@ -60,6 +60,12 @@
                     "permission_denied",
                     "immutable_violation",
                     "network_error",
+                    "rate_limit",
+                    "gas_exceeded",
+                    "bcs_error",
+                    "signature_error",
+                    "config_error",
+                    "wip_verification_failed",
                     "unknown"
                   ],
                   "description": "Error classification for programmatic recovery"

package/dist/schemas/local_mark_operation.output.json

@@ -60,7 +60,7 @@
                           "address"
                         ],
                         "additionalProperties": false,
-                        "description": "LOCAL PRIVATE: Local mark data structure for storing address names and tags privately on your device. This data is NEVER published to the blockchain."
+                        "description": "LOCAL PRIVATE: Local mark data structure for storing address names and tags privately on your device. This data is NEVER published to the blockchain. CROSS-NETWORK ISOLATION (DOC-02): LocalMark names are scoped per network — the same name 'my-service' can map to different addresses on testnet vs mainnet. When switching networks (e.g., testnet→mainnet deployment), re-create marks with the same names pointing to the new mainnet addresses. This enables name-based object references that work identically across networks without code changes."
                       },
                       "description": "List of added mark data"
                     },
@@ -104,6 +104,12 @@
                     "permission_denied",
                     "immutable_violation",
                     "network_error",
+                    "rate_limit",
+                    "gas_exceeded",
+                    "bcs_error",
+                    "signature_error",
+                    "config_error",
+                    "wip_verification_failed",
                     "unknown"
                   ],
                   "description": "Error classification for programmatic recovery"

package/dist/schemas/local_mark_operation.schema.json

@@ -59,7 +59,7 @@
                   "address"
                 ],
                 "additionalProperties": false,
-                "description": "LOCAL ONLY: Parameters for creating or updating a LOCAL mark. This data is stored privately on your device and will NEVER be published to the blockchain. For public on-chain marks, use the 'personal' tool instead. IMPORTANT: 'name' field is an OBJECT {value, replaceExistName?}, not a string."
+                "description": "LOCAL ONLY: Parameters for creating or updating a LOCAL mark. This data is stored privately on your device and will NEVER be published to the blockchain. For public on-chain marks, use the 'personal' tool instead. IMPORTANT: 'name' field is an OBJECT {value, replaceExistName?}, not a string. FIX-011 cross-network consistency: LocalMark names are scoped per network. When creating marks for the same logical object on different networks (e.g. testnet and mainnet), use the SAME name value to keep name-based references portable. Before creating a mark on mainnet, check if a mark with the same name already exists on testnet (via query_local with network='testnet') and replicate the same name on mainnet for consistency."
               },
               "minItems": 1,
               "description": "Array of mark data to add (at least 1 item)"

package/dist/schemas/machineNode2file.schema.json

@@ -50,7 +50,7 @@
                 "testnet",
                 "mainnet"
               ],
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             },
             "referrer": {
               "$ref": "#/definitions/machineNode2file/properties/env/properties/account",

package/dist/schemas/messenger_operation.schema.json

@@ -82,8 +82,8 @@
             "to": {
               "anyOf": [
                 {
-                  "type": "string",
-                  "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x1234...' - uses address directly"
+                  "$ref": "#/definitions/messenger_operation/anyOf/1/properties/from",
+                  "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                 },
                 {
                   "type": "object",
@@ -943,9 +943,9 @@
                         {
                           "type": "array",
                           "items": {
-                            "type": "string"
+                            "$ref": "#/definitions/messenger_operation/anyOf/1/properties/from"
                           },
-                          "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry"
+                          "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry. EXAMPLE: ['alice', '0x2...', 'bob']"
                         },
                         {
                           "type": "object",

package/dist/schemas/onchain_events.output.json

@@ -219,7 +219,7 @@
                               "number",
                               "string"
                             ],
-                            "description": "Balance type"
+                            "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
                           }
                         },
                         "required": [