@wowok/agent-mcp 2.4.3 → 2.5.1

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

@@ -0,0 +1,113 @@
+import { type RewardRiskAssessment } from "./reward-risk.js";
+export type RewardConfirmGateStatus = "approved" | "blocked_checklist" | "blocked_risk" | "blocked_user" | "blocked_environment";
+export interface RewardConfirmGateResult {
+    status: RewardConfirmGateStatus;
+    checklist_result: RewardChecklistResult;
+    risk_result?: RewardRiskAssessment;
+    user_confirmation?: RewardUserConfirmation;
+    environment_result?: RewardEnvironmentResult;
+    confirmation_text?: string;
+    block_reason?: string;
+    decision_record: RewardDecisionRecord;
+}
+export interface RewardChecklistResult {
+    all_passed: boolean;
+    items: RewardChecklistItem[];
+}
+export interface RewardChecklistItem {
+    id: string;
+    description: string;
+    passed: boolean;
+    message: string;
+}
+export interface RewardUserConfirmation {
+    questions_asked: RewardConfirmationQuestion[];
+    responses: RewardConfirmationResponse[];
+    all_confirmed: boolean;
+}
+export interface RewardConfirmationQuestion {
+    id: string;
+    question: string;
+    requires_explicit_yes: boolean;
+    related_risk_ids?: string[];
+}
+export interface RewardConfirmationResponse {
+    question_id: string;
+    response: "yes" | "no" | "skip";
+}
+export interface RewardEnvironmentResult {
+    passed: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+        message: string;
+    }[];
+}
+export interface RewardDecisionRecord {
+    timestamp: string;
+    gate_version: string;
+    final_status: RewardConfirmGateStatus;
+    layers_passed: string[];
+    layers_failed: string[];
+}
+export interface RewardJsonForConfirm {
+    object?: string | null;
+    claim?: string;
+    description?: string;
+    coin_add?: {
+        amount: string | number;
+        coin_type: string;
+    };
+    receive?: {
+        token_type: string;
+    };
+    guard_add?: Array<{
+        guard: string;
+        recipient: {
+            GuardIdentifier: number;
+        } | {
+            Entity: string;
+        } | {
+            Signer: unknown;
+        };
+        amount: {
+            type: string;
+            value: number | string;
+        };
+        expiration_time?: number;
+        store_from_id?: number | null;
+    }>;
+    guard_remove_expired?: boolean;
+    guard_expiration_time?: number | null;
+    owner_receive?: unknown;
+    um?: string | null;
+}
+export interface RewardConfirmGateInput {
+    reward_json: RewardJsonForConfirm;
+    intent?: string;
+    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>;
+    skip_user_confirmation?: boolean;
+    skip_environment_check?: boolean;
+}
+export declare const REWARD_OPERATION_CHECKLIST: RewardChecklistItem[];
+export declare const REWARD_CONFIRMATION_QUESTIONS: RewardConfirmationQuestion[];
+export declare const REWARD_CONFIRM_VERSION = "1.0.0";
+export declare function runRewardConfirmGate(input: RewardConfirmGateInput): RewardConfirmGateResult;
+export interface ProgressiveRewardCheckResult {
+    stage: "checklist" | "risk" | "confirmation" | "environment" | "complete";
+    status: "pass" | "fail" | "pending";
+    message: string;
+    next_action?: string;
+}
+export declare function progressiveRewardCheck(input: RewardConfirmGateInput): ProgressiveRewardCheckResult;

package/dist/knowledge/reward-confirm.js

