@wowok/agent-mcp 2.4.3 → 2.5.0

package/dist/knowledge/reward-puzzle.d.ts

@@ -0,0 +1,97 @@
+import { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD } from "./onchain-constants.js";
+import { resolveGuardConstructor, getGuardConstructorSpec, type RewardBuiltinPermissionEntry, type RewardGuardConstructor, type RewardRecipientType, type RewardAmountType } from "./reward-ledger.js";
+export interface RewardIntentPuzzle {
+    action: "create" | "claim" | "guard_add" | "guard_remove_expired" | "guard_expiration_time_add" | "coin_add" | "receive" | "owner_receive" | "um_set" | "um_none" | "description_set" | "permission_set" | "query";
+    target_reward?: string;
+    rule_sentence: string;
+    failure_conditions: string[];
+}
+export interface RewardConfigPuzzle {
+    coin_type: string;
+    description: string;
+    permission: string;
+    permission_is_new: boolean;
+}
+export interface RewardGuardPuzzle {
+    guard: string;
+    recipient_type: RewardRecipientType;
+    recipient_param?: number | string;
+    amount_type: RewardAmountType;
+    amount_param: number | string;
+    expiration_time?: number | null;
+    store_from_id?: number | null;
+    constructor: RewardGuardConstructor;
+}
+export interface RewardFundsPuzzle {
+    current_balance: string;
+    coin_add_amount?: string;
+    receive_payment?: {
+        payment: string;
+        token_type: string;
+    };
+    claim_amount_estimate?: string;
+    owner_receive_envelope?: string;
+}
+export interface RewardPermissionPuzzle {
+    builtin_indexes_used: RewardBuiltinPermissionEntry[];
+    is_permission_free: boolean;
+    requires_passport: boolean;
+    signer?: string;
+    signer_is_owner?: boolean;
+}
+export interface RewardConstraintChecklist {
+    F_R_01_guard_count_le_200: boolean;
+    F_R_02_record_count_le_5200: boolean;
+    F_R_03_balance_sufficient_for_claim: boolean;
+    F_R_04_guard_not_locked: boolean;
+    F_R_05_guard_not_expired: boolean;
+    F_R_06_recipient_amount_valid_pairing: boolean;
+    F_R_07_coin_type_matches_reward_t: boolean;
+    F_R_08_passport_required_for_claim: boolean;
+}
+export type RewardPuzzleDimension = "A" | "B" | "C" | "D" | "E" | "F";
+export interface RewardPuzzle {
+    intent?: RewardIntentPuzzle;
+    config?: RewardConfigPuzzle;
+    guard?: RewardGuardPuzzle;
+    funds?: RewardFundsPuzzle;
+    permission?: RewardPermissionPuzzle;
+    constraints?: RewardConstraintChecklist;
+}
+export interface RewardPuzzleCompleteness {
+    dimensions: RewardPuzzleDimension[];
+    missing: RewardPuzzleDimension[];
+    missing_details: {
+        dimension: RewardPuzzleDimension;
+        reason: string;
+    }[];
+    complete: boolean;
+    next_step: string;
+}
+export type RewardFieldMutability = "immutable" | "admin_mutable" | "runtime";
+export interface RewardFieldMutabilityEntry {
+    field: string;
+    mutability: RewardFieldMutability;
+    permission_index?: number;
+    set_at_creation: boolean;
+}
+export declare const REWARD_FIELD_MUTABILITY: RewardFieldMutabilityEntry[];
+export declare function initPuzzleFromIntent(intent: Partial<RewardIntentPuzzle>): RewardPuzzle;
+export declare function checkPuzzleCompleteness(puzzle: RewardPuzzle): RewardPuzzleCompleteness;
+export interface RewardConstraintViolation {
+    constraint_id: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+    message: string;
+    current_value?: string | number;
+    limit?: string | number;
+}
+export declare function validateConstraints(puzzle: RewardPuzzle): RewardConstraintViolation[];
+export declare function generateConfirmationText(puzzle: RewardPuzzle): string;
+export declare function resolveBuiltinPermission(index: number): RewardBuiltinPermissionEntry | undefined;
+export declare function requiresGuardConfig(puzzle: RewardPuzzle): boolean;
+export declare function requiresPassport(puzzle: RewardPuzzle): boolean;
+export declare function getRelevantDimensions(action: RewardIntentPuzzle["action"]): RewardPuzzleDimension[];
+export declare function getFieldMutability(field: string): RewardFieldMutabilityEntry | undefined;
+export declare function isAdminMutableField(field: string): boolean;
+export declare function getFieldPermissionIndex(field: string): number | undefined;
+export { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, resolveGuardConstructor, getGuardConstructorSpec, };

