@cogcoin/client 1.1.8 → 1.1.9

package/dist/wallet/tx/field/draft.js

@@ -0,0 +1,202 @@
+import { randomBytes } from "node:crypto";
+import { lookupDomain } from "@cogcoin/indexer/queries";
+import { findDomainField } from "../../read/index.js";
+import { createWalletMutationFeeMetadata, unlockTemporaryBuilderLocks, updateMutationRecord, } from "../common.js";
+import { persistWalletMutationState } from "../executor.js";
+import { upsertPendingMutation } from "../journal.js";
+export function createStandaloneFieldMutation(options) {
+    if (options.existing !== null && options.existing !== undefined) {
+        return {
+            ...options.existing,
+            kind: options.kind,
+            domainName: options.domainName,
+            senderScriptPubKeyHex: options.sender.scriptPubKeyHex,
+            senderLocalIndex: options.sender.localIndex,
+            fieldName: options.fieldName,
+            fieldId: options.fieldId ?? null,
+            fieldPermanent: options.fieldPermanent ?? null,
+            fieldFormat: options.fieldFormat ?? null,
+            fieldValueHex: options.fieldValueHex ?? null,
+            status: "draft",
+            lastUpdatedAtUnixMs: options.nowUnixMs,
+            attemptedTxid: null,
+            attemptedWtxid: null,
+            ...createWalletMutationFeeMetadata(options.feeSelection),
+            temporaryBuilderLockedOutpoints: [],
+        };
+    }
+    return {
+        mutationId: randomBytes(12).toString("hex"),
+        kind: options.kind,
+        domainName: options.domainName,
+        parentDomainName: null,
+        senderScriptPubKeyHex: options.sender.scriptPubKeyHex,
+        senderLocalIndex: options.sender.localIndex,
+        fieldName: options.fieldName,
+        fieldId: options.fieldId ?? null,
+        fieldPermanent: options.fieldPermanent ?? null,
+        fieldFormat: options.fieldFormat ?? null,
+        fieldValueHex: options.fieldValueHex ?? null,
+        intentFingerprintHex: options.intentFingerprintHex,
+        status: "draft",
+        createdAtUnixMs: options.nowUnixMs,
+        lastUpdatedAtUnixMs: options.nowUnixMs,
+        attemptedTxid: null,
+        attemptedWtxid: null,
+        ...createWalletMutationFeeMetadata(options.feeSelection),
+        temporaryBuilderLockedOutpoints: [],
+    };
+}
+function isActiveMutationStatus(status) {
+    return status === "draft"
+        || status === "broadcasting"
+        || status === "broadcast-unknown"
+        || status === "live"
+        || status === "repair-required";
+}
+export function findActiveFieldCreateMutationByDomain(state, domainName, intentFingerprintHex) {
+    return (state.pendingMutations ?? []).find((mutation) => mutation.kind === "field-create"
+        && mutation.domainName === domainName
+        && mutation.intentFingerprintHex !== intentFingerprintHex
+        && isActiveMutationStatus(mutation.status)) ?? null;
+}
+export function getObservedFieldState(context, domainName, fieldName) {
+    if (context.snapshot === null) {
+        return null;
+    }
+    return findDomainField(context, domainName, fieldName);
+}
+function standaloneMutationConfirmedOnChain(mutation, context) {
+    const observed = mutation.fieldName == null
+        ? null
+        : getObservedFieldState(context, mutation.domainName, mutation.fieldName);
+    const chainDomain = context.snapshot === null ? null : lookupDomain(context.snapshot.state, mutation.domainName);
+    if (chainDomain === null || !chainDomain.anchored) {
+        return false;
+    }
+    const ownerHex = Buffer.from(chainDomain.ownerScriptPubKey).toString("hex");
+    if (ownerHex !== mutation.senderScriptPubKeyHex) {
+        return false;
+    }
+    if (mutation.kind === "field-create") {
+        return observed !== null
+            && (mutation.fieldPermanent == null || observed.permanent === mutation.fieldPermanent);
+    }
+    if (mutation.kind === "field-clear") {
+        return observed !== null && !observed.hasValue;
+    }
+    return observed !== null
+        && observed.hasValue
+        && observed.format === (mutation.fieldFormat ?? null)
+        && observed.rawValueHex === (mutation.fieldValueHex ?? null);
+}
+function standaloneMutationNeedsRepair(mutation, context) {
+    if (context.snapshot === null) {
+        return false;
+    }
+    const chainDomain = lookupDomain(context.snapshot.state, mutation.domainName);
+    if (chainDomain === null || !chainDomain.anchored) {
+        return true;
+    }
+    const ownerHex = Buffer.from(chainDomain.ownerScriptPubKey).toString("hex");
+    if (ownerHex !== mutation.senderScriptPubKeyHex) {
+        return true;
+    }
+    if (mutation.fieldName == null) {
+        return false;
+    }
+    const observed = getObservedFieldState(context, mutation.domainName, mutation.fieldName);
+    if (mutation.kind === "field-create") {
+        return observed !== null
+            && mutation.fieldPermanent !== null
+            && observed.permanent !== mutation.fieldPermanent;
+    }
+    if (mutation.kind === "field-set") {
+        return observed !== null
+            && observed.hasValue
+            && ((mutation.fieldFormat ?? null) !== observed.format || (mutation.fieldValueHex ?? null) !== observed.rawValueHex);
+    }
+    return false;
+}
+export async function reconcilePendingFieldMutation(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",
+        };
+    }
+    if (standaloneMutationConfirmedOnChain(options.mutation, options.context)) {
+        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
+        const confirmed = updateMutationRecord(options.mutation, "confirmed", options.nowUnixMs, {
+            temporaryBuilderLockedOutpoints: [],
+        });
+        let nextState = upsertPendingMutation(options.state, confirmed);
+        nextState = await persistWalletMutationState({
+            state: nextState,
+            provider: options.provider,
+            nowUnixMs: options.nowUnixMs,
+            paths: options.paths,
+        });
+        return { state: nextState, mutation: confirmed, resolution: "confirmed" };
+    }
+    if (standaloneMutationNeedsRepair(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 persistWalletMutationState({
+            state: nextState,
+            provider: options.provider,
+            nowUnixMs: options.nowUnixMs,
+            paths: options.paths,
+        });
+        return { state: nextState, mutation: repair, resolution: "repair-required" };
+    }
+    const known = options.mutation.attemptedTxid === null
+        ? false
+        : await options.rpc.getRawTransaction(options.mutation.attemptedTxid, true).then(() => true).catch(() => false);
+    if (known) {
+        await unlockTemporaryBuilderLocks(options.rpc, options.walletName, options.mutation.temporaryBuilderLockedOutpoints);
+        const live = updateMutationRecord(options.mutation, "live", options.nowUnixMs, {
+            temporaryBuilderLockedOutpoints: [],
+        });
+        let nextState = upsertPendingMutation(options.state, live);
+        nextState = await persistWalletMutationState({
+            state: nextState,
+            provider: options.provider,
+            nowUnixMs: options.nowUnixMs,
+            paths: options.paths,
+        });
+        return { state: nextState, mutation: live, resolution: "live" };
+    }
+    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 persistWalletMutationState({
+            state: nextState,
+            provider: options.provider,
+            nowUnixMs: options.nowUnixMs,
+            paths: options.paths,
+        });
+        return { state: nextState, mutation: canceled, resolution: "not-seen" };
+    }
+    return {
+        state: options.state,
+        mutation: options.mutation,
+        resolution: "continue",
+    };
+}