@@ -0,0 +1,496 @@
+import { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, } from "./onchain-constants.js";
+import { assessRewardRisks, } from "./reward-risk.js";
+export const REWARD_OPERATION_CHECKLIST = [
+    { id: "C-R-01", description: "guard_add count < MAX_GUARD_COUNT_REWARD (200)", passed: false, message: "" },
+    { id: "C-R-02", description: "Per-recipient record count < MAX_RECORD_COUNT_REWARD (5200)", passed: false, message: "" },
+    { id: "C-R-03", description: "claim: balance ≥ amount (E_INSUFFICIENT_BALANCE)", passed: false, message: "" },
+    { id: "C-R-04", description: "guard_add: clock > guard_not_added_expiration_time (if Some)", passed: false, message: "" },
+    { id: "C-R-05", description: "guard_add / claim: clock ≤ guard.expiration_time (if Some)", passed: false, message: "" },
+    { id: "C-R-06", description: "guard_add: valid Recipient × Amount pairing (6 constructors)", passed: false, message: "" },
+    { id: "C-R-07", description: "coin_add: coin type T matches Reward<T>", passed: false, message: "" },
+    { id: "C-R-08", description: "claim: Passport is provided (SDK W_ERROR if missing)", passed: false, message: "" },
+    { id: "C-R-09", description: "owner_receive (156): user double-confirms blast radius", passed: false, message: "" },
+    { id: "C-R-10", description: "guard_expiration_time_add (155): new time > current clock", passed: false, message: "" },
+];
+function runStaticChecklist(input) {
+    const items = REWARD_OPERATION_CHECKLIST.map(c => ({ ...c }));
+    const data = input.reward_json;
+    const cr01 = items.find(i => i.id === "C-R-01");
+    if (data.guard_add && data.guard_add.length > 0) {
+        const current = input.current_guard_count ?? 0;
+        if (current + data.guard_add.length > MAX_GUARD_COUNT_REWARD) {
+            cr01.passed = false;
+            cr01.message = `${current + data.guard_add.length} > ${MAX_GUARD_COUNT_REWARD}`;
+        }
+        else {
+            cr01.passed = true;
+        }
+    }
+    else {
+        cr01.passed = true;
+    }
+    const cr02 = items.find(i => i.id === "C-R-02");
+    if (data.claim) {
+        const records = input.current_record_count_for_recipient ?? 0;
+        if (records >= MAX_RECORD_COUNT_REWARD) {
+            cr02.passed = false;
+            cr02.message = `${records} ≥ ${MAX_RECORD_COUNT_REWARD}`;
+        }
+        else {
+            cr02.passed = true;
+        }
+    }
+    else {
+        cr02.passed = true;
+    }
+    const cr03 = items.find(i => i.id === "C-R-03");
+    if (data.claim && input.current_balance !== undefined) {
+        const balance = BigInt(input.current_balance);
+        if (balance === 0n) {
+            cr03.passed = false;
+            cr03.message = `balance=0 — claim will abort E_INSUFFICIENT_BALANCE`;
+        }
+        else {
+            cr03.passed = true;
+        }
+    }
+    else {
+        cr03.passed = true;
+    }
+    const cr04 = items.find(i => i.id === "C-R-04");
+    if (data.guard_add && data.guard_add.length > 0 && input.current_guard_not_added_expiration_time != null) {
+        const clock = input.current_clock_ms ?? Date.now();
+        if (clock <= input.current_guard_not_added_expiration_time) {
+            cr04.passed = false;
+            cr04.message = `clock ${clock} ≤ lock ${input.current_guard_not_added_expiration_time}`;
+        }
+        else {
+            cr04.passed = true;
+        }
+    }
+    else {
+        cr04.passed = true;
+    }
+    const cr05 = items.find(i => i.id === "C-R-05");
+    cr05.passed = true;
+    const cr06 = items.find(i => i.id === "C-R-06");
+    if (data.guard_add) {
+        const validRecipientKeys = ["GuardIdentifier", "Entity", "Signer"];
+        const validAmountTypes = ["Fixed", "GuardU64Identifier", "GUARDU64IDENTIFIER", "GUARD_U64_IDENTIFIER"];
+        let allValid = true;
+        for (const g of data.guard_add) {
+            const rKeys = Object.keys(g.recipient);
+            if (rKeys.length !== 1 || !validRecipientKeys.includes(rKeys[0])) {
+                allValid = false;
+                break;
+            }
+            if (!validAmountTypes.includes(String(g.amount.type).toUpperCase())) {
+                allValid = false;
+                break;
+            }
+        }
+        cr06.passed = allValid;
+        cr06.message = allValid ? "" : "Invalid Recipient × Amount pairing";
+    }
+    else {
+        cr06.passed = true;
+    }
+    const cr07 = items.find(i => i.id === "C-R-07");
+    if (data.coin_add && input.reward_type) {
+        cr07.passed = data.coin_add.coin_type === input.reward_type;
+        cr07.message = cr07.passed ? "" : `${data.coin_add.coin_type} ≠ ${input.reward_type}`;
+    }
+    else {
+        cr07.passed = true;
+    }
+    const cr08 = items.find(i => i.id === "C-R-08");
+    if (data.claim) {
+        cr08.passed = true;
+        cr08.message = "Passport presence verified by SDK operate()";
+    }
+    else {
+        cr08.passed = true;
+    }
+    const cr09 = items.find(i => i.id === "C-R-09");
+    if (data.owner_receive != null) {
+        cr09.passed = false;
+        cr09.message = "Pending user confirmation in L3 (QRW3)";
+    }
+    else {
+        cr09.passed = true;
+    }
+    const cr10 = items.find(i => i.id === "C-R-10");
+    if (data.guard_expiration_time !== undefined && data.guard_expiration_time !== null) {
+        const clock = input.current_clock_ms ?? Date.now();
+        if (data.guard_expiration_time <= clock) {
+            cr10.passed = false;
+            cr10.message = `${data.guard_expiration_time} ≤ clock ${clock}`;
+        }
+        else {
+            cr10.passed = true;
+        }
+    }
+    else {
+        cr10.passed = true;
+    }
+    return {
+        all_passed: items.filter(i => i.id !== "C-R-09").every(i => i.passed),
+        items,
+    };
+}
+function adaptRiskAssessment(input) {
+    const ctx = {
+        object: input.reward_json.object,
+        claim: input.reward_json.claim,
+        description: input.reward_json.description,
+        coin_add: input.reward_json.coin_add,
+        receive: input.reward_json.receive,
+        guard_add: input.reward_json.guard_add,
+        guard_remove_expired: input.reward_json.guard_remove_expired,
+        guard_expiration_time: input.reward_json.guard_expiration_time,
+        owner_receive: input.reward_json.owner_receive,
+        um: input.reward_json.um,
+        reward_type: input.reward_type,
+        current_balance: input.current_balance,
+        current_guard_count: input.current_guard_count,
+        current_record_count_for_recipient: input.current_record_count_for_recipient,
+        current_guard_not_added_expiration_time: input.current_guard_not_added_expiration_time,
+        current_clock_ms: input.current_clock_ms,
+        permission_address: input.permission_address,
+        signer: input.signer,
+        target_guard_addresses: input.target_guard_addresses,
+        passport_submission_value_types: input.passport_submission_value_types,
+        passport_identifier_is_address: input.passport_identifier_is_address,
+        guard_store_from_id_compatible: input.guard_store_from_id_compatible,
+    };
+    return assessRewardRisks(ctx);
+}
+export const REWARD_CONFIRMATION_QUESTIONS = [
+    {
+        id: "QRW1",
+        question: "Is the target Reward object address correct, and does its coin type T match the intended token?",
+        requires_explicit_yes: true,
+    },
+    {
+        id: "QRW2",
+        question: "For guard_add: is the Guard address valid and added to this Reward (E_GUARD_NOT_FOUND on claim if not)?",
+        requires_explicit_yes: true,
+        related_risk_ids: ["R-R-5-01"],
+    },
+    {
+        id: "QRW3",
+        question: "⚠️ For owner_receive (156): do you confirm sweeping receivables to the Permission owner? Grant 156 only to dedicated addresses.",
+        requires_explicit_yes: true,
+        related_risk_ids: ["R-R-3-02"],
+    },
+    {
+        id: "QRW4",
+        question: "For guard_expiration_time_add (155): do you acknowledge this sets a time-lock on guard additions (cannot be shortened below current clock)?",
+        requires_explicit_yes: true,
+        related_risk_ids: ["R-R-3-03", "R-R-4-04"],
+    },
+    {
+        id: "QRW5",
+        question: "For claim: is the Passport provided with valid submissions for the Guard (recipient + amount + store_from_id if set)?",
+        requires_explicit_yes: true,
+        related_risk_ids: ["R-R-2-01", "R-R-2-02", "R-R-2-03"],
+    },
+    {
+        id: "QRW6",
+        question: "For coin_add: have you verified the coin type T matches Reward<T> (type mismatch will abort in SDK operate)?",
+        requires_explicit_yes: false,
+        related_risk_ids: ["R-R-5-02"],
+    },
+];
+function processUserConfirmation(input, assessment) {
+    const questions = [...REWARD_CONFIRMATION_QUESTIONS];
+    const data = input.reward_json;
+    const filtered = [];
+    for (const q of questions) {
+        if (q.id === "QRW2" && !data.guard_add)
+            continue;
+        if (q.id === "QRW3" && data.owner_receive == null)
+            continue;
+        if (q.id === "QRW4" && data.guard_expiration_time === undefined)
+            continue;
+        if (q.id === "QRW5" && !data.claim)
+            continue;
+        if (q.id === "QRW6" && !data.coin_add)
+            continue;
+        filtered.push(q);
+    }
+    if (input.skip_user_confirmation) {
+        return {
+            questions_asked: filtered,
+            responses: filtered.map(q => ({ question_id: q.id, response: "yes" })),
+            all_confirmed: true,
+        };
+    }
+    return {
+        questions_asked: filtered,
+        responses: [],
+        all_confirmed: false,
+    };
+}
+function verifyEnvironment(input) {
+    const checks = [];
+    if (input.reward_json.object) {
+        checks.push({
+            name: "reward_exists",
+            passed: true,
+            message: `Reward ${input.reward_json.object} assumed to exist`,
+        });
+    }
+    if (input.permission_address) {
+        checks.push({
+            name: "permission_exists",
+            passed: true,
+            message: `Permission ${input.permission_address} assumed to exist`,
+        });
+    }
+    if (input.reward_json.claim && input.target_guard_addresses) {
+        const isBound = input.target_guard_addresses.includes(input.reward_json.claim);
+        checks.push({
+            name: "guard_bound_to_reward",
+            passed: isBound,
+            message: isBound
+                ? `Guard ${input.reward_json.claim} is in Reward.guards`
+                : `Guard ${input.reward_json.claim} NOT in Reward.guards — E_GUARD_NOT_FOUND will abort`,
+        });
+    }
+    if (input.reward_json.claim && input.current_balance !== undefined) {
+        const balance = BigInt(input.current_balance);
+        checks.push({
+            name: "balance_positive_for_claim",
+            passed: balance > 0n,
+            message: balance > 0n
+                ? `Balance ${input.current_balance} > 0`
+                : `Balance is 0 — E_INSUFFICIENT_BALANCE will abort`,
+        });
+    }
+    if (input.signer && input.permission_address) {
+        checks.push({
+            name: "signer_authorization",
+            passed: true,
+            message: `Signer ${input.signer} assumed authorized (verify via queryObjectPermission)`,
+        });
+    }
+    const allPassed = checks.every(c => c.passed);
+    return { passed: allPassed, checks };
+}
+export const REWARD_CONFIRM_VERSION = "1.0.0";
+export function runRewardConfirmGate(input) {
+    const layersPassed = [];
+    const layersFailed = [];
+    const checklist = runStaticChecklist(input);
+    if (!checklist.all_passed) {
+        layersFailed.push("L1_checklist");
+        return {
+            status: "blocked_checklist",
+            checklist_result: checklist,
+            confirmation_text: generateConfirmationText(input, checklist),
+            block_reason: `Checklist failed: ${checklist.items.filter(i => !i.passed).map(i => i.id).join(", ")}`,
+            decision_record: {
+                timestamp: new Date().toISOString(),
+                gate_version: REWARD_CONFIRM_VERSION,
+                final_status: "blocked_checklist",
+                layers_passed: layersPassed,
+                layers_failed: layersFailed,
+            },
+        };
+    }
+    layersPassed.push("L1_checklist");
+    const assessment = adaptRiskAssessment(input);
+    const hasCritical = assessment.risks.some(r => r.level === "CRITICAL");
+    if (hasCritical) {
+        layersFailed.push("L2_risk");
+        return {
+            status: "blocked_risk",
+            checklist_result: checklist,
+            risk_result: assessment,
+            confirmation_text: generateConfirmationText(input, checklist, assessment),
+            block_reason: `CRITICAL risks: ${assessment.risks.filter(r => r.level === "CRITICAL").map(r => r.id).join(", ")}`,
+            decision_record: {
+                timestamp: new Date().toISOString(),
+                gate_version: REWARD_CONFIRM_VERSION,
+                final_status: "blocked_risk",
+                layers_passed: layersPassed,
+                layers_failed: layersFailed,
+            },
+        };
+    }
+    layersPassed.push("L2_risk");
+    const userConf = processUserConfirmation(input, assessment);
+    if (!userConf.all_confirmed) {
+        if (input.reward_json.owner_receive != null) {
+            const cr09 = checklist.items.find(i => i.id === "C-R-09");
+            if (cr09) {
+                const qrw3 = userConf.responses.find(r => r.question_id === "QRW3");
+                cr09.passed = qrw3?.response === "yes";
+                cr09.message = cr09.passed ? "" : "owner_receive not confirmed by user (QRW3)";
+            }
+        }
+        if (input.reward_json.owner_receive != null) {
+            const cr09 = checklist.items.find(i => i.id === "C-R-09");
+            if (cr09 && !cr09.passed) {
+                layersFailed.push("L3_user");
+                return {
+                    status: "blocked_user",
+                    checklist_result: checklist,
+                    risk_result: assessment,
+                    user_confirmation: userConf,
+                    confirmation_text: generateConfirmationText(input, checklist, assessment),
+                    block_reason: "User did not confirm owner_receive (QRW3)",
+                    decision_record: {
+                        timestamp: new Date().toISOString(),
+                        gate_version: REWARD_CONFIRM_VERSION,
+                        final_status: "blocked_user",
+                        layers_passed: layersPassed,
+                        layers_failed: layersFailed,
+                    },
+                };
+            }
+        }
+    }
+    layersPassed.push("L3_user");
+    if (input.skip_environment_check) {
+        layersPassed.push("L4_environment");
+    }
+    else {
+        const env = verifyEnvironment(input);
+        if (!env.passed) {
+            layersFailed.push("L4_environment");
+            return {
+                status: "blocked_environment",
+                checklist_result: checklist,
+                risk_result: assessment,
+                user_confirmation: userConf,
+                environment_result: env,
+                confirmation_text: generateConfirmationText(input, checklist, assessment),
+                block_reason: `Environment check failed: ${env.checks.filter(c => !c.passed).map(c => c.name).join(", ")}`,
+                decision_record: {
+                    timestamp: new Date().toISOString(),
+                    gate_version: REWARD_CONFIRM_VERSION,
+                    final_status: "blocked_environment",
+                    layers_passed: layersPassed,
+                    layers_failed: layersFailed,
+                },
+            };
+        }
+        layersPassed.push("L4_environment");
+    }
+    return {
+        status: "approved",
+        checklist_result: checklist,
+        risk_result: assessment,
+        user_confirmation: userConf,
+        confirmation_text: generateConfirmationText(input, checklist, assessment),
+        decision_record: {
+            timestamp: new Date().toISOString(),
+            gate_version: REWARD_CONFIRM_VERSION,
+            final_status: "approved",
+            layers_passed: layersPassed,
+            layers_failed: layersFailed,
+        },
+    };
+}
+function generateConfirmationText(input, checklist, assessment) {
+    const lines = [];
+    const data = input.reward_json;
+    lines.push("═══ Reward Operation Confirmation ═══");
+    lines.push("");
+    if (data.object) {
+        lines.push(`Reward: ${data.object}`);
+    }
+    else {
+        lines.push("Reward: NEW (will be created in this tx)");
+    }
+    if (input.reward_type) {
+        lines.push(`Coin type T: ${input.reward_type}`);
+    }
+    if (input.current_balance !== undefined) {
+        lines.push(`Current balance: ${input.current_balance}`);
+    }
+    if (input.current_guard_count !== undefined) {
+        lines.push(`Current guard count: ${input.current_guard_count}/${MAX_GUARD_COUNT_REWARD}`);
+    }
+    lines.push("");
+    lines.push("─ Checklist ──────────────────");
+    for (const item of checklist.items) {
+        const mark = item.passed ? "✓" : "✗";
+        lines.push(`  ${mark} ${item.id}: ${item.description}${item.message ? " — " + item.message : ""}`);
+    }
+    lines.push("");
+    if (assessment) {
+        lines.push("─ Risk Assessment ──────────────────");
+        lines.push(`Overall: ${assessment.overall_risk}`);
+        lines.push(`Detected: ${assessment.risks.length} risk(s)`);
+        for (const r of assessment.risks) {
+            lines.push(`  [${r.level}] ${r.id}: ${r.title}`);
+        }
+        lines.push("");
+    }
+    lines.push("─ Operations ──────────────────");
+    if (data.claim)
+        lines.push(`- claim: guard=${data.claim} (passport-driven, no permission)`);
+    if (data.description != null)
+        lines.push(`- description_set: "${data.description}"`);
+    if (data.coin_add)
+        lines.push(`- coin_add: ${data.coin_add.amount} of ${data.coin_add.coin_type}`);
+    if (data.receive)
+        lines.push(`- receive: payment token=${data.receive.token_type}`);
+    if (data.guard_add) {
+        lines.push(`- guard_add: ${data.guard_add.length} guard(s)`);
+        for (let i = 0; i < data.guard_add.length; i++) {
+            const g = data.guard_add[i];
+            const rKey = Object.keys(g.recipient)[0];
+            lines.push(`  [${i}] guard=${g.guard}, recipient=${rKey}, amount=${g.amount.type}(${g.amount.value})`);
+        }
+    }
+    if (data.guard_remove_expired)
+        lines.push(`- guard_remove_expired: true`);
+    if (data.guard_expiration_time !== undefined) {
+        const t = data.guard_expiration_time;
+        lines.push(`- guard_expiration_time_add: ${t === null ? "null (cancel lock)" : t}`);
+    }
+    if (data.owner_receive != null)
+        lines.push(`- ⚠️ owner_receive (156): unwrap to Permission owner`);
+    if (data.um !== undefined) {
+        lines.push(`- um_${data.um ? "set" : "none"}: ${data.um ?? "(unbind)"}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function progressiveRewardCheck(input) {
+    const checklist = runStaticChecklist(input);
+    if (!checklist.all_passed) {
+        return {
+            stage: "checklist",
+            status: "fail",
+            message: `Checklist failed: ${checklist.items.filter(i => !i.passed).map(i => i.id).join(", ")}`,
+            next_action: "Fix failing checklist items",
+        };
+    }
+    const assessment = adaptRiskAssessment(input);
+    if (assessment.risks.some(r => r.level === "CRITICAL")) {
+        return {
+            stage: "risk",
+            status: "fail",
+            message: `CRITICAL risks: ${assessment.risks.filter(r => r.level === "CRITICAL").map(r => r.id).join(", ")}`,
+            next_action: "Resolve CRITICAL risks before proceeding",
+        };
+    }
+    if (assessment.needs_human_review) {
+        return {
+            stage: "confirmation",
+            status: "pending",
+            message: "Human review required for HIGH risks",
+            next_action: "Confirm risk acceptance",
+        };
+    }
+    return {
+        stage: "complete",
+        status: "pass",
+        message: "All checks passed",
+    };
+}