package/dist/knowledge/reward-puzzle.js

@@ -0,0 +1,288 @@
+import { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, } from "./onchain-constants.js";
+import { resolveGuardConstructor, getGuardConstructorSpec, } from "./reward-ledger.js";
+export const REWARD_FIELD_MUTABILITY = [
+    { field: "id", mutability: "immutable", set_at_creation: true },
+    { field: "description", mutability: "admin_mutable", permission_index: 151, set_at_creation: true },
+    { field: "guards", mutability: "admin_mutable", permission_index: 152, set_at_creation: true },
+    { field: "balance", mutability: "runtime", set_at_creation: true },
+    { field: "guard_not_added_expiration_time", mutability: "admin_mutable", permission_index: 155, set_at_creation: true },
+    { field: "record", mutability: "runtime", set_at_creation: true },
+    { field: "um", mutability: "admin_mutable", permission_index: 157, set_at_creation: true },
+    { field: "permission", mutability: "admin_mutable", set_at_creation: true },
+];
+export function initPuzzleFromIntent(intent) {
+    const puzzle = {};
+    if (intent.action || intent.rule_sentence) {
+        puzzle.intent = {
+            action: intent.action ?? "create",
+            target_reward: intent.target_reward,
+            rule_sentence: intent.rule_sentence ?? "",
+            failure_conditions: intent.failure_conditions ?? [],
+        };
+    }
+    puzzle.constraints = {
+        F_R_01_guard_count_le_200: true,
+        F_R_02_record_count_le_5200: true,
+        F_R_03_balance_sufficient_for_claim: true,
+        F_R_04_guard_not_locked: true,
+        F_R_05_guard_not_expired: true,
+        F_R_06_recipient_amount_valid_pairing: false,
+        F_R_07_coin_type_matches_reward_t: false,
+        F_R_08_passport_required_for_claim: false,
+    };
+    return puzzle;
+}
+export function checkPuzzleCompleteness(puzzle) {
+    const missing = [];
+    const missing_details = [];
+    if (!puzzle.intent) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "Intent not specified (action + rule_sentence)" });
+    }
+    else if (!puzzle.intent.rule_sentence) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "rule_sentence is empty" });
+    }
+    const action = puzzle.intent?.action;
+    const isQueryOnly = action === "query";
+    const isClaim = action === "claim";
+    if (!isQueryOnly) {
+        if (action === "create") {
+            if (!puzzle.config) {
+                missing.push("B");
+                missing_details.push({ dimension: "B", reason: "Reward config not specified (coin_type + description + permission)" });
+            }
+            else if (!puzzle.config.coin_type) {
+                missing.push("B");
+                missing_details.push({ dimension: "B", reason: "coin_type missing (Reward<T> phantom T)" });
+            }
+            else if (!puzzle.config.permission && !puzzle.config.permission_is_new) {
+                missing.push("B");
+                missing_details.push({ dimension: "B", reason: "permission address missing (or set permission_is_new=true)" });
+            }
+        }
+    }
+    if (action === "guard_add") {
+        if (!puzzle.guard) {
+            missing.push("C");
+            missing_details.push({ dimension: "C", reason: "Guard config not specified (guard + recipient + amount)" });
+        }
+        else if (!puzzle.guard.guard) {
+            missing.push("C");
+            missing_details.push({ dimension: "C", reason: "guard address missing" });
+        }
+        else {
+            const c = resolveGuardConstructor(puzzle.guard.recipient_type, puzzle.guard.amount_type);
+            if (!c) {
+                missing.push("C");
+                missing_details.push({ dimension: "C", reason: `Invalid Recipient × Amount pairing: ${puzzle.guard.recipient_type} × ${puzzle.guard.amount_type}` });
+            }
+        }
+    }
+    if (action === "coin_add" || action === "receive" || action === "claim" || action === "owner_receive") {
+        if (!puzzle.funds) {
+            missing.push("D");
+            missing_details.push({ dimension: "D", reason: "Funds data not specified" });
+        }
+        else if (action === "coin_add" && !puzzle.funds.coin_add_amount) {
+            missing.push("D");
+            missing_details.push({ dimension: "D", reason: "coin_add_amount missing" });
+        }
+        else if (action === "receive" && !puzzle.funds.receive_payment) {
+            missing.push("D");
+            missing_details.push({ dimension: "D", reason: "receive_payment missing (payment address + token_type)" });
+        }
+        else if (action === "owner_receive" && !puzzle.funds.owner_receive_envelope) {
+            missing.push("D");
+            missing_details.push({ dimension: "D", reason: "owner_receive_envelope missing (Receiving<K> address)" });
+        }
+    }
+    if (!puzzle.permission) {
+        missing.push("E");
+        missing_details.push({ dimension: "E", reason: "Permission config not specified" });
+    }
+    else if (isClaim && !puzzle.permission.requires_passport) {
+        missing.push("E");
+        missing_details.push({ dimension: "E", reason: "claim requires Passport (requires_passport must be true)" });
+    }
+    if (!puzzle.constraints) {
+        missing.push("F");
+        missing_details.push({ dimension: "F", reason: "Constraints not checked" });
+    }
+    return {
+        dimensions: ["A", "B", "C", "D", "E", "F"],
+        missing,
+        missing_details,
+        complete: missing.length === 0,
+        next_step: missing.length === 0
+            ? "Puzzle complete — ready for confirmation text generation"
+            : `Next: complete dimension ${missing[0]} — ${missing_details[0].reason}`,
+    };
+}
+export function validateConstraints(puzzle) {
+    const violations = [];
+    if (puzzle.intent?.action === "claim" && puzzle.funds && puzzle.constraints) {
+        if (!puzzle.constraints.F_R_03_balance_sufficient_for_claim) {
+            violations.push({
+                constraint_id: "F-R-03",
+                severity: "HIGH",
+                message: "Balance insufficient for claim — E_INSUFFICIENT_BALANCE will abort",
+                current_value: puzzle.funds.current_balance,
+                limit: puzzle.funds.claim_amount_estimate,
+            });
+        }
+    }
+    if (puzzle.intent?.action === "guard_add" && puzzle.constraints && !puzzle.constraints.F_R_04_guard_not_locked) {
+        violations.push({
+            constraint_id: "F-R-04",
+            severity: "HIGH",
+            message: "guard_not_added_expiration_time is in the future — E_GUARD_LOCKED_TIME will abort guard_add",
+        });
+    }
+    if ((puzzle.intent?.action === "guard_add" || puzzle.intent?.action === "claim") &&
+        puzzle.constraints && !puzzle.constraints.F_R_05_guard_not_expired) {
+        violations.push({
+            constraint_id: "F-R-05",
+            severity: "HIGH",
+            message: "guard.expiration_time < now — E_GUARD_EXPIRED will abort",
+        });
+    }
+    if (puzzle.guard) {
+        const c = resolveGuardConstructor(puzzle.guard.recipient_type, puzzle.guard.amount_type);
+        if (!c) {
+            violations.push({
+                constraint_id: "F-R-06",
+                severity: "HIGH",
+                message: `Invalid Recipient × Amount pairing: ${puzzle.guard.recipient_type} × ${puzzle.guard.amount_type} — no matching Move constructor`,
+                current_value: `${puzzle.guard.recipient_type} × ${puzzle.guard.amount_type}`,
+                limit: "one of 6 valid pairings (see REWARD_GUARD_CONSTRUCTORS)",
+            });
+        }
+    }
+    if (puzzle.intent?.action === "coin_add" && puzzle.config && puzzle.funds && puzzle.constraints) {
+        if (!puzzle.constraints.F_R_07_coin_type_matches_reward_t) {
+            violations.push({
+                constraint_id: "F-R-07",
+                severity: "CRITICAL",
+                message: `coin_add coin type does not match Reward<T> (${puzzle.config.coin_type})`,
+                current_value: puzzle.funds.receive_payment?.token_type ?? "(unknown)",
+                limit: puzzle.config.coin_type,
+            });
+        }
+    }
+    if (puzzle.intent?.action === "claim" && puzzle.permission && !puzzle.permission.requires_passport) {
+        violations.push({
+            constraint_id: "F-R-08",
+            severity: "CRITICAL",
+            message: "claim requires Passport — SDK W_ERROR if missing",
+        });
+    }
+    return violations;
+}
+export function generateConfirmationText(puzzle) {
+    const lines = [];
+    lines.push("═══ Reward Confirmation ═══");
+    lines.push("");
+    if (puzzle.intent) {
+        lines.push(`Action: ${puzzle.intent.action}`);
+        if (puzzle.intent.target_reward)
+            lines.push(`Target Reward: ${puzzle.intent.target_reward}`);
+        lines.push(`Rule: ${puzzle.intent.rule_sentence}`);
+        if (puzzle.intent.failure_conditions.length > 0) {
+            lines.push("Failure conditions:");
+            for (const fc of puzzle.intent.failure_conditions)
+                lines.push(`  - ${fc}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.config) {
+        lines.push("─ Reward Config ──────────────");
+        lines.push(`Coin type T: ${puzzle.config.coin_type}`);
+        lines.push(`Description: ${puzzle.config.description}`);
+        lines.push(`Permission: ${puzzle.config.permission} (new: ${puzzle.config.permission_is_new ? "YES" : "NO"})`);
+        lines.push("");
+    }
+    if (puzzle.guard) {
+        lines.push("─ Guard Config ──────────────");
+        lines.push(`Guard: ${puzzle.guard.guard}`);
+        lines.push(`Recipient: ${puzzle.guard.recipient_type}` +
+            (puzzle.guard.recipient_param !== undefined ? ` (${puzzle.guard.recipient_param})` : ""));
+        lines.push(`Amount: ${puzzle.guard.amount_type} (${puzzle.guard.amount_param})`);
+        lines.push(`Constructor: ${puzzle.guard.constructor}`);
+        if (puzzle.guard.expiration_time != null) {
+            lines.push(`expiration_time: ${puzzle.guard.expiration_time}`);
+        }
+        if (puzzle.guard.store_from_id != null) {
+            lines.push(`store_from_id: ${puzzle.guard.store_from_id}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.funds) {
+        lines.push("─ Funds ──────────────");
+        lines.push(`Current balance: ${puzzle.funds.current_balance}`);
+        if (puzzle.funds.coin_add_amount)
+            lines.push(`coin_add amount: ${puzzle.funds.coin_add_amount}`);
+        if (puzzle.funds.receive_payment) {
+            lines.push(`receive payment: ${puzzle.funds.receive_payment.payment} (token: ${puzzle.funds.receive_payment.token_type})`);
+        }
+        if (puzzle.funds.claim_amount_estimate)
+            lines.push(`Estimated claim amount: ${puzzle.funds.claim_amount_estimate}`);
+        if (puzzle.funds.owner_receive_envelope)
+            lines.push(`owner_receive envelope: ${puzzle.funds.owner_receive_envelope}`);
+        lines.push("");
+    }
+    if (puzzle.permission) {
+        lines.push("─ Permission ──────────────");
+        if (puzzle.permission.builtin_indexes_used.length > 0) {
+            lines.push("Builtin indexes used:");
+            for (const p of puzzle.permission.builtin_indexes_used) {
+                lines.push(`  [${p.index}] ${p.name}: ${p.description}`);
+            }
+        }
+        lines.push(`Permission-free: ${puzzle.permission.is_permission_free ? "YES (claim)" : "NO"}`);
+        lines.push(`Requires Passport: ${puzzle.permission.requires_passport ? "YES" : "NO"}`);
+        if (puzzle.permission.signer) {
+            lines.push(`Signer: ${puzzle.permission.signer} (is_owner: ${puzzle.permission.signer_is_owner ? "YES" : "NO"})`);
+        }
+        lines.push("");
+    }
+    const violations = validateConstraints(puzzle);
+    if (violations.length > 0) {
+        lines.push("─ Constraint Violations ──────────────");
+        for (const v of violations)
+            lines.push(`  [${v.severity}] ${v.constraint_id}: ${v.message}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function resolveBuiltinPermission(index) {
+    void index;
+    return undefined;
+}
+export function requiresGuardConfig(puzzle) {
+    return puzzle.intent?.action === "guard_add";
+}
+export function requiresPassport(puzzle) {
+    return puzzle.intent?.action === "claim";
+}
+export function getRelevantDimensions(action) {
+    const base = ["A", "E", "F"];
+    if (action === "create")
+        base.push("B");
+    if (action === "guard_add")
+        base.push("C");
+    if (action === "coin_add" || action === "receive" || action === "claim" || action === "owner_receive") {
+        base.push("D");
+    }
+    return base;
+}
+export function getFieldMutability(field) {
+    return REWARD_FIELD_MUTABILITY.find(f => f.field === field);
+}
+export function isAdminMutableField(field) {
+    return getFieldMutability(field)?.mutability === "admin_mutable";
+}
+export function getFieldPermissionIndex(field) {
+    return getFieldMutability(field)?.permission_index;
+}
+export { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, resolveGuardConstructor, getGuardConstructorSpec, };

package/dist/knowledge/reward-risk.d.ts

@@ -0,0 +1,84 @@
+import { type RewardScene, type RewardAmountType } from "./reward-ledger.js";
+export type RewardRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+export type RewardRiskCategory = "structural" | "semantic" | "permission" | "lifecycle" | "cross_object";
+export interface RewardRisk {
+    id: string;
+    level: RewardRiskLevel;
+    category: RewardRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: RewardStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export type RewardStakeholder = "owner" | "claimer" | "service_provider" | "system";
+export interface RewardRiskRule {
+    id: string;
+    category: RewardRiskCategory;
+    trigger: string;
+    check: (ctx: RewardRiskCheckContext) => RewardRisk | null;
+}
+export interface RewardGuardAddEntry {
+    guard: string;
+    recipient: {
+        GuardIdentifier: number;
+    } | {
+        Entity: string;
+    } | {
+        Signer: unknown;
+    };
+    amount: {
+        type: RewardAmountType | string;
+        value: number | string;
+    };
+    expiration_time?: number;
+    store_from_id?: number | null;
+}
+export interface RewardRiskCheckContext {
+    object?: string | null;
+    claim?: string;
+    description?: string;
+    coin_add?: {
+        amount: string | number;
+        coin_type: string;
+    };
+    receive?: {
+        token_type: string;
+    };
+    guard_add?: RewardGuardAddEntry[];
+    guard_remove_expired?: boolean;
+    guard_expiration_time?: number | null;
+    owner_receive?: unknown;
+    um?: string | null;
+    reward_type?: string;
+    current_balance?: string;
+    current_guard_count?: number;
+    current_record_count_for_recipient?: number;
+    current_guard_not_added_expiration_time?: number | null;
+    current_clock_ms?: number;
+    permission_address?: string;
+    signer?: string;
+    target_guard_addresses?: string[];
+    passport_submission_value_types?: Record<number, string>;
+    passport_identifier_is_address?: Record<number, boolean>;
+    guard_store_from_id_compatible?: Record<string, boolean>;
+}
+export declare const REWARD_RISK_VERSION = "1.0.0";
+export declare function getAllRewardRiskRules(): RewardRiskRule[];
+export declare function getRewardRiskRulesCount(): number;
+export declare function getRewardRiskRulesByCategory(category: RewardRiskCategory): RewardRiskRule[];
+export interface RewardRiskAssessment {
+    summary: string;
+    scene?: RewardScene;
+    risks: RewardRisk[];
+    overall_risk: RewardRiskLevel;
+    risks_by_category: Partial<Record<RewardRiskCategory, number>>;
+    stakeholder_advice: Partial<Record<RewardStakeholder, string[]>>;
+    needs_human_review: boolean;
+}
+export declare function assessRewardRisks(ctx: RewardRiskCheckContext): RewardRiskAssessment;
+export declare const REWARD_STAKEHOLDERS: RewardStakeholder[];
+export declare function getRewardRiskRulesByStakeholder(stakeholder: RewardStakeholder): RewardRiskRule[];