@hazbase/simplicity 0.1.1 → 0.2.1

package/dist/domain/fund.js

@@ -10,6 +10,7 @@ exports.prepareCapitalCall = prepareCapitalCall;
 exports.verifyCapitalCall = verifyCapitalCall;
 exports.signPositionReceipt = signPositionReceipt;
 exports.verifyPositionReceipt = verifyPositionReceipt;
+exports.verifyPositionReceiptChain = verifyPositionReceiptChain;
 exports.inspectCapitalCallClaim = inspectCapitalCallClaim;
 exports.executeCapitalCallClaim = executeCapitalCallClaim;
 exports.inspectCapitalCallRollover = inspectCapitalCallRollover;
@@ -31,6 +32,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const errors_1 = require("../core/errors");
 const summary_1 = require("../core/summary");
 const outputBinding_1 = require("../core/outputBinding");
+const reporting_1 = require("../core/reporting");
 const fundValidation_1 = require("./fundValidation");
 const FUND_VERIFICATION_REPORT_SCHEMA_VERSION = "fund-verification-report/v1";
 const FUND_EVIDENCE_BUNDLE_SCHEMA_VERSION = "fund-evidence-bundle/v1";
@@ -305,8 +307,23 @@ function buildRolloverWitness() {
         },
     };
 }
