unit-tests: token/core/zkatdlog/nogh/v1/transfer #1331 (#1333)

Signed-off-by: Angelo De Caro <adc@zurich.ibm.com>

Author: adecaro

token/core/zkatdlog/nogh/v1/transfer.go

@@ -127,17 +127,18 @@ func (s *TransferService) Transfer(ctx context.Context, anchor driver.TokenReque
 		return nil, nil, errors.New("failed to prepare transfer action: nil output token")
 	}
 
-	// load tokens with the passed token identifiers
+	// 1. Load tokens with the passed token identifiers from the vault.
 	loadedTokens, err := s.TokenLoader.LoadTokens(ctx, ids)
 	if err != nil {
 		return nil, nil, errors.Wrapf(err, "failed to load tokens")
 	}
+	// 2. Deserialize the loaded tokens into a format usable for generating the ZK proof.
 	prepareInputs, err := s.prepareInputs(ctx, loadedTokens)
 	if err != nil {
 		return nil, nil, errors.Wrapf(err, "failed to prepare inputs")
 	}
 
-	// get sender
+	// 3. Initialize the Sender which will coordinate the ZK proof generation.
 	pp := s.PublicParametersManager.PublicParams()
 	sender, err := transfer.NewSender(nil, prepareInputs.Tokens(), ids, prepareInputs.Metadata(), pp)
 	if err != nil {
@@ -146,7 +147,7 @@ func (s *TransferService) Transfer(ctx context.Context, anchor driver.TokenReque
 	values := make([]uint64, 0, len(outputs))
 	owners := make([][]byte, 0, len(outputs))
 	var isRedeem bool
-	// get values and owners of outputs
+	// 4. Extract target values and owners from the requested outputs.
 	s.Logger.DebugfContext(ctx, "Prepare %d output tokens", len(outputs))
 	for i, output := range outputs {
 		q, err := token2.ToQuantity(output.Quantity, pp.Precision())
@@ -160,8 +161,7 @@ func (s *TransferService) Transfer(ctx context.Context, anchor driver.TokenReque
 			isRedeem = true
 		}
 	}
-	// produce zkatdlog transfer action
-	// return for each output its information in the clear
+	// 5. Generate the ZK-SNARK transfer action and the metadata for the new outputs.
 	start := time.Now()
 	s.Logger.DebugfContext(ctx, "Generate zk transfer")
 	transfer, outputsMetadata, err := sender.GenerateZKTransfer(ctx, values, owners)
@@ -172,17 +172,16 @@ func (s *TransferService) Transfer(ctx context.Context, anchor driver.TokenReque
 	}
 	s.Metrics.zkTransferDuration.Observe(duration.Seconds())
 
-	// add transfer action's transferMetadata
+	// 6. Enrich the transfer action with additional metadata and upgrade witnesses if present.
 	if opts != nil {
 		transfer.Metadata = meta.TransferActionMetadata(opts.Attributes)
 	}
 
-	// add upgrade witness
 	for i, input := range transfer.Inputs {
 		input.UpgradeWitness = prepareInputs[i].UpgradeWitness
 	}
 
-	// prepare transferMetadata
+	// 7. Prepare the TransferMetadata which contains audit information for auditors.
 	ws := s.AuditInfoProvider
 
 	var transferInputsMetadata []*driver.TransferInputMetadata
@@ -265,6 +264,7 @@ func (s *TransferService) Transfer(ctx context.Context, anchor driver.TokenReque
 		ExtraSigners: nil,
 	}
 
+	// 8. If this is a redeem, select an issuer who can authorize it.
 	if isRedeem {
 		issuer, err := common.SelectIssuerForRedeem(pp.Issuers(), opts)
 		if err != nil {

token/core/zkatdlog/nogh/v1/transfer/action.go

@@ -24,12 +24,15 @@ import (
 
 const ProtocolV1 = 1
 
+// ActionInput represents a single input to a transfer action.
+// It includes the token identifier, the token itself, and an optional upgrade witness.
 type ActionInput struct {
 	ID             *token2.ID
 	Token          *token.Token
 	UpgradeWitness *token.UpgradeWitness
 }
 
+// ToProtos converts the ActionInput to its protobuf representation.
 func (a *ActionInput) ToProtos() (*actions.TransferActionInput, error) {
 	var id *actions.TokenID
 	if a.ID != nil {
@@ -76,6 +79,7 @@ func (a *ActionInput) ToProtos() (*actions.TransferActionInput, error) {
 	}, nil
 }
 
+// FromProtos populates the ActionInput from its protobuf representation.
 func (a *ActionInput) FromProtos(input *actions.TransferActionInput) error {
 	if input.TokenId != nil {
 		a.ID = &token2.ID{
@@ -117,7 +121,7 @@ func (a *ActionInput) FromProtos(input *actions.TransferActionInput) error {
 
 // Action specifies a transfer of one or more tokens
 type Action struct {
-	// Inputs specify the identifiers in of the tokens to be spent
+	// Inputs specify the tokens to be spent
 	Inputs []*ActionInput
 	// Outputs are the new tokens resulting from the transfer
 	Outputs []*token.Token
@@ -129,13 +133,13 @@ type Action struct {
 	Issuer driver.Identity
 }
 
-// NewTransfer returns the Action that matches the passed arguments
-func NewTransfer(tokenIDs []*token2.ID, inputToken []*token.Token, commitments []*math.G1, owners [][]byte, proof []byte) (*Action, error) {
+// NewAction returns the Action that matches the passed arguments
+func NewAction(tokenIDs []*token2.ID, inputToken []*token.Token, commitments []*math.G1, owners [][]byte, proof []byte) (*Action, error) {
 	if len(commitments) != len(owners) {
-		return nil, errors.Errorf("number of recipients [%d] does not match number of outputs [%d]", len(commitments), len(owners))
+		return nil, errors.Wrapf(ErrMismatchedRecipientsOutputs, "number of recipients [%d] does not match number of outputs [%d]", len(commitments), len(owners))
 	}
 	if len(tokenIDs) != len(inputToken) {
-		return nil, errors.Errorf("number of inputs [%d] does not match number of input tokens [%d]", len(tokenIDs), len(inputToken))
+		return nil, errors.Wrapf(ErrMismatchedInputsTokens, "number of inputs [%d] does not match number of input tokens [%d]", len(tokenIDs), len(inputToken))
 	}
 
 	inputs := make([]*ActionInput, len(tokenIDs))
@@ -160,11 +164,23 @@ func NewTransfer(tokenIDs []*token2.ID, inputToken []*token.Token, commitments [
 	}, nil
 }
 
+// NewActionFromProtos creates a new action from protos
+func NewActionFromProtos(raw []byte) (*Action, error) {
+	action := &Action{}
+	err := action.Deserialize(raw)
+	if err != nil {
+		return nil, err
+	}
+
+	return action, nil
+}
+
+// NumInputs returns the number of inputs in the Action
 func (t *Action) NumInputs() int {
 	return len(t.Inputs)
 }
 
-// GetInputs returns the inputs in the Action
+// GetInputs returns the identifiers of the tokens spent in the Action
 func (t *Action) GetInputs() []*token2.ID {
 	res := make([]*token2.ID, len(t.Inputs))
 	for i, input := range t.Inputs {
@@ -174,6 +190,7 @@ func (t *Action) GetInputs() []*token2.ID {
 	return res
 }
 
+// GetSerializedInputs returns the serialized tokens spent in the Action
 func (t *Action) GetSerializedInputs() ([][]byte, error) {
 	var res [][]byte
 	for _, input := range t.Inputs {
@@ -201,6 +218,7 @@ func (t *Action) GetSerializedInputs() ([][]byte, error) {
 	return res, nil
 }
 
+// GetSerialNumbers returns nil as zkatdlog doesn't use serial numbers for graph hiding
 func (t *Action) GetSerialNumbers() []string {
 	return nil
 }
@@ -225,7 +243,7 @@ func (t *Action) IsRedeemAt(index int) bool {
 	return t.Outputs[index].IsRedeem()
 }
 
-// IsRedeem checks if this action is a Redeem Transfer
+// IsRedeem checks if this action contains any redeemed outputs
 func (t *Action) IsRedeem() bool {
 	for _, output := range t.Outputs {
 		if output.IsRedeem() {
@@ -255,38 +273,38 @@ func (t *Action) GetSerializedOutputs() ([][]byte, error) {
 	return res, nil
 }
 
-// IsGraphHiding returns false
-// zkatdlog is not graph hiding
+// IsGraphHiding returns false as zkatdlog is not graph hiding
 func (t *Action) IsGraphHiding() bool {
 	return false
 }
 
-// GetMetadata returns metadata of the Action
+// GetMetadata returns the metadata of the Action
 func (t *Action) GetMetadata() map[string][]byte {
 	return t.Metadata
 }
 
-// GetIssuer returns the issuer to sign the transaction
+// GetIssuer returns the identity of the issuer who must sign the transaction
 func (t *Action) GetIssuer() driver.Identity {
 	return t.Issuer
 }
 
+// Validate ensures the Action is well-formed
 func (t *Action) Validate() error {
 	if len(t.Inputs) == 0 {
-		return errors.Errorf("invalid number of token inputs, expected at least 1")
+		return ErrInvalidInputs
 	}
 	for i, in := range t.Inputs {
 		if in == nil {
-			return errors.Errorf("invalid input at index [%d], empty input", i)
+			return errors.Wrapf(ErrEmptyInput, "invalid input at index [%d], empty input", i)
 		}
 		if in.ID == nil {
-			return errors.Errorf("invalid input's ID at index [%d], it is empty", i)
+			return errors.Wrapf(ErrEmptyInputID, "invalid input's ID at index [%d], it is empty", i)
 		}
 		if len(in.ID.TxId) == 0 {
-			return errors.Errorf("invalid input's ID at index [%d], tx id is empty", i)
+			return errors.Wrapf(ErrEmptyInputTxID, "invalid input's ID at index [%d], tx id is empty", i)
 		}
 		if in.Token == nil {
-			return errors.Errorf("invalid input's token at index [%d], empty token", i)
+			return errors.Wrapf(ErrEmptyInputToken, "invalid input's token at index [%d], empty token", i)
 		}
 		if err := in.Token.Validate(true); err != nil {
 			return errors.Wrapf(err, "invalid input token at index [%d]", i)
@@ -299,28 +317,29 @@ func (t *Action) Validate() error {
 		}
 	}
 	if len(t.Outputs) == 0 {
-		return errors.Errorf("invalid number of token outputs, expected at least 1")
+		return ErrInvalidOutputs
 	}
 	for i, out := range t.Outputs {
 		if out == nil {
-			return errors.Errorf("invalid output token at index [%d]", i)
+			return errors.Wrapf(ErrEmptyOutputToken, "invalid output token at index [%d]", i)
 		}
 		if err := out.Validate(false); err != nil {
 			return errors.Wrapf(err, "invalid output at index [%d]", i)
 		}
 	}
 	if t.IsRedeem() && (t.Issuer == nil) {
-		return errors.Errorf("Expected Issuer for a Redeem action")
+		return ErrMissingIssuer
 	}
 
 	return nil
 }
 
+// ExtraSigners returns nil as zkatdlog doesn't require extra signers
 func (t *Action) ExtraSigners() []driver.Identity {
 	return nil
 }
 
-// Serialize marshal TransferAction
+// Serialize marshals the TransferAction to bytes
 func (t *Action) Serialize() ([]byte, error) {
 	// inputs
 	inputs, err := protos.ToProtosSlice[actions.TransferActionInput, *ActionInput](t.Inputs)
@@ -367,24 +386,24 @@ func (t *Action) Serialize() ([]byte, error) {
 	return proto.Marshal(action)
 }
 
-// Deserialize un-marshals TransferAction
+// Deserialize un-marshals a TransferAction from bytes
 func (t *Action) Deserialize(raw []byte) error {
 	action := &actions.TransferAction{}
 	err := proto.Unmarshal(raw, action)
 	if err != nil {
-		return errors.Wrap(err, "failed to deserialize issue action")
+		return errors.Wrap(err, "failed to deserialize transfer action")
 	}
 
 	// assert version
 	if action.Version != ProtocolV1 {
-		return errors.Errorf("invalid issue version, expected [%d], got [%d]", ProtocolV1, action.Version)
+		return errors.Wrapf(ErrInvalidVersion, "expected [%d], got [%d]", ProtocolV1, action.Version)
 	}
 
 	// inputs
 	t.Inputs = make([]*ActionInput, len(action.Inputs))
 	t.Inputs = slices.GenericSliceOfPointers[ActionInput](len(action.Inputs))
 	if err := protos.FromProtosSlice(action.Inputs, t.Inputs); err != nil {
-		return errors.Wrap(err, "failed unmarshalling receivers metadata")
+		return errors.Wrap(err, "failed unmarshalling inputs")
 	}
 
 	// outputs
@@ -417,12 +436,12 @@ func (t *Action) Deserialize(raw []byte) error {
 	return nil
 }
 
-// GetProof returns the proof in the Action
+// GetProof returns the zero-knowledge proof in the Action
 func (t *Action) GetProof() []byte {
 	return t.Proof
 }
 
-// GetOutputCommitments returns the Pedersen commitments in the Action
+// GetOutputCommitments returns the cryptographic commitments of the outputs
 func (t *Action) GetOutputCommitments() []*math.G1 {
 	com := make([]*math.G1, len(t.Outputs))
 	for i := 0; i < len(com); i++ {
@@ -432,6 +451,7 @@ func (t *Action) GetOutputCommitments() []*math.G1 {
 	return com
 }
 
+// InputTokens returns the tokens spent in the Action
 func (t *Action) InputTokens() []*token.Token {
 	tokens := make([]*token.Token, len(t.Inputs))
 	for i, in := range t.Inputs {