@hazbase/simplicity 0.0.5 → 0.2.0

package/dist/domain/bondSettlementValidation.d.ts

@@ -15,4 +15,6 @@ export declare function validateBondSettlementMatchesExpected(actual: BondSettle
     assetIdMatch: boolean;
     nextAmountSatMatch: boolean;
     maxFeeSatMatch: boolean;
+    expectedOutputDescriptorHashMatch: boolean;
+    outputBindingModeMatch: boolean;
 };

package/dist/domain/bondSettlementValidation.js

@@ -33,6 +33,17 @@ function validateBondSettlementDescriptor(value) {
     assertFiniteNumber(descriptor?.redeemAmount, "BOND_SETTLEMENT_REDEEM_AMOUNT_INVALID", "redeemAmount must be a finite number");
     assertFiniteNumber(descriptor?.nextAmountSat, "BOND_SETTLEMENT_AMOUNT_INVALID", "nextAmountSat must be a finite number");
     assertFiniteNumber(descriptor?.maxFeeSat, "BOND_SETTLEMENT_MAX_FEE_INVALID", "maxFeeSat must be a finite number");
+    if (descriptor.expectedOutputDescriptorHash !== undefined && descriptor.expectedOutputDescriptorHash !== null) {
+        assertNonEmptyString(descriptor.expectedOutputDescriptorHash, "BOND_SETTLEMENT_EXPECTED_OUTPUT_DESCRIPTOR_HASH_INVALID", "expectedOutputDescriptorHash must be a non-empty string");
+    }
+    if (descriptor.outputBindingMode !== undefined
+        && descriptor.outputBindingMode !== "none"
+        && descriptor.outputBindingMode !== "script-bound"
+        && descriptor.outputBindingMode !== "descriptor-bound") {
+        throw new errors_1.ValidationError("outputBindingMode must be none, script-bound, or descriptor-bound", {
+            code: "BOND_SETTLEMENT_OUTPUT_BINDING_MODE_INVALID",
+        });
+    }
     assertFiniteNumber(descriptor?.principal?.issued, "BOND_SETTLEMENT_PRINCIPAL_INVALID", "principal.issued must be a finite number");
     assertFiniteNumber(descriptor?.principal?.previousOutstanding, "BOND_SETTLEMENT_PRINCIPAL_INVALID", "principal.previousOutstanding must be a finite number");
     assertFiniteNumber(descriptor?.principal?.nextOutstanding, "BOND_SETTLEMENT_PRINCIPAL_INVALID", "principal.nextOutstanding must be a finite number");
@@ -58,6 +69,11 @@ function validateBondSettlementDescriptor(value) {
             code: "BOND_SETTLEMENT_MAX_FEE_INVALID",
         });
     }
