multi: add new proof version TransitionV1

gijswijs · guggero · commit e5023633aeca · 2025-05-16T13:42:20.000+02:00
The proof version is bumped to indicate the usage and support of stxo
style proofs.
diff --git a/proof/append.go b/proof/append.go
@@ -11,6 +11,33 @@ import (
 	"github.com/lightninglabs/taproot-assets/commitment"
 )
 
+// GenConfig is a struct that holds the configuration for creating Taproot Asset
+// proofs.
+type GenConfig struct {
+	// transitionVersion is the version of the asset state transition proof
+	// that is going to be used.
+	transitionVersion TransitionVersion
+}
+
+// DefaultGenConfig returns a default proof generation configuration.
+func DefaultGenConfig() GenConfig {
+	return GenConfig{
+		transitionVersion: TransitionV0,
+	}
+}
+
+// GenOption is a function type that can be used to modify the proof generation
+// configuration.
+type GenOption func(*GenConfig)
+
+// WithVersion is an option that can be used to create a transition proof of the
+// given version.
+func WithVersion(v TransitionVersion) GenOption {
+	return func(cfg *GenConfig) {
+		cfg.transitionVersion = v
+	}
+}
+
 // TransitionParams holds the set of chain level information needed to append a
 // proof to an existing file for the given asset state transition.
 type TransitionParams struct {
@@ -42,8 +69,8 @@ type TransitionParams struct {
 // on-chain output, this function takes the script key of the asset to return
 // the proof for. This method returns both the encoded full provenance (proof
 // chain) and the added latest proof.
-func AppendTransition(blob Blob, params *TransitionParams,
-	vCtx VerifierCtx) (Blob, *Proof, error) {
+func AppendTransition(blob Blob, params *TransitionParams, vCtx VerifierCtx,
+	opts ...GenOption) (Blob, *Proof, error) {
 
 	// Decode the proof blob into a proper file structure first.
 	f := NewEmptyFile(V0)
@@ -69,7 +96,7 @@ func AppendTransition(blob Blob, params *TransitionParams,
 	}
 
 	// We can now create the new proof entry for the asset in the params.
-	newProof, err := CreateTransitionProof(lastPrevOut, params)
+	newProof, err := CreateTransitionProof(lastPrevOut, params, opts...)
 	if err != nil {
 		return nil, nil, fmt.Errorf("error creating transition "+
 			"proof: %w", err)
@@ -122,10 +149,17 @@ func (p *Proof) UpdateTransitionProof(params *BaseProofParams) error {
 
 // CreateTransitionProof creates a proof for an asset transition, based on the
 // last proof of the last asset state and the new asset in the params.
-func CreateTransitionProof(prevOut wire.OutPoint,
-	params *TransitionParams) (*Proof, error) {
+func CreateTransitionProof(prevOut wire.OutPoint, params *TransitionParams,
+	opts ...GenOption) (*Proof, error) {
 
-	proof, err := baseProof(&params.BaseProofParams, prevOut)
+	cfg := DefaultGenConfig()
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	proof, err := baseProof(
+		&params.BaseProofParams, prevOut, cfg.transitionVersion,
+	)
 	if err != nil {
 		return nil, fmt.Errorf("error creating base proofs: %w", err)
 	}
diff --git a/proof/mint.go b/proof/mint.go
@@ -212,13 +212,15 @@ type MintingBlobOption func(*mintingBlobOpts)
 type mintingBlobOpts struct {
 	metaReveals        map[asset.SerializedKey]*MetaReveal
 	tapSiblingPreimage *commitment.TapscriptPreimage
+	genConfig          GenConfig
 }
 
 // defaultMintingBlobOpts returns the default set of options for creating a
 // minting blob.
 func defaultMintingBlobOpts() *mintingBlobOpts {
 	return &mintingBlobOpts{
 		metaReveals: make(map[asset.SerializedKey]*MetaReveal),
+		genConfig:   DefaultGenConfig(),
 	}
 }
 
@@ -243,6 +245,14 @@ func WithSiblingPreimage(
 	}
 }
 
+// WithGenOption is a MintingBlobOption that allows the caller to modify the
+// proof generation configuration used to create the minting blob.
+func WithGenOption(genOpts GenOption) MintingBlobOption {
+	return func(o *mintingBlobOpts) {
+		genOpts(&o.genConfig)
+	}
+}
+
 // NewMintingBlobs takes a set of minting parameters, and produces a series of
 // serialized proof files, which proves the creation/existence of each of the
 // assets within the batch.
@@ -254,7 +264,10 @@ func NewMintingBlobs(params *MintParams, vCtx VerifierCtx,
 		blobOpt(opts)
 	}
 
-	base, err := baseProof(&params.BaseProofParams, params.GenesisPoint)
+	base, err := baseProof(
+		&params.BaseProofParams, params.GenesisPoint,
+		opts.genConfig.transitionVersion,
+	)
 	if err != nil {
 		return nil, err
 	}
@@ -289,7 +302,9 @@ func NewMintingBlobs(params *MintParams, vCtx VerifierCtx,
 
 // baseProof creates the basic proof template that contains all anchor
 // transaction related fields.
-func baseProof(params *BaseProofParams, prevOut wire.OutPoint) (*Proof, error) {
+func baseProof(params *BaseProofParams, prevOut wire.OutPoint,
+	version TransitionVersion) (*Proof, error) {
+
 	// First, we'll create the merkle proof for the anchor transaction. In
 	// this case, since all the assets were created in the same block, we
 	// only need a single merkle proof.
@@ -306,6 +321,7 @@ func baseProof(params *BaseProofParams, prevOut wire.OutPoint) (*Proof, error) {
 		InternalKey: params.InternalKey,
 	}
 	proof.ExclusionProofs = params.ExclusionProofs
+	proof.Version = version
 
 	return proof, nil
 }
diff --git a/proof/mock.go b/proof/mock.go
@@ -578,6 +578,7 @@ func NewTestFromProof(t testing.TB, p *Proof) *TestProof {
 	t.Helper()
 
 	tp := &TestProof{
+		Version:         p.Version,
 		PrevOut:         p.PrevOut.String(),
 		BlockHeader:     NewTestFromBlockHeader(t, &p.BlockHeader),
 		BlockHeight:     p.BlockHeight,
@@ -651,6 +652,7 @@ func NewTestFromProof(t testing.TB, p *Proof) *TestProof {
 }
 
 type TestProof struct {
+	Version          TransitionVersion         `json:"version"`
 	PrevOut          string                    `json:"prev_out"`
 	BlockHeader      *TestBlockHeader          `json:"block_header"`
 	BlockHeight      uint32                    `json:"block_height"`
@@ -673,6 +675,7 @@ func (tp *TestProof) ToProof(t testing.TB) *Proof {
 	t.Helper()
 
 	p := &Proof{
+		Version:         tp.Version,
 		PrevOut:         test.ParseOutPoint(t, tp.PrevOut),
 		BlockHeader:     *tp.BlockHeader.ToBlockHeader(t),
 		BlockHeight:     tp.BlockHeight,
diff --git a/proof/proof.go b/proof/proof.go
@@ -228,6 +228,10 @@ type TransitionVersion uint32
 const (
 	// TransitionV0 is the first version of the state transition proof.
 	TransitionV0 TransitionVersion = 0
+
+	// TransitionV1 is the second version of the state transition proof.
+	// This version added STXO inclusion and exclusion proofs.
+	TransitionV1 TransitionVersion = 1
 )
 
 // Proof encodes all of the data necessary to prove a valid state transition for
@@ -494,11 +498,23 @@ func (p *Proof) IsUnknownVersion() bool {
 	switch p.Version {
 	case TransitionV0:
 		return false
+	case TransitionV1:
+		return false
 	default:
 		return true
 	}
 }
 
+// IsVersionV0 returns true if the proof is of version V0.
+func (p *Proof) IsVersionV0() bool {
+	return p.Version == TransitionV0
+}
+
+// IsVersionV1 returns true if the proof is of version V1.
+func (p *Proof) IsVersionV1() bool {
+	return p.Version == TransitionV1
+}
+
 // ToChainAsset converts the proof to a ChainAsset.
 func (p *Proof) ToChainAsset() (asset.ChainAsset, error) {
 	emptyAsset := asset.ChainAsset{}
diff --git a/proof/testdata/proof_tlv_encoding_generated.json b/proof/testdata/proof_tlv_encoding_generated.json
@@ -2,6 +2,7 @@
   "valid_test_cases": [
     {
       "proof": {
+        "version": 0,
         "prev_out": "8d73ec3f2525632186845c95d4491d1b3a768b7c4e0b6804951aa42655d9b95f:2092150027",
         "block_header": {
           "version": 0,
@@ -149,6 +150,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "cd36e9f7676678e7aa2d92faded7e41173fac825416fed825e117039374b7964:3197016449",
         "block_header": {
           "version": 0,
@@ -262,6 +264,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "098047936c9c64b74e91e98b02c9173a0c2bf9fc6568bb5389421657ffb92d01:3276740653",
         "block_header": {
           "version": 0,
@@ -409,6 +412,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "ba3a5aceec2c8aaaacfc5dc154086425fcd6090ec04ff5f26283efc6c65ca80d:2394154145",
         "block_header": {
           "version": 0,
@@ -522,6 +526,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "3a7d712e166bdfbeaa0fe2f8c1fe0aedf1a6e222f59e3bdcdc02b390baf44754:1840451127",
         "block_header": {
           "version": 0,
@@ -652,6 +657,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "4fbff2770eb58f0d25580a4f5ae17c02d5b55397b4926431624c583b0a7f2080:1409563238",
         "block_header": {
           "version": 0,
@@ -747,6 +753,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "0efd7a84af6747c045d99121ebdd8f44c9ab40aaab031f765a41fc24541c3b6b:2955392992",
         "block_header": {
           "version": 0,
@@ -860,6 +867,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "5c92e2b89ad1bdc176163dea42afc12d154eb95e8cca59939285764813883142:3818717915",
         "block_header": {
           "version": 0,
@@ -973,6 +981,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "a14c5136fd600756ff805584aa5403510d6531e066191291a585e696d511e10f:1312193188",
         "block_header": {
           "version": 0,
@@ -1076,6 +1085,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "dfc122306066091f323f491a95baf7d30e4b85439851da45809354827163240d:2200192249",
         "block_header": {
           "version": 0,
@@ -1197,6 +1207,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "7de34688825d31521f73085cddf29420b53e139a8ecad480ca0d379b5bf1350c:4074289298",
         "block_header": {
           "version": 0,
@@ -1320,6 +1331,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "42bb7a587d976edf598dd3a5962b00cb9f048fe6b5780b2194ba1cceb7074974:2992579926",
         "block_header": {
           "version": 0,
@@ -1477,6 +1489,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "f52bfe55e280959e40fd3182a38aae50dc0977d1d2a8dee9e4b406ea6f9c6427:1573797138",
         "block_header": {
           "version": 0,
@@ -1600,6 +1613,7 @@
     },
     {
       "proof": {
+        "version": 0,
         "prev_out": "4ce6979ab1bc2dce1e8b8992f678e1bd4132c8f4a49a233fe5d74c1c45c2c834:3986124895",
         "block_header": {
           "version": 0,
diff --git a/tappsbt/testdata/psbt_encoding_generated.json b/tappsbt/testdata/psbt_encoding_generated.json
@@ -209,6 +209,7 @@
               "unknown_odd_types": null
             },
             "proof": {
+              "version": 0,
               "prev_out": "676678e7aa2d92faded7e41173fac825416fed825e117039374b7964976f269a:3197016449",
               "block_header": {
                 "version": 1,
@@ -524,6 +525,7 @@
             "tr_merkle_root": "",
             "proof_delivery_address": "https://example.com",
             "proof_suffix": {
+              "version": 0,
               "prev_out": "676678e7aa2d92faded7e41173fac825416fed825e117039374b7964976f269a:3197016449",
               "block_header": {
                 "version": 1,
@@ -990,6 +992,7 @@
               "unknown_odd_types": null
             },
             "proof": {
+              "version": 0,
               "prev_out": "0a7f201283b654043a6680d58fe8ba8f22c93fb09f6c47ac3f0d6fb73c32eded:2773153607",
               "block_header": {
                 "version": 1,
@@ -1305,6 +1308,7 @@
             "tr_merkle_root": "",
             "proof_delivery_address": "https://example.com",
             "proof_suffix": {
+              "version": 0,
               "prev_out": "0a7f201283b654043a6680d58fe8ba8f22c93fb09f6c47ac3f0d6fb73c32eded:2773153607",
               "block_header": {
                 "version": 1,
diff --git a/tapsend/proof.go b/tapsend/proof.go
@@ -114,8 +114,8 @@ type ExclusionProofGenerator func(target *proof.BaseProofParams,
 // finalTxPacketOutputs.
 func CreateProofSuffix(chainTx *wire.MsgTx, finalTxPacketOutputs []psbt.POutput,
 	vPacket *tappsbt.VPacket, outputCommitments tappsbt.OutputCommitments,
-	outIndex int, allAnchoredVPackets []*tappsbt.VPacket) (*proof.Proof,
-	error) {
+	outIndex int, allAnchoredVPackets []*tappsbt.VPacket,
+	opts ...proof.GenOption) (*proof.Proof, error) {
 
 	return CreateProofSuffixCustom(
 		chainTx, vPacket, outputCommitments, outIndex,
@@ -133,7 +133,7 @@ func CreateProofSuffix(chainTx *wire.MsgTx, finalTxPacketOutputs []psbt.POutput,
 				target, chainTx, finalTxPacketOutputs,
 				isAnchor,
 			)
-		},
+		}, opts...,
 	)
 }
 
@@ -150,7 +150,8 @@ func CreateProofSuffix(chainTx *wire.MsgTx, finalTxPacketOutputs []psbt.POutput,
 func CreateProofSuffixCustom(finalTx *wire.MsgTx, vPacket *tappsbt.VPacket,
 	outputCommitments tappsbt.OutputCommitments, outIndex int,
 	allAnchoredVPackets []*tappsbt.VPacket,
-	genExclusionProofs ExclusionProofGenerator) (*proof.Proof, error) {
+	genExclusionProofs ExclusionProofGenerator,
+	opts ...proof.GenOption) (*proof.Proof, error) {
 
 	inputPrevID := vPacket.Inputs[0].PrevID
 
@@ -195,7 +196,7 @@ func CreateProofSuffixCustom(finalTx *wire.MsgTx, vPacket *tappsbt.VPacket,
 	}
 
 	proofSuffix, err := proof.CreateTransitionProof(
-		inputPrevID.OutPoint, params,
+		inputPrevID.OutPoint, params, opts...,
 	)
 	if err != nil {
 		return nil, err
