@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/arbitration-templates.js

@@ -0,0 +1,276 @@
+export const ARBITRATION_TEMPLATES = [
+    {
+        id: "T-AB-01",
+        name: "Single-arbiter quick ruling",
+        description: "Simplest Arbitration: one arbiter makes all rulings. voting_guard empty (open vote, but only arbiter has 358 perm). Suitable for small-scale / fast dispute resolution.",
+        applicable_scenes: ["arbitration_create", "arbitration_ruling", "arbitration_confirm"],
+        industry_tags: ["retail", "freelance", "small_business"],
+        params: [
+            { name: "owner_address", type: "address", description: "Arbitration owner (also admin)", required: true },
+            { name: "arbiter_address", type: "address", description: "Single arbiter address (gets ARBITRATION_VOTE=358 + ARBITRATION_ARBITRATION=359)", required: true },
+            { name: "coin_type", type: "string", description: "Coin type for arbitration fee (e.g. 0x2::wow::WOW)", required: true },
+            { name: "description", type: "string", description: "Arbitration description", required: true },
+            { name: "fee_amount", type: "number", description: "Dispute application fee (u64, in Coin base units)", required: false, default: 0 },
+            { name: "arbitration_name", type: "string", description: "Local name for the Arbitration object", required: false },
+        ],
+        body: (p) => ({
+            object: {
+                name: p.arbitration_name ?? "single_arb_arbitration",
+                type_parameter: p.coin_type,
+                permission: { name: `${p.arbitration_name ?? "single_arb"}_permission` },
+            },
+            description: p.description,
+            fee: String(p.fee_amount ?? 0),
+            pause: false,
+        }),
+        notes: [
+            "voting_guard remains empty → vote() uses open vote (1 person 1 vote)",
+            "Only arbiter_address should be granted ARBITRATION_VOTE (358) + ARBITRATION_ARBITRATION (359)",
+            "Fast ruling: arbiter confirms materials → votes → makes ruling in one session",
+            "Not suitable for high-value disputes (no consensus check)",
+        ],
+    },
+    {
+        id: "T-AB-02",
+        name: "Multi-arbiter voting (weighted)",
+        description: "Multiple arbiters vote with weighted voting_guard. Each arbiter's Guard has FixedValue weight. Ruling requires majority weight.",
+        applicable_scenes: ["arbitration_create", "arbitration_vote", "arbitration_voting_guard_config"],
+        industry_tags: ["governance", "dao", "committee"],
+        params: [
+            { name: "owner_address", type: "address", description: "Arbitration owner", required: true },
+            { name: "arbiter_guards", type: "string[]", description: "Guard addresses for each arbiter (will be added to voting_guard)", required: true },
+            { name: "vote_weights", type: "string[]", description: "FixedValue weights for each arbiter (parallel to arbiter_guards)", required: true },
+            { name: "coin_type", type: "string", description: "Coin type", required: true },
+            { name: "description", type: "string", description: "Arbitration description", required: true },
+            { name: "fee_amount", type: "number", description: "Dispute fee", required: false, default: 0 },
+        ],
+        body: (p) => {
+            const guards = p.arbiter_guards.map((guard, i) => ({
+                guard,
+                vote_weight: { FixedValue: Number(p.vote_weights[i] ?? 1) },
+            }));
+            return {
+                object: {
+                    name: "weighted_arbitration",
+                    type_parameter: p.coin_type,
+                    permission: { name: "weighted_arb_permission" },
+                },
+                description: p.description,
+                fee: String(p.fee_amount ?? 0),
+                pause: false,
+                voting_guard: {
+                    op: "set",
+                    guards,
+                },
+            };
+        },
+        notes: [
+            "voting_guard non-empty → vote MUST use vote_with_voting_guard",
+            "Each arbiter's Guard must be a valid Guard object they can submit Passport for",
+            "Consider: max(arbiter_weights) / total_weights < 0.5 to avoid collusion (see R-AB-3-01)",
+            "Max 50 voting_guards (MAX_VOTING_GUARD_COUNT)",
+        ],
+    },
+    {
+        id: "T-AB-03",
+        name: "Public voting arbitration",
+        description: "voting_guard allows public to vote (anyone with a Guard can vote). Suitable for community-driven dispute resolution.",
+        applicable_scenes: ["arbitration_create", "arbitration_vote", "arbitration_voting_guard_config"],
+        industry_tags: ["community", "public_goods", "social"],
+        params: [
+            { name: "owner_address", type: "address", description: "Arbitration owner", required: true },
+            { name: "public_guard", type: "address", description: "Guard address anyone can submit Passport for (e.g. based on account existence)", required: true },
+            { name: "vote_weight", type: "number", description: "FixedValue weight per public voter (e.g. 1)", required: false, default: 1 },
+            { name: "coin_type", type: "string", description: "Coin type", required: true },
+            { name: "description", type: "string", description: "Arbitration description", required: true },
+        ],
+        body: (p) => ({
+            object: {
+                name: "public_arbitration",
+                type_parameter: p.coin_type,
+                permission: { name: "public_arb_permission" },
+            },
+            description: p.description,
+            fee: "0",
+            pause: false,
+            voting_guard: {
+                op: "set",
+                guards: [
+                    { guard: p.public_guard, vote_weight: { FixedValue: Number(p.vote_weight ?? 1) } },
+                ],
+            },
+        }),
+        notes: [
+            "Public voting: anyone holding the public_guard can vote",
+            "Consider using GuardIdentifier (dynamic weight) for token-weighted voting",
+            "Low/zero fee to encourage participation — but watch for spam disputes",
+            "Suitable for community moderation, content disputes, public goods arbitration",
+        ],
+    },
+    {
+        id: "T-AB-04",
+        name: "Scope-restricted arbitration",
+        description: "usage_guard filters which disputes can be filed. Only users passing the Guard can file disputes. Suitable for verified-merchant / KYC arbitration.",
+        applicable_scenes: ["arbitration_create", "arbitration_usage_guard_config", "arbitration_dispute"],
+        industry_tags: ["kyc", "verified_merchant", "enterprise"],
+        params: [
+            { name: "owner_address", type: "address", description: "Arbitration owner", required: true },
+            { name: "usage_guard_address", type: "address", description: "Guard address that filters who can file disputes (KYC/verification)", required: true },
+            { name: "coin_type", type: "string", description: "Coin type", required: true },
+            { name: "description", type: "string", description: "Arbitration description", required: true },
+            { name: "arbiter_address", type: "address", description: "Arbiter address (single arbiter for simplicity)", required: true },
+            { name: "fee_amount", type: "number", description: "Dispute fee (higher to deter spam)", required: false, default: 1000000000 },
+        ],
+        body: (p) => ({
+            object: {
+                name: "restricted_arbitration",
+                type_parameter: p.coin_type,
+                permission: { name: "restricted_arb_permission" },
+            },
+            description: p.description,
+            fee: String(p.fee_amount ?? 1000000000),
+            pause: false,
+            usage_guard: p.usage_guard_address,
+        }),
+        notes: [
+            "usage_guard set → dispute MUST use dispute_with_passport variant",
+            "Guard verifies: KYC / membership / token-balance / etc.",
+            "Higher fee (default 1 WOW) to deter spam from verified users",
+            "Arbiter should also be Guard-verified for consistency",
+        ],
+    },
+    {
+        id: "T-AB-05",
+        name: "Arbitration committee",
+        description: "Multi-arbiter committee with weighted voting + usage_guard. Most controlled configuration — restricted dispute filing + weighted voting + multi-arbiter ruling.",
+        applicable_scenes: ["arbitration_create", "arbitration_voting_guard_config", "arbitration_usage_guard_config", "arbitration_ruling"],
+        industry_tags: ["enterprise", "legal", "high_value"],
+        params: [
+            { name: "owner_address", type: "address", description: "Committee owner", required: true },
+            { name: "committee_guards", type: "string[]", description: "Guard addresses for each committee member", required: true },
+            { name: "member_weights", type: "string[]", description: "Vote weights for each member (parallel to committee_guards)", required: true },
+            { name: "membership_guard", type: "address", description: "usage_guard for dispute filing (membership verification)", required: true },
+            { name: "coin_type", type: "string", description: "Coin type", required: true },
+            { name: "description", type: "string", description: "Arbitration description", required: true },
+            { name: "fee_amount", type: "number", description: "Dispute fee (high for high-value disputes)", required: false, default: 10000000000 },
+        ],
+        body: (p) => {
+            const guards = p.committee_guards.map((guard, i) => ({
+                guard,
+                vote_weight: { FixedValue: Number(p.member_weights[i] ?? 1) },
+            }));
+            return {
+                object: {
+                    name: "committee_arbitration",
+                    type_parameter: p.coin_type,
+                    permission: { name: "committee_arb_permission" },
+                },
+                description: p.description,
+                fee: String(p.fee_amount ?? 10000000000),
+                pause: false,
+                voting_guard: { op: "set", guards },
+                usage_guard: p.membership_guard,
+            };
+        },
+        notes: [
+            "Most restrictive config: weighted voting + restricted filing",
+            "Suitable for high-value B2B disputes, legal arbitration, enterprise SLA enforcement",
+            "Committee members should have clear escalation / tiebreaker rules",
+            "All disputes require Passport (both filing and voting)",
+        ],
+    },
+    {
+        id: "T-AB-06",
+        name: "Fee-split arbitration",
+        description: "Pre-configured fees_alloc / fees_transfer destination. After arb_withdraw, fees are automatically distributed to Allocation (for arbiter compensation).",
+        applicable_scenes: ["arbitration_create", "arbitration_arb_withdraw", "arbitration_fees_alloc"],
+        industry_tags: ["marketplace", "service", "platform"],
+        params: [
+            { name: "owner_address", type: "address", description: "Arbitration owner", required: true },
+            { name: "allocation_address", type: "address", description: "Allocation object address for fee distribution to arbiters", required: true },
+            { name: "coin_type", type: "string", description: "Coin type", required: true },
+            { name: "description", type: "string", description: "Arbitration description", required: true },
+            { name: "arbiter_address", type: "address", description: "Arbiter (single for simplicity)", required: true },
+            { name: "fee_amount", type: "number", description: "Dispute fee (will be split to arbiters via Allocation)", required: false, default: 5000000000 },
+        ],
+        body: (p) => ({
+            object: {
+                name: "feesplit_arbitration",
+                type_parameter: p.coin_type,
+                permission: { name: "feesplit_arb_permission" },
+            },
+            description: p.description,
+            fee: String(p.fee_amount ?? 5000000000),
+            pause: false,
+        }),
+        notes: [
+            "Fee-split is a 2-step process: arb_withdraw → fees_transfer",
+            "arb_withdraw (364) moves fees from Arb → Arbitration.balance",
+            "fees_alloc (365) or fees_transfer (366) moves fees → Allocation/Treasury",
+            "Allocation policy determines how fees are split among arbiters",
+            "Payment object is created for bookkeeping (payment_remark + payment_index)",
+        ],
+    },
+    {
+        id: "T-AB-07",
+        name: "Appeal arbitration (reset flow)",
+        description: "Template for reset operation — disputant objects to ruling and resubmits materials. Restarts Arb lifecycle from Principal_confirming.",
+        applicable_scenes: ["arbitration_reset", "arbitration_ruling"],
+        industry_tags: ["legal", "appeal", "high_value"],
+        params: [
+            { name: "arbitration_address", type: "address", description: "Existing Arbitration object address", required: true },
+            { name: "arb_address", type: "address", description: "Arb object address to reset (must be in Objectionable/Arbitrated status)", required: true },
+            { name: "reset_feedback", type: "string", description: "Feedback explaining why disputant objects to the ruling", required: true },
+        ],
+        body: (p) => ({
+            object: p.arbitration_address,
+            reset: {
+                arb: p.arb_address,
+                feedback: p.reset_feedback,
+            },
+        }),
+        notes: [
+            "Precondition: Arb must be in Objectionable (4) or Arbitrated (3) status",
+            "Post-condition: Arb status → Principal_confirming (0), lifecycle restarts",
+            "Original ruling is invalidated — new voting + ruling required",
+            "Consider capping reset count to prevent infinite appeals",
+            "reset feedback is permanent — recorded on-chain for audit trail",
+        ],
+    },
+];
+export const ARBITRATION_TEMPLATES_VERSION = "1.0.0";
+export function getAllTemplates() {
+    return [...ARBITRATION_TEMPLATES];
+}
+export function getTemplateById(id) {
+    return ARBITRATION_TEMPLATES.find(t => t.id === id);
+}
+export function getTemplatesByScene(sceneId) {
+    return ARBITRATION_TEMPLATES.filter(t => t.applicable_scenes.includes(sceneId));
+}
+export function getTemplatesByIndustry(industry) {
+    return ARBITRATION_TEMPLATES.filter(t => t.industry_tags.includes(industry) || t.industry_tags.includes("universal"));
+}
+export function suggestTemplateForScene(sceneId) {
+    const matches = getTemplatesByScene(sceneId);
+    return matches.length > 0 ? matches[0] : undefined;
+}
+export function listTemplates() {
+    return ARBITRATION_TEMPLATES.map(t => ({
+        id: t.id,
+        name: t.name,
+        description: t.description,
+        scenes: t.applicable_scenes,
+    }));
+}
+export function fillTemplate(templateId, params) {
+    const tpl = getTemplateById(templateId);
+    if (!tpl)
+        return { ok: false, error: `Template ${templateId} not found` };
+    for (const p of tpl.params) {
+        if (p.required && !(p.name in params)) {
+            return { ok: false, error: `Missing required param: ${p.name}` };
+        }
+    }
+    return { ok: true, body: tpl.body(params) };
+}

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

