@wowok/agent-mcp 2.3.16 → 2.4.1

package/dist/knowledge/guard-templates.d.ts

@@ -0,0 +1,37 @@
+export type TemplateParamType = "address" | "string" | "number" | "boolean" | "vec_address";
+export interface GuardTemplateParam {
+    name: string;
+    type: TemplateParamType;
+    description: string;
+    required: boolean;
+    default?: string;
+    constraint?: string;
+}
+export interface GuardTemplate {
+    id: string;
+    scene_id: string;
+    name: string;
+    description: string;
+    recommended_patterns: string[];
+    parameters: GuardTemplateParam[];
+    example_table: object;
+    example_root: object;
+    applicable_industries: string[];
+    relevant_risks: string[];
+    creation_notes: string[];
+    example_use_case: string;
+}
+export declare const GUARD_TEMPLATES: GuardTemplate[];
+export declare function getTemplatesByScene(sceneId: string): GuardTemplate[];
+export declare function getTemplateById(templateId: string): GuardTemplate | undefined;
+export declare function getTemplatesByIndustry(industry: string): GuardTemplate[];
+export declare function getTemplatesByPattern(patternId: string): GuardTemplate[];
+export declare function listGuardTemplates(): GuardTemplate[];
+export declare function suggestTemplateForScene(sceneId: string): GuardTemplate | undefined;
+export declare function getTemplateParameters(templateId: string): GuardTemplateParam[];
+export declare function validateTemplateParams(templateId: string, params: Record<string, unknown>): {
+    valid: boolean;
+    missing: string[];
+};
+export declare const GUARD_TEMPLATES_VERSION = "1.0.0";
+export declare const GUARD_TEMPLATES_COUNT: number;

package/dist/knowledge/guard-templates.js