package/dist/wallet/tx/field/index.d.ts

@@ -0,0 +1,5 @@
+import type { ClearFieldOptions, CreateFieldOptions, FieldMutationResult, SetFieldOptions } from "./types.js";
+export type { ClearFieldOptions, CreateFieldOptions, FieldMutationResult, FieldResolvedEffect, FieldResolvedPath, FieldResolvedSenderSummary, FieldResolvedSummary, FieldResolvedValueSummary, FieldValueInputSource, SetFieldOptions, } from "./types.js";
+export declare function createField(options: CreateFieldOptions): Promise<FieldMutationResult>;
+export declare function setField(options: SetFieldOptions): Promise<FieldMutationResult>;
+export declare function clearField(options: ClearFieldOptions): Promise<FieldMutationResult>;

package/dist/wallet/tx/field/index.js

@@ -0,0 +1,140 @@
+import { mergeFixedWalletInputs, } from "../common.js";
+import { executeWalletMutationOperation, publishWalletMutation, resolveExistingWalletMutation, } from "../executor.js";
+import { getObservedFieldState, reconcilePendingFieldMutation, } from "./draft.js";
+import { createFieldIntentFingerprint, normalizeFieldDomainName, normalizeFieldNameInput, resolveAnchoredFieldOperation, } from "./intent.js";
+import { buildAnchoredFieldPlan, buildFieldTransaction, } from "./plan.js";
+import { createFieldResult, createFieldReuseResult, } from "./result.js";
+import { createClearFieldVariant } from "./variants/clear.js";
+import { createFieldCreateVariant } from "./variants/create.js";
+import { createSetFieldVariant } from "./variants/set.js";
+async function submitStandaloneFieldMutation(options, variant) {
+    if (!options.prompter.isInteractive && options.assumeYes !== true) {
+        throw new Error(`${variant.errorPrefix}_requires_tty`);
+    }
+    const execution = await executeWalletMutationOperation({
+        ...options,
+        controlLockPurpose: variant.errorPrefix,
+        preemptionReason: variant.errorPrefix,
+        resolveOperation(readContext) {
+            const normalizedDomainName = normalizeFieldDomainName(options.domainName);
+            const normalizedFieldName = normalizeFieldNameInput(options.fieldName);
+            const operation = resolveAnchoredFieldOperation(readContext, normalizedDomainName, variant.errorPrefix);
+            return {
+                ...operation,
+                normalizedDomainName,
+                normalizedFieldName,
+                existingObservedField: getObservedFieldState(readContext, normalizedDomainName, normalizedFieldName),
+            };
+        },
+        createIntentFingerprint(operation) {
+            return createFieldIntentFingerprint([
+                variant.kind,
+                operation.state.walletRootId,
+                operation.normalizedDomainName,
+                operation.normalizedFieldName,
+            ]);
+        },
+        async resolveExistingMutation({ operation, existingMutation, execution }) {
+            if (existingMutation === null) {
+                return {
+                    state: operation.state,
+                    replacementFixedInputs: null,
+                    result: null,
+                };
+            }
+            return resolveExistingWalletMutation({
+                existingMutation,
+                execution,
+                repairRequiredErrorCode: `${variant.errorPrefix}_repair_required`,
+                reconcileExistingMutation: (mutation) => reconcilePendingFieldMutation({
+                    state: operation.state,
+                    mutation,
+                    provider: execution.provider,
+                    nowUnixMs: execution.nowUnixMs,
+                    paths: execution.paths,
+                    rpc: execution.rpc,
+                    walletName: execution.walletName,
+                    context: execution.readContext,
+                }),
+                createReuseResult: ({ mutation, resolution, fees }) => createFieldReuseResult({
+                    kind: variant.kind,
+                    operation,
+                    mutation,
+                    resolution,
+                    fees,
+                }),
+            });
+        },
+        confirm({ operation }) {
+            return variant.confirm(operation);
+        },
+        async createDraftMutation({ operation, existingMutation, execution }) {
+            const prepared = await variant.createMutation({
+                operation,
+                existing: existingMutation,
+                feeSelection: execution.feeSelection,
+                nowUnixMs: execution.nowUnixMs,
+            });
+            return {
+                mutation: prepared.mutation,
+                prepared: {
+                    opReturnData: prepared.opReturnData,
+                },
+            };
+        },
+        async build({ operation, state, execution, replacementFixedInputs, prepared }) {
+            const fieldPlan = buildAnchoredFieldPlan({
+                state,
+                allUtxos: await execution.rpc.listUnspent(execution.walletName, 1),
+                sender: operation.sender,
+                opReturnData: prepared.opReturnData,
+                errorPrefix: variant.errorPrefix,
+            });
+            return buildFieldTransaction({
+                rpc: execution.rpc,
+                walletName: execution.walletName,
+                state,
+                plan: {
+                    ...fieldPlan,
+                    fixedInputs: mergeFixedWalletInputs(fieldPlan.fixedInputs, replacementFixedInputs),
+                },
+                feeRateSatVb: execution.feeSelection.feeRateSatVb,
+            });
+        },
+        publish({ state, execution, built, mutation }) {
+            return publishWalletMutation({
+                rpc: execution.rpc,
+                walletName: execution.walletName,
+                snapshotHeight: execution.readContext.snapshot?.tip?.height ?? null,
+                built,
+                mutation,
+                state,
+                provider: execution.provider,
+                nowUnixMs: execution.nowUnixMs,
+                paths: execution.paths,
+                errorPrefix: variant.errorPrefix,
+            });
+        },
+        createResult({ operation, mutation, built, status, reusedExisting, fees }) {
+            return createFieldResult({
+                kind: variant.kind,
+                operation,
+                mutation,
+                builtTxid: built?.txid ?? null,
+                status: status,
+                reusedExisting,
+                fees,
+            });
+        },
+    });
+    return execution.result;
+}
+export async function createField(options) {
+    return submitStandaloneFieldMutation(options, createFieldCreateVariant(options));
+}
+export async function setField(options) {
+    return submitStandaloneFieldMutation(options, await createSetFieldVariant(options));
+}
+export async function clearField(options) {
+    return submitStandaloneFieldMutation(options, createClearFieldVariant(options));
+}

