customanchor: expose output commitment roots

Persist the Taproot Asset and final BIP341 roots for each committed
output so host protocols can compose policy control blocks without parsing
proprietary PSBT fields.

Reconstruct both roots from the complete packet set, bind tapd root hints,
and cover Ark-like siblings, grouped issuances, passive assets, tampering,
and live exact/P2A transfers.

Author: darioAnongba

custom_anchor_builder_test.go

@@ -639,9 +639,20 @@ func TestCustomAnchorBuilderGroupedMultiIssuance(t *testing.T) {
 	require.Len(t, packageSnapshot.Outputs, 2)
 	require.Len(t, packageSnapshot.ProofUpdates, 2)
 	packageIssuances := make(map[AssetID]struct{})
-	for _, output := range packageSnapshot.Outputs {
+	for idx, output := range packageSnapshot.Outputs {
 		packageIssuances[output.IssuanceID] = struct{}{}
 		require.Equal(t, "group-receiver", output.LogicalOutputID)
+		require.NotZero(t, output.TaprootAssetRoot)
+		if idx > 0 {
+			require.Equal(t,
+				packageSnapshot.Outputs[0].TaprootAssetRoot,
+				output.TaprootAssetRoot,
+			)
+			require.Equal(t,
+				packageSnapshot.Outputs[0].TaprootMerkleRoot,
+				output.TaprootMerkleRoot,
+			)
+		}
 	}
 	require.Len(t, packageIssuances, 2)
 

custom_anchor_lifecycle.go

@@ -1099,6 +1099,18 @@ func (p *CustomAnchorPlan) committedOutputSummaries(anchor *psbt.Packet,
 	[]CustomAnchorProofUpdate, error) {
 
 	txID := anchor.UnsignedTx.TxHash()
+	allPackets := append(
+		append([]*tappsbt.VPacket(nil), active...), passive...,
+	)
+	// The committed packets already contain tapd's deterministic STXO alt
+	// leaves. Reconstruct roots from those persisted leaves without adding a
+	// second copy.
+	commitments, err := tapsend.CreateOutputCommitments(
+		allPackets, tapsend.WithNoSTXOProofs(),
+	)
+	if err != nil {
+		return nil, nil, fmt.Errorf("derive committed output roots: %w", err)
+	}
 	outputs := make([]CustomAnchorAssetOutputSummary, 0, len(p.outputs))
 	updates := make([]CustomAnchorProofUpdate, 0, len(p.outputs))
 	for idx := range p.outputs {
@@ -1141,6 +1153,12 @@ func (p *CustomAnchorPlan) committedOutputSummaries(anchor *psbt.Packet,
 			return nil, nil, fmt.Errorf("committed output %q anchor value "+
 				"changed", planned.LogicalOutputID)
 		}
+		taprootAssetRoot, taprootMerkleRoot, err :=
+			deriveCustomAnchorOutputRoots(vOut, commitments)
+		if err != nil {
+			return nil, nil, fmt.Errorf("derive output %q commitment roots: %w",
+				planned.LogicalOutputID, err)
+		}
 		proofBlob, err := encodeTransitionProof(vOut.ProofSuffix)
 		if err != nil {
 			return nil, nil, fmt.Errorf("encode output %q proof suffix: %w",
@@ -1159,6 +1177,8 @@ func (p *CustomAnchorPlan) committedOutputSummaries(anchor *psbt.Packet,
 			AssetType:          planned.AssetType,
 			AnchorOutpoint:     anchorOutpoint,
 			AnchorValueSat:     anchorValue,
+			TaprootAssetRoot:   taprootAssetRoot,
+			TaprootMerkleRoot:  taprootMerkleRoot,
 			ScriptKey:          planned.ScriptKey,
 			Amount:             planned.Amount,
 			ScriptMode:         planned.ScriptMode,

custom_anchor_lifecycle_test.go

@@ -86,6 +86,10 @@ func TestCustomAnchorLifecycleBackendSigningAndPublish(t *testing.T) {
 	t.Parallel()
 
 	fixture := newCustomAnchorBuilderFixture(t)
+	policyLeaf := txscript.NewBaseTapLeaf([]byte{txscript.OP_TRUE})
+	fixture.request.Outputs[0].Anchor.Tapscript = CustomAnchorTapscriptPlan{
+		TapLeaves: []TapLeaf{{Script: cloneBytes(policyLeaf.Script)}},
+	}
 	var (
 		signCalls     int
 		commitRequest *CommitVirtualPsbtsRequest
@@ -171,6 +175,14 @@ func TestCustomAnchorLifecycleBackendSigningAndPublish(t *testing.T) {
 	require.Len(t, packageSnapshot.ProofUpdates, 1)
 	require.NotEmpty(t, packageSnapshot.ProofUpdates[0].ProofBlob)
 	require.Equal(t, publishMetadata, packageSnapshot.Publish)
+	outputSummary := packageSnapshot.Outputs[0]
+	require.NotZero(t, outputSummary.TaprootAssetRoot)
+	require.NotZero(t, outputSummary.TaprootMerkleRoot)
+	policyRoot := policyLeaf.TapHash()
+	expectedRoot := asset.NewTapBranchHash(
+		chainhash.Hash(outputSummary.TaprootAssetRoot), policyRoot,
+	)
+	require.Equal(t, Hash(expectedRoot), outputSummary.TaprootMerkleRoot)
 
 	before, err := decodeAnchorPSBT(plan.AnchorPSBT())
 	require.NoError(t, err)
@@ -192,6 +204,17 @@ func TestCustomAnchorLifecycleBackendSigningAndPublish(t *testing.T) {
 		committed.UnsignedTx.TxOut[1].PkScript)
 	require.Equal(t, before.UnsignedTx.TxOut[1].Value,
 		committed.UnsignedTx.TxOut[1].Value)
+	internalKey, err := btcec.ParsePubKey(
+		fixture.request.Outputs[0].Anchor.InternalKey.PubKey[:],
+	)
+	require.NoError(t, err)
+	outputKey := txscript.ComputeTaprootOutputKey(
+		internalKey, outputSummary.TaprootMerkleRoot[:],
+	)
+	expectedPkScript, err := txscript.PayToTaprootScript(outputKey)
+	require.NoError(t, err)
+	require.Equal(t, expectedPkScript,
+		committed.UnsignedTx.TxOut[outputSummary.AnchorOutputIndex].PkScript)
 
 	_, err = wallet.PublishCustomAnchorTransfer(
 		context.Background(), packageSnapshot,

custom_anchor_package.go

@@ -285,6 +285,16 @@ type CustomAnchorAssetOutputSummary struct {
 	// AnchorValueSat is the BTC value assigned to the asset-bearing output.
 	AnchorValueSat int64 `json:"anchor_value_sat"`
 
+	// TaprootAssetRoot is the root of the Taproot Asset commitment before
+	// combining it with the host-supplied tapscript sibling. Hosts such as
+	// SwapDK use this root to compose their policy tree and control blocks.
+	TaprootAssetRoot Hash `json:"taproot_asset_root"`
+
+	// TaprootMerkleRoot is the final BIP341 root that combines the Taproot
+	// Asset commitment with the optional host-supplied tapscript sibling.
+	// It is the tweak committed to by the anchor output key.
+	TaprootMerkleRoot Hash `json:"taproot_merkle_root"`
+
 	// ScriptKey is the asset script key for the new output.
 	ScriptKey PubKey `json:"script_key"`
 
@@ -1034,6 +1044,11 @@ func validatePackageOutputMapping(anchor *psbt.Packet, txID chainhash.Hash,
 	}
 	anchorOutpoint := Outpoint{Txid: [32]byte(txID), Index: anchorIndex}
 	anchorValue := anchor.UnsignedTx.TxOut[anchorIndex].Value
+	taprootAssetRoot, taprootMerkleRoot, err :=
+		deriveCustomAnchorOutputRoots(virtualOutput, commitments)
+	if err != nil {
+		return fmt.Errorf("derive output commitment roots: %w", err)
+	}
 	if !customAnchorAssetRefMatchesIssuance(
 		summary.AssetRef, actualRef, issuanceID,
 	) ||
@@ -1045,6 +1060,16 @@ func validatePackageOutputMapping(anchor *psbt.Packet, txID chainhash.Hash,
 
 		return fmt.Errorf("output summary does not match virtual output")
 	}
+	if summary.TaprootAssetRoot != taprootAssetRoot ||
+		summary.TaprootMerkleRoot != taprootMerkleRoot {
+
+		return fmt.Errorf("output commitment roots do not match virtual output")
+	}
+	if err := validateCustomAnchorOutputRootHints(
+		anchor, anchorIndex, taprootAssetRoot, taprootMerkleRoot,
+	); err != nil {
+		return err
+	}
 	if customAnchorProofCourierString(
 		virtualOutput.ProofDeliveryAddress,
 	) != summary.ProofDelivery.CourierAddress {
@@ -1096,6 +1121,69 @@ func validatePackageOutputMapping(anchor *psbt.Packet, txID chainhash.Hash,
 	return nil
 }
 
+func deriveCustomAnchorOutputRoots(output *tappsbt.VOutput,
+	commitments tappsbt.OutputCommitments) (Hash, Hash, error) {
+
+	if output == nil {
+		return Hash{}, Hash{}, fmt.Errorf("virtual output is missing")
+	}
+	if output.AnchorOutputInternalKey == nil {
+		return Hash{}, Hash{}, fmt.Errorf("anchor output internal key is missing")
+	}
+	anchorCommitment, ok := commitments[output.AnchorOutputIndex]
+	if !ok || anchorCommitment == nil {
+		return Hash{}, Hash{}, fmt.Errorf(
+			"anchor output %d commitment is missing",
+			output.AnchorOutputIndex,
+		)
+	}
+
+	_, merkleRoot, assetRoot, err := tapsend.AnchorOutputScript(
+		output.AnchorOutputInternalKey,
+		output.AnchorOutputTapscriptSibling, anchorCommitment,
+	)
+	if err != nil {
+		return Hash{}, Hash{}, err
+	}
+
+	return Hash(assetRoot), Hash(merkleRoot), nil
+}
+
+func validateCustomAnchorOutputRootHints(anchor *psbt.Packet,
+	anchorIndex uint32, assetRoot, merkleRoot Hash) error {
+
+	if anchorIndex >= uint32(len(anchor.Outputs)) {
+		return fmt.Errorf("anchor output metadata is out of range")
+	}
+	unknowns := anchor.Outputs[anchorIndex].Unknowns
+	assetRootHint := tappsbt.ExtractCustomField(
+		unknowns, tappsbt.PsbtKeyTypeOutputAssetRoot,
+	)
+	if len(assetRootHint) != len(assetRoot) {
+		return fmt.Errorf("anchor output %d Taproot Asset root hint must be %d "+
+			"bytes, was %d", anchorIndex, len(assetRoot), len(assetRootHint))
+	}
+	if !bytes.Equal(assetRootHint, assetRoot[:]) {
+		return fmt.Errorf("anchor output %d Taproot Asset root hint does not "+
+			"match the committed assets", anchorIndex)
+	}
+
+	merkleRootHint := tappsbt.ExtractCustomField(
+		unknowns, tappsbt.PsbtKeyTypeOutputTaprootMerkleRoot,
+	)
+	if len(merkleRootHint) != len(merkleRoot) {
+		return fmt.Errorf("anchor output %d Taproot merkle root hint must be %d "+
+			"bytes, was %d", anchorIndex, len(merkleRoot),
+			len(merkleRootHint))
+	}
+	if !bytes.Equal(merkleRootHint, merkleRoot[:]) {
+		return fmt.Errorf("anchor output %d Taproot merkle root hint does not "+
+			"match the committed assets", anchorIndex)
+	}
+
+	return nil
+}
+
 // Clone returns a deep copy of the package so callers can snapshot a committed
 // state before external signing or broadcast mutates host-owned buffers.
 func (p *CustomAnchorTransferPackage) Clone() *CustomAnchorTransferPackage {

custom_anchor_package_test.go

@@ -604,6 +604,24 @@ func TestCustomAnchorTransferPackageRejectsSemanticTamper(t *testing.T) {
 			},
 			wantErr: "output proof courier does not match output summary",
 		},
+		{
+			name: "output taproot asset root",
+			mutate: func(_ *testing.T,
+				pkg *CustomAnchorTransferPackage) {
+
+				pkg.Outputs[0].TaprootAssetRoot[0] ^= 1
+			},
+			wantErr: "output commitment roots do not match virtual output",
+		},
+		{
+			name: "output taproot merkle root",
+			mutate: func(_ *testing.T,
+				pkg *CustomAnchorTransferPackage) {
+
+				pkg.Outputs[0].TaprootMerkleRoot[0] ^= 1
+			},
+			wantErr: "output commitment roots do not match virtual output",
+		},
 		{
 			name: "output anchor index",
 			mutate: func(t *testing.T,
@@ -779,6 +797,75 @@ func TestCustomAnchorTransferPackageRejectsSemanticTamper(t *testing.T) {
 	}
 }
 
+func TestCustomAnchorTransferPackageRejectsRootHintTamper(t *testing.T) {
+	tests := []struct {
+		name    string
+		mutate  func([]*btcpsbt.Unknown) []*btcpsbt.Unknown
+		wantErr string
+	}{
+		{
+			name: "missing asset root",
+			mutate: func(unknowns []*btcpsbt.Unknown) []*btcpsbt.Unknown {
+				return removeCustomAnchorTestField(
+					unknowns, tappsbt.PsbtKeyTypeOutputAssetRoot,
+				)
+			},
+			wantErr: "Taproot Asset root hint must be 32 bytes, was 0",
+		},
+		{
+			name: "short merkle root",
+			mutate: func(unknowns []*btcpsbt.Unknown) []*btcpsbt.Unknown {
+				return tappsbt.AddCustomField(
+					unknowns,
+					tappsbt.PsbtKeyTypeOutputTaprootMerkleRoot,
+					[]byte{1},
+				)
+			},
+			wantErr: "Taproot merkle root hint must be 32 bytes, was 1",
+		},
+		{
+			name: "wrong asset root",
+			mutate: func(unknowns []*btcpsbt.Unknown) []*btcpsbt.Unknown {
+				return tappsbt.AddCustomField(
+					unknowns, tappsbt.PsbtKeyTypeOutputAssetRoot,
+					bytes.Repeat([]byte{1}, 32),
+				)
+			},
+			wantErr: "Taproot Asset root hint does not match",
+		},
+		{
+			name: "wrong merkle root",
+			mutate: func(unknowns []*btcpsbt.Unknown) []*btcpsbt.Unknown {
+				return tappsbt.AddCustomField(
+					unknowns,
+					tappsbt.PsbtKeyTypeOutputTaprootMerkleRoot,
+					bytes.Repeat([]byte{2}, 32),
+				)
+			},
+			wantErr: "Taproot merkle root hint does not match",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			pkg := newCustomAnchorTestFixture(t).unsealed
+			for _, current := range []*[]byte{
+				&pkg.CommittedAnchorPsbt, &pkg.AnchorPsbt,
+			} {
+				packet := mustDecodeAnchorPSBT(t, *current)
+				index := pkg.Outputs[0].AnchorOutputIndex
+				packet.Outputs[index].Unknowns = test.mutate(
+					packet.Outputs[index].Unknowns,
+				)
+				*current = mustSerializeAnchorPSBT(t, packet)
+			}
+
+			_, err := pkg.Seal()
+			require.ErrorContains(t, err, test.wantErr)
+		})
+	}
+}
+
 func TestCustomAnchorTransferPackageRejectsPassiveSemanticTamper(
 	t *testing.T) {
 
@@ -1595,6 +1682,20 @@ func mutateCustomAnchorPackageVPacket(t *testing.T,
 	require.NoError(t, err)
 }
 
+func removeCustomAnchorTestField(unknowns []*btcpsbt.Unknown,
+	key []byte) []*btcpsbt.Unknown {
+
+	filtered := make([]*btcpsbt.Unknown, 0, len(unknowns))
+	for _, unknown := range unknowns {
+		if unknown != nil && bytes.Equal(unknown.Key, key) {
+			continue
+		}
+		filtered = append(filtered, unknown)
+	}
+
+	return filtered
+}
+
 func mustDecodeAnchorPSBT(t *testing.T, raw []byte) *btcpsbt.Packet {
 	t.Helper()
 	packet, err := decodeAnchorPSBT(raw)

custom_anchor_passive_test.go

@@ -109,6 +109,12 @@ func TestCustomAnchorPassiveCallerReanchor(t *testing.T) {
 		packageSnapshot.Outputs[1].PacketRole)
 	require.Equal(t, customAnchorPassiveCourier,
 		packageSnapshot.Outputs[1].ProofDelivery.CourierAddress)
+	require.Equal(t, packageSnapshot.Outputs[0].AnchorOutputIndex,
+		packageSnapshot.Outputs[1].AnchorOutputIndex)
+	require.Equal(t, packageSnapshot.Outputs[0].TaprootAssetRoot,
+		packageSnapshot.Outputs[1].TaprootAssetRoot)
+	require.Equal(t, packageSnapshot.Outputs[0].TaprootMerkleRoot,
+		packageSnapshot.Outputs[1].TaprootMerkleRoot)
 }
 
 func TestCustomAnchorPassiveCallerReanchorRejectsMutation(t *testing.T) {

docs/design/advanced-custom-anchor-transactions.md

@@ -306,6 +306,9 @@ phase and is follow-up work.
 - the caller's custom lock ID and requested expiration, when wallet funding
   was used;
 - logical-to-concrete input and output mappings;
+- each output's Taproot Asset commitment root and final BIP341 merkle root,
+  derived from the complete committed active/passive packet set rather than
+  trusted proprietary PSBT fields;
 - the self-contained confirmed proof file or compact proof path for every
   selected input, bound by a domain-separated content ID;
 - every output proof suffix and complete proof-delivery metadata;
@@ -332,6 +335,16 @@ Funding metadata is mode-strict. Caller-funded exact and external P2A packages
 cannot carry backend change, lock, locked-UTXO, or backend-managed-input
 metadata; wallet-funded packages require their deterministic custom lock ID.
 
+For a host-owned policy tree, such as an Ark VTXO, the host combines its known
+policy root with `CustomAnchorAssetOutputSummary.TaprootAssetRoot`. The result
+must equal the summary's `TaprootMerkleRoot`; that final root is the tweak
+committed by the anchor output key. The SDK exposes both values so the host can
+build and persist its control blocks without parsing tapd's proprietary PSBT
+output fields. The host remains responsible for persisting its complete policy
+descriptor, leaves, signers, and internal key. The SDK also requires tapd's
+PSBT root hints to be present and equal to these independently reconstructed
+values because the downstream transfer logger persists those hints.
+
 The committed PSBT metadata is also sealed. Before finalization, the current
 PSBT may differ only in signature and finalization fields; changes to prevout,
 sighash, Taproot key/leaf, or other signing metadata are rejected. Standard