@wowok/agent-mcp 2.6.1 → 2.6.4

package/dist/schema/call/service.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { TypedPermissionObjectSchema, CoinParamSchema, NamedObjectSchema, ObjectsSchema, CallEnvSchema, SubmissionCallSchema } from "./base.js";
-import { AllocatorsSchema, DiscountTypeSchema, ServiceSaleSchema } from "../query/index.js";
-import { AccountOrMark_AddressSchema, DescriptionSchema, LongNameSchema, ManyAccountOrMark_AddressSchema, NameOrAddressSchema, NotEmptyNameSchema, ReceivedBalanceOrRecentlySchema, ReceivedObjectsOrRecentlySchema } from "../common/index.js";
+import { AllocatorsSchema, DiscountTypeSchema, ServiceSaleSchema, PaymentInfoSchema } from "../query/index.js";
+import { AccountOrMark_AddressSchema, DescriptionSchema, LongNameSchema, ManyAccountOrMark_AddressSchema, NameOrAddressSchema, NotEmptyNameSchema, ReceivedBalanceOrRecentlySchema, ReceivedObjectsOrRecentlySchema, RECEIVE_FORMAT_BLOCK_OBJECTS, RECEIVE_FORMAT_BLOCK_BALANCE } from "../common/index.js";
 import { BalanceTypeSchema } from "../common/index.js";
 export const ServiceBuyItemSchema = z.object({
     name: LongNameSchema.describe("Name of the product or service to purchase"),
@@ -10,7 +10,9 @@ export const ServiceBuyItemSchema = z.object({
 }).strict();
 export const BuySchema = z.object({
     items: z.array(ServiceBuyItemSchema).describe("List of products or services to purchase"),
-    total_pay: CoinParamSchema.describe("Actual payment amount"),
+    total_pay: CoinParamSchema.describe("Actual payment amount. FORMAT: {balance: <amount_in_smallest_unit>} or {coin: <coin_object_id>}. " +
+        "The token type and precision are determined by the Service object's type_parameter (the generic type set when the Service was created). " +
+        "For WOW (9 decimals): {balance: 1000000000} = 1 WOW. For SUI (9 decimals): {balance: 1000000000} = 1 SUI."),
     discount: z.string().optional().describe("Discount object ID or name"),
     payment_remark: z.string().optional().describe("Payment remark"),
     payment_index: z.number().optional().describe("Payment index"),
@@ -31,9 +33,15 @@ export const OrderNewSchema = z.object({
     agents: ManyAccountOrMark_AddressSchema.optional().describe("Order agents. Agents can operate the order, such as canceling the order, modifying the order status, etc.; but cannot receive the funds received by the order."),
     order_required_info: z.string().optional().describe("Contact object ID or WTS Proof object"),
     transfer: AccountOrMark_AddressSchema.optional().describe("Set the new owner of the order. Requires order owner permission to set."),
-    namedNewOrder: NamedObjectSchema.optional().describe("Set the local name of the order object."),
-    namedNewAllocation: NamedObjectSchema.optional().describe("Set the local name of the order's Allocation object."),
-    namedNewProgress: NamedObjectSchema.optional().describe("Set the local name of the order's Progress object."),
+    namedNewOrder: NamedObjectSchema.optional().describe("RECOMMENDED: Set a local name for the newly created Order object. " +
+        "Without this, the Order is only referenceable by its on-chain address. " +
+        "Example: {name: 'my_order_v1'} allows subsequent operations to use 'my_order_v1' instead of the address."),
+    namedNewAllocation: NamedObjectSchema.optional().describe("RECOMMENDED: Set a local name for the order's Allocation object. " +
+        "Without this, the Allocation is only referenceable by its address. " +
+        "Example: {name: 'my_allocation_v1'} allows alloc_by_guard to reference 'my_allocation_v1'."),
+    namedNewProgress: NamedObjectSchema.optional().describe("RECOMMENDED: Set a local name for the order's Progress object. " +
+        "Without this, the Progress is only referenceable by its address. " +
+        "Example: {name: 'my_progress_v1'} allows progress operations to use 'my_progress_v1'."),
 }).strict();
 export const SalesSchema = z.discriminatedUnion("op", [
     z.object({
@@ -59,42 +67,98 @@ export const CallService_DataSchema = z.object({
     location: LongNameSchema.optional().describe("Location of the Service"),
     sales: SalesSchema.optional().describe("Service sales products or services list."),
     repositories: ObjectsSchema.optional().describe("Service Repository object list."),
-    rewards: ObjectsSchema.optional().describe("Service Reward object list."),
-    arbitrations: ObjectsSchema.optional().describe("Service Arbitration object list."),
+    rewards: ObjectsSchema.optional().describe("Service Reward object list. " +
+        "May share the Service's Permission (no conflict check — intentional: rewards are the provider's own " +
+        "incentive tool; only Arbitration requires a different Permission for neutrality)."),
+    arbitrations: ObjectsSchema.optional().describe("Service Arbitration object list. " +
+        "FORMAT: same as repositories — use the `objects` field name inside the operation data. " +
+        "Example: {arbitrations: [{name: 'my_arb_1'}, {name: 'my_arb_2'}]}. " +
+        "Each item is a NameOrAddress (object ID or local mark name). " +
+        "⚠️ PERMISSION RULE (contract-enforced, service.move arbitration_add_imp): every Arbitration bound here " +
+        "MUST use a Permission object DIFFERENT from THIS Service's permission — binding an Arbitration that shares " +
+        "the Service's Permission aborts with E_ARBITRATION_PERMISSION_CONFLICT (error 33). " +
+        "Create a dedicated Permission for each Arbitration BEFORE binding. " +
+        "DESIGN RATIONALE (confirmed intentional): dispute resolution requires NEUTRALITY — an Arbitration controlled " +
+        "by the same Permission admins as the Service it judges would be a conflict of interest. ONLY Arbitration has " +
+        "this check: Reward and Treasury objects MAY share the Service's Permission (they are the provider's own tools)."),
     machine: z.union([NameOrAddressSchema, z.null()]).optional().describe("Service Machine object ID or name. The Machine object must be in published state."),
     discount: DiscountSchema.optional().describe("Issue discount."),
     discount_destroy: z.array(NameOrAddressSchema).optional().describe("Destroy existing discount object ID list."),
     customer_required: z.array(NotEmptyNameSchema).optional().describe("Customer required information. Such as phone, email, etc."),
-    order_allocators: z.union([AllocatorsSchema, z.null()]).optional().describe("Order fund allocator."),
+    order_allocators: z.union([AllocatorsSchema, z.null()]).optional().describe("Order fund allocator. Max 100 allocators (MAX_ALLOCATOR_COUNT). " +
+        "Each allocator has a guard (first matching guard wins) and a sharing list. " +
+        "Set to null to clear. " +
+        "⚠️ PERMANENTLY IMMUTABLE after publish: order_allocators can ONLY be set BEFORE publish=true " +
+        "(Move service.move:503: assert!(!self.bPublished, E_ALREADY_PUBLISHED)). " +
+        "After publish, the ONLY way to change allocation rules is to create a NEW Service object. " +
+        "There is NO pause+lock exception for order_allocators (unlike arbitrations/rewards which have time-lock removal). " +
+        "PRE-PUBLISH CHECKLIST: verify all guard names resolve, all sharing amounts are correct, " +
+        "threshold is set, and recipient types (Entity/Signer/GuardIdentifier) are intended before calling publish=true. " +
+        "GuardIdentifier sharing mode: {who: {GuardIdentifier: <u8>}, sharing: <rate>, mode: 'Rate'} — " +
+        "resolves recipient from Guard table submission at allocation time (e.g., refund to customer). " +
+        "MULTI-CALL ALLOCATION: Allocation.alloc() can be called MULTIPLE times (no consumed flag in contract). " +
+        "Use Amount mode (not Surplus) for recurring allocations — Surplus calls balance::withdraw_all which drains the balance. " +
+        "For monthly payment scenarios, create multiple Allocators with time-based Guards + Amount mode sharing items."),
     buy_guard: z.union([NameOrAddressSchema, z.null()]).optional().describe("Buy guard object ID or name."),
-    compensation_fund_add: CoinParamSchema.optional().describe("Compensation fund. Used to claim compensation based on the arbitration result of the Arb object when resolving order disputes."),
-    setting_locked_time_add: z.number().optional().describe("Additional lock duration (milliseconds) to extend the 'setting_lock_duration'. Initial value is 30 days, can only be increased, not decreased. Affects: rewards, arbitrations, and compensation_fund_receive."),
-    compensation_fund_receive: ReceivedBalanceOrRecentlySchema.optional().describe("Receive order compensation funds."),
-    owner_receive: ReceivedObjectsOrRecentlySchema.optional().describe("Unwrap CoinWrapper objects and other objects received by this object and send them to the owner of its Permission object."),
+    compensation_fund_add: CoinParamSchema.optional().describe("Deposit funds into the Service compensation_fund. Used to pay indemnity when arbitration resolves in customer's favor. " +
+        "FORMAT: {balance: <amount_in_smallest_unit>} — the field name is 'balance' (NOT 'amount'). " +
+        "The token type and precision are determined by the Service object's type_parameter (the generic type set when the Service was created). " +
+        "For WOW (9 decimals): {balance: 1000000000} = 1 WOW. For SUI (9 decimals): {balance: 1000000000} = 1 SUI. " +
+        "For tokens with different decimals, adjust accordingly (e.g. USDC has 6 decimals, so {balance: 1000000} = 1 USDC). " +
+        "REQUIRES: Permission index 315 (SERVICE_COMPENSATION_FUND_DEPOSIT) must be granted to the calling account first. " +
+        "COMMON MISTAKE: using {amount: ...} or {amount: ..., type: 'WOW'} — these will fail. The correct field is 'balance'."),
+    compensation_fund_withdraw: z.object({
+        receipt: AccountOrMark_AddressSchema.describe("Receipt address that will receive the withdrawn funds (as a new Payment object)"),
+        payment_info: PaymentInfoSchema.describe("Payment info for the new Payment object created to hold the withdrawn funds"),
+    }).strict().optional().describe("Withdraw ALL funds from the compensation_fund to a new Payment object owned by `receipt`. " +
+        "Move layer: service::compensation_fund_withdraw (service.move L383-390). " +
+        "REQUIRES: Service must be paused AND setting_lock_duration must have elapsed since pause (assert_not_published at L384-385). " +
+        "Withdraws the ENTIRE compensation_fund balance via balance::withdraw_all. " +
+        "DIFFERENT from compensation_claim (order-side, for arbitration-winning users, no pause+lock required)."),
+    setting_lock_duration_add: z.number().optional().describe("Additional lock duration to ADD to 'setting_lock_duration' (Move field name). " +
+        "UNIT: milliseconds (ms). Example: 2592000000 = 30 days, 7776000000 = 90 days, 86400000 = 1 day. " +
+        "DEFAULT: 2592000000 (30 days, DEFAULT_LOCK_DURATION). This is the initial value when a Service is created. " +
+        "Behavior: additive (safe_add) — only increases, never decreases. " +
+        "Move entry: service::setting_lock_duration_add / setting_lock_duration_add_with_passport. " +
+        "Can be called BEFORE or AFTER publish (no publish check). " +
+        "Affects the waiting time required by: compensation_fund_withdraw, arbitrations remove/clear, rewards remove/clear " +
+        "(all require pause + setting_lock_duration elapsed since pause)."),
+    compensation_fund_receive: ReceivedBalanceOrRecentlySchema.optional().describe("Receive order compensation funds from this Service object." + RECEIVE_FORMAT_BLOCK_BALANCE),
+    owner_receive: ReceivedObjectsOrRecentlySchema.optional().describe("Unwrap CoinWrapper objects and other objects received by this Service object and send them to the owner of its Permission object." + RECEIVE_FORMAT_BLOCK_OBJECTS),
     um: z.union([NameOrAddressSchema, z.null()]).optional().describe("Contact object ID or name."),
     pause: z.boolean().optional().describe("Whether to pause accepting new orders."),
     publish: z.boolean().optional().describe("Whether to publish the Service. After publishing, customers can place orders. " +
-        "BUG-04 fix (v2.2 — verified against Move source service.move + SDK service.ts):\n" +
-        "  SDK-LOCKED after publish (checkNotPublished — cannot modify, must clone new Service):\n" +
-        "    • machine          (permanently locked — workflow template)\n" +
-        "    • order_allocators (permanently locked — fund distribution rules)\n" +
-        "    • arbitrations     (permanently locked at SDK level — dispute resolution objects)\n" +
-        "  TIME-LOCKED after publish (modifiable only after pause + setting_lock_duration elapsed):\n" +
-        "    • rewards remove/clear  (assert_not_published — time-based lock)\n" +
-        "  REMAIN MUTABLE after publish (no SDK check, no Move check):\n" +
-        "    • buy_guard            (CAN be modified after publish — purchase eligibility guard)\n" +
-        "    • setting_locked_time_add (CAN be extended — only increases, never decreases)\n" +
-        "    • sales, discount, description, location, pause, repositories,\n" +
-        "    • compensation_fund_add, customer_required, um (Contact), rewards add\n" +
-        "These 3 SDK-LOCKED fields (machine/order_allocators/arbitrations) MUST be set BEFORE publish=true.\n" +
+        "VERIFIED against Move source service.move + SDK service.ts (4-level immutability matrix):\n" +
+        "  L1 — PERMANENTLY LOCKED after publish (assert!(!bPublished), no pause+lock exception):\n" +
+        "    • machine          (service.move L633/L653 — workflow template)\n" +
+        "    • order_allocators (service.move L503 — fund distribution rules)\n" +
+        "  L2 — TIME-LOCKED after publish (assert_not_published — requires pause + setting_lock_duration elapsed):\n" +
+        "    • arbitrations remove/clear (service.move L433/L445 — dispute resolution objects)\n" +
+        "    • rewards remove/clear       (service.move L402/L414 — reward objects)\n" +
+        "    • compensation_fund_withdraw (service.move L384-385 — withdraw ALL funds)\n" +
+        "  L3 — REMAIN MUTABLE after publish (no SDK check, no Move check):\n" +
+        "    • arbitrations add, rewards add (no assert — can add after publish)\n" +
+        "    • buy_guard, sales, discount, description, location, pause, repositories,\n" +
+        "    • compensation_fund_add, setting_lock_duration_add, customer_required, um (Contact)\n" +
+        "These 2 L1-LOCKED fields (machine/order_allocators) MUST be set BEFORE publish=true.\n" +
+        "arbitrations/rewards can be ADDED after publish but remove/clear requires pause+lock.\n" +
+        "\n" +
+        "⚠️ COMPENSATION_FUND + ARBITRATION LINKAGE (service.move:494-499):\n" +
+        "  At publish time, if compensation_fund > 0, Arbitration MUST be bound:\n" +
+        "    if (balance::value(&self.compensation_fund) > 0) {\n" +
+        "        assert!(arbitration_count > 0, E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND);\n" +
+        "    }\n" +
+        "  The MCP handler enforces this as a HARD PRE-CHECK: if publish=true AND compensation_fund_add " +
+        "  is set in the same call AND arbitrations is empty, the call is REJECTED before submission. " +
+        "  If compensation_fund was deposited in a prior call, a SOFT WARNING is issued.\n" +
         "\n" +
         "SCHEMA-03 / P0-01 fix — DEPLOYMENT WORKFLOW (two-phase, avoids circular dependency):\n" +
         "  Phase 1 — CREATE (no publish): object={name:'my-service', type_parameter, permission} + machine + order_allocators + arbitrations.\n" +
         "    NOTE: buy_guard can use a LocalMark NAME (not address) to break the Guard→Service circular dependency.\n" +
         "    The name is resolved to an address at transaction build time.\n" +
         "  Phase 2 — PUBLISH: object='my-service' (string ref) + publish=true.\n" +
-        "    All SDK-LOCKED fields must be set in Phase 1; Phase 2 only flips the publish flag.\n" +
-        "  Post-publish updates: buy_guard, sales, description, repositories (add), rewards (add), etc."),
+        "    All L1-LOCKED fields must be set in Phase 1; Phase 2 only flips the publish flag.\n" +
+        "  Post-publish updates: buy_guard, sales, description, repositories (add), rewards (add), arbitrations (add), etc."),
 }).strict().describe("On-chain Service operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create a Service. NOTE: 'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation.");
 export const CallService_InputSchema = z.object({
     data: CallService_DataSchema,

package/dist/schema/call/treasury.d.ts

@@ -841,6 +841,15 @@ export declare const CallTreasury_DataSchema: z.ZodObject<{
             onChain?: boolean | undefined;
         } | undefined;
     } | undefined;
+    receive?: {
+        received: {
+            id: string;
+            balance: string | number;
+            payment: string;
+        }[];
+        balance: string | number;
+        token_type: string;
+    } | "recently" | undefined;
     um?: string | null | undefined;
     withdraw?: {
         amount: {
@@ -878,15 +887,6 @@ export declare const CallTreasury_DataSchema: z.ZodObject<{
         id: string;
         content_raw?: any;
     }[] | undefined;
-    receive?: {
-        received: {
-            id: string;
-            balance: string | number;
-            payment: string;
-        }[];
-        balance: string | number;
-        token_type: string;
-    } | "recently" | undefined;
     external_deposit_guard?: {
         op: "add";
         guards: {
@@ -963,6 +963,15 @@ export declare const CallTreasury_DataSchema: z.ZodObject<{
             onChain?: boolean | undefined;
         } | undefined;
     } | undefined;
+    receive?: {
+        received: {
+            id: string;
+            balance: string | number;
+            payment: string;
+        }[];
+        balance: string | number;
+        token_type: string;
+    } | "recently" | undefined;
     um?: string | null | undefined;
     withdraw?: {
         amount: {
@@ -1000,15 +1009,6 @@ export declare const CallTreasury_DataSchema: z.ZodObject<{
         id: string;
         content_raw?: any;
     }[] | undefined;
-    receive?: {
-        received: {
-            id: string;
-            balance: string | number;
-            payment: string;
-        }[];
-        balance: string | number;
-        token_type: string;
-    } | "recently" | undefined;
     external_deposit_guard?: {
         op: "add";
         guards: {
@@ -1558,6 +1558,15 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
                 onChain?: boolean | undefined;
             } | undefined;
         } | undefined;
+        receive?: {
+            received: {
+                id: string;
+                balance: string | number;
+                payment: string;
+            }[];
+            balance: string | number;
+            token_type: string;
+        } | "recently" | undefined;
         um?: string | null | undefined;
         withdraw?: {
             amount: {
@@ -1595,15 +1604,6 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
             id: string;
             content_raw?: any;
         }[] | undefined;
-        receive?: {
-            received: {
-                id: string;
-                balance: string | number;
-                payment: string;
-            }[];
-            balance: string | number;
-            token_type: string;
-        } | "recently" | undefined;
         external_deposit_guard?: {
             op: "add";
             guards: {
@@ -1680,6 +1680,15 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
                 onChain?: boolean | undefined;
             } | undefined;
         } | undefined;
+        receive?: {
+            received: {
+                id: string;
+                balance: string | number;
+                payment: string;
+            }[];
+            balance: string | number;
+            token_type: string;
+        } | "recently" | undefined;
         um?: string | null | undefined;
         withdraw?: {
             amount: {
@@ -1717,15 +1726,6 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
             id: string;
             content_raw?: any;
         }[] | undefined;
-        receive?: {
-            received: {
-                id: string;
-                balance: string | number;
-                payment: string;
-            }[];
-            balance: string | number;
-            token_type: string;
-        } | "recently" | undefined;
         external_deposit_guard?: {
             op: "add";
             guards: {
@@ -1777,10 +1777,11 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
         user_intent_phrases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         project: z.ZodOptional<z.ZodString>;
         client_schema_version: z.ZodOptional<z.ZodString>;
-        schema_strict_mode: z.ZodOptional<z.ZodBoolean>;
+        schema_strict_mode: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
         dry_run: z.ZodOptional<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         account: string;
+        schema_strict_mode: boolean;
         no_cache?: boolean | undefined;
         network?: import("@wowok/wowok").ENTRYPOINT | undefined;
         permission_guard?: string[] | undefined;
@@ -1789,7 +1790,6 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
         user_intent_phrases?: string[] | undefined;
         project?: string | undefined;
         client_schema_version?: string | undefined;
-        schema_strict_mode?: boolean | undefined;
         dry_run?: boolean | undefined;
     }, {
         no_cache?: boolean | undefined;
@@ -2021,6 +2021,15 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
                 onChain?: boolean | undefined;
             } | undefined;
         } | undefined;
+        receive?: {
+            received: {
+                id: string;
+                balance: string | number;
+                payment: string;
+            }[];
+            balance: string | number;
+            token_type: string;
+        } | "recently" | undefined;
         um?: string | null | undefined;
         withdraw?: {
             amount: {
@@ -2058,15 +2067,6 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
             id: string;
             content_raw?: any;
         }[] | undefined;
-        receive?: {
-            received: {
-                id: string;
-                balance: string | number;
-                payment: string;
-            }[];
-            balance: string | number;
-            token_type: string;
-        } | "recently" | undefined;
         external_deposit_guard?: {
             op: "add";
             guards: {
@@ -2137,6 +2137,7 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
     } | undefined;
     env?: {
         account: string;
+        schema_strict_mode: boolean;
         no_cache?: boolean | undefined;
         network?: import("@wowok/wowok").ENTRYPOINT | undefined;
         permission_guard?: string[] | undefined;
@@ -2145,7 +2146,6 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
         user_intent_phrases?: string[] | undefined;
         project?: string | undefined;
         client_schema_version?: string | undefined;
-        schema_strict_mode?: boolean | undefined;
         dry_run?: boolean | undefined;
     } | undefined;
 }, {
@@ -2185,6 +2185,15 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
                 onChain?: boolean | undefined;
             } | undefined;
         } | undefined;
+        receive?: {
+            received: {
+                id: string;
+                balance: string | number;
+                payment: string;
+            }[];
+            balance: string | number;
+            token_type: string;
+        } | "recently" | undefined;
         um?: string | null | undefined;
         withdraw?: {
             amount: {
@@ -2222,15 +2231,6 @@ export declare const CallTreasury_InputSchema: z.ZodObject<{
             id: string;
             content_raw?: any;
         }[] | undefined;
-        receive?: {
-            received: {
-                id: string;
-                balance: string | number;
-                payment: string;
-            }[];
-            balance: string | number;
-            token_type: string;
-        } | "recently" | undefined;
         external_deposit_guard?: {
             op: "add";
             guards: {

package/dist/schema/call/treasury.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { TypedPermissionObjectSchema, CoinParamSchema, NamedObjectSchema, SubmissionCallSchema, CallEnvSchema } from "./base.js";
 import { AmountFromDepositGuardSchema, AmountFromWithdrawGuardSchema, PaymentInfoSchema } from "../query/index.js";
-import { AccountOrMark_AddressSchema, DescriptionSchema, ReceivedBalanceOrRecentlySchema, ReceivedObjectsOrRecentlySchema, NameOrAddressSchema } from "../common/index.js";
+import { AccountOrMark_AddressSchema, DescriptionSchema, ReceivedBalanceOrRecentlySchema, ReceivedObjectsOrRecentlySchema, NameOrAddressSchema, RECEIVE_FORMAT_BLOCK_OBJECTS, RECEIVE_FORMAT_BLOCK_BALANCE } from "../common/index.js";
 import { BalanceTypeSchema } from "../common/index.js";
 export const DepositSchema = z.object({
     coin: CoinParamSchema.describe("Asset to deposit"),
@@ -56,12 +56,12 @@ export const ExternalWithdrawGuardSchema = z.discriminatedUnion("op", [
 export const CallTreasury_DataSchema = z.object({
     object: TypedPermissionObjectSchema,
     description: DescriptionSchema.optional(),
-    receive: ReceivedBalanceOrRecentlySchema.optional().describe("Receive CoinWrapper objects received by the object and deposit them into its balance."),
+    receive: ReceivedBalanceOrRecentlySchema.optional().describe("Receive CoinWrapper objects received by this Treasury object and deposit them into its balance." + RECEIVE_FORMAT_BLOCK_BALANCE),
     deposit: DepositSchema.optional().describe("Deposit to Treasury object"),
     withdraw: WithdrawSchema.optional().describe("Withdraw from Treasury object"),
     external_deposit_guard: ExternalDepositGuardSchema.optional().describe("Set external deposit Guard for Treasury object"),
     external_withdraw_guard: ExternalWithdrawGuardSchema.optional().describe("Set external withdrawal Guard for Treasury object"),
-    owner_receive: ReceivedObjectsOrRecentlySchema.optional().describe("Unwrap CoinWrapper objects and other objects received by this object and send them to the owner of its Permission object."),
+    owner_receive: ReceivedObjectsOrRecentlySchema.optional().describe("Unwrap CoinWrapper objects and other objects received by this Treasury object and send them to the owner of its Permission object." + RECEIVE_FORMAT_BLOCK_OBJECTS),
     um: z.union([NameOrAddressSchema, z.null()]).optional().describe("Contact object ID or name."),
 }).strict().describe("On-chain Treasury operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create a Treasury. NOTE: 'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation.");
 export const CallTreasury_InputSchema = z.object({

package/dist/schema/common/index.d.ts

@@ -715,6 +715,8 @@ export declare const ReceivedObjectsOrRecentlySchema: z.ZodUnion<[z.ZodArray<z.Z
     balance: string | number;
     token_type: string;
 }>, z.ZodLiteral<"recently">]>;
+export declare const RECEIVE_FORMAT_BLOCK_OBJECTS: string;
+export declare const RECEIVE_FORMAT_BLOCK_BALANCE: string;
 export declare const QueryReceivedResultSchema: z.ZodObject<{
     result: z.ZodUnion<[z.ZodObject<{
         balance: z.ZodUnion<[z.ZodNumber, z.ZodString]>;

package/dist/schema/common/index.js

@@ -222,15 +222,18 @@ export const ObjectTypeSchema = z.enum([
     WowObjectType.TableItem_AddressMark,
     WowObjectType.TableItem_EntityRegistrar,
 ]).describe("Wowok object type");
-export const BalanceTypeSchema = z.union([z.number(), z.string()]).describe("A coin/balance amount in the smallest on-chain unit (u64). " +
-    "Accepts a JS number OR a numeric string. " +
-    "PRECISION RULE: for values exceeding 2^53 (e.g. token amounts with 18 decimals), " +
-    "ALWAYS pass a numeric STRING (e.g. \"1000000000000000000\") to preserve precision — " +
-    "JS numbers lose precision above 2^53. " +
-    "UNIT: this is the smallest unit, NOT the display unit. " +
-    "For SUI: 1 SUI = 10^9 MIST, so 10 SUI = 10000000000. " +
-    "For custom tokens: use the token's native smallest unit (decimals from coin metadata). " +
-    "Examples: 10000000000 (10 SUI), \"1000000000000000000\" (1 token with 18 decimals), 500 (500 units of a token with 0 decimals). " +
+export const BalanceTypeSchema = z.union([z.number(), z.string()]).describe("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.");
 export const QueryIdSchema = z.number().int().min(0).describe("Query ID");
 export const CacheExpireTypeSchema = z.union([z.number(), z.literal("INFINITE")]).describe("Cache expiration time type");
@@ -253,7 +256,18 @@ export const SupportedValueSchema = SupportedValueUserSchema.or(ValueContainerSc
 export const GuardIdentifierSchema = z.number().int().min(0).max(255).describe("Identifier (0-255) for data lookup in Guard table.");
 export const GuardTableItemBaseSchema = z.object({
     identifier: GuardIdentifierSchema,
-    b_submission: z.boolean().describe("Whether user submission is required for this data"),
+    b_submission: z.boolean().describe("Whether this table item's value is submitted dynamically at Guard trigger time (alloc_by_guard call). " +
+        "\n\n" +
+        "true = value is submitted by the caller when triggering the Guard. " +
+        "Use for runtime-context-dependent values like order address, user address. " +
+        "The 'value' field is ignored when b_submission=true; the caller must provide it via submissions[]. " +
+        "\n\n" +
+        "false = value is static, set at Guard creation time. " +
+        "Use for values known when the Guard is created: expected node names, expected merchant address, expected service address. " +
+        "The 'value' field must be populated and will be stored on-chain permanently. " +
+        "\n\n" +
+        "Rule of thumb: if the value is the SAME for all future Guard triggers, use false. " +
+        "If the value DIFFERS per trigger (e.g., which order to release funds for), use true."),
     value_type: ValueTypeUserSchema.describe("Type of the value stored in `value`. One of: Bool(0), Address(1), String(2), U8(3), U16(4), U32(5), U64(6), U128(7), U256(8), VecBool(9), VecAddress(10), VecString(11), VecU8(12), VecU16(13), VecU32(14), VecU64(15), VecU128(16), VecU256(17), VecVecU8(18). " +
         "When value_type=Address (1), the `value` field accepts a hex address string, a LocalMark name, or an AccountOrMark_Address object — see `value` field description for details."),
     value: SupportedValueUserSchema.optional().describe("The actual value data. Format depends on `value_type`:\n" +
@@ -363,6 +377,28 @@ export const ReceivedObjectsOrRecentlySchema = z.union([
     ReceivedBalanceSchema,
     z.literal("recently"),
 ]).describe("Specified received object records or all recently received object records");
+export const RECEIVE_FORMAT_BLOCK_OBJECTS = "\n\nACCEPTED FORMATS (F-06 unified receive operation block):\n" +
+    "• 'recently' (string literal) — auto-query and receive ALL recently received objects.\n" +
+    "  Use this for the common case: \"withdraw everything the object has received.\"\n" +
+    "  Example: receive: 'recently'\n" +
+    "• ReceivedNormal[] (array) — explicit list of received objects to unwrap.\n" +
+    "  Use this when you want to receive specific objects only (not all).\n" +
+    "  Example: receive: [{id: '0xobj1', type: '0x2::coin::Coin<0x2::sui::SUI>'}]\n" +
+    "• ReceivedBalance ({token_type, balance, received: [{id, balance, payment}]}) —\n" +
+    "  receive a balance record from a specific Payment/payer.\n" +
+    "  Use this for precise balance targeting (advanced — usually after querying\n" +
+    "  the object's received history via query_received).\n" +
+    "  Example: receive: {token_type: '0x2::sui::SUI', balance: 1000000, received: [{id: '0xrec1', balance: 1000000, payment: '0xpay1'}]}\n" +
+    "ANTI-PATTERN: do NOT wrap in {result: ...} — pass the value directly.";
+export const RECEIVE_FORMAT_BLOCK_BALANCE = "\n\nACCEPTED FORMATS (F-06 unified receive operation block):\n" +
+    "• 'recently' (string literal) — auto-query and receive ALL recently received balance.\n" +
+    "  Use this for the common case: \"deposit all recently received coins into pending balance.\"\n" +
+    "  Example: receive: 'recently'\n" +
+    "• ReceivedBalance ({token_type, balance, received: [{id, balance, payment}]}) —\n" +
+    "  receive a specific balance record from a Payment/payer.\n" +
+    "  Use this when targeting a specific received balance (advanced).\n" +
+    "  Example: receive: {token_type: '0x2::sui::SUI', balance: 1000000, received: [{id: '0xrec1', balance: 1000000, payment: '0xpay1'}]}\n" +
+    "ANTI-PATTERN: do NOT wrap in {result: ...} — pass the value directly.";
 export const QueryReceivedResultSchema = z.object({
     result: z.union([
         ReceivedBalanceSchema,

package/dist/schema/local/index.js

@@ -568,7 +568,11 @@ export const AccountOperationSchema = z
 })
     .strict()
     .refine((data) => Object.keys(data).length > 0, "At least one operation (gen/faucet/suspend/resume/rename/swap_name/transfer/get/signData/messenger) must be specified")
-    .describe("Account operations. Parameters MUST be wrapped in the operation type property (e.g. {transfer: {...}}, NOT {amount: ...}). Unwrapped parameters are rejected.");
+    .describe("Account operations (mutations only: gen/faucet/suspend/resume/rename/swap_name/transfer/get/signData/messenger). " +
+    "Parameters MUST be wrapped in the operation type property (e.g. {transfer: {...}}, NOT {amount: ...}). Unwrapped parameters are rejected. " +
+    "TO LIST ALL ACCOUNTS: use the query_toolkit tool with query_type='account_list' (returns name, address, suspended status, messenger status for all local accounts). " +
+    "This separation follows CQRS: account_operation = mutations, query_toolkit = queries. " +
+    "Common workflow after MCP restart: (1) query_toolkit query_type='account_list' to see all accounts, (2) account_operation with the appropriate mutation.");
 export const AccountOperationResultSchema = z
     .object({
     gen: z

package/dist/schema/messenger/index.js

@@ -378,7 +378,10 @@ export const MessengerOperationInputSchema = z.discriminatedUnion("operation", [
         account: NameOrAddressSchema.optional().describe("Account name or address. If not specified, uses default account"),
         limit: z.number().optional().describe("Maximum number of messages to pull from server"),
     }).strict(),
-]).describe("Messenger operation input schema");
+]).describe("Messenger operation input schema. PREREQUISITE: an account must ENABLE messenger before sending/receiving. " +
+    "There is NO 'enable' operation in this tool — enable via account_operation {messenger: {enabled: true, name_or_account: '<account>'}}, " +
+    "or implicitly via send_message/send_file with options.enable_messenger: true. " +
+    "Use proof_message to anchor a message's WTS proof on-chain (creates a Proof object consumable by Guards via proof.signer/proof.time queries).");
 export const MessengerOperationOutputSchema = z.object({
     result: z.discriminatedUnion("operation", [
         z.object({