package/dist/wallet/tx/field/intent.d.ts

@@ -0,0 +1,5 @@
+import type { FieldOperation, ReadyWalletReadContext } from "./types.js";
+export declare function normalizeFieldDomainName(domainName: string): string;
+export declare function normalizeFieldNameInput(fieldName: string): string;
+export declare function createFieldIntentFingerprint(parts: Array<string | number | bigint>): string;
+export declare function resolveAnchoredFieldOperation(context: ReadyWalletReadContext, domainName: string, errorPrefix: string): FieldOperation;

package/dist/wallet/tx/field/intent.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { lookupDomain } from "@cogcoin/indexer/queries";
+import { validateFieldName } from "../../cogop/validate-name.js";
+import { assertWalletMutationContextReady } from "../common.js";
+export function normalizeFieldDomainName(domainName) {
+    const normalized = domainName.trim().toLowerCase();
+    if (normalized.length === 0) {
+        throw new Error("wallet_field_missing_domain");
+    }
+    return normalized;
+}
+export function normalizeFieldNameInput(fieldName) {
+    const normalized = fieldName.trim().toLowerCase();
+    if (normalized.length === 0) {
+        throw new Error("wallet_field_missing_field_name");
+    }
+    validateFieldName(normalized);
+    return normalized;
+}
+export function createFieldIntentFingerprint(parts) {
+    return createHash("sha256")
+        .update(parts.map((part) => String(part)).join("\n"))
+        .digest("hex");
+}
+export function resolveAnchoredFieldOperation(context, domainName, errorPrefix) {
+    assertWalletMutationContextReady(context, errorPrefix);
+    const chainDomain = lookupDomain(context.snapshot.state, domainName);
+    if (chainDomain === null) {
+        throw new Error(`${errorPrefix}_domain_not_found`);
+    }
+    if (!chainDomain.anchored) {
+        throw new Error(`${errorPrefix}_domain_not_anchored`);
+    }
+    const ownerHex = Buffer.from(chainDomain.ownerScriptPubKey).toString("hex");
+    const state = context.localState.state;
+    if (ownerHex !== state.funding.scriptPubKeyHex || state.funding.address.trim() === "") {
+        throw new Error(`${errorPrefix}_owner_not_locally_controlled`);
+    }
+    return {
+        readContext: context,
+        state,
+        sender: {
+            localIndex: 0,
+            scriptPubKeyHex: state.funding.scriptPubKeyHex,
+            address: state.funding.address,
+        },
+        senderSelector: state.funding.address,
+        chainDomain,
+    };
+}

