Exercise WithSortBy and WithTimeRange in tests; rename WithBalanceType; add GoDocs

Signed-off-by: Soumya Mohapatra <soumyaranjanmohapatra8@gmail.com>
Signed-off-by: Soumya Mohapatra <mohapatras@microsoft.com>

Author: Soumya Mohapatra

integration/token/dvp/views/balance.go

@@ -40,7 +40,7 @@ func (b *BalanceView) Call(context view.Context) (interface{}, error) {
 		return nil, fmt.Errorf("wallet %s not found: %w", b.Wallet, err)
 	}
 
-	balance, err := wallet.Balance(context.Context(), token.WithBalanceType(b.Type))
+	balance, err := wallet.Balance(context.Context(), token.WithBalanceTokenType(b.Type))
 	if err != nil {
 		return nil, err
 	}

integration/token/fungible/views/accept.go

@@ -42,7 +42,7 @@ func (a *AcceptCashView) Call(context view.Context) (interface{}, error) {
 		if output.Type == "MAX" {
 			continue
 		}
-		balance, err := ttx.MyWallet(context, token.WithTMSID(tx.TMSID())).Balance(context.Context(), token.WithBalanceType(output.Type))
+		balance, err := ttx.MyWallet(context, token.WithTMSID(tx.TMSID())).Balance(context.Context(), token.WithBalanceTokenType(output.Type))
 		assert.NoError(err, "failed retrieving balance for type [%s]", output.Type)
 		assert.True(balance <= 3000, "cannot have more than 3000 unspent quantity for type [%s]", output.Type)
 	}

integration/token/fungible/views/balance.go

@@ -63,7 +63,7 @@ func (b *BalanceView) Call(context view.Context) (interface{}, error) {
 	assert.NoError(err, "failed to compute the sum of the co-owned tokens")
 
 	if !b.SkipCheck {
-		balance, err := wallet.Balance(context.Context(), token.WithBalanceType(b.Type))
+		balance, err := wallet.Balance(context.Context(), token.WithBalanceTokenType(b.Type))
 		if err != nil {
 			return nil, err
 		}

integration/token/fungible/views/history.go

@@ -200,7 +200,7 @@ func (p *IssuedBalanceView) Call(context view.Context) (interface{}, error) {
 		return nil, errors.Errorf("wallet [%s] not found", p.Wallet)
 	}
 
-	return wallet.IssuedBalance(context.Context(), token.WithBalanceType(p.TokenType))
+	return wallet.IssuedBalance(context.Context(), token.WithBalanceTokenType(p.TokenType))
 }
 
 type IssuedBalanceViewFactory struct{}
@@ -225,7 +225,7 @@ func (p *RedeemedBalanceView) Call(context view.Context) (interface{}, error) {
 		return nil, errors.Errorf("wallet [%s] not found", p.Wallet)
 	}
 
-	return wallet.RedeemedBalance(context.Context(), token.WithBalanceType(p.TokenType))
+	return wallet.RedeemedBalance(context.Context(), token.WithBalanceTokenType(p.TokenType))
 }
 
 type RedeemedBalanceViewFactory struct{}
@@ -250,7 +250,7 @@ func (p *OutstandingBalanceView) Call(context view.Context) (interface{}, error)
 		return nil, errors.Errorf("wallet [%s] not found", p.Wallet)
 	}
 
-	return wallet.OutstandingBalance(context.Context(), token.WithBalanceType(p.TokenType))
+	return wallet.OutstandingBalance(context.Context(), token.WithBalanceTokenType(p.TokenType))
 }
 
 type OutstandingBalanceViewFactory struct{}

integration/token/interop/views/balance.go

