multi: Taproot Assets Ark integration (PoC)

arkrpc/ancestry_path_convert.go

@@ -57,12 +57,41 @@ func AncestryPathFromTree(t *tree.Tree, commitmentTxID chainhash.Hash,
 
 // AncestryPathToTree reconstructs a tree.Tree from an AncestryPath. Returns
 // (nil, nil) when the path or its embedded tree_path is unset; callers must
-// treat a nil tree as an absent ancestry.
+// treat a nil tree as absent ancestry.
+//
+// A present tree_path with zero nodes is the explicit external-root variant.
+// It reconstructs as a non-nil tree with Root == nil while retaining the exact
+// BatchOutpoint and BatchOutput. Keeping it distinct from an absent tree lets
+// receive validation bind a confirmed direct VTXO to its checkpoint without
+// inventing a recovery transaction.
 func AncestryPathToTree(p *AncestryPath) (*tree.Tree, error) {
 	if p == nil || p.TreePath == nil {
 		return nil, nil
 	}
 
+	if len(p.TreePath.Nodes) == 0 {
+		batchOutpoint, err := outpointFromProto(
+			p.TreePath.BatchOutpoint,
+		)
+		if err != nil {
+			return nil, fmt.Errorf("external root outpoint: %w",
+				err)
+		}
+
+		batchOutput, err := txOutFromProto(p.TreePath.BatchOutput)
+		if err != nil {
+			return nil, fmt.Errorf("external root output: %w", err)
+		}
+
+		return &tree.Tree{
+			BatchOutpoint: batchOutpoint,
+			BatchOutput:   batchOutput,
+			SweepTapscriptRoot: append(
+				[]byte(nil), p.TreePath.SweepTapscriptRoot...,
+			),
+		}, nil
+	}
+
 	return TreePathToTree(p.TreePath)
 }
 

arkrpc/ancestry_path_convert_test.go

@@ -132,6 +132,59 @@ func TestAncestryPathRoundTrip(t *testing.T) {
 	}
 }
 
+// TestAncestryPathToTreeExternalRoot verifies that a present, zero-node
+// tree_path remains distinguishable from absent ancestry. This is the wire
+// sentinel used for a confirmed direct-on-chain VTXO: it has no Ark recovery
+// transaction but must retain the exact outpoint and output spent by the
+// first checkpoint.
+func TestAncestryPathToTreeExternalRoot(t *testing.T) {
+	t.Parallel()
+
+	commitment := chainhash.Hash{
+		0x10, 0x20, 0x30,
+	}
+	pkScript := []byte{
+		0x51, 0x20, 0x01,
+	}
+
+	got, err := AncestryPathToTree(&AncestryPath{
+		TreePath: &TreePath{
+			BatchOutpoint: &OutPoint{
+				Txid: commitment[:],
+				Vout: 3,
+			},
+			BatchOutput: &TxOut{
+				Value:    4_321,
+				PkScript: pkScript,
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("AncestryPathToTree: %v", err)
+	}
+
+	if got == nil {
+		t.Fatalf("decoded external-root tree is nil")
+	}
+	if got.Root != nil {
+		t.Fatalf("external-root sentinel unexpectedly has a root node")
+	}
+	if got.BatchOutpoint != (wire.OutPoint{
+		Hash:  commitment,
+		Index: 3,
+	}) {
+
+		t.Fatalf("external-root outpoint mismatch: %v",
+			got.BatchOutpoint)
+	}
+	if got.BatchOutput == nil ||
+		got.BatchOutput.Value != 4_321 ||
+		!bytes.Equal(got.BatchOutput.PkScript, pkScript) {
+
+		t.Fatalf("external-root output mismatch: %v", got.BatchOutput)
+	}
+}
+
 // TestAncestryCommitmentTxIDRejectsBadLength ensures malformed commitment
 // txid byte slices are rejected, not silently truncated.
 func TestAncestryCommitmentTxIDRejectsBadLength(t *testing.T) {