-function buildRefundWitness() {
-    return { values: {} };
+function buildRefundWitness(descriptor) {
+    return {
+        values: {
+            EXPECTED_PAYOUT_OUTPUT_HASH: {
+                type: "u256",
+                value: `0x${descriptor.nextOutputHash ?? "0000000000000000000000000000000000000000000000000000000000000000"}`,
+            },
+            EXPECTED_PAYOUT_OUTPUT_SCRIPT_HASH: {
+                type: "u256",
+                value: `0x${descriptor.nextOutputScriptHash ?? "0000000000000000000000000000000000000000000000000000000000000000"}`,
+            },
+            OUTPUT_BINDING_MODE: {
+                type: "u8",
+                value: buildBindingModeWitnessValue(descriptor.outputBindingMode),
+            },
+        },
+    };
 }
 function buildDistributionWitness(descriptor) {
     return {
@@ -391,6 +408,18 @@ async function loadPositionReceiptEnvelopeDocument(sdk, input) {
         envelopeSummary: (0, fundValidation_1.summarizeLPPositionReceiptEnvelope)(value),
     };
 }
+async function loadPositionReceiptEnvelopeChainDocuments(sdk, input) {
+    const combinedPaths = [...(input.positionReceiptChainPaths ?? [])];
+    const combinedValues = [...(input.positionReceiptChainValues ?? [])];
+    const results = [];
+    for (const positionReceiptPath of combinedPaths) {
+        results.push(await loadPositionReceiptEnvelopeDocument(sdk, { positionReceiptPath }));
+    }
+    for (const positionReceiptValue of combinedValues) {
+        results.push(await loadPositionReceiptEnvelopeDocument(sdk, { positionReceiptValue }));
+    }
+    return results;
+}
 async function loadDistributionDocument(sdk, input) {
     const source = resolveValueOrPath({ pathValue: input.distributionPath, objectValue: input.distributionValue });
     let value;
@@ -461,8 +490,33 @@ async function loadClosingDocument(sdk, input) {
     });
     return { descriptor, value, summary: (0, fundValidation_1.summarizeFundClosingDescriptor)(value) };
 }
-function buildBaseFundReport() {
-    return { schemaVersion: FUND_VERIFICATION_REPORT_SCHEMA_VERSION };
+function buildEmptyFundDefinitionTrust() {
+    return {
+        artifactMatch: false,
+        onChainAnchorPresent: false,
+        onChainAnchorVerified: false,
+        effectiveMode: "none",
+    };
+}
+function buildEmptyFundStateTrust() {
+    return {
+        artifactMatch: false,
+        onChainAnchorPresent: false,
+        onChainAnchorVerified: false,
+        effectiveMode: "none",
+    };
+}
+function buildBaseFundReport(input) {
+    return {
+        schemaVersion: FUND_VERIFICATION_REPORT_SCHEMA_VERSION,
+        ...(0, reporting_1.buildVerificationTrustSections)({
+            definitionTrust: input?.definitionTrust,
+            stateTrust: input?.stateTrust,
+            requireArtifactTrust: input?.requireArtifactTrust,
+            emptyDefinitionTrust: buildEmptyFundDefinitionTrust(),
+            emptyStateTrust: buildEmptyFundStateTrust(),
+        }),
+    };
 }
 async function compileOpenCapitalCallContract(sdk, input) {
     return sdk.compileFromFile({
@@ -549,10 +603,28 @@ async function requireRefundOnlyArtifact(sdk, input) {
     }
     return artifact;
 }
-function ensureVerifiedEnvelope(definition, envelope) {
-    const checks = (0, fundValidation_1.verifyLPPositionReceiptEnvelope)({
+async function ensureVerifiedEnvelope(definition, envelope) {
+    const checks = await (0, fundValidation_1.verifyLPPositionReceiptEnvelope)({
+        envelope,
+        expectedManagerXonly: definition.managerXonly,
+    });
+    if (!checks.positionReceiptHashMatch
+        || !checks.sequenceMatch
+        || !checks.sequenceMonotonic
+        || !checks.attestingSignerMatch
+        || !checks.attestationVerified) {
+        throw new errors_1.ValidationError("Position receipt envelope must be attested and internally consistent", {
+            code: "FUND_POSITION_ENVELOPE_VERIFY_FAILED",
+            checks,
+        });
+    }
+    return checks;
+}
+async function ensureVerifiedEnvelopeContinuity(definition, envelope, previousEnvelope) {
+    const checks = await (0, fundValidation_1.verifyLPPositionReceiptEnvelope)({
         envelope,
         expectedManagerXonly: definition.managerXonly,
+        previousEnvelope,
     });
     if (!checks.positionReceiptHashMatch
         || !checks.sequenceMatch
@@ -564,6 +636,20 @@ function ensureVerifiedEnvelope(definition, envelope) {
             checks,
         });
     }
+    if (envelope.receipt.sequence > 0) {
+        if (!previousEnvelope) {
+            throw new errors_1.ValidationError("sequence>0 receipts require the immediate previous receipt envelope", {
+                code: "FUND_PREVIOUS_POSITION_ENVELOPE_REQUIRED",
+                checks,
+            });
+        }
+        if (!checks.continuityVerified) {
+            throw new errors_1.ValidationError("Position receipt envelope continuity must match the immediate previous envelope", {
+                code: "FUND_POSITION_ENVELOPE_CONTINUITY_VERIFY_FAILED",
+                checks,
+            });
+        }
+    }
     return checks;
 }
 function buildReceiptTrust(input) {
@@ -576,6 +662,79 @@ function buildReceiptTrust(input) {
         sequence: input.envelope.receipt.sequence,
         sequenceMonotonic: input.checks.sequenceMonotonic && input.checks.sequenceMatch,
         attestingSignerMatch: input.checks.attestingSignerMatch,
+        previousEnvelopeProvided: input.checks.previousEnvelopeProvided,
+        previousReceiptHashMatch: input.checks.previousReceiptHashMatch,
+        previousSequenceMatch: input.checks.previousSequenceMatch,
+        continuityVerified: input.checks.continuityVerified,
+    };
+}
+function buildReceiptChainTrust(input) {
+    const identityConsistent = input.fundConsistent
+        && input.positionConsistent
+        && input.lpConsistent
+        && input.callConsistent
+        && input.currencyConsistent
+        && input.lpXonlyConsistent
+        && input.attestingSignerConsistent;
+    return {
+        ...(0, reporting_1.buildLineageTrustBase)({
+            lineageKind: "receipt-chain",
+            chainLength: input.chainLength,
+            latestOrdinal: input.latestSequence ?? Math.max(0, input.chainLength - 1),
+            allHashLinksVerified: input.allContinuityVerified && input.allPositionReceiptHashMatch,
+            identityConsistent,
+            fullLineageVerified: input.fullChainVerified,
+        }),
+        latestSequence: input.latestSequence,
+        startsAtGenesis: input.startsAtGenesis,
+        latestSequenceCovered: input.latestSequenceCovered,
+        sequenceContiguous: input.sequenceContiguous,
+        fundConsistent: input.fundConsistent,
+        positionConsistent: input.positionConsistent,
+        lpConsistent: input.lpConsistent,
+        callConsistent: input.callConsistent,
+        currencyConsistent: input.currencyConsistent,
+        lpXonlyConsistent: input.lpXonlyConsistent,
+        attestingSignerConsistent: input.attestingSignerConsistent,
+        allPositionReceiptHashMatch: input.allPositionReceiptHashMatch,
+        allSequenceMatch: input.allSequenceMatch,
+        allSequenceMonotonic: input.allSequenceMonotonic,
+        allAttestingSignerMatch: input.allAttestingSignerMatch,
+        allAttestationVerified: input.allAttestationVerified,
+        allContinuityVerified: input.allContinuityVerified,
+        fullChainVerified: input.fullChainVerified,
+    };
+}
+function resolveReceiptChainContext(input) {
+    const chainEntries = input.chainEntries && input.chainEntries.length > 0
+        ? input.chainEntries
+        : input.receipt
+            ? [
+                ...(input.previousEnvelope ? [input.previousEnvelope] : []),
+                input.receipt,
+            ]
+            : [];
+    const receipt = input.receipt ?? chainEntries.at(-1);
+    if (!receipt) {
+        throw new errors_1.ValidationError("position receipt envelope is required", {
+            code: "FUND_POSITION_RECEIPT_REQUIRED",
+        });
+    }
+    const latestChainEntry = chainEntries.at(-1);
+    if (latestChainEntry && latestChainEntry.envelopeSummary.hash !== receipt.envelopeSummary.hash) {
+        throw new errors_1.ValidationError("position receipt chain must end with the provided latest envelope", {
+            code: "FUND_POSITION_CHAIN_LATEST_MISMATCH",
+            latestEnvelopeHash: receipt.envelopeSummary.hash,
+            chainLatestEnvelopeHash: latestChainEntry.envelopeSummary.hash,
+        });
+    }
+    const previousEnvelope = chainEntries.length > 1
+        ? chainEntries[chainEntries.length - 2]
+        : input.previousEnvelope;
+    return {
+        receipt,
+        previousEnvelope,
+        chainEntries,
     };
 }
 async function define(sdk, input) {
@@ -713,16 +872,10 @@ async function verifyCapitalCall(sdk, input) {
             ? { definition: definitionVerification, state: stateVerification }
             : undefined,
         report: {
-            ...buildBaseFundReport(),
-            ...(definitionVerification && stateVerification
-                ? {
-                    artifactTrust: {
-                        definition: definitionVerification.trust,
-                        state: stateVerification.trust,
-                    },
-                    stateTrust: stateVerification.trust,
-                }
-                : {}),
+            ...buildBaseFundReport({
+                definitionTrust: definitionVerification?.trust,
+                stateTrust: stateVerification?.trust,
+            }),
             capitalCallTrust: {
                 capitalCallStage: deriveCapitalCallStage(capitalCall.value),
                 cutoffMode: "rollover-window",
@@ -742,7 +895,7 @@ async function verifyCapitalCall(sdk, input) {
 async function signPositionReceipt(sdk, input) {
     const definition = await loadFundDefinitionDocument(sdk, input);
     const receipt = await loadBarePositionReceiptDocument(sdk, input);
-    const positionReceiptEnvelope = (0, fundValidation_1.signLPPositionReceipt)({
+    const positionReceiptEnvelope = await (0, fundValidation_1.signLPPositionReceipt)({
         receipt: receipt.value,
         managerXonly: definition.value.managerXonly,
         signer: input.signer,
@@ -761,21 +914,101 @@ async function signPositionReceipt(sdk, input) {
 }
 async function verifyPositionReceipt(sdk, input) {
     const definition = await loadFundDefinitionDocument(sdk, input);
-    const envelope = await loadPositionReceiptEnvelopeDocument(sdk, input);
-    const receiptChecks = ensureVerifiedEnvelope(definition.value, envelope.value);
+    const envelope = input.positionReceiptPath || input.positionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, input)
+        : undefined;
+    const previousEnvelope = input.previousPositionReceiptPath || input.previousPositionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, {
+            positionReceiptPath: input.previousPositionReceiptPath,
+            positionReceiptValue: input.previousPositionReceiptValue,
+        })
+        : undefined;
+    const chainEntries = input.positionReceiptChainPaths || input.positionReceiptChainValues
+        ? await loadPositionReceiptEnvelopeChainDocuments(sdk, {
+            positionReceiptChainPaths: input.positionReceiptChainPaths,
+            positionReceiptChainValues: input.positionReceiptChainValues,
+        })
+        : [];
+    const context = resolveReceiptChainContext({
+        receipt: envelope,
+        previousEnvelope,
+        chainEntries,
+    });
+    const receiptChecks = await ensureVerifiedEnvelopeContinuity(definition.value, context.receipt.value, context.previousEnvelope?.value);
+    const chainChecks = await (0, fundValidation_1.verifyLPPositionReceiptEnvelopeChain)({
+        envelopes: context.chainEntries.map((entry) => entry.value),
+        expectedManagerXonly: definition.value.managerXonly,
+    });
     return {
         verified: true,
         definition: definition.descriptor,
         definitionValue: definition.value,
         definitionSummary: definition.summary,
-        positionReceipt: envelope.descriptor,
-        positionReceiptValue: envelope.value,
-        positionReceiptSummary: envelope.receiptSummary,
-        positionReceiptEnvelopeSummary: envelope.envelopeSummary,
+        positionReceipt: context.receipt.descriptor,
+        positionReceiptValue: context.receipt.value,
+        positionReceiptSummary: context.receipt.receiptSummary,
+        positionReceiptEnvelopeSummary: context.receipt.envelopeSummary,
+        ...(context.previousEnvelope
+            ? {
+                previousPositionReceipt: context.previousEnvelope.descriptor,
+                previousPositionReceiptValue: context.previousEnvelope.value,
+                previousPositionReceiptSummary: context.previousEnvelope.receiptSummary,
+                previousPositionReceiptEnvelopeSummary: context.previousEnvelope.envelopeSummary,
+            }
+            : {}),
+        ...(context.chainEntries.length > 0
+            ? {
+                positionReceiptChain: context.chainEntries.map((entry) => entry.descriptor),
+                positionReceiptChainValues: context.chainEntries.map((entry) => entry.value),
+                positionReceiptChainSummaries: context.chainEntries.map((entry) => entry.receiptSummary),
+                positionReceiptEnvelopeChainSummaries: context.chainEntries.map((entry) => entry.envelopeSummary),
+            }
+            : {}),
+        receiptChecks,
+        receiptChainChecks: chainChecks,
+        report: {
+            ...buildBaseFundReport(),
+            receiptTrust: buildReceiptTrust({ generated: false, envelope: context.receipt.value, checks: receiptChecks }),
+            receiptChainTrust: buildReceiptChainTrust(chainChecks),
+        },
+    };
+}
+async function verifyPositionReceiptChain(sdk, input) {
+    const definition = await loadFundDefinitionDocument(sdk, input);
+    const chainEntries = await loadPositionReceiptEnvelopeChainDocuments(sdk, input);
+    const context = resolveReceiptChainContext({ chainEntries });
+    const receiptChecks = await ensureVerifiedEnvelopeContinuity(definition.value, context.receipt.value, context.previousEnvelope?.value);
+    const chainChecks = await (0, fundValidation_1.verifyLPPositionReceiptEnvelopeChain)({
+        envelopes: context.chainEntries.map((entry) => entry.value),
+        expectedManagerXonly: definition.value.managerXonly,
+    });
+    return {
+        verified: chainChecks.fullChainVerified,
+        definition: definition.descriptor,
+        definitionValue: definition.value,
+        definitionSummary: definition.summary,
+        positionReceipt: context.receipt.descriptor,
+        positionReceiptValue: context.receipt.value,
+        positionReceiptSummary: context.receipt.receiptSummary,
+        positionReceiptEnvelopeSummary: context.receipt.envelopeSummary,
+        ...(context.previousEnvelope
+            ? {
+                previousPositionReceipt: context.previousEnvelope.descriptor,
+                previousPositionReceiptValue: context.previousEnvelope.value,
+                previousPositionReceiptSummary: context.previousEnvelope.receiptSummary,
+                previousPositionReceiptEnvelopeSummary: context.previousEnvelope.envelopeSummary,
+            }
+            : {}),
+        positionReceiptChain: context.chainEntries.map((entry) => entry.descriptor),
+        positionReceiptChainValues: context.chainEntries.map((entry) => entry.value),
+        positionReceiptChainSummaries: context.chainEntries.map((entry) => entry.receiptSummary),
+        positionReceiptEnvelopeChainSummaries: context.chainEntries.map((entry) => entry.envelopeSummary),
         receiptChecks,
+        receiptChainChecks: chainChecks,
         report: {
             ...buildBaseFundReport(),
-            receiptTrust: buildReceiptTrust({ generated: false, envelope: envelope.value, checks: receiptChecks }),
+            receiptTrust: buildReceiptTrust({ generated: false, envelope: context.receipt.value, checks: receiptChecks }),
+            receiptChainTrust: buildReceiptChainTrust(chainChecks),
         },
     };
 }
@@ -805,13 +1038,13 @@ async function inspectCapitalCallClaim(sdk, input) {
         capitalCall: verified.capitalCallValue,
         effectiveAt: claimedAt,
     });
-    const positionReceiptEnvelope = (0, fundValidation_1.signLPPositionReceipt)({
+    const positionReceiptEnvelope = await (0, fundValidation_1.signLPPositionReceipt)({
         receipt: positionReceipt,
         managerXonly: definition.value.managerXonly,
         signer: input.signer,
         signedAt: claimedAt,
     });
-    const receiptChecks = ensureVerifiedEnvelope(definition.value, positionReceiptEnvelope);
+    const receiptChecks = await ensureVerifiedEnvelope(definition.value, positionReceiptEnvelope);
     const contract = sdk.fromArtifact(artifact);
     const inspect = await contract.inspectCall({
         wallet: input.wallet,
@@ -940,22 +1173,43 @@ async function inspectCapitalCallRefund(sdk, input) {
             },
         });
     }
+    const payout = await buildFundPayoutDescriptor(sdk, {
+        receiverAddress: input.refundAddress,
+        amountSat: refundAmountSat,
+        assetId: verified.capitalCallValue.currencyAssetId,
+        nextOutputHash: input.nextOutputHash,
+        outputForm: input.outputForm,
+        rawOutput: input.rawOutput,
+        outputBindingMode: input.outputBindingMode,
+    });
     const contract = sdk.fromArtifact(artifact);
     const inspect = await contract.inspectCall({
         wallet: input.wallet,
-        toAddress: input.refundAddress,
+        toAddress: payout.descriptor.receiverAddress,
         signer: input.signer,
-        sendAmount: satToBtcAmount(refundAmountSat),
+        sendAmount: satToBtcAmount(payout.descriptor.amountSat),
         feeSat,
         utxoPolicy: input.utxoPolicy,
-        witness: buildRefundWitness(),
+        witness: buildRefundWitness(payout.descriptor),
     });
     return {
         mode: "refund",
         verified,
+        payoutDescriptor: payout.descriptor,
+        payoutSummary: payout.summary,
         refundedCapitalCall,
         inspect,
-        report: verified.report,
+        report: {
+            ...verified.report,
+            outputBindingTrust: buildFundOutputBindingReport({
+                descriptor: payout.descriptor,
+                supportedForm: payout.supportedForm,
+                reasonCode: payout.reasonCode,
+                autoDerived: payout.autoDerivedNextOutputHash,
+                fallbackReason: payout.fallbackReason,
+                bindingInputs: payout.bindingInputs,
+            }),
+        },
     };
 }
 async function executeCapitalCallRefund(sdk, input) {
@@ -963,16 +1217,15 @@ async function executeCapitalCallRefund(sdk, input) {
     const artifact = await requireFundArtifact(sdk, input);
     const contract = sdk.fromArtifact(artifact);
     const feeSat = input.feeSat ?? 100;
-    const refundAmountSat = inspected.verified.capitalCallValue.amount - feeSat;
     const execution = await contract.execute({
         wallet: input.wallet,
-        toAddress: input.refundAddress,
+        toAddress: inspected.payoutDescriptor.receiverAddress,
         signer: input.signer,
-        sendAmount: satToBtcAmount(refundAmountSat),
+        sendAmount: satToBtcAmount(inspected.payoutDescriptor.amountSat),
         feeSat,
         utxoPolicy: input.utxoPolicy,
         broadcast: input.broadcast,
-        witness: buildRefundWitness(),
+        witness: buildRefundWitness(inspected.payoutDescriptor),
     });
     return {
         ...inspected,
@@ -983,7 +1236,7 @@ async function executeCapitalCallRefund(sdk, input) {
 async function prepareDistribution(sdk, input) {
     const definition = await loadFundDefinitionDocument(sdk, input);
     const receipt = await loadPositionReceiptEnvelopeDocument(sdk, input);
-    const receiptChecks = ensureVerifiedEnvelope(definition.value, receipt.value);
+    const receiptChecks = await ensureVerifiedEnvelope(definition.value, receipt.value);
     const distribution = await loadDistributionDocument(sdk, {
         distributionPath: input.distributionPath,
         distributionValue: input.distributionValue,
@@ -1024,13 +1277,13 @@ async function prepareDistribution(sdk, input) {
 async function reconcilePosition(sdk, input) {
     const definition = await loadFundDefinitionDocument(sdk, input);
     const receipt = await loadPositionReceiptEnvelopeDocument(sdk, input);
-    ensureVerifiedEnvelope(definition.value, receipt.value);
+    await ensureVerifiedEnvelope(definition.value, receipt.value);
     const distributions = await loadDistributionDocuments(sdk, input);
     const reconciledReceiptValue = (0, fundValidation_1.reconcileLPPositionReceipt)({
         previousEnvelope: receipt.value,
         distributions: distributions.map((entry) => entry.value),
     });
-    const reconciledReceiptEnvelope = (0, fundValidation_1.signLPPositionReceipt)({
+    const reconciledReceiptEnvelope = await (0, fundValidation_1.signLPPositionReceipt)({
         receipt: reconciledReceiptValue,
         managerXonly: definition.value.managerXonly,
         signer: input.signer,
@@ -1058,7 +1311,7 @@ async function reconcilePosition(sdk, input) {
 async function verifyDistribution(sdk, input) {
     const definition = await loadFundDefinitionDocument(sdk, input);
     const receipt = await loadPositionReceiptEnvelopeDocument(sdk, input);
-    const receiptChecks = ensureVerifiedEnvelope(definition.value, receipt.value);
+    const receiptChecks = await ensureVerifiedEnvelope(definition.value, receipt.value);
     const distribution = await loadDistributionDocument(sdk, {
         distributionPath: input.distributionPath,
         distributionValue: input.distributionValue,
@@ -1111,16 +1364,10 @@ async function verifyDistribution(sdk, input) {
             ? { definition: definitionVerification, state: stateVerification }
             : undefined,
         report: {
-            ...buildBaseFundReport(),
-            ...(definitionVerification && stateVerification
-                ? {
-                    artifactTrust: {
-                        definition: definitionVerification.trust,
-                        state: stateVerification.trust,
-                    },
-                    stateTrust: stateVerification.trust,
-                }
-                : {}),
+            ...buildBaseFundReport({
+                definitionTrust: definitionVerification?.trust,
+                stateTrust: stateVerification?.trust,
+            }),
             distributionTrust: {
                 ...crossChecks,
                 positionStatusEligible: crossChecks.positionStatusEligible && lpCommitted,
@@ -1196,26 +1443,63 @@ async function executeDistributionClaim(sdk, input) {
     };
 }
 async function prepareClosing(sdk, input) {
-    const definition = input.definitionPath || input.definitionValue
-        ? await loadFundDefinitionDocument(sdk, input)
+    const definition = await loadFundDefinitionDocument(sdk, input);
+    const receipt = input.positionReceiptPath || input.positionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, input)
         : undefined;
-    const receipt = await loadPositionReceiptEnvelopeDocument(sdk, input);
-    const receiptChecks = definition ? ensureVerifiedEnvelope(definition.value, receipt.value) : (0, fundValidation_1.verifyLPPositionReceiptEnvelope)({ envelope: receipt.value });
+    const previousEnvelope = input.previousPositionReceiptPath || input.previousPositionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, {
+            positionReceiptPath: input.previousPositionReceiptPath,
+            positionReceiptValue: input.previousPositionReceiptValue,
+        })
+        : undefined;
+    const chainEntries = input.positionReceiptChainPaths || input.positionReceiptChainValues
+        ? await loadPositionReceiptEnvelopeChainDocuments(sdk, {
+            positionReceiptChainPaths: input.positionReceiptChainPaths,
+            positionReceiptChainValues: input.positionReceiptChainValues,
+        })
+        : [];
+    const context = resolveReceiptChainContext({
+        receipt,
+        previousEnvelope,
+        chainEntries,
+    });
+    const receiptChecks = await ensureVerifiedEnvelopeContinuity(definition.value, context.receipt.value, context.previousEnvelope?.value);
+    const chainChecks = await (0, fundValidation_1.verifyLPPositionReceiptEnvelopeChain)({
+        envelopes: context.chainEntries.map((entry) => entry.value),
+        expectedManagerXonly: definition.value.managerXonly,
+    });
     const closing = await loadClosingDocument(sdk, {
         closingPath: input.closingPath,
         closingValue: input.closingValue,
-        positionReceipt: receipt.value.receipt,
+        positionReceipt: context.receipt.value.receipt,
         closingId: input.closingId,
         finalDistributionHashes: input.finalDistributionHashes,
         closedAt: input.closedAt,
         closingReason: input.closingReason,
     });
-    const checks = (0, fundValidation_1.validateClosingAgainstReceipt)(receipt.value.receipt, closing.value);
+    const checks = (0, fundValidation_1.validateClosingAgainstReceipt)(context.receipt.value.receipt, closing.value);
     return {
-        positionReceipt: receipt.descriptor,
-        positionReceiptValue: receipt.value,
-        positionReceiptSummary: receipt.receiptSummary,
-        positionReceiptEnvelopeSummary: receipt.envelopeSummary,
+        positionReceipt: context.receipt.descriptor,
+        positionReceiptValue: context.receipt.value,
+        positionReceiptSummary: context.receipt.receiptSummary,
+        positionReceiptEnvelopeSummary: context.receipt.envelopeSummary,
+        ...(context.previousEnvelope
+            ? {
+                previousPositionReceipt: context.previousEnvelope.descriptor,
+                previousPositionReceiptValue: context.previousEnvelope.value,
+                previousPositionReceiptSummary: context.previousEnvelope.receiptSummary,
+                previousPositionReceiptEnvelopeSummary: context.previousEnvelope.envelopeSummary,
+            }
+            : {}),
+        ...(context.chainEntries.length > 0
+            ? {
+                positionReceiptChain: context.chainEntries.map((entry) => entry.descriptor),
+                positionReceiptChainValues: context.chainEntries.map((entry) => entry.value),
+                positionReceiptChainSummaries: context.chainEntries.map((entry) => entry.receiptSummary),
+                positionReceiptEnvelopeChainSummaries: context.chainEntries.map((entry) => entry.envelopeSummary),
+            }
+            : {}),
         closing: closing.descriptor,
         closingValue: closing.value,
         closingSummary: closing.summary,
@@ -1226,26 +1510,67 @@ async function prepareClosing(sdk, input) {
             closingTrust: checks,
             receiptTrust: buildReceiptTrust({
                 generated: false,
-                envelope: receipt.value,
+                envelope: context.receipt.value,
                 checks: receiptChecks,
             }),
+            receiptChainTrust: buildReceiptChainTrust(chainChecks),
         },
     };
 }
 async function verifyClosing(sdk, input) {
-    const definition = input.definitionPath || input.definitionValue
-        ? await loadFundDefinitionDocument(sdk, input)
+    const definition = await loadFundDefinitionDocument(sdk, input);
+    const receipt = input.positionReceiptPath || input.positionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, input)
         : undefined;
-    const receipt = await loadPositionReceiptEnvelopeDocument(sdk, input);
-    const receiptChecks = definition ? ensureVerifiedEnvelope(definition.value, receipt.value) : (0, fundValidation_1.verifyLPPositionReceiptEnvelope)({ envelope: receipt.value });
+    const previousEnvelope = input.previousPositionReceiptPath || input.previousPositionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, {
+            positionReceiptPath: input.previousPositionReceiptPath,
+            positionReceiptValue: input.previousPositionReceiptValue,
+        })
+        : undefined;
+    const chainEntries = input.positionReceiptChainPaths || input.positionReceiptChainValues
+        ? await loadPositionReceiptEnvelopeChainDocuments(sdk, {
+            positionReceiptChainPaths: input.positionReceiptChainPaths,
+            positionReceiptChainValues: input.positionReceiptChainValues,
+        })
+        : [];
+    const context = resolveReceiptChainContext({
+        receipt,
+        previousEnvelope,
+        chainEntries,
+    });
+    const receiptChecks = await ensureVerifiedEnvelopeContinuity(definition.value, context.receipt.value, context.previousEnvelope?.value);
+    const chainChecks = await (0, fundValidation_1.verifyLPPositionReceiptEnvelopeChain)({
+        envelopes: context.chainEntries.map((entry) => entry.value),
+        expectedManagerXonly: definition.value.managerXonly,
+    });
     const closing = await loadClosingDocument(sdk, { closingPath: input.closingPath, closingValue: input.closingValue });
-    const checks = (0, fundValidation_1.validateClosingAgainstReceipt)(receipt.value.receipt, closing.value);
+    const checks = (0, fundValidation_1.validateClosingAgainstReceipt)(context.receipt.value.receipt, closing.value);
     return {
         verified: true,
-        positionReceipt: receipt.descriptor,
-        positionReceiptValue: receipt.value,
-        positionReceiptSummary: receipt.receiptSummary,
-        positionReceiptEnvelopeSummary: receipt.envelopeSummary,
+        definition: definition.descriptor,
+        definitionValue: definition.value,
+        definitionSummary: definition.summary,
+        positionReceipt: context.receipt.descriptor,
+        positionReceiptValue: context.receipt.value,
+        positionReceiptSummary: context.receipt.receiptSummary,
+        positionReceiptEnvelopeSummary: context.receipt.envelopeSummary,
+        ...(context.previousEnvelope
+            ? {
+                previousPositionReceipt: context.previousEnvelope.descriptor,
+                previousPositionReceiptValue: context.previousEnvelope.value,
+                previousPositionReceiptSummary: context.previousEnvelope.receiptSummary,
+                previousPositionReceiptEnvelopeSummary: context.previousEnvelope.envelopeSummary,
+            }
+            : {}),
+        ...(context.chainEntries.length > 0
+            ? {
+                positionReceiptChain: context.chainEntries.map((entry) => entry.descriptor),
+                positionReceiptChainValues: context.chainEntries.map((entry) => entry.value),
+                positionReceiptChainSummaries: context.chainEntries.map((entry) => entry.receiptSummary),
+                positionReceiptEnvelopeChainSummaries: context.chainEntries.map((entry) => entry.envelopeSummary),
+            }
+            : {}),
         closing: closing.descriptor,
         closingValue: closing.value,
         closingSummary: closing.summary,
@@ -1253,7 +1578,8 @@ async function verifyClosing(sdk, input) {
         report: {
             ...buildBaseFundReport(),
             closingTrust: checks,
-            receiptTrust: buildReceiptTrust({ generated: false, envelope: receipt.value, checks: receiptChecks }),
+            receiptTrust: buildReceiptTrust({ generated: false, envelope: context.receipt.value, checks: receiptChecks }),
+            receiptChainTrust: buildReceiptChainTrust(chainChecks),
         },
     };
 }
@@ -1263,6 +1589,25 @@ async function exportEvidence(sdk, input) {
     const receipt = input.positionReceiptPath || input.positionReceiptValue
         ? await loadPositionReceiptEnvelopeDocument(sdk, input)
         : undefined;
+    const previousEnvelope = input.previousPositionReceiptPath || input.previousPositionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, {
+            positionReceiptPath: input.previousPositionReceiptPath,
+            positionReceiptValue: input.previousPositionReceiptValue,
+        })
+        : undefined;
+    const chainEntries = input.positionReceiptChainPaths || input.positionReceiptChainValues
+        ? await loadPositionReceiptEnvelopeChainDocuments(sdk, {
+            positionReceiptChainPaths: input.positionReceiptChainPaths,
+            positionReceiptChainValues: input.positionReceiptChainValues,
+        })
+        : [];
+    const receiptContext = receipt || chainEntries.length > 0
+        ? resolveReceiptChainContext({
+            receipt,
+            previousEnvelope,
+            chainEntries,
+        })
+        : undefined;
     const distributions = input.distributionPath || input.distributionValue || input.distributionPaths || input.distributionValues
         ? await loadDistributionDocuments(sdk, {
             distributionPath: input.distributionPath,
@@ -1277,11 +1622,11 @@ async function exportEvidence(sdk, input) {
         : undefined;
     const artifact = input.artifact ?? (input.artifactPath ? (await sdk.loadArtifact(input.artifactPath)).artifact : undefined);
     const trust = input.verificationReportValue
-        ?? (distribution && receipt && artifact
+        ?? (distribution && receiptContext?.receipt && artifact
             ? (await verifyDistribution(sdk, {
                 artifact,
                 definitionValue: definition.value,
-                positionReceiptValue: receipt.value,
+                positionReceiptValue: receiptContext.receipt.value,
                 distributionValue: distribution.value,
             })).report
             : capitalCall && artifact
@@ -1290,16 +1635,20 @@ async function exportEvidence(sdk, input) {
                     definitionValue: definition.value,
                     capitalCallValue: capitalCall.value,
                 })).report
-                : closing && receipt
+                : closing && receiptContext?.receipt
                     ? (await verifyClosing(sdk, {
                         definitionValue: definition.value,
-                        positionReceiptValue: receipt.value,
+                        positionReceiptValue: receiptContext.receipt.value,
+                        previousPositionReceiptValue: receiptContext.previousEnvelope?.value,
+                        positionReceiptChainValues: receiptContext.chainEntries.map((entry) => entry.value),
                         closingValue: closing.value,
                     })).report
-                    : receipt
+                    : receiptContext?.receipt
                         ? (await verifyPositionReceipt(sdk, {
                             definitionValue: definition.value,
-                            positionReceiptValue: receipt.value,
+                            positionReceiptValue: receiptContext.receipt.value,
+                            previousPositionReceiptValue: receiptContext.previousEnvelope?.value,
+                            positionReceiptChainValues: receiptContext.chainEntries.map((entry) => entry.value),
                         })).report
                         : buildBaseFundReport());
     const renderedSourceHash = artifact?.source.simfPath && (0, node_fs_1.existsSync)(artifact.source.simfPath)
@@ -1310,16 +1659,22 @@ async function exportEvidence(sdk, input) {
         ...(artifact ? { artifact } : {}),
         definition: definition.summary,
         ...(capitalCall ? { capitalCall: capitalCall.summary } : {}),
-        ...(receipt
+        ...(receiptContext?.receipt
             ? {
-                positionReceipt: receipt.receiptSummary,
-                positionReceiptEnvelope: receipt.envelopeSummary,
+                positionReceipt: receiptContext.receipt.receiptSummary,
+                positionReceiptEnvelope: receiptContext.receipt.envelopeSummary,
             }
             : {}),
         ...(distribution ? { distribution: distribution.summary } : {}),
         ...(distributions.length > 1 ? { distributions: distributions.map((entry) => entry.summary) } : {}),
         ...(closing ? { closing: closing.summary } : {}),
         trust,
+        trustSummary: (0, reporting_1.buildVerificationTrustSummary)({
+            definitionTrust: trust.artifactTrust?.definition,
+            stateTrust: trust.stateTrust,
+            bindingMode: trust.outputBindingTrust?.mode ?? "none",
+            lineageTrust: trust.receiptChainTrust,
+        }),
         renderedSourceHash,
         sourceVerificationMode: renderedSourceHash ? "source-reloaded" : "artifact-only",
         ...(artifact
@@ -1340,6 +1695,25 @@ async function exportFinalityPayload(sdk, input) {
     const receipt = input.positionReceiptPath || input.positionReceiptValue
         ? await loadPositionReceiptEnvelopeDocument(sdk, input)
         : undefined;
+    const previousEnvelope = input.previousPositionReceiptPath || input.previousPositionReceiptValue
+        ? await loadPositionReceiptEnvelopeDocument(sdk, {
+            positionReceiptPath: input.previousPositionReceiptPath,
+            positionReceiptValue: input.previousPositionReceiptValue,
+        })
+        : undefined;
+    const chainEntries = input.positionReceiptChainPaths || input.positionReceiptChainValues
+        ? await loadPositionReceiptEnvelopeChainDocuments(sdk, {
+            positionReceiptChainPaths: input.positionReceiptChainPaths,
+            positionReceiptChainValues: input.positionReceiptChainValues,
+        })
+        : [];
+    const receiptContext = receipt || chainEntries.length > 0
+        ? resolveReceiptChainContext({
+            receipt,
+            previousEnvelope,
+            chainEntries,
+        })
+        : undefined;
     const distributions = input.distributionPath || input.distributionValue || input.distributionPaths || input.distributionValues
         ? await loadDistributionDocuments(sdk, {
             distributionPath: input.distributionPath,
@@ -1352,7 +1726,7 @@ async function exportFinalityPayload(sdk, input) {
     const closing = input.closingPath || input.closingValue
         ? await loadClosingDocument(sdk, { closingPath: input.closingPath, closingValue: input.closingValue })
         : undefined;
-    const lpId = closing?.value.lpId ?? distribution?.value.lpId ?? receipt?.value.receipt.lpId ?? capitalCall?.value.lpId;
+    const lpId = closing?.value.lpId ?? distribution?.value.lpId ?? receiptContext?.receipt.value.receipt.lpId ?? capitalCall?.value.lpId;
     if (!lpId) {
         throw new errors_1.ValidationError("Finality payload requires at least one LP-linked document", {
             code: "FUND_FINALITY_LP_ID_REQUIRED",
@@ -1363,22 +1737,20 @@ async function exportFinalityPayload(sdk, input) {
         fundId: definition.value.fundId,
         lpId,
         ...(capitalCall?.value.callId ? { callId: capitalCall.value.callId } : {}),
-        ...(receipt?.value.receipt.positionId ?? distribution?.value.positionId ?? closing?.value.positionId
-            ? { positionId: receipt?.value.receipt.positionId ?? distribution?.value.positionId ?? closing?.value.positionId }
+        ...(receiptContext?.receipt.value.receipt.positionId ?? distribution?.value.positionId ?? closing?.value.positionId
+            ? {
+                positionId: receiptContext?.receipt.value.receipt.positionId ?? distribution?.value.positionId ?? closing?.value.positionId,
+            }
             : {}),
         definitionHash: definition.summary.hash,
         capitalCallStateHash: capitalCall?.summary.hash ?? null,
-        positionReceiptHash: receipt?.receiptSummary.hash ?? null,
-        positionReceiptEnvelopeHash: receipt?.envelopeSummary.hash ?? null,
+        positionReceiptHash: receiptContext?.receipt.receiptSummary.hash ?? null,
+        positionReceiptEnvelopeHash: receiptContext?.receipt.envelopeSummary.hash ?? null,
         distributionHash: distribution?.summary.hash ?? null,
         distributionHashes: distributions.length > 0 ? distributions.map((entry) => entry.summary.hash) : null,
         closingHash: closing?.summary.hash ?? null,
         bindingMode: evidence.trust.outputBindingTrust?.mode ?? "none",
         trust: evidence.trust,
-        trustSummary: {
-            definition: evidence.trust.artifactTrust?.definition,
-            state: evidence.trust.stateTrust,
-            bindingMode: evidence.trust.outputBindingTrust?.mode ?? "none",
-        },
+        trustSummary: evidence.trustSummary,
     };
 }