@@ -48,7 +48,7 @@ func (b *BalanceView) Call(context view.Context) (interface{}, error) {
 	precision := tms.PublicParametersManager().PublicParameters().Precision()
 
 	// owned
-	balance, err := wallet.Balance(context.Context(), token.WithBalanceType(b.Type))
+	balance, err := wallet.Balance(context.Context(), token.WithBalanceTokenType(b.Type))
 	assert.NoError(err, "failed to get unspent tokens")
 
 	htlcWallet := htlc.Wallet(context, wallet)

token/vault.go

@@ -121,14 +121,20 @@ func (q *QueryEngine) ListHistoryIssuedTokens(ctx context.Context) (*token.Issue
 	return q.qe.ListHistoryIssuedTokens(ctx)
 }
 
+// IssuedBalance returns the total amount of tokens issued by the given issuer that have not been redeemed,
+// optionally filtered by token type and time range.
 func (q *QueryEngine) IssuedBalance(ctx context.Context, tokenType token.Type, issuerRaw driver.Identity, from, to *time.Time) (uint64, error) {
 	return q.qe.IssuedBalance(ctx, tokenType, issuerRaw, from, to)
 }
 
+// ListRedeemedTokens returns the list of redeemed tokens originally issued by the given issuer,
+// optionally filtered by token type, time range, and sorted by the specified field and direction.
 func (q *QueryEngine) ListRedeemedTokens(ctx context.Context, tokenType token.Type, issuerRaw driver.Identity, from, to *time.Time, sortBy driver.SortField, sortDirection driver.SortDirection) (*token.IssuedTokens, error) {
 	return q.qe.ListRedeemedTokens(ctx, tokenType, issuerRaw, from, to, sortBy, sortDirection)
 }
 
+// RedeemedBalance returns the total amount of redeemed tokens originally issued by the given issuer,
+// optionally filtered by token type and time range.
 func (q *QueryEngine) RedeemedBalance(ctx context.Context, tokenType token.Type, issuerRaw driver.Identity, from, to *time.Time) (uint64, error) {
 	return q.qe.RedeemedBalance(ctx, tokenType, issuerRaw, from, to)
 }

token/wallet.go

@@ -56,14 +56,18 @@ func WithSortBy(field driver.SortField, dir driver.SortDirection) ListTokensOpti
 	}
 }
 
-// BalanceOpts contains options for balance queries.
+// BalanceOpts contains options for balance queries (methods that return a scalar
+// total rather than a list of tokens). Sort fields are intentionally excluded
+// because the result is a single number.
 type BalanceOpts = driver.BalanceOpts
 
-// BalanceOption is a function that configures BalanceOpts
+// BalanceOption is a functional option that configures a BalanceOpts struct.
+// Use WithBalanceTokenType and WithTimeRange to construct values.
 type BalanceOption func(*BalanceOpts) error
 