@@ -0,0 +1,329 @@
+export const GUARD_TEMPLATES = [
+    {
+        id: "tpl_buy_guard_whitelist",
+        scene_id: "service_buy_guard",
+        name: "Whitelist purchase validation",
+        description: "Only addresses in the whitelist can purchase the service. Suitable for limited-time sales, VIP exclusives, internal testing eligibility, etc.",
+        recommended_patterns: ["P04", "P03"],
+        parameters: [
+            { name: "whitelist", type: "vec_address", description: "List of authorized addresses", required: true,
+                constraint: "Each address must be valid and unique" },
+            { name: "service_name", type: "string", description: "Service object name (used for circular references)", required: false,
+                constraint: "If P16 circular reference is used, a name must be provided rather than an address" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: false, value_type: "Vec<Address>", value: "${whitelist}", name: "Authorized purchase whitelist" },
+        ],
+        example_root: {
+            type: "vec_contains_address",
+            vec: { type: "identifier", identifier: 0 },
+            target: { type: "context", context: "Signer" },
+        },
+        applicable_industries: ["rental", "ecommerce", "education", "travel", "subscription"],
+        relevant_risks: ["R-C1-01", "R-C3-01", "R-C4-01"],
+        creation_notes: [
+            "Updating the whitelist requires rebuilding the Guard (buy_guard is iterable)",
+            "If the Service is already published, the table can use the address directly; otherwise use the name (P16 circular reference)",
+        ],
+        example_use_case: "Internal testing phase for camera equipment rental, allowing only the first 50 seed users to place rental orders.",
+    },
+    {
+        id: "tpl_allocator_threshold",
+        scene_id: "service_order_allocators_guard",
+        name: "Allocation amount threshold validation",
+        description: "Selects different allocation strategies based on the order amount. When the amount exceeds the threshold, advanced allocation is used; otherwise, default allocation applies.",
+        recommended_patterns: ["P02", "P10"],
+        parameters: [
+            { name: "threshold", type: "number", description: "Allocation threshold (unit: smallest precision)", required: true,
+                constraint: "Must be > 0; a reasonable range is recommended to avoid boundary gaming" },
+            { name: "service_name", type: "string", description: "Service object name", required: true },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: false, value_type: "Address", value: "${service_name}", name: "Service object" },
+            { identifier: 1, b_submission: false, value_type: "U64", value: "${threshold}", name: "Allocation threshold" },
+        ],
+        example_root: {
+            type: "logic_as_u256_greater",
+            left: { type: "query", query: "order.amount", object: { identifier: 0 }, parameters: [] },
+            right: { type: "identifier", identifier: 1 },
+        },
+        applicable_industries: ["ecommerce", "rental", "education", "travel"],
+        relevant_risks: ["R-X1-01", "R-X1-05", "R-X1-08"],
+        creation_notes: [
+            "order_allocators cannot be modified after binding (immutable after publish)",
+            "First-match-wins mechanism: multiple allocators are matched in order; the first one that passes executes",
+            "Threshold boundary must be tested: behavior when exactly equal to the threshold (> vs >=)",
+        ],
+        example_use_case: "E-commerce platform: order amount > 1000 WOW triggers 3-way allocation (platform + merchant + logistics); otherwise 2-way allocation (platform + merchant).",
+    },
+    {
+        id: "tpl_forward_node_check",
+        scene_id: "machine_forward_guard",
+        name: "Workflow node state validation",
+        description: "Verifies that the order is currently at the correct Machine node before advancing to the next step. Prevents skipping nodes or reverse operations.",
+        recommended_patterns: ["P06", "P09"],
+        parameters: [
+            { name: "expected_node", type: "string", description: "Expected current node name", required: true,
+                constraint: "Must exactly match the name defined in Machine nodes (case-sensitive)" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address", name: "Order object address",
+                object_type: "Order" },
+            { identifier: 1, b_submission: false, value_type: "String", value: "${expected_node}",
+                name: "Expected current node name" },
+        ],
+        example_root: {
+            type: "logic_equal",
+            left: {
+                type: "query", query: "progress.current_node_name",
+                object: { identifier: 0, convert_witness: 100 },
+                parameters: [],
+            },
+            right: { type: "identifier", identifier: 1 },
+        },
+        applicable_industries: ["rental", "ecommerce", "education", "travel", "subscription"],
+        relevant_risks: ["R-C2-01", "R-C2-03", "R-X1-08"],
+        creation_notes: [
+            "Forward.guard cannot be modified after binding (immutable after Machine publish)",
+            "witness 100 (Order→Progress) is a single hop; no risk of chained-derivation breakage",
+            "Node names are case-sensitive; query returns a String type",
+        ],
+        example_use_case: "Camera equipment rental flow: the user must be at the 'pending return' node to perform the return operation.",
+    },
+    {
+        id: "tpl_submission_signer_binding",
+        scene_id: "progress_submission_guard",
+        name: "Submission data signer binding validation",
+        description: "Verifies that the user submitting the data is a legitimate Progress participant and that the submitted value matches expectations.",
+        recommended_patterns: ["P08", "P15"],
+        parameters: [
+            { name: "expected_value", type: "string", description: "Expected submitted value (e.g. node name, status code)", required: true },
+            { name: "provider_address", type: "address", description: "Service provider address (used for identity verification)", required: true },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "String",
+                name: "User-submitted operation type (e.g. 'return' / 'damage')",
+                binding_constraint: "Must be one of the predefined operation types" },
+            { identifier: 1, b_submission: false, value_type: "Address",
+                value: "${provider_address}", name: "Service provider address" },
+            { identifier: 2, b_submission: false, value_type: "String",
+                value: "${expected_value}", name: "Expected submitted value" },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                { type: "logic_equal",
+                    nodes: [{ type: "identifier", identifier: 0 }, { type: "identifier", identifier: 2 }] },
+                { type: "logic_equal",
+                    nodes: [{ type: "context", context: "Signer" }, { type: "identifier", identifier: 1 }] },
+            ],
+        },
+        applicable_industries: ["rental", "ecommerce", "education", "travel"],
+        relevant_risks: ["R-C3-01", "R-C3-03", "R-X1-12"],
+        creation_notes: [
+            "submission guard cannot be modified after binding",
+            "The name of b_submission=true entries must be a complete natural-language description (≥10 characters)",
+            "Providing a binding_constraint field describing value rules is recommended (R-X1-12)",
+        ],
+        example_use_case: "On equipment return, the user submits the 'return' operation; the Guard verifies that the submitter is the service provider and that the operation type is correct.",
+    },
+    {
+        id: "tpl_reward_one_time_claim",
+        scene_id: "reward_guard",
+        name: "One-time reward claim validation",
+        description: "Verifies that the user is claiming the reward for the first time, preventing duplicate claims. Implemented by querying the historical record count via Repository.",
+        recommended_patterns: ["P07", "P13"],
+        parameters: [
+            { name: "repository_address", type: "address", description: "Repository object address (stores claim records)", required: true },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: false, value_type: "Address",
+                value: "${repository_address}", name: "Reward claim record Repository",
+                object_type: "Repository" },
+            { identifier: 1, b_submission: false, value_type: "U64",
+                value: "0", name: "First-claim threshold (record_count == 0)" },
+        ],
+        example_root: {
+            type: "logic_equal",
+            left: {
+                type: "query", query: "repository.data",
+                object: { identifier: 0 },
+                parameters: [{ type: "context", context: "Signer" }],
+            },
+            right: { type: "identifier", identifier: 1 },
+        },
+        applicable_industries: ["ecommerce", "education", "travel", "subscription"],
+        relevant_risks: ["R-C1-03", "R-X1-01", "R-X1-10"],
+        creation_notes: [
+            "Repository queries require quote_guard==None (otherwise impack_list is empty, causing IMPACK_GUARD_NOT_FOUND)",
+            "repository.data query returns U64 (record count), compared with identifier[1] (value 0)",
+            "Reward guard is iterable; duplicate-claim protection requires rebuilding the Guard to update the Repository address",
+        ],
+        example_use_case: "New-user first-order reward: query the user's historical order count via Repository; allow claim only when record_count==0.",
+    },
+    {
+        id: "tpl_write_guard_type_check",
+        scene_id: "repository_write_guard",
+        name: "Storage write type validation",
+        description: "Verifies that the data type written to the Repository matches the declaration and that the writer's identity is legitimate.",
+        recommended_patterns: ["P08", "P11"],
+        parameters: [
+            { name: "repository_address", type: "address", description: "Repository object address", required: true,
+                constraint: "Must be the address of an already-published Repository" },
+            { name: "entity_registrar", type: "address", description: "EntityRegistrar address (fixed 0xaab)", required: false,
+                default: "0xaab" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address",
+                name: "Writer address (submitted by caller)",
+                binding_constraint: "Must be a valid Entity address" },
+            { identifier: 1, b_submission: true, value_type: "String",
+                name: "Write data key name (submitted by caller)",
+                binding_constraint: "Key name format must be 'category:key'" },
+            { identifier: 2, b_submission: false, value_type: "Address",
+                value: "${entity_registrar}", name: "EntityRegistrar system address",
+                is_system_address: true },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                { type: "logic_equal",
+                    nodes: [{ type: "context", context: "Signer" }, { type: "identifier", identifier: 0 }] },
+                { type: "logic_not_equal",
+                    nodes: [{ type: "identifier", identifier: 0 }, { type: "identifier", identifier: 2 }] },
+            ],
+        },
+        applicable_industries: ["ecommerce", "education", "travel", "subscription", "rental"],
+        relevant_risks: ["R-C1-02", "R-C3-03", "R-C3-04"],
+        creation_notes: [
+            "id_from_submission in write_guard must be of Address type",
+            "data_from_submission must match the Repository value_type",
+            "EntityRegistrar (0xaab) and EntityLinker (0xaaa) are fixed system addresses",
+        ],
+        example_use_case: "E-commerce platform merchant writes product review data; the Guard verifies that the writer is a registered Entity and not a system address.",
+    },
+    {
+        id: "tpl_usage_guard_threshold",
+        scene_id: "arbitration_usage_guard",
+        name: "Dispute initiation threshold validation",
+        description: "Verifies that the dispute initiator meets minimum conditions (e.g. order amount, time window), filtering out meaningless disputes.",
+        recommended_patterns: ["P02", "P10"],
+        parameters: [
+            { name: "min_amount", type: "number", description: "Minimum dispute amount threshold", required: true,
+                constraint: "A reasonable threshold is recommended; too high hinders user rights protection, too low produces many invalid disputes" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address",
+                name: "Dispute-related Order object address", object_type: "Order" },
+            { identifier: 1, b_submission: false, value_type: "U64",
+                value: "${min_amount}", name: "Minimum dispute amount threshold" },
+        ],
+        example_root: {
+            type: "logic_as_u256_greater_or_equal",
+            left: { type: "query", query: "order.amount", object: { identifier: 0 }, parameters: [] },
+            right: { type: "identifier", identifier: 1 },
+        },
+        applicable_industries: ["ecommerce", "rental", "education", "travel"],
+        relevant_risks: ["R-X1-01", "R-X1-07", "R-C3-03"],
+        creation_notes: [
+            "usage_guard is iterable (Arbitration can be updated)",
+            "AND conditions should not be too many (R-X1-07); ≤3 conditions recommended",
+            "When Arbitration bPaused=true, blocking takes priority (checked before Guard)",
+        ],
+        example_use_case: "Rental service dispute: only disputes with order amount ≥ 10 WOW are accepted, filtering out small-amount conflicts.",
+    },
+    {
+        id: "tpl_voting_guard_numeric_weight",
+        scene_id: "arbitration_voting_guard",
+        name: "Numeric voting weight validation",
+        description: "Assigns numeric voting weights based on arbitrator rank; higher-rank arbitrators have greater weight.",
+        recommended_patterns: ["P12"],
+        parameters: [
+            { name: "arbiter_weights", type: "vec_address", description: "Arbitrator address to weight mapping (address:weight pairs)", required: true,
+                constraint: "Weights must be numeric types U8-U256" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address",
+                name: "Arbitrator address (submitted by caller)", object_type: "Arb" },
+            { identifier: 1, b_submission: false, value_type: "Vec<Address>",
+                value: "${arbiter_weights}", name: "Authorized arbitrator address list" },
+        ],
+        example_root: {
+            type: "vec_contains_address",
+            vec: { type: "identifier", identifier: 1 },
+            target: { type: "identifier", identifier: 0 },
+        },
+        applicable_industries: ["ecommerce", "rental", "education", "travel"],
+        relevant_risks: ["R-C3-02", "R-C2-01", "R-C2-02"],
+        creation_notes: [
+            "The GuardIdentifier for voting_guard must be numeric (U8-U256), otherwise E_GUARD_IDENTIFIER_NOT_NUMBER",
+            "Weights from submitted data (b_submission=true) carry forgery risk (R-C3-02 critical)",
+            "Deriving weights from the Arb object via witness is recommended, rather than submitting them directly",
+        ],
+        example_use_case: "3-person arbitration panel: chief arbitrator weight 3, regular arbitrators weight 1, majority vote decision.",
+    },
+    {
+        id: "tpl_gen_passport_identity",
+        scene_id: "gen_passport_guard",
+        name: "Passport identity credential generation validation",
+        description: "Standalone Guard; after verifying the user's identity, generates a Passport with a credential, used as submission data for subsequent operations.",
+        recommended_patterns: ["P03", "P14"],
+        parameters: [
+            { name: "authorized_address", type: "address", description: "Authorized address (or use Vec<Address> whitelist)", required: true },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: false, value_type: "Address",
+                value: "${authorized_address}", name: "Authorized address" },
+        ],
+        example_root: {
+            type: "logic_equal",
+            nodes: [
+                { type: "context", context: "Signer" },
+                { type: "identifier", identifier: 0 },
+            ],
+        },
+        applicable_industries: ["ecommerce", "education", "travel", "subscription", "rental"],
+        relevant_risks: ["R-C1-01", "R-X1-10", "R-X1-13"],
+        creation_notes: [
+            "gen_passport is a standalone Guard; it does not bind a Host Object (host_object: Standalone)",
+            "impack_list is always empty during the verify phase; quote_guard queries will always fail",
+            "The Guard can be depended on by other Guards via rely (requires rep=true)",
+            "The generated Passport can be used as submission data for subsequent operations",
+        ],
+        example_use_case: "After the user passes identity verification, a Passport is generated; this Passport is then submitted as an identity credential in subsequent service purchases.",
+    },
+];
+export function getTemplatesByScene(sceneId) {
+    return GUARD_TEMPLATES.filter((t) => t.scene_id === sceneId);
+}
+export function getTemplateById(templateId) {
+    return GUARD_TEMPLATES.find((t) => t.id === templateId);
+}
+export function getTemplatesByIndustry(industry) {
+    return GUARD_TEMPLATES.filter((t) => t.applicable_industries.includes(industry));
+}
+export function getTemplatesByPattern(patternId) {
+    return GUARD_TEMPLATES.filter((t) => t.recommended_patterns.includes(patternId));
+}
+export function listGuardTemplates() {
+    return GUARD_TEMPLATES;
+}
+export function suggestTemplateForScene(sceneId) {
+    return GUARD_TEMPLATES.find((t) => t.scene_id === sceneId);
+}
+export function getTemplateParameters(templateId) {
+    const template = getTemplateById(templateId);
+    return template?.parameters ?? [];
+}
+export function validateTemplateParams(templateId, params) {
+    const template = getTemplateById(templateId);
+    if (!template) {
+        return { valid: false, missing: ["template_not_found"] };
+    }
+    const missing = template.parameters
+        .filter((p) => p.required && !(p.name in params))
+        .map((p) => p.name);
+    return { valid: missing.length === 0, missing };
+}
+export const GUARD_TEMPLATES_VERSION = "1.0.0";
+export const GUARD_TEMPLATES_COUNT = GUARD_TEMPLATES.length;

