Add time-range filtering, ORDER BY, OutstandingBalance, and unit tests

- Issue #3: Thread From/To *time.Time params through all 6 layers for
  IssuedBalance, ListRedeemedTokens, and RedeemedBalance. SQL uses
  cond.Gte/cond.Lte on stored_at column.

- Issue #4: Thread SortBy/SortDirection to ListRedeemedTokens SQL.
  SortByQuantity maps to ORDER BY amount ASC/DESC.

- Issue #5: Add unit tests for IssuedBalance, RedeemedTokens,
  RedeemedBalance, and OutstandingBalance (happy path, error
  propagation, edge cases).

- Issue #6: Add OutstandingBalance method to IssuerWallet
  (IssuedBalance minus RedeemedBalance) with overflow guard.

Author: Soumya Mohapatra

token/driver/mock/iw.go

@@ -8,6 +8,7 @@ package driver
 
 import (
 	"context"
+	"time"
 
 	"github.com/hyperledger-labs/fabric-smart-client/platform/common/utils/collections/iterators"
 	"github.com/hyperledger-labs/fabric-token-sdk/token/token"
@@ -87,15 +88,17 @@ type QueryEngine interface {
 	// IssuedBalance returns the sum of amounts of non-deleted tokens flagged as issued.
 	// If tokenType is non-empty, only tokens of that type are included.
 	// If issuerRaw is non-empty, only tokens issued by that identity are included.
-	IssuedBalance(ctx context.Context, tokenType token.Type, issuerRaw Identity) (uint64, error)
+	IssuedBalance(ctx context.Context, tokenType token.Type, issuerRaw Identity, from, to *time.Time) (uint64, error)
 	// ListRedeemedTokens returns issued tokens that were spent by a Redeem action.
 	// If tokenType is non-empty, only tokens of that type are included.
 	// If issuerRaw is non-empty, only tokens issued by that identity are included.
-	ListRedeemedTokens(ctx context.Context, tokenType token.Type, issuerRaw Identity) (*token.IssuedTokens, error)
+	// If from/to are non-nil, only tokens stored within that time range are included.
+	ListRedeemedTokens(ctx context.Context, tokenType token.Type, issuerRaw Identity, from, to *time.Time, sortBy SortField, sortDirection SortDirection) (*token.IssuedTokens, error)
 	// RedeemedBalance returns the sum of amounts of issued tokens spent by a Redeem action.
 	// If tokenType is non-empty, only tokens of that type are included.
 	// If issuerRaw is non-empty, only tokens issued by that identity are included.
-	RedeemedBalance(ctx context.Context, tokenType token.Type, issuerRaw Identity) (uint64, error)
+	// If from/to are non-nil, only tokens stored within that time range are included.
+	RedeemedBalance(ctx context.Context, tokenType token.Type, issuerRaw Identity, from, to *time.Time) (uint64, error)
 	// PublicParams returns the serialized public parameters used by the driver.
 	PublicParams(ctx context.Context) ([]byte, error)
 	// GetTokenMetadata retrieves the private information (metadata) for the given token IDs.

token/driver/mock/qe.go

@@ -8,6 +8,7 @@ package driver
 
 import (
 	"context"
+	"time"
 
 	"github.com/hyperledger-labs/fabric-smart-client/platform/view/view"
 	"github.com/hyperledger-labs/fabric-token-sdk/token/token"
@@ -98,6 +99,10 @@ type ListTokensOptions struct {
 	SortBy SortField
 	// SortDirection specifies ascending or descending order.
 	SortDirection SortDirection
+	// From, if non-nil, restricts results to tokens stored at or after this time.
+	From *time.Time
+	// To, if non-nil, restricts results to tokens stored at or before this time.
+	To *time.Time
 }
 
 // Wallet models a generic wallet
@@ -184,6 +189,9 @@ type IssuerWallet interface {
 
 	// RedeemedBalance returns the total amount of redeemed tokens that were originally issued by this wallet.
 	RedeemedBalance(ctx context.Context, opts *ListTokensOptions) (uint64, error)
+
+	// OutstandingBalance returns the net amount still in circulation: IssuedBalance − RedeemedBalance.
+	OutstandingBalance(ctx context.Context, opts *ListTokensOptions) (uint64, error)
 }
 
 // AuditorWallet models the wallet of an auditor