package/dist/wallet/tx/field/plan.d.ts

@@ -0,0 +1,20 @@
+import type { RpcDecodedPsbt, RpcListUnspentEntry } from "../../../bitcoind/types.js";
+import { type BuiltWalletMutationTransaction, type MutationSender } from "../common.js";
+import type { FieldPlan, FieldRpcClient } from "./types.js";
+import type { WalletStateV1 } from "../../types.js";
+export declare function buildAnchoredFieldPlan(options: {
+    state: WalletStateV1;
+    allUtxos: RpcListUnspentEntry[];
+    sender: MutationSender;
+    opReturnData: Uint8Array;
+    errorPrefix: string;
+}): FieldPlan;
+export declare function validateFieldDraft(decoded: RpcDecodedPsbt, funded: BuiltWalletMutationTransaction["funded"], plan: FieldPlan): void;
+export declare function buildFieldTransaction(options: {
+    rpc: FieldRpcClient;
+    walletName: string;
+    state: WalletStateV1;
+    plan: FieldPlan;
+    feeRateSatVb: number;
+    availableFundingMinConf?: number;
+}): Promise<BuiltWalletMutationTransaction>;

package/dist/wallet/tx/field/plan.js

@@ -0,0 +1,65 @@
+import { buildWalletMutationTransactionWithReserveFallback, outpointKey, } from "../common.js";
+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");
+}
+export function buildAnchoredFieldPlan(options) {
+    const fundingUtxos = options.allUtxos.filter((entry) => entry.scriptPubKey === options.state.funding.scriptPubKeyHex
+        && entry.confirmations >= 1
+        && entry.spendable !== false
+        && entry.safe !== false);
+    return {
+        sender: options.sender,
+        changeAddress: options.state.funding.address,
+        fixedInputs: [],
+        outputs: [{ data: Buffer.from(options.opReturnData).toString("hex") }],
+        changePosition: 1,
+        expectedOpReturnScriptHex: encodeOpReturnScript(options.opReturnData),
+        allowedFundingScriptPubKeyHex: options.state.funding.scriptPubKeyHex,
+        eligibleFundingOutpointKeys: new Set(fundingUtxos.map((entry) => outpointKey({ txid: entry.txid, vout: entry.vout }))),
+        errorPrefix: options.errorPrefix,
+    };
+}
+export function validateFieldDraft(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 (outputs[0]?.scriptPubKey?.hex !== plan.expectedOpReturnScriptHex) {
+        throw new Error(`${plan.errorPrefix}_opreturn_mismatch`);
+    }
+    if (funded.changepos === -1) {
+        if (outputs.length !== 1) {
+            throw new Error(`${plan.errorPrefix}_unexpected_output_count`);
+        }
+        return;
+    }
+    if (funded.changepos !== plan.changePosition || outputs.length !== 2) {
+        throw new Error(`${plan.errorPrefix}_change_position_mismatch`);
+    }
+    if (outputs[funded.changepos]?.scriptPubKey?.hex !== plan.allowedFundingScriptPubKeyHex) {
+        throw new Error(`${plan.errorPrefix}_change_output_mismatch`);
+    }
+}
+export async function buildFieldTransaction(options) {
+    return buildWalletMutationTransactionWithReserveFallback({
+        rpc: options.rpc,
+        walletName: options.walletName,
+        state: options.state,
+        plan: options.plan,
+        validateFundedDraft: validateFieldDraft,
+        finalizeErrorCode: `${options.plan.errorPrefix}_finalize_failed`,
+        mempoolRejectPrefix: `${options.plan.errorPrefix}_mempool_rejected`,
+        feeRate: options.feeRateSatVb,
+        availableFundingMinConf: options.availableFundingMinConf,
+    });
+}

package/dist/wallet/tx/field/result.d.ts

@@ -0,0 +1,29 @@
+import type { PendingMutationRecord } from "../../types.js";
+import type { FieldMutationKind, FieldMutationResult, FieldResolvedEffect, FieldResolvedSenderSummary, FieldResolvedSummary, FieldResolvedValueSummary, StandaloneFieldMutationOperation } from "./types.js";
+import type { MutationSender, WalletMutationFeeSummary } from "../common.js";
+export declare function createResolvedFieldSenderSummary(sender: MutationSender, selector: string): FieldResolvedSenderSummary;
+export declare function createResolvedFieldValueSummary(format: number, value: Uint8Array | string): FieldResolvedValueSummary;
+export declare function createResolvedFieldSummary(options: {
+    sender: MutationSender;
+    senderSelector: string;
+    kind: FieldMutationKind;
+    value: FieldResolvedValueSummary | null;
+}): FieldResolvedSummary;
+export declare function createResolvedFieldValueFromStoredData(kind: FieldMutationKind, format: number | null | undefined, valueHex: string | null | undefined): FieldResolvedValueSummary | null;
+export declare function describeFieldEffect(effect: FieldResolvedEffect): string;
+export declare function createFieldReuseResult(options: {
+    kind: FieldMutationKind;
+    operation: StandaloneFieldMutationOperation;
+    mutation: PendingMutationRecord;
+    resolution: "confirmed" | "live";
+    fees: WalletMutationFeeSummary;
+}): FieldMutationResult;
+export declare function createFieldResult(options: {
+    kind: FieldMutationKind;
+    operation: StandaloneFieldMutationOperation;
+    mutation: PendingMutationRecord;
+    builtTxid: string | null;
+    status: "live" | "confirmed";
+    reusedExisting: boolean;
+    fees: WalletMutationFeeSummary;
+}): FieldMutationResult;

