feat(ttx): add WithApprovalMetadata option to forward metadata to approvers

Signed-off-by: atharrva01 <atharvaborade568@gmail.com>

Author: atharrva01

token/core/common/driver/mock/network_driver.go

@@ -62,7 +62,8 @@ type Network interface {
 	NewEnvelope() Envelope
 
 	// RequestApproval requests an endorsement for a token request from the network's approval service.
-	RequestApproval(context view.Context, tms *token2.ManagementService, requestRaw []byte, signer view.Identity, txID TxID) (Envelope, error)
+	// metadata carries optional application-level key-value pairs forwarded to the approver.
+	RequestApproval(context view.Context, tms *token2.ManagementService, requestRaw []byte, signer view.Identity, txID TxID, metadata TransientMap) (Envelope, error)
 
 	// ComputeTxID calculates the ledger-specific transaction ID from an abstract TxID.
 	ComputeTxID(id *TxID) string

token/services/auditor/mock/network_driver.go

@@ -27,8 +27,8 @@ func NewChaincodeEndorsementService(tmsID token2.TMSID) *ChaincodeEndorsementSer
 	return &ChaincodeEndorsementService{TMSID: tmsID}
 }
 
-func (e *ChaincodeEndorsementService) Endorse(context view.Context, requestRaw []byte, signer view.Identity, txID driver.TxID) (driver.Envelope, error) {
-	env, err := chaincode.NewEndorseView(
+func (e *ChaincodeEndorsementService) Endorse(context view.Context, requestRaw []byte, signer view.Identity, txID driver.TxID, metadata driver.TransientMap) (driver.Envelope, error) {
+	ev := chaincode.NewEndorseView(
 		e.TMSID.Namespace,
 		InvokeFunction,
 	).WithNetwork(
@@ -44,7 +44,11 @@ func (e *ChaincodeEndorsementService) Endorse(context view.Context, requestRaw [
 			Nonce:   txID.Nonce,
 			Creator: txID.Creator,
 		},
-	).Endorse(context)
+	)
+	for k, v := range metadata {
+		ev = ev.WithTransientEntry(k, v)
+	}
+	env, err := ev.Endorse(context)
 	if err != nil {
 		return nil, err
 	}

token/services/network/driver/network.go

@@ -7,6 +7,7 @@ SPDX-License-Identifier: Apache-2.0
 package fsc
 
 import (
+	"encoding/json"
 	"time"
 
 	"github.com/hyperledger-labs/fabric-smart-client/pkg/utils/errors"
@@ -16,6 +17,10 @@ import (
 	"github.com/hyperledger-labs/fabric-token-sdk/token/services/network/driver"
 )
 
+// TransientApprovalMetadataKey is the transient map key used to carry optional application-level
+// approval metadata from the initiator to the responder.
+const TransientApprovalMetadataKey = "approval_metadata"
+
 // RequestApprovalView is the initiator of the request approval protocol
 type RequestApprovalView struct {
 	TMSID      token.TMSID
@@ -26,6 +31,8 @@ type RequestApprovalView struct {
 	Nonce []byte
 	// Endorsers are the identities of the FSC node that play the role of endorser
 	Endorsers []view.Identity
+	// Metadata carries optional application-level key-value pairs forwarded to the approver via transient data.
+	Metadata driver.TransientMap
 
 	// EndorserService is the endorser service
 	EndorserService EndorserService
@@ -41,6 +48,7 @@ func NewRequestApprovalView(
 	nonce []byte,
 	endorsers []view.Identity,
 	endorserService EndorserService,
+	metadata driver.TransientMap,
 ) *RequestApprovalView {
 	return &RequestApprovalView{
 		TMSID:           TMSID,
@@ -49,6 +57,7 @@ func NewRequestApprovalView(
 		Nonce:           nonce,
 		Endorsers:       endorsers,
 		EndorserService: endorserService,
+		Metadata:        metadata,
 	}
 }
 
@@ -76,6 +85,15 @@ func (r *RequestApprovalView) Call(ctx view.Context) (any, error) {
 	if err := tx.SetTransient(TransientTokenRequestKey, r.RequestRaw); err != nil {
 		return nil, errors.WithMessagef(err, "failed to set token request transient")
 	}
+	if len(r.Metadata) > 0 {
+		metadataRaw, err := json.Marshal(r.Metadata)
+		if err != nil {
+			return nil, errors.WithMessagef(err, "failed to marshal approval metadata")
+		}
+		if err := tx.SetTransient(TransientApprovalMetadataKey, metadataRaw); err != nil {
+			return nil, errors.WithMessagef(err, "failed to set approval metadata transient")
+		}
+	}
 
 	logger.DebugfContext(ctx.Context(), "request endorsement on tx [%s] to [%v]...", tx.ID(), r.Endorsers)
 	err = r.EndorserService.CollectEndorsements(ctx, tx, 2*time.Minute, r.Endorsers...)

token/services/network/fabric/endorsement/chaincode.go

@@ -80,6 +80,7 @@ func mockNewRequestApprovalView(t *testing.T, overrideTMSID *token.TMSID) *MockN
 		nil,
 		nil,
 		es,
+		nil,
 	)
 
 	return &MockNewRequestApprovalView{
@@ -128,6 +129,22 @@ func TestRequestApprovalView(t *testing.T) {
 			},
 			expectError: false,
 		},
+		{
+			name: "Success with approval metadata",
+			setup: func() *MockNewRequestApprovalView {
+				m := mockNewRequestApprovalView(t, nil)
+				m.view.Metadata = driver.TransientMap{
+					"info": []byte("extra"),
+				}
+
+				return m
+			},
+			verify: func(m *MockNewRequestApprovalView, res any) {
+				assert.Len(t, m.transientMap, 3)
+				assert.Contains(t, m.transientMap, fsc.TransientApprovalMetadataKey)
+			},
+			expectError: false,
+		},
 		{
 			name: "failed NewTransaction",
 			setup: func() *MockNewRequestApprovalView {

token/services/network/fabric/endorsement/fsc/initiator.go

@@ -8,6 +8,7 @@ package fsc
 
 import (
 	"context"
+	"encoding/json"
 
 	"github.com/hyperledger-labs/fabric-smart-client/pkg/utils/errors"
 	"github.com/hyperledger-labs/fabric-smart-client/platform/fabric"
@@ -36,6 +37,7 @@ type Request struct {
 	RequestRaw       []byte
 	Actions          []any
 	Meta             map[string][]byte
+	ApprovalMetadata map[string][]byte
 	Tms              *token2.ManagementService
 	PublicParamsHash tdriver.PPHash
 }
@@ -114,10 +116,10 @@ func (r *RequestApprovalResponderView) receive(ctx view.Context) (*Request, erro
 
 	// validate transient
 
-	// check the number of transient keys
+	// check the number of transient keys: 2 required (tmsID + token_request) plus 1 optional (approval_metadata)
 	var tmsID token2.TMSID
-	if len(tx.Transaction.Transient()) != 2 {
-		return nil, errors.Wrapf(ErrInvalidTransient, "invalid number of transient field, expected 2, got %d", len(tx.Transaction.Transient()))
+	if n := len(tx.Transaction.Transient()); n < 2 || n > 3 {
+		return nil, errors.Wrapf(ErrInvalidTransient, "invalid number of transient fields, expected 2 or 3, got %d", n)
 	}
 
 	// TMS ID
@@ -142,6 +144,14 @@ func (r *RequestApprovalResponderView) receive(ctx view.Context) (*Request, erro
 		return nil, errors.Wrapf(ErrInvalidTransient, "empty token request")
 	}
 
+	// approval metadata (optional)
+	var approvalMetadata map[string][]byte
+	if raw := tx.GetTransient(TransientApprovalMetadataKey); len(raw) > 0 {
+		if err := json.Unmarshal(raw, &approvalMetadata); err != nil {
+			return nil, errors.Wrapf(ErrInvalidTransient, "failed to unmarshal approval metadata")
+		}
+	}
+
 	// request anchor
 	requestAnchor := tx.ID()
 
@@ -183,6 +193,7 @@ func (r *RequestApprovalResponderView) receive(ctx view.Context) (*Request, erro
 		TMSID:            tmsID,
 		RequestRaw:       requestRaw,
 		Anchor:           requestAnchor,
+		ApprovalMetadata: approvalMetadata,
 		Tms:              tms,
 		PublicParamsHash: tms.PublicParametersManager().PublicParamsHash(),
 	}, nil

token/services/network/fabric/endorsement/fsc/initiator_test.go

@@ -191,7 +191,7 @@ func TestRequestApprovalResponderView(t *testing.T) {
 			},
 		},
 		{
-			name: "invalid number of transient field",
+			name: "invalid number of transient fields",
 			setup: func() *MockNewRequestApprovalResponderView {
 				m := mockNewRequestApprovalResponderView(t, nil)
 				m.fabricTx.TransientReturns(map[string][]byte{
@@ -202,7 +202,7 @@ func TestRequestApprovalResponderView(t *testing.T) {
 			},
 			expectError:      true,
 			expectErrorType:  fsc.ErrReceivedProposal,
-			expectErrContain: "invalid number of transient field, expected 2, got 1",
+			expectErrContain: "invalid number of transient fields, expected 2 or 3, got 1",
 			verify: func(m *MockNewRequestApprovalResponderView, res any) {
 				assert.Equal(t, 0, m.rws.DoneCallCount())
 			},
@@ -618,6 +618,44 @@ func TestRequestApprovalResponderView(t *testing.T) {
 				assert.Equal(t, 1, m.rws.DoneCallCount())
 			},
 		},
+		{
+			name: "success with approval metadata",
+			setup: func() *MockNewRequestApprovalResponderView {
+				m := mockNewRequestApprovalResponderView(t, nil)
+				metadataRaw, err := json.Marshal(map[string][]byte{"info": []byte("extra")})
+				require.NoError(t, err)
+				m.fabricTx.TransientReturns(map[string][]byte{
+					fsc.TransientTMSIDKey:            m.tmsIDRaw,
+					fsc.TransientTokenRequestKey:     []byte("a_token_request"),
+					fsc.TransientApprovalMetadataKey: metadataRaw,
+				})
+
+				return m
+			},
+			expectError: false,
+			verify: func(m *MockNewRequestApprovalResponderView, res any) {
+				assert.Equal(t, 1, m.rws.DoneCallCount())
+			},
+		},
+		{
+			name: "invalid approval metadata encoding",
+			setup: func() *MockNewRequestApprovalResponderView {
+				m := mockNewRequestApprovalResponderView(t, nil)
+				m.fabricTx.TransientReturns(map[string][]byte{
+					fsc.TransientTMSIDKey:            m.tmsIDRaw,
+					fsc.TransientTokenRequestKey:     []byte("a_token_request"),
+					fsc.TransientApprovalMetadataKey: []byte("not-valid-json"),
+				})
+
+				return m
+			},
+			expectError:      true,
+			expectErrorType:  fsc.ErrReceivedProposal,
+			expectErrContain: "failed to unmarshal approval metadata",
+			verify: func(m *MockNewRequestApprovalResponderView, res any) {
+				assert.Equal(t, 0, m.rws.DoneCallCount())
+			},
+		},
 	}
 
 	for _, tc := range testCases {

token/services/network/fabric/endorsement/fsc/responder.go

@@ -106,7 +106,7 @@ func NewEndorsementService(
 	}, nil
 }
 
-func (e *EndorsementService) Endorse(context view.Context, requestRaw []byte, signer view.Identity, txID driver.TxID) (driver.Envelope, error) {
+func (e *EndorsementService) Endorse(context view.Context, requestRaw []byte, signer view.Identity, txID driver.TxID, metadata driver.TransientMap) (driver.Envelope, error) {
 	var endorsers []view.Identity
 	switch e.PolicyType {
 	case OneOutNPolicy:
@@ -125,6 +125,7 @@ func (e *EndorsementService) Endorse(context view.Context, requestRaw []byte, si
 		nil,
 		endorsers,
 		e.EndorserService,
+		metadata,
 	))
 	if err != nil {
 		return nil, errors.WithMessagef(err, "failed to request approval")