@cogcoin/client 0.5.0

package/dist/wallet/tx/reputation.js

@@ -0,0 +1,693 @@
+import { createHash, randomBytes } from "node:crypto";
+import { encodeSentence } from "@cogcoin/scoring";
+import { getBalance, lookupDomain, } from "@cogcoin/indexer/queries";
+import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import { acquireFileLock } from "../fs/lock.js";
+import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { createDefaultWalletSecretProvider, } from "../state/provider.js";
+import { serializeRepCommit, serializeRepRevoke, validateDomainName, } from "../cogop/index.js";
+import { openWalletReadContext } from "../read/index.js";
+import { assertWalletMutationContextReady, buildWalletMutationTransaction, formatCogAmount, isAlreadyAcceptedError, isBroadcastUnknownError, pauseMiningForWalletMutation, saveWalletStatePreservingUnlock, unlockTemporaryBuilderLocks, updateMutationRecord, } from "./common.js";
+import { confirmTypedAcknowledgement as confirmSharedTypedAcknowledgement, confirmYesNo as confirmSharedYesNo, } from "./confirm.js";
+import { getCanonicalIdentitySelector } from "./identity-selector.js";
+import { findPendingMutationByIntent, upsertPendingMutation } from "./journal.js";
+function normalizeDomainName(domainName, errorCode) {
+    const normalized = domainName.trim().toLowerCase();
+    if (normalized.length === 0) {
+        throw new Error(errorCode);
+    }
+    validateDomainName(normalized);
+    return normalized;
+}
+function createSupportKey(sourceDomainId, targetDomainId) {
+    return `${sourceDomainId}:${targetDomainId}`;
+}
+function encodeOpReturnScript(payload) {
+    if (payload.length <= 75) {
+        return Buffer.concat([
+            Buffer.from([0x6a, payload.length]),
+            Buffer.from(payload),
+        ]).toString("hex");
+    }
+    return Buffer.concat([
+        Buffer.from([0x6a, 0x4c, payload.length]),
+        Buffer.from(payload),
+    ]).toString("hex");
+}
+function satsToBtcNumber(value) {
+    return Number(value) / 100_000_000;
+}
+function valueToSats(value) {
+    const text = typeof value === "number" ? value.toFixed(8) : value;
+    const match = /^(-?)(\d+)(?:\.(\d{0,8}))?$/.exec(text.trim());
+    if (match == null) {
+        throw new Error(`wallet_reputation_invalid_amount_${text}`);
+    }
+    const sign = match[1] === "-" ? -1n : 1n;
+    const whole = BigInt(match[2] ?? "0");
+    const fraction = BigInt((match[3] ?? "").padEnd(8, "0"));
+    return sign * ((whole * 100000000n) + fraction);
+}
+function createIntentFingerprint(parts) {
+    return createHash("sha256")
+        .update(parts.map((part) => String(part)).join("\n"))
+        .digest("hex");
+}
+function createResolvedReputationSenderSummary(sender, selector) {
+    return {
+        selector,
+        localIndex: sender.localIndex,
+        scriptPubKeyHex: sender.scriptPubKeyHex,
+        address: sender.address,
+    };
+}
+function createResolvedReputationSummary(options) {
+    return {
+        sender: createResolvedReputationSenderSummary(options.sender, options.senderSelector),
+        effect: options.kind === "give"
+            ? {
+                kind: "give-support",
+                burnCogtoshi: options.amountCogtoshi.toString(),
+            }
+            : {
+                kind: "revoke-support",
+                burnCogtoshi: options.amountCogtoshi.toString(),
+            },
+        review: {
+            included: options.review.payloadHex !== null,
+            byteLength: options.review.payload?.length ?? null,
+        },
+        selfStake: options.selfStake,
+    };
+}
+function describeReputationEffect(effect) {
+    if (effect.kind === "give-support") {
+        return `burn ${effect.burnCogtoshi} cogtoshi to publish support`;
+    }
+    return `revoke visible support with no refund of the previously burned ${effect.burnCogtoshi} cogtoshi`;
+}
+function describeReputationReview(review) {
+    if (!review.included || review.byteLength === null) {
+        return "none";
+    }
+    return `included (${review.byteLength} bytes)`;
+}
+function resolveAnchorOutpointForSender(state, sender, errorPrefix) {
+    const anchoredDomain = state.domains.find((domain) => domain.currentOwnerLocalIndex === sender.index
+        && domain.canonicalChainStatus === "anchored") ?? null;
+    if (anchoredDomain?.currentCanonicalAnchorOutpoint === null || anchoredDomain === null) {
+        throw new Error(`${errorPrefix}_anchor_outpoint_unavailable`);
+    }
+    return {
+        txid: anchoredDomain.currentCanonicalAnchorOutpoint.txid,
+        vout: anchoredDomain.currentCanonicalAnchorOutpoint.vout,
+    };
+}
+function resolveReputationOperation(context, sourceDomainName, targetDomainName, errorPrefix) {
+    assertWalletMutationContextReady(context, errorPrefix);
+    const sourceDomain = lookupDomain(context.snapshot.state, sourceDomainName);
+    if (sourceDomain === null) {
+        throw new Error(`${errorPrefix}_source_domain_not_found`);
+    }
+    if (!sourceDomain.anchored) {
+        throw new Error(`${errorPrefix}_source_domain_not_anchored`);
+    }
+    const targetDomain = lookupDomain(context.snapshot.state, targetDomainName);
+    if (targetDomain === null) {
+        throw new Error(`${errorPrefix}_target_domain_not_found`);
+    }
+    if (!targetDomain.anchored) {
+        throw new Error(`${errorPrefix}_target_domain_not_anchored`);
+    }
+    const ownerHex = Buffer.from(sourceDomain.ownerScriptPubKey).toString("hex");
+    const ownerIdentity = context.model.identities.find((identity) => identity.scriptPubKeyHex === ownerHex) ?? null;
+    if (ownerIdentity === null || ownerIdentity.address === null) {
+        throw new Error(`${errorPrefix}_source_owner_not_locally_controlled`);
+    }
+    if (ownerIdentity.readOnly) {
+        throw new Error(`${errorPrefix}_source_owner_read_only`);
+    }
+    return {
+        readContext: context,
+        state: context.localState.state,
+        unlockUntilUnixMs: context.localState.unlockUntilUnixMs,
+        sender: {
+            localIndex: ownerIdentity.index,
+            scriptPubKeyHex: ownerIdentity.scriptPubKeyHex,
+            address: ownerIdentity.address,
+        },
+        senderSelector: getCanonicalIdentitySelector(ownerIdentity),
+        anchorOutpoint: resolveAnchorOutpointForSender(context.localState.state, ownerIdentity, errorPrefix),
+        sourceDomain,
+        targetDomain,
+        availableBalanceCogtoshi: getBalance(context.snapshot.state, sourceDomain.ownerScriptPubKey),
+        currentNetSupportCogtoshi: context.snapshot.state.consensus.supportByPair.get(createSupportKey(sourceDomain.domainId, targetDomain.domainId)) ?? 0n,
+    };
+}
+function buildPlanForReputationOperation(options) {
+    const fundingUtxos = options.allUtxos.filter((entry) => entry.scriptPubKey === options.state.funding.scriptPubKeyHex
+        && entry.confirmations >= 1
+        && entry.spendable !== false
+        && entry.safe !== false);
+    const anchorUtxo = options.allUtxos.find((entry) => entry.txid === options.anchorOutpoint.txid
+        && entry.vout === options.anchorOutpoint.vout
+        && entry.scriptPubKey === options.sender.scriptPubKeyHex
+        && entry.confirmations >= 1
+        && entry.spendable !== false
+        && entry.safe !== false);
+    if (anchorUtxo === undefined) {
+        throw new Error(`${options.errorPrefix}_anchor_utxo_missing`);
+    }
+    return {
+        sender: options.sender,
+        changeAddress: options.state.funding.address,
+        inputs: [
+            { txid: anchorUtxo.txid, vout: anchorUtxo.vout },
+            ...fundingUtxos.map((entry) => ({ txid: entry.txid, vout: entry.vout })),
+        ],
+        outputs: [
+            { data: Buffer.from(options.opReturnData).toString("hex") },
+            { [options.sender.address]: satsToBtcNumber(BigInt(options.state.anchorValueSats)) },
+        ],
+        changePosition: 2,
+        expectedOpReturnScriptHex: encodeOpReturnScript(options.opReturnData),
+        expectedAnchorScriptHex: options.sender.scriptPubKeyHex,
+        expectedAnchorValueSats: BigInt(options.state.anchorValueSats),
+        allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
+        errorPrefix: options.errorPrefix,
+    };
+}
+function validateFundedDraft(decoded, funded, plan) {
+    const inputs = decoded.tx.vin;
+    const outputs = decoded.tx.vout;
+    if (inputs.length === 0) {
+        throw new Error(`${plan.errorPrefix}_missing_sender_input`);
+    }
+    if (inputs[0]?.prevout?.scriptPubKey?.hex !== plan.sender.scriptPubKeyHex) {
+        throw new Error(`${plan.errorPrefix}_sender_input_mismatch`);
+    }
+    for (let index = 1; index < inputs.length; index += 1) {
+        if (inputs[index]?.prevout?.scriptPubKey?.hex !== plan.allowedFundingScriptPubKeyHex) {
+            throw new Error(`${plan.errorPrefix}_unexpected_funding_input`);
+        }
+    }
+    if (outputs[0]?.scriptPubKey?.hex !== plan.expectedOpReturnScriptHex) {
+        throw new Error(`${plan.errorPrefix}_opreturn_mismatch`);
+    }
+    if (outputs[1]?.scriptPubKey?.hex !== plan.expectedAnchorScriptHex) {
+        throw new Error(`${plan.errorPrefix}_anchor_output_mismatch`);
+    }
+    if (valueToSats(outputs[1]?.value ?? 0) !== plan.expectedAnchorValueSats) {
+        throw new Error(`${plan.errorPrefix}_anchor_value_mismatch`);
+    }
+    if (funded.changepos === -1) {
+        if (outputs.length !== 2) {
+            throw new Error(`${plan.errorPrefix}_unexpected_output_count`);
+        }
+        return;
+    }
+    if (funded.changepos !== plan.changePosition || outputs.length !== 3) {
+        throw new Error(`${plan.errorPrefix}_change_position_mismatch`);
+    }
+    if (outputs[funded.changepos]?.scriptPubKey?.hex !== plan.allowedFundingScriptPubKeyHex) {
+        throw new Error(`${plan.errorPrefix}_change_output_mismatch`);
+    }
+}
+async function buildTransaction(options) {
+    return buildWalletMutationTransaction({
+        rpc: options.rpc,
+        walletName: options.walletName,
+        plan: options.plan,
+        validateFundedDraft,
+        finalizeErrorCode: `${options.plan.errorPrefix}_finalize_failed`,
+        mempoolRejectPrefix: `${options.plan.errorPrefix}_mempool_rejected`,
+    });
+}
+function createDraftMutation(options) {
+    if (options.existing !== null && options.existing !== undefined) {
+        return {
+            ...options.existing,
+            kind: options.kind,
+            domainName: options.sourceDomainName,
+            senderScriptPubKeyHex: options.sender.scriptPubKeyHex,
+            senderLocalIndex: options.sender.localIndex,
+            recipientDomainName: options.targetDomainName,
+            amountCogtoshi: options.amountCogtoshi,
+            reviewPayloadHex: options.reviewPayloadHex,
+            status: "draft",
+            lastUpdatedAtUnixMs: options.nowUnixMs,
+            attemptedTxid: null,
+            attemptedWtxid: null,
+            temporaryBuilderLockedOutpoints: [],
+        };
+    }
+    return {
+        mutationId: randomBytes(12).toString("hex"),
+        kind: options.kind,
+        domainName: options.sourceDomainName,
+        parentDomainName: null,
+        senderScriptPubKeyHex: options.sender.scriptPubKeyHex,
+        senderLocalIndex: options.sender.localIndex,
+        amountCogtoshi: options.amountCogtoshi,
+        recipientDomainName: options.targetDomainName,
+        reviewPayloadHex: options.reviewPayloadHex,
+        intentFingerprintHex: options.intentFingerprintHex,
+        status: "draft",
+        createdAtUnixMs: options.nowUnixMs,
+        lastUpdatedAtUnixMs: options.nowUnixMs,
+        attemptedTxid: null,
+        attemptedWtxid: null,
+        temporaryBuilderLockedOutpoints: [],
+    };
+}
+async function saveUpdatedMutationState(options) {
+    const nextState = {
+        ...options.state,
+        stateRevision: options.state.stateRevision + 1,
+        lastWrittenAtUnixMs: options.nowUnixMs,
+    };
+    await saveWalletStatePreservingUnlock({
+        state: nextState,
+        provider: options.provider,
+        unlockUntilUnixMs: options.unlockUntilUnixMs,
+        nowUnixMs: options.nowUnixMs,
+        paths: options.paths,
+    });
+    return nextState;
+}
+function mutationNeedsRepair(mutation, context) {
+    if (context.snapshot === null || mutation.recipientDomainName == null) {
+        return false;
+    }
+    const sourceDomain = lookupDomain(context.snapshot.state, mutation.domainName);
+    const targetDomain = lookupDomain(context.snapshot.state, mutation.recipientDomainName);
+    if (sourceDomain === null || targetDomain === null) {
+        return true;
+    }
+    return !sourceDomain.anchored
+        || !targetDomain.anchored
+        || Buffer.from(sourceDomain.ownerScriptPubKey).toString("hex") !== mutation.senderScriptPubKeyHex;
+}
+async function reconcilePendingReputationMutation(options) {
+    if (options.mutation.status === "confirmed" || options.mutation.status === "live") {
+        return {
+            state: options.state,
+            mutation: options.mutation,
+            resolution: options.mutation.status,
+        };
+    }
+    if (options.mutation.status === "repair-required") {
+        return {
+            state: options.state,
+            mutation: options.mutation,
+            resolution: "repair-required",
+        };
+    }
+    const walletTx = options.mutation.attemptedTxid === null
+        ? null
+        : await options.rpc.getTransaction(options.walletName, options.mutation.attemptedTxid).catch(() => null);
+    if (walletTx !== null) {
+        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
+        const status = walletTx.confirmations > 0 ? "confirmed" : "live";
+        const nextMutation = updateMutationRecord(options.mutation, status, options.nowUnixMs, {
+            temporaryBuilderLockedOutpoints: [],
+        });
+        let nextState = upsertPendingMutation(options.state, nextMutation);
+        nextState = await saveUpdatedMutationState({
+            state: nextState,
+            provider: options.provider,
+            unlockUntilUnixMs: options.unlockUntilUnixMs,
+            nowUnixMs: options.nowUnixMs,
+            paths: options.paths,
+        });
+        return {
+            state: nextState,
+            mutation: nextMutation,
+            resolution: status,
+        };
+    }
+    if (mutationNeedsRepair(options.mutation, options.context)) {
+        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
+        const repair = updateMutationRecord(options.mutation, "repair-required", options.nowUnixMs, {
+            temporaryBuilderLockedOutpoints: [],
+        });
+        let nextState = upsertPendingMutation(options.state, repair);
+        nextState = await saveUpdatedMutationState({
+            state: nextState,
+            provider: options.provider,
+            unlockUntilUnixMs: options.unlockUntilUnixMs,
+            nowUnixMs: options.nowUnixMs,
+            paths: options.paths,
+        });
+        return { state: nextState, mutation: repair, resolution: "repair-required" };
+    }
+    if (options.mutation.status === "broadcast-unknown"
+        || options.mutation.status === "draft"
+        || options.mutation.status === "broadcasting") {
+        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
+        const canceled = updateMutationRecord(options.mutation, "canceled", options.nowUnixMs, {
+            temporaryBuilderLockedOutpoints: [],
+        });
+        let nextState = upsertPendingMutation(options.state, canceled);
+        nextState = await saveUpdatedMutationState({
+            state: nextState,
+            provider: options.provider,
+            unlockUntilUnixMs: options.unlockUntilUnixMs,
+            nowUnixMs: options.nowUnixMs,
+            paths: options.paths,
+        });
+        return { state: nextState, mutation: canceled, resolution: "not-seen" };
+    }
+    return {
+        state: options.state,
+        mutation: options.mutation,
+        resolution: "continue",
+    };
+}
+async function confirmYesNo(prompter, message, errorCode, options) {
+    await confirmSharedYesNo(prompter, message, {
+        assumeYes: options.assumeYes,
+        errorCode,
+        requiresTtyErrorCode: options.requiresTtyErrorCode,
+    });
+}
+async function confirmTyped(prompter, expected, prompt, errorCode, options) {
+    await confirmSharedTypedAcknowledgement(prompter, {
+        assumeYes: options.assumeYes,
+        expected,
+        prompt,
+        errorCode,
+        requiresTtyErrorCode: options.requiresTtyErrorCode,
+        typedAckRequiredErrorCode: options.typedAckRequiredErrorCode,
+    });
+}
+async function confirmReputationMutation(prompter, options) {
+    prompter.writeLine(`${options.kind === "give" ? "Giving" : "Revoking"} reputation from "${options.sourceDomainName}" to "${options.targetDomainName}".`);
+    prompter.writeLine(`Resolved sender: ${options.resolved.sender.selector} (${options.resolved.sender.address})`);
+    prompter.writeLine(`Burn amount: ${formatCogAmount(options.amountCogtoshi)}`);
+    prompter.writeLine(`Effect: ${describeReputationEffect(options.resolved.effect)}.`);
+    prompter.writeLine(`Review: ${describeReputationReview(options.resolved.review)}.`);
+    if (options.reviewText !== null) {
+        prompter.writeLine("Warning: review text will be encoded and published publicly in the mempool and on-chain.");
+    }
+    if (options.kind === "give" && options.resolved.selfStake) {
+        prompter.writeLine("Self-stake: yes.");
+        prompter.writeLine("Warning: this is self-stake.");
+        prompter.writeLine("Self-stake is irrevocable and cannot later be revoked.");
+        await confirmTyped(prompter, options.sourceDomainName, `Type ${options.sourceDomainName} to continue: `, "wallet_rep_give_confirmation_rejected", {
+            assumeYes: options.assumeYes,
+            requiresTtyErrorCode: "wallet_rep_give_requires_tty",
+            typedAckRequiredErrorCode: "wallet_rep_give_typed_ack_required",
+        });
+        return;
+    }
+    await confirmYesNo(prompter, options.kind === "give"
+        ? "This burns COG to publish a reputation commitment."
+        : "This revokes visible support but the burned COG is not refunded.", options.kind === "give"
+        ? "wallet_rep_give_confirmation_rejected"
+        : "wallet_rep_revoke_confirmation_rejected", {
+        assumeYes: options.assumeYes,
+        requiresTtyErrorCode: options.kind === "give"
+            ? "wallet_rep_give_requires_tty"
+            : "wallet_rep_revoke_requires_tty",
+    });
+}
+async function encodeReviewText(reviewText, errorPrefix) {
+    const trimmed = reviewText?.trim() ?? "";
+    if (trimmed === "") {
+        return {
+            text: null,
+            payload: undefined,
+            payloadHex: null,
+        };
+    }
+    return encodeSentence(trimmed)
+        .then((payload) => ({
+        text: trimmed,
+        payload,
+        payloadHex: Buffer.from(payload).toString("hex"),
+    }))
+        .catch((error) => {
+        throw new Error(error instanceof Error ? `${errorPrefix}_invalid_review_${error.message}` : `${errorPrefix}_invalid_review`);
+    });
+}
+async function sendBuiltTransaction(options) {
+    let nextState = options.state;
+    const broadcasting = updateMutationRecord(options.mutation, "broadcasting", options.nowUnixMs, {
+        attemptedTxid: options.built.txid,
+        attemptedWtxid: options.built.wtxid,
+        temporaryBuilderLockedOutpoints: options.built.temporaryBuilderLockedOutpoints,
+    });
+    nextState = upsertPendingMutation(nextState, broadcasting);
+    nextState = await saveUpdatedMutationState({
+        state: nextState,
+        provider: options.provider,
+        unlockUntilUnixMs: options.unlockUntilUnixMs,
+        nowUnixMs: options.nowUnixMs,
+        paths: options.paths,
+    });
+    if (options.snapshotHeight !== null && options.snapshotHeight !== (await options.rpc.getBlockchainInfo()).blocks) {
+        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.built.temporaryBuilderLockedOutpoints);
+        throw new Error(`${options.errorPrefix}_tip_mismatch`);
+    }
+    try {
+        await options.rpc.sendRawTransaction(options.built.rawHex);
+    }
+    catch (error) {
+        if (!isAlreadyAcceptedError(error)) {
+            if (isBroadcastUnknownError(error)) {
+                const unknown = updateMutationRecord(broadcasting, "broadcast-unknown", options.nowUnixMs, {
+                    attemptedTxid: options.built.txid,
+                    attemptedWtxid: options.built.wtxid,
+                    temporaryBuilderLockedOutpoints: options.built.temporaryBuilderLockedOutpoints,
+                });
+                nextState = upsertPendingMutation(nextState, unknown);
+                nextState = await saveUpdatedMutationState({
+                    state: nextState,
+                    provider: options.provider,
+                    unlockUntilUnixMs: options.unlockUntilUnixMs,
+                    nowUnixMs: options.nowUnixMs,
+                    paths: options.paths,
+                });
+                throw new Error(`${options.errorPrefix}_broadcast_unknown`);
+            }
+            await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.built.temporaryBuilderLockedOutpoints);
+            const canceled = updateMutationRecord(broadcasting, "canceled", options.nowUnixMs, {
+                attemptedTxid: options.built.txid,
+                attemptedWtxid: options.built.wtxid,
+                temporaryBuilderLockedOutpoints: [],
+            });
+            nextState = upsertPendingMutation(nextState, canceled);
+            nextState = await saveUpdatedMutationState({
+                state: nextState,
+                provider: options.provider,
+                unlockUntilUnixMs: options.unlockUntilUnixMs,
+                nowUnixMs: options.nowUnixMs,
+                paths: options.paths,
+            });
+            throw error;
+        }
+    }
+    await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.built.temporaryBuilderLockedOutpoints);
+    const live = updateMutationRecord(broadcasting, "live", options.nowUnixMs, {
+        attemptedTxid: options.built.txid,
+        attemptedWtxid: options.built.wtxid,
+        temporaryBuilderLockedOutpoints: [],
+    });
+    nextState = upsertPendingMutation(nextState, live);
+    nextState = await saveUpdatedMutationState({
+        state: nextState,
+        provider: options.provider,
+        unlockUntilUnixMs: options.unlockUntilUnixMs,
+        nowUnixMs: options.nowUnixMs,
+        paths: options.paths,
+    });
+    return { state: nextState, mutation: live };
+}
+async function submitReputationMutation(options) {
+    if (!options.prompter.isInteractive && options.assumeYes !== true) {
+        throw new Error(`${options.errorPrefix}_requires_tty`);
+    }
+    if (options.amountCogtoshi <= 0n) {
+        throw new Error(`${options.errorPrefix}_invalid_amount`);
+    }
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const controlLock = await acquireFileLock(paths.walletControlLockPath, {
+        purpose: options.errorPrefix,
+        walletRootId: null,
+    });
+    try {
+        const miningPreemption = await pauseMiningForWalletMutation({
+            paths,
+            reason: options.errorPrefix,
+        });
+        const readContext = await (options.openReadContext ?? openWalletReadContext)({
+            dataDir: options.dataDir,
+            databasePath: options.databasePath,
+            secretProvider: provider,
+            paths,
+        });
+        try {
+            const normalizedSourceDomainName = normalizeDomainName(options.sourceDomainName, `${options.errorPrefix}_missing_source_domain`);
+            const normalizedTargetDomainName = normalizeDomainName(options.targetDomainName, `${options.errorPrefix}_missing_target_domain`);
+            const operation = resolveReputationOperation(readContext, normalizedSourceDomainName, normalizedTargetDomainName, options.errorPrefix);
+            if (operation.availableBalanceCogtoshi < options.amountCogtoshi) {
+                throw new Error(`${options.errorPrefix}_insufficient_cog_balance`);
+            }
+            if (options.kind === "rep-revoke") {
+                if (operation.sourceDomain.domainId === operation.targetDomain.domainId) {
+                    throw new Error(`${options.errorPrefix}_self_revoke_not_allowed`);
+                }
+                if (options.amountCogtoshi > operation.currentNetSupportCogtoshi) {
+                    throw new Error(`${options.errorPrefix}_amount_exceeds_net_support`);
+                }
+            }
+            const review = await encodeReviewText(options.reviewText, options.errorPrefix);
+            const selfStake = operation.sourceDomain.domainId === operation.targetDomain.domainId;
+            const resolved = createResolvedReputationSummary({
+                kind: options.kind === "rep-give" ? "give" : "revoke",
+                sender: operation.sender,
+                senderSelector: operation.senderSelector,
+                amountCogtoshi: options.amountCogtoshi,
+                review,
+                selfStake,
+            });
+            const intentFingerprintHex = createIntentFingerprint([
+                options.kind,
+                operation.state.walletRootId,
+                operation.sourceDomain.name,
+                operation.targetDomain.name,
+                options.amountCogtoshi,
+                review.payloadHex ?? "",
+            ]);
+            const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
+                dataDir: options.dataDir,
+                chain: "main",
+                startHeight: 0,
+                walletRootId: operation.state.walletRootId,
+            });
+            const rpc = (options.rpcFactory ?? createRpcClient)(node.rpc);
+            const walletName = operation.state.managedCoreWallet.walletName;
+            const existingMutation = findPendingMutationByIntent(operation.state, intentFingerprintHex);
+            if (existingMutation !== null) {
+                const reconciled = await reconcilePendingReputationMutation({
+                    state: operation.state,
+                    mutation: existingMutation,
+                    provider,
+                    unlockUntilUnixMs: operation.unlockUntilUnixMs,
+                    nowUnixMs,
+                    paths,
+                    rpc,
+                    walletName,
+                    context: readContext,
+                });
+                if (reconciled.resolution === "confirmed" || reconciled.resolution === "live") {
+                    return {
+                        kind: options.kind === "rep-give" ? "give" : "revoke",
+                        sourceDomainName: normalizedSourceDomainName,
+                        targetDomainName: normalizedTargetDomainName,
+                        amountCogtoshi: options.amountCogtoshi,
+                        txid: reconciled.mutation.attemptedTxid ?? "unknown",
+                        status: reconciled.resolution,
+                        reusedExisting: true,
+                        reviewIncluded: review.payloadHex !== null,
+                        resolved,
+                    };
+                }
+                if (reconciled.resolution === "repair-required") {
+                    throw new Error(`${options.errorPrefix}_repair_required`);
+                }
+            }
+            await confirmReputationMutation(options.prompter, {
+                kind: options.kind === "rep-give" ? "give" : "revoke",
+                sourceDomainName: normalizedSourceDomainName,
+                targetDomainName: normalizedTargetDomainName,
+                amountCogtoshi: options.amountCogtoshi,
+                reviewText: review.text,
+                resolved,
+                assumeYes: options.assumeYes,
+            });
+            let nextState = upsertPendingMutation(operation.state, createDraftMutation({
+                kind: options.kind,
+                sourceDomainName: normalizedSourceDomainName,
+                targetDomainName: normalizedTargetDomainName,
+                amountCogtoshi: options.amountCogtoshi,
+                sender: operation.sender,
+                intentFingerprintHex,
+                nowUnixMs,
+                reviewPayloadHex: review.payloadHex,
+                existing: existingMutation,
+            }));
+            nextState = await saveUpdatedMutationState({
+                state: nextState,
+                provider,
+                unlockUntilUnixMs: operation.unlockUntilUnixMs,
+                nowUnixMs,
+                paths,
+            });
+            const opReturnData = options.kind === "rep-give"
+                ? serializeRepCommit(operation.sourceDomain.domainId, operation.targetDomain.domainId, options.amountCogtoshi, review.payload).opReturnData
+                : serializeRepRevoke(operation.sourceDomain.domainId, operation.targetDomain.domainId, options.amountCogtoshi, review.payload).opReturnData;
+            const built = await buildTransaction({
+                rpc,
+                walletName,
+                plan: buildPlanForReputationOperation({
+                    state: nextState,
+                    allUtxos: await rpc.listUnspent(walletName, 1),
+                    sender: operation.sender,
+                    anchorOutpoint: operation.anchorOutpoint,
+                    opReturnData,
+                    errorPrefix: options.errorPrefix,
+                }),
+            });
+            const final = await sendBuiltTransaction({
+                rpc,
+                walletName,
+                snapshotHeight: readContext.snapshot?.tip?.height ?? null,
+                built,
+                mutation: nextState.pendingMutations.find((mutation) => mutation.intentFingerprintHex === intentFingerprintHex),
+                state: nextState,
+                provider,
+                unlockUntilUnixMs: operation.unlockUntilUnixMs,
+                nowUnixMs,
+                paths,
+                errorPrefix: options.errorPrefix,
+            });
+            return {
+                kind: options.kind === "rep-give" ? "give" : "revoke",
+                sourceDomainName: normalizedSourceDomainName,
+                targetDomainName: normalizedTargetDomainName,
+                amountCogtoshi: options.amountCogtoshi,
+                txid: final.mutation.attemptedTxid ?? built.txid,
+                status: "live",
+                reusedExisting: false,
+                reviewIncluded: review.payloadHex !== null,
+                resolved,
+            };
+        }
+        finally {
+            await readContext.close();
+            await miningPreemption.release();
+        }
+    }
+    finally {
+        await controlLock.release();
+    }
+}
+export async function giveReputation(options) {
+    return submitReputationMutation({
+        ...options,
+        kind: "rep-give",
+        errorPrefix: "wallet_rep_give",
+    });
+}
+export async function revokeReputation(options) {
+    return submitReputationMutation({
+        ...options,
+        kind: "rep-revoke",
+        errorPrefix: "wallet_rep_revoke",
+    });
+}