package/dist/knowledge/guard-translation.d.ts

@@ -0,0 +1,58 @@
+export interface SemanticToSchemaRule {
+    id: string;
+    pattern_name: string;
+    data_source_combination: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_elements: {
+        root_type: string;
+        table_entries: Array<{
+            value_type: string;
+            b_submission: boolean;
+            purpose: string;
+        }>;
+        query_nodes?: Array<{
+            query_name: string;
+            object_type: string;
+            convert_witness?: number;
+        }>;
+        context_nodes?: Array<{
+            context_type: "Signer" | "Clock" | "Guard";
+            purpose: string;
+        }>;
+        tree_structure: string;
+    };
+    constraints: string[];
+    example: Record<string, unknown>;
+}
+export declare const SEMANTIC_TO_SCHEMA_RULES: SemanticToSchemaRule[];
+export interface SchemaToSemanticRule {
+    element_type: "node" | "table_entry" | "query" | "witness" | "rely" | "context";
+    type_name: string;
+    semantic: string;
+    return_type?: string;
+    child_constraints?: string;
+    data_source_class?: "Type1_OnChainConstant" | "Type2_WitnessDerived" | "Type3_SubmittedObject" | "Type4_SystemContext";
+    discovery_tool?: string;
+}
+export declare const SCHEMA_TO_SEMANTIC_RULES: SchemaToSemanticRule[];
+export interface GuardConstraintRule {
+    id: string;
+    name: string;
+    description: string;
+    category: "root" | "table" | "query" | "witness" | "rely" | "binding" | "input" | "immutable" | "runtime";
+    phase: "creation" | "runtime";
+    validation_logic: string;
+    failure_message: string;
+    verification_location: string;
+    pitfall_number?: number;
+}
+export declare const GUARD_CONSTRAINT_RULES: GuardConstraintRule[];
+export declare function matchSemanticPattern(userIntent: string): SemanticToSchemaRule[];
+export declare function explainNode(nodeType: string): SchemaToSemanticRule | undefined;
+export declare function explainWitness(witnessType: number): SchemaToSemanticRule | undefined;
+export declare function explainContext(contextType: string): SchemaToSemanticRule | undefined;
+export declare function getConstraintsByCategory(category: GuardConstraintRule["category"]): GuardConstraintRule[];
+export declare function getConstraintsByPhase(phase: GuardConstraintRule["phase"]): GuardConstraintRule[];
+export declare function getPatternById(id: string): SemanticToSchemaRule | undefined;
+export declare function getDataSourceCombinations(): string[];