@@ -0,0 +1,91 @@
+import { type ArbStatus } from "./arbitration-ledger.js";
+export interface SemanticToSchemaRule {
+    id: string;
+    pattern_name: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_fields: string[];
+    example_json: object;
+    reverse_explanation: string;
+}
+export interface SchemaToSemanticRule {
+    element_type: "field" | "op" | "index" | "status";
+    type_name: string;
+    semantic_explanation: string;
+    constraints?: string[];
+}
+export interface ArbitrationConstraintRule {
+    id: string;
+    category: "structural" | "semantic" | "authority" | "lifecycle" | "cross_object";
+    rule: string;
+    applies_to: string[];
+}
+export declare const SEMANTIC_TO_SCHEMA_RULES: SemanticToSchemaRule[];
+export declare const SCHEMA_TO_SEMANTIC_RULES: SchemaToSemanticRule[];
+export declare const ARBITRATION_CONSTRAINT_RULES: ArbitrationConstraintRule[];
+export declare const ARBITRATION_TRANSLATION_VERSION = "1.0.0";
+export declare function matchSemanticPattern(userIntent: string): SemanticToSchemaRule[];
+export declare function explainArbitrationCallData(data: {
+    object?: string | null | object;
+    description?: string;
+    location?: string;
+    fee?: string | number;
+    pause?: boolean;
+    dispute?: {
+        order: string;
+        description?: string;
+        proposition: string[];
+        fee?: unknown;
+        namedArb?: unknown;
+    };
+    confirm?: {
+        arb: string;
+        voting_deadline: number | null;
+    };
+    voting_deadline_change?: {
+        arb: string;
+        voting_deadline: number | null;
+    };
+    vote?: {
+        arb: string;
+        votes: number[];
+        voting_guard?: string;
+    };
+    feedback?: {
+        arb: string;
+        feedback: string;
+    };
+    arbitration?: {
+        arb: string;
+        feedback: string;
+        indemnity: number;
+    };
+    reset?: {
+        arb: string;
+        feedback: string;
+    };
+    arb_withdraw?: {
+        arb: string;
+    };
+    fees_transfer?: {
+        to: {
+            allocation?: string;
+            treasury?: string;
+        };
+        payment_remark: string;
+        payment_index: number;
+    };
+    usage_guard?: string | null;
+    voting_guard?: {
+        op: string;
+        guards?: unknown[];
+    };
+    um?: string | null;
+    builder?: string;
+}): string;
+export declare function explainField(fieldName: string): SchemaToSemanticRule | undefined;
+export declare function explainOp(opName: string): SchemaToSemanticRule | undefined;
+export declare function explainStatus(statusName: string): SchemaToSemanticRule | undefined;
+export declare function getConstraintsByCategory(category: ArbitrationConstraintRule["category"]): ArbitrationConstraintRule[];
+export declare function explainPermissionIndex(index: number): string;
+export declare function explainArbStatus(status: ArbStatus): string;