package/dist/wallet/tx/field/result.js

@@ -0,0 +1,103 @@
+export function createResolvedFieldSenderSummary(sender, selector) {
+    return {
+        selector,
+        localIndex: sender.localIndex,
+        scriptPubKeyHex: sender.scriptPubKeyHex,
+        address: sender.address,
+    };
+}
+export function createResolvedFieldValueSummary(format, value) {
+    return {
+        format,
+        byteLength: typeof value === "string" ? value.length / 2 : value.length,
+    };
+}
+export function createResolvedFieldSummary(options) {
+    if (options.kind === "field-create") {
+        return {
+            sender: createResolvedFieldSenderSummary(options.sender, options.senderSelector),
+            path: "standalone-field-reg",
+            value: null,
+            effect: {
+                kind: "create-empty-field",
+                burnCogtoshi: "100",
+            },
+        };
+    }
+    if (options.kind === "field-set") {
+        return {
+            sender: createResolvedFieldSenderSummary(options.sender, options.senderSelector),
+            path: "standalone-data-update",
+            value: options.value,
+            effect: {
+                kind: "write-field-value",
+                burnCogtoshi: "1",
+            },
+        };
+    }
+    return {
+        sender: createResolvedFieldSenderSummary(options.sender, options.senderSelector),
+        path: "standalone-data-clear",
+        value: null,
+        effect: {
+            kind: "clear-field-value",
+            burnCogtoshi: "0",
+        },
+    };
+}
+export function createResolvedFieldValueFromStoredData(kind, format, valueHex) {
+    if (kind === "field-clear" || format === null || format === undefined || valueHex === null || valueHex === undefined) {
+        return null;
+    }
+    return createResolvedFieldValueSummary(format, valueHex);
+}
+export function describeFieldEffect(effect) {
+    switch (effect.kind) {
+        case "create-empty-field":
+            return `burn ${effect.burnCogtoshi} cogtoshi to create an empty field`;
+        case "write-field-value":
+            return `burn ${effect.burnCogtoshi} cogtoshi to write the field value`;
+        case "clear-field-value":
+            return "clear the field value with no additional COG burn";
+    }
+}
+export function createFieldReuseResult(options) {
+    return {
+        kind: options.kind,
+        domainName: options.operation.normalizedDomainName,
+        fieldName: options.operation.normalizedFieldName,
+        fieldId: options.mutation.fieldId ?? options.operation.existingObservedField?.fieldId ?? null,
+        txid: options.mutation.attemptedTxid ?? "unknown",
+        permanent: options.mutation.fieldPermanent ?? options.operation.existingObservedField?.permanent ?? null,
+        format: options.mutation.fieldFormat ?? options.operation.existingObservedField?.format ?? null,
+        status: options.resolution,
+        reusedExisting: true,
+        resolved: createResolvedFieldSummary({
+            sender: options.operation.sender,
+            senderSelector: options.operation.senderSelector,
+            kind: options.kind,
+            value: createResolvedFieldValueFromStoredData(options.kind, options.mutation.fieldFormat ?? options.operation.existingObservedField?.format ?? null, options.mutation.fieldValueHex),
+        }),
+        fees: options.fees,
+    };
+}
+export function createFieldResult(options) {
+    return {
+        kind: options.kind,
+        domainName: options.operation.normalizedDomainName,
+        fieldName: options.operation.normalizedFieldName,
+        fieldId: options.mutation.fieldId ?? options.operation.existingObservedField?.fieldId ?? null,
+        txid: options.mutation.attemptedTxid ?? options.builtTxid ?? "unknown",
+        permanent: options.mutation.fieldPermanent ?? options.operation.existingObservedField?.permanent ?? null,
+        format: options.mutation.fieldFormat ?? options.operation.existingObservedField?.format ?? null,
+        status: options.status,
+        reusedExisting: options.reusedExisting,
+        resolved: createResolvedFieldSummary({
+            sender: options.operation.sender,
+            senderSelector: options.operation.senderSelector,
+            kind: options.kind,
+            value: createResolvedFieldValueFromStoredData(options.kind, options.mutation.fieldFormat ?? options.operation.existingObservedField?.format ?? null, options.mutation.fieldValueHex),
+        }),
+        fees: options.fees,
+    };
+}