-// WithBalanceType returns a balance option that filters by the passed token type.
-func WithBalanceType(tokenType token.Type) BalanceOption {
+// WithBalanceTokenType returns a BalanceOption that restricts the balance
+// computation to the given token type. An empty token type means all types.
+func WithBalanceTokenType(tokenType token.Type) BalanceOption {
 	return func(o *BalanceOpts) error {
 		o.TokenType = tokenType
 
@@ -394,7 +398,7 @@ func (i *IssuerWallet) ListIssuedTokens(ctx context.Context, opts ...ListTokensO
 }
 
 // IssuedBalance returns the total amount of non-redeemed tokens issued by this wallet.
-// Options: WithBalanceType, WithTimeRange
+// Options: WithBalanceTokenType, WithTimeRange
 func (i *IssuerWallet) IssuedBalance(ctx context.Context, opts ...BalanceOption) (uint64, error) {
 	compiledOpts, err := CompileBalanceOption(opts...)
 	if err != nil {
@@ -416,7 +420,7 @@ func (i *IssuerWallet) ListRedeemedTokens(ctx context.Context, opts ...ListToken
 }
 
 // RedeemedBalance returns the total amount of redeemed tokens originally issued by this wallet.
-// Options: WithBalanceType, WithTimeRange
+// Options: WithBalanceTokenType, WithTimeRange
 func (i *IssuerWallet) RedeemedBalance(ctx context.Context, opts ...BalanceOption) (uint64, error) {
 	compiledOpts, err := CompileBalanceOption(opts...)
 	if err != nil {
@@ -427,7 +431,7 @@ func (i *IssuerWallet) RedeemedBalance(ctx context.Context, opts ...BalanceOptio
 }
 
 // OutstandingBalance returns the net amount still in circulation: IssuedBalance − RedeemedBalance.
-// Options: WithBalanceType, WithTimeRange
+// Options: WithBalanceTokenType, WithTimeRange
 func (i *IssuerWallet) OutstandingBalance(ctx context.Context, opts ...BalanceOption) (uint64, error) {
 	compiledOpts, err := CompileBalanceOption(opts...)
 	if err != nil {
@@ -456,7 +460,8 @@ func CompileListTokensOption(opts ...ListTokensOption) (*driver.ListTokensOption
 	}, nil
 }
 
-// CompileBalanceOption compiles variadic BalanceOption values into a single BalanceOpts struct.
+// CompileBalanceOption compiles variadic BalanceOption values into a single
+// BalanceOpts struct ready to be passed to a driver-level balance method.
 func CompileBalanceOption(opts ...BalanceOption) (*driver.BalanceOpts, error) {
 	bo := &driver.BalanceOpts{}
 	for _, opt := range opts {

token/wallet_test.go

@@ -10,6 +10,7 @@ package token
 import (
 	"context"
 	"testing"
+	"time"
 
 	"github.com/hyperledger-labs/fabric-smart-client/pkg/utils/errors"
 	"github.com/hyperledger-labs/fabric-token-sdk/token/driver"
@@ -572,7 +573,7 @@ func TestOwnerWallet_Balance(t *testing.T) {
 	wallet := &OwnerWallet{w: mockOW}
 	ctx := context.Background()
 
-	balance, err := wallet.Balance(ctx, WithBalanceType("USD"))
+	balance, err := wallet.Balance(ctx, WithBalanceTokenType("USD"))
 
 	require.NoError(t, err)
 	assert.Equal(t, uint64(1000), balance)
@@ -623,6 +624,51 @@ func TestIssuerWallet_ListIssuedTokens(t *testing.T) {
 	assert.Equal(t, expectedTokens, tokens)
 }
 
+// TestIssuerWallet_ListIssuedTokens_WithSortBy verifies that WithSortBy passes the sort
+// field and direction through to the driver.
+func TestIssuerWallet_ListIssuedTokens_WithSortBy(t *testing.T) {
+	mockIW := &mock.IssuerWallet{}
+	expectedTokens := &token.IssuedTokens{}
+	mockIW.HistoryTokensReturns(expectedTokens, nil)
+
+	wallet := &IssuerWallet{w: mockIW}
+	ctx := context.Background()
+
+	tokens, err := wallet.ListIssuedTokens(ctx, WithType("USD"), WithSortBy(driver.SortByQuantity, driver.SortDescending))
+
+	require.NoError(t, err)
+	assert.Equal(t, expectedTokens, tokens)
+
+	// Verify the compiled options include sort fields.
+	_, opts := mockIW.HistoryTokensArgsForCall(0)
+	assert.Equal(t, driver.SortByQuantity, opts.SortBy)
+	assert.Equal(t, driver.SortDescending, opts.SortDirection)
+}
+
+// TestOwnerWallet_Balance_WithTimeRange verifies that WithTimeRange passes the
+// time bounds through to the driver.
+func TestOwnerWallet_Balance_WithTimeRange(t *testing.T) {
+	mockOW := &mock.OwnerWallet{}
+	mockOW.BalanceReturns(uint64(500), nil)
+
+	wallet := &OwnerWallet{w: mockOW}
+	ctx := context.Background()
+
+	from := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)
+	to := time.Date(2025, 12, 31, 23, 59, 59, 0, time.UTC)
+
+	balance, err := wallet.Balance(ctx, WithBalanceTokenType("USD"), WithTimeRange(&from, &to))
+
+	require.NoError(t, err)
+	assert.Equal(t, uint64(500), balance)
+
+	// Verify the compiled options include time range.
+	_, opts := mockOW.BalanceArgsForCall(0)
+	assert.Equal(t, &from, opts.From)
+	assert.Equal(t, &to, opts.To)
+	assert.Equal(t, token.Type("USD"), opts.TokenType)
+}
+
 // TestWalletManager_OwnerWalletIDs_Error verifies error handling
 func TestWalletManager_OwnerWalletIDs_Error(t *testing.T) {
 	mockWS := &mock.WalletService{}
@@ -763,7 +809,7 @@ func TestOwnerWallet_Balance_Error(t *testing.T) {
 	wallet := &OwnerWallet{w: mockOW}
 	ctx := context.Background()
 
-	balance, err := wallet.Balance(ctx, WithBalanceType("USD"))
+	balance, err := wallet.Balance(ctx, WithBalanceTokenType("USD"))
 
 	require.Error(t, err)
 	assert.Equal(t, expectedErr, err)