address+tappsbt: add ProofDeliveryAddress to VOutput

When interactively signing a transfer that goes to a TAP address, the
participants might want to be able to check the proof courier delivery
URL that will be used to transfer the proof.
This information currently gets lost when converting a TAP address into
a vPSBT and is transported in a different data structure inside of the
freighter. For a flow that doesn't use the freighter (or just in the
very end), there currently is no way to specify the proof courier
address, which this commit now changes.
A follow-up commit will refactor the freighter to use this new field.

Author: guggero

address/encoding.go

@@ -42,17 +42,17 @@ func compressedPubKeyDecoder(r io.Reader, val any, buf *[8]byte, l uint64) error
 	)
 }
 
-// urlEncoder encodes a url.URL as a variable length byte slice.
-func urlEncoder(w io.Writer, val any, buf *[8]byte) error {
+// UrlEncoder encodes a url.URL as a variable length byte slice.
+func UrlEncoder(w io.Writer, val any, buf *[8]byte) error {
 	if t, ok := val.(*url.URL); ok {
 		addrBytes := []byte((*t).String())
 		return tlv.EVarBytes(w, &addrBytes, buf)
 	}
 	return tlv.NewTypeForEncodingErr(val, "*url.URL")
 }
 
-// urlDecoder decodes a variable length byte slice as an url.URL.
-func urlDecoder(r io.Reader, val any, buf *[8]byte, l uint64) error {
+// UrlDecoder decodes a variable length byte slice as an url.URL.
+func UrlDecoder(r io.Reader, val any, buf *[8]byte, l uint64) error {
 	if t, ok := val.(*url.URL); ok {
 		var addrBytes []byte
 		err := tlv.DVarBytes(r, &addrBytes, buf, l)
@@ -68,9 +68,7 @@ func urlDecoder(r io.Reader, val any, buf *[8]byte, l uint64) error {
 
 		return nil
 	}
-	return tlv.NewTypeForDecodingErr(
-		val, "*url.URL", l, l,
-	)
+	return tlv.NewTypeForDecodingErr(val, "*url.URL", l, l)
 }
 
 func VersionEncoder(w io.Writer, val any, buf *[8]byte) error {

address/records.go

@@ -115,6 +115,6 @@ func newProofCourierAddrRecord(addr *url.URL) tlv.Record {
 
 	return tlv.MakeDynamicRecord(
 		addrProofCourierAddrType, addr, recordSize,
-		urlEncoder, urlDecoder,
+		UrlEncoder, UrlDecoder,
 	)
 }

tappsbt/decode.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net/url"
 
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/btcec/v2/schnorr"
@@ -284,6 +285,10 @@ func (o *VOutput) decode(pOut psbt.POutput, txOut *wire.TxOut) error {
 				&o.AssetVersion, vOutputAssetVersionDecoder,
 			),
 		},
+		{
+			key:     PsbtKeyTypeOutputTapProofDeliveryAddress,
+			decoder: urlDecoder(&o.ProofDeliveryAddress),
+		},
 	}
 
 	for idx := range mapping {
@@ -478,3 +483,17 @@ func vOutputAssetVersionDecoder(r io.Reader, val any, buf *[8]byte,
 	}
 	return tlv.NewTypeForDecodingErr(val, "VOutputAssetVersion", 8, l)
 }
+
+// urlDecoder returns a decoder function that can handle nil URLs.
+func urlDecoder(u **url.URL) decoderFunc {
+	return func(key, byteVal []byte) error {
+		if len(byteVal) == 0 {
+			return nil
+		}
+
+		if *u == nil {
+			*u = &url.URL{}
+		}
+		return tlvDecoder(*u, address.UrlDecoder)(key, byteVal)
+	}
+}

tappsbt/encode.go

@@ -6,12 +6,14 @@ import (
 	"fmt"
 	"io"
 	"math"
+	"net/url"
 
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/btcec/v2/schnorr"
 	"github.com/btcsuite/btcd/btcutil/psbt"
 	"github.com/btcsuite/btcd/txscript"
 	"github.com/btcsuite/btcd/wire"
+	"github.com/lightninglabs/taproot-assets/address"
 	"github.com/lightninglabs/taproot-assets/asset"
 	"github.com/lightninglabs/taproot-assets/commitment"
 	"github.com/lightninglabs/taproot-assets/fn"
@@ -283,6 +285,10 @@ func (o *VOutput) encode(coinType uint32) (psbt.POutput, *wire.TxOut, error) {
 				&o.AssetVersion, vOutputAssetVersionEncoder,
 			),
 		},
+		{
+			key:     PsbtKeyTypeOutputTapProofDeliveryAddress,
+			encoder: urlEncoder(o.ProofDeliveryAddress),
+		},
 	}
 
 	for idx := range mapping {
@@ -481,3 +487,29 @@ func vOutputAssetVersionEncoder(w io.Writer, val any, buf *[8]byte) error {
 	}
 	return tlv.NewTypeForEncodingErr(val, "VOutputAssetVersion")
 }
+
+// urlEncoder returns a function that encodes the given URL as a custom PSBT
+// field.
+func urlEncoder(val *url.URL) encoderFunc {
+	return func(key []byte) ([]*customPsbtField, error) {
+		if val == nil {
+			return nil, nil
+		}
+
+		var (
+			b       bytes.Buffer
+			scratch [8]byte
+		)
+		if err := address.UrlEncoder(&b, val, &scratch); err != nil {
+			return nil, fmt.Errorf("error encoding TLV record: %w",
+				err)
+		}
+
+		return []*customPsbtField{
+			{
+				Key:   fn.CopySlice(key),
+				Value: b.Bytes(),
+			},
+		}, nil
+	}
+}

tappsbt/interface.go

@@ -3,6 +3,7 @@ package tappsbt
 import (
 	"bytes"
 	"fmt"
+	"net/url"
 
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/btcutil"
@@ -52,6 +53,7 @@ var (
 	PsbtKeyTypeOutputTapSplitAsset                         = []byte{0x77}
 	PsbtKeyTypeOutputTapAnchorTapscriptSibling             = []byte{0x78}
 	PsbtKeyTypeOutputTapAssetVersion                       = []byte{0x79}
+	PsbtKeyTypeOutputTapProofDeliveryAddress               = []byte{0x7a}
 )
 
 // The following keys are used as custom fields on the BTC level anchor
@@ -522,6 +524,10 @@ type VOutput struct {
 	// serialized, this will be stored in the TaprootInternalKey and
 	// TaprootDerivationPath fields of the PSBT output.
 	ScriptKey asset.ScriptKey
+
+	// ProofDeliveryAddress is the address to which the proof of the asset
+	// transfer should be delivered.
+	ProofDeliveryAddress *url.URL
 }
 
 // SplitLocator creates a split locator from the output. The asset ID is passed

tappsbt/mock.go

@@ -3,6 +3,7 @@ package tappsbt
 import (
 	"bytes"
 	"encoding/hex"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -100,6 +101,9 @@ func RandPacket(t testing.TB) *VPacket {
 		t, testAsset.Genesis, inputScriptKey.PubKey, oddTxBlock, 1, 0,
 	)
 
+	courierAddress, err := url.Parse("https://example.com")
+	require.NoError(t, err)
+
 	vPacket := &VPacket{
 		Inputs: []*VInput{{
 			PrevID: asset.PrevID{
@@ -136,6 +140,7 @@ func RandPacket(t testing.TB) *VPacket {
 			ScriptKey:                          testOutputAsset.ScriptKey,
 			SplitAsset:                         testOutputAsset,
 			AnchorOutputTapscriptSibling:       testPreimage1,
+			ProofDeliveryAddress:               courierAddress,
 		}, {
 			Amount: 345,
 			AssetVersion: asset.Version(
@@ -493,6 +498,10 @@ func NewTestFromVOutput(t testing.TB, v *VOutput,
 		vo.Asset = asset.NewTestFromAsset(t, v.Asset)
 	}
 
+	if v.ProofDeliveryAddress != nil {
+		vo.ProofDeliveryAddress = v.ProofDeliveryAddress.String()
+	}
+
 	if v.ScriptKey.TweakedScriptKey != nil {
 		bip32Derivation, trBip32Derivation := Bip32DerivationFromKeyDesc(
 			v.ScriptKey.RawKey, coinType,
@@ -572,6 +581,7 @@ type TestVOutput struct {
 	TrBip32Derivation             []*TestTrBip32Derivation `json:"tr_bip32_derivation"`
 	TrInternalKey                 string                   `json:"tr_internal_key"`
 	TrMerkleRoot                  string                   `json:"tr_merkle_root"`
+	ProofDeliveryAddress          string                   `json:"proof_delivery_address"`
 }
 
 func (to *TestVOutput) ToVOutput(t testing.TB) *VOutput {
@@ -609,6 +619,12 @@ func (to *TestVOutput) ToVOutput(t testing.TB) *VOutput {
 		v.SplitAsset = to.SplitAsset.ToAsset(t)
 	}
 
+	if to.ProofDeliveryAddress != "" {
+		var err error
+		v.ProofDeliveryAddress, err = url.Parse(to.ProofDeliveryAddress)
+		require.NoError(t, err)
+	}
+
 	if len(to.Bip32Derivation) > 0 && to.TrInternalKey != "" {
 		firstDerivation := to.Bip32Derivation[0].ToBip32Derivation(t)
 		keyDesc, err := KeyDescFromBip32Derivation(firstDerivation)