+    if (descriptor.expectedOutputDescriptorHash && !/^[0-9a-f]{64}$/i.test(descriptor.expectedOutputDescriptorHash)) {
+        throw new errors_1.ValidationError("expectedOutputDescriptorHash must be a 64-character hex string", {
+            code: "BOND_SETTLEMENT_EXPECTED_OUTPUT_DESCRIPTOR_HASH_INVALID",
+        });
+    }
     if (Number.isNaN(Date.parse(descriptor.transitionAt))) {
         throw new errors_1.ValidationError("transitionAt must be an ISO8601 string", {
             code: "BOND_SETTLEMENT_TRANSITION_AT_INVALID",
@@ -77,6 +93,8 @@ function validateBondSettlementMatchesExpected(actual, expected) {
         assetIdMatch: actual.assetId === expected.assetId,
         nextAmountSatMatch: actual.nextAmountSat === expected.nextAmountSat,
         maxFeeSatMatch: actual.maxFeeSat === expected.maxFeeSat,
+        expectedOutputDescriptorHashMatch: (actual.expectedOutputDescriptorHash ?? null) === (expected.expectedOutputDescriptorHash ?? null),
+        outputBindingModeMatch: (actual.outputBindingMode ?? "none") === (expected.outputBindingMode ?? "none"),
     };
     if (!result.bondIdMatch) {
         throw new errors_1.ValidationError("Bond settlement bondId does not match expected value", {
@@ -118,5 +136,15 @@ function validateBondSettlementMatchesExpected(actual, expected) {
             code: "BOND_SETTLEMENT_AMOUNT_INVALID",
         });
     }
+    if (!result.expectedOutputDescriptorHashMatch) {
+        throw new errors_1.ValidationError("Bond settlement expectedOutputDescriptorHash does not match expected value", {
+            code: "BOND_SETTLEMENT_EXPECTED_OUTPUT_DESCRIPTOR_HASH_MISMATCH",
+        });
+    }
+    if (!result.outputBindingModeMatch) {
+        throw new errors_1.ValidationError("Bond settlement outputBindingMode does not match expected value", {
+            code: "BOND_SETTLEMENT_OUTPUT_BINDING_MODE_MISMATCH",
+        });
+    }
     return result;
 }

package/dist/domain/bondValidation.d.ts

@@ -1,4 +1,4 @@
-import { BondDefinition, BondIssuanceState } from "../core/types";
+import { BondDefinition, BondIssuanceState, BondIssuanceStatus } from "../core/types";
 export declare function summarizeBondIssuanceState(state: BondIssuanceState): {
     canonicalJson: string;
     hash: string;
@@ -27,3 +27,39 @@ export declare function buildRedeemedBondIssuanceState(input: {
     amount: number;
     redeemedAt: string;
 }): BondIssuanceState;
+export declare function buildClosedBondIssuanceState(input: {
+    previous: BondIssuanceState;
+    closedAt: string;
+    closingReason: "REDEEMED" | "CANCELLED" | "MATURED_OUT";
+    finalSettlementDescriptorHash: string;
+}): BondIssuanceState;
+export declare function verifyBondIssuanceHistory(input: {
+    history: BondIssuanceState[];
+}): {
+    chainLength: number;
+    latestStatus: BondIssuanceStatus | undefined;
+    startsAtGenesis: boolean;
+    previousStateHashLinked: boolean;
+    issuanceIdConsistent: boolean;
+    bondIdConsistent: boolean;
+    currencyConsistent: boolean;
+    controllerConsistent: boolean;
+    issuerEntityConsistent: boolean;
+    issuedPrincipalConsistent: boolean;
+    allPreviousStateHashMatch: boolean;
+    allRedemptionArithmeticValid: boolean;
+    allStatusProgressionValid: boolean;
+    allTransitionIdentitiesMatch: boolean;
+    fullHistoryVerified: boolean;
+    transitionChecks: {
+        issuanceIdMatch: boolean;
+        bondIdMatch: boolean;
+        currencyMatch: boolean;
+        controllerMatch: boolean;
+        issuerEntityMatch: boolean;
+        issuedPrincipalMatch: boolean;
+        previousStateHashMatch: boolean;
+        redemptionArithmeticValid: boolean;
+        statusProgressionValid: boolean;
+    }[];
+};

package/dist/domain/bondValidation.js

@@ -6,8 +6,11 @@ exports.validateBondIssuanceState = validateBondIssuanceState;
 exports.validateBondCrossChecks = validateBondCrossChecks;
 exports.validateBondStateTransition = validateBondStateTransition;
 exports.buildRedeemedBondIssuanceState = buildRedeemedBondIssuanceState;
-const summary_1 = require("../core/summary");
+exports.buildClosedBondIssuanceState = buildClosedBondIssuanceState;
+exports.verifyBondIssuanceHistory = verifyBondIssuanceHistory;
 const errors_1 = require("../core/errors");
+const lineage_1 = require("../core/lineage");
+const summary_1 = require("../core/summary");
 function assertNonEmptyString(value, code, message) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throw new errors_1.ValidationError(message, { code });
@@ -19,8 +22,8 @@ function assertFiniteNumber(value, code, message) {
     }
 }
 function assertValidStatus(status) {
-    if (status !== "ISSUED" && status !== "PARTIALLY_REDEEMED" && status !== "REDEEMED") {
-        throw new errors_1.ValidationError("status must be ISSUED, PARTIALLY_REDEEMED, or REDEEMED", {
+    if (status !== "ISSUED" && status !== "PARTIALLY_REDEEMED" && status !== "REDEEMED" && status !== "CLOSED") {
+        throw new errors_1.ValidationError("status must be ISSUED, PARTIALLY_REDEEMED, REDEEMED, or CLOSED", {
             code: "BOND_STATUS_INVALID",
         });
     }
@@ -153,6 +156,40 @@ function validateBondIssuanceState(value) {
             });
         }
     }
+    if (issuance.status === "CLOSED") {
+        if (issuance.outstandingPrincipal !== 0 || issuance.redeemedPrincipal !== issuance.issuedPrincipal) {
+            throw new errors_1.ValidationError("CLOSED state must have zero outstanding principal and full redeemed principal", {
+                code: "BOND_STATUS_TRANSITION_INVALID",
+            });
+        }
+        if (!issuance.previousStateHash) {
+            throw new errors_1.ValidationError("CLOSED state must set previousStateHash", {
+                code: "BOND_PREVIOUS_STATE_HASH_INVALID",
+            });
+        }
+        if (!issuance.closedAt || Number.isNaN(Date.parse(issuance.closedAt))) {
+            throw new errors_1.ValidationError("CLOSED state must set closedAt as an ISO8601 string", {
+                code: "BOND_CLOSED_AT_INVALID",
+            });
+        }
+        if (issuance.closingReason !== "REDEEMED"
+            && issuance.closingReason !== "CANCELLED"
+            && issuance.closingReason !== "MATURED_OUT") {
+            throw new errors_1.ValidationError("CLOSED state must set a valid closingReason", {
+                code: "BOND_CLOSING_REASON_INVALID",
+            });
+        }
+        if (!issuance.finalSettlementDescriptorHash || !/^[0-9a-f]{64}$/i.test(issuance.finalSettlementDescriptorHash)) {
+            throw new errors_1.ValidationError("CLOSED state must set finalSettlementDescriptorHash as a 64-character hex string", {
+                code: "BOND_FINAL_SETTLEMENT_DESCRIPTOR_HASH_INVALID",
+            });
+        }
+        if (!transition || transition.type !== "REDEEM") {
+            throw new errors_1.ValidationError("CLOSED state must carry a REDEEM transition", {
+                code: "BOND_TRANSITION_TYPE_INVALID",
+            });
+        }
+    }
     return issuance;
 }
 function validateBondCrossChecks(definition, issuance) {
@@ -241,21 +278,29 @@ function validateBondStateTransition(previous, next) {
             code: "BOND_TRANSITION_TYPE_INVALID",
         });
     }
-    const expectedOutstanding = previous.outstandingPrincipal - transition.amount;
-    const expectedRedeemed = previous.redeemedPrincipal + transition.amount;
-    result.redemptionArithmeticValid =
-        expectedOutstanding >= 0 &&
-            next.outstandingPrincipal === expectedOutstanding &&
-            next.redeemedPrincipal === expectedRedeemed;
+    if (previous.status === "REDEEMED" && next.status === "CLOSED") {
+        result.redemptionArithmeticValid =
+            next.outstandingPrincipal === previous.outstandingPrincipal &&
+                next.redeemedPrincipal === previous.redeemedPrincipal;
+    }
+    else {
+        const expectedOutstanding = previous.outstandingPrincipal - transition.amount;
+        const expectedRedeemed = previous.redeemedPrincipal + transition.amount;
+        result.redemptionArithmeticValid =
+            expectedOutstanding >= 0 &&
+                next.outstandingPrincipal === expectedOutstanding &&
+                next.redeemedPrincipal === expectedRedeemed;
+    }
     if (!result.redemptionArithmeticValid) {
         throw new errors_1.ValidationError("Bond issuance redemption arithmetic is invalid", {
             code: "BOND_REDEMPTION_ARITHMETIC_INVALID",
         });
     }
     result.statusProgressionValid =
-        (previous.status === "ISSUED" || previous.status === "PARTIALLY_REDEEMED") &&
+        (((previous.status === "ISSUED" || previous.status === "PARTIALLY_REDEEMED") &&
             ((next.status === "PARTIALLY_REDEEMED" && next.outstandingPrincipal > 0) ||
-                (next.status === "REDEEMED" && next.outstandingPrincipal === 0));
+                (next.status === "REDEEMED" && next.outstandingPrincipal === 0))) ||
+            (previous.status === "REDEEMED" && next.status === "CLOSED" && next.outstandingPrincipal === 0));
     if (!result.statusProgressionValid) {
         throw new errors_1.ValidationError("Bond issuance status progression is invalid", {
             code: "BOND_STATUS_TRANSITION_INVALID",
@@ -301,3 +346,84 @@ function buildRedeemedBondIssuanceState(input) {
     };
     return validateBondIssuanceState(next);
 }
+function buildClosedBondIssuanceState(input) {
+    const previous = validateBondIssuanceState(input.previous);
+    if (previous.status !== "REDEEMED") {
+        throw new errors_1.ValidationError("Only a REDEEMED issuance state can be closed", {
+            code: "BOND_CLOSING_PRECONDITION_INVALID",
+        });
+    }
+    assertNonEmptyString(input.closedAt, "BOND_CLOSED_AT_INVALID", "closedAt must be a non-empty string");
+    if (Number.isNaN(Date.parse(input.closedAt))) {
+        throw new errors_1.ValidationError("closedAt must be an ISO8601 string", {
+            code: "BOND_CLOSED_AT_INVALID",
+        });
+    }
+    if (!/^[0-9a-f]{64}$/i.test(input.finalSettlementDescriptorHash)) {
+        throw new errors_1.ValidationError("finalSettlementDescriptorHash must be a 64-character hex string", {
+            code: "BOND_FINAL_SETTLEMENT_DESCRIPTOR_HASH_INVALID",
+        });
+    }
+    return validateBondIssuanceState({
+        ...previous,
+        status: "CLOSED",
+        previousStateHash: summarizeBondIssuanceState(previous).hash,
+        closedAt: input.closedAt,
+        closingReason: input.closingReason,
+        finalSettlementDescriptorHash: input.finalSettlementDescriptorHash,
+    });
+}
+function verifyBondIssuanceHistory(input) {
+    if (input.history.length === 0) {
+        throw new errors_1.ValidationError("bond issuance history must include at least one state", {
+            code: "BOND_ISSUANCE_HISTORY_REQUIRED",
+        });
+    }
+    const history = input.history.map((state) => validateBondIssuanceState(state));
+    const lineage = (0, lineage_1.verifyHashLinkedLineage)({
+        entries: history,
+        summarize: summarizeBondIssuanceState,
+        getPreviousHash: (state) => state.previousStateHash,
+        isGenesis: (state) => state.status === "ISSUED" && !state.previousStateHash,
+        consistencyChecks: {
+            issuanceIdConsistent: (state, first) => state.issuanceId === first.issuanceId,
+            bondIdConsistent: (state, first) => state.bondId === first.bondId,
+            currencyConsistent: (state, first) => state.currencyAssetId === first.currencyAssetId,
+            controllerConsistent: (state, first) => state.controllerXonly === first.controllerXonly,
+            issuerEntityConsistent: (state, first) => state.issuerEntityId === first.issuerEntityId,
+            issuedPrincipalConsistent: (state, first) => state.issuedPrincipal === first.issuedPrincipal,
+        },
+    });
+    const transitionChecks = history.slice(1).map((state, index) => validateBondStateTransition(history[index], state));
+    const allPreviousStateHashMatch = transitionChecks.every((check) => check.previousStateHashMatch);
+    const allRedemptionArithmeticValid = transitionChecks.every((check) => check.redemptionArithmeticValid);
+    const allStatusProgressionValid = transitionChecks.every((check) => check.statusProgressionValid);
+    const allTransitionIdentitiesMatch = transitionChecks.every((check) => (check.issuanceIdMatch
+        && check.bondIdMatch
+        && check.currencyMatch
+        && check.controllerMatch
+        && check.issuerEntityMatch
+        && check.issuedPrincipalMatch));
+    return {
+        chainLength: history.length,
+        latestStatus: history.at(-1)?.status,
+        startsAtGenesis: lineage.startsAtGenesis,
+        previousStateHashLinked: lineage.previousHashLinked,
+        issuanceIdConsistent: lineage.consistency.issuanceIdConsistent,
+        bondIdConsistent: lineage.consistency.bondIdConsistent,
+        currencyConsistent: lineage.consistency.currencyConsistent,
+        controllerConsistent: lineage.consistency.controllerConsistent,
+        issuerEntityConsistent: lineage.consistency.issuerEntityConsistent,
+        issuedPrincipalConsistent: lineage.consistency.issuedPrincipalConsistent,
+        allPreviousStateHashMatch,
+        allRedemptionArithmeticValid,
+        allStatusProgressionValid,
+        allTransitionIdentitiesMatch,
+        fullHistoryVerified: lineage.fullLineageVerified
+            && allPreviousStateHashMatch
+            && allRedemptionArithmeticValid
+            && allStatusProgressionValid
+            && allTransitionIdentitiesMatch,
+        transitionChecks,
+    };
+}