Balance to return big.Int

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

Author: adecaro

docs/imgs/storage_db.png

@@ -24,7 +24,7 @@ package "Transaction & Audit Store (TTXDB / AuditDB)" {
         sender_eid : TEXT
         recipient_eid : TEXT
         token_type : TEXT <<NOT NULL>>
-        amount : BIGINT <<NOT NULL>>
+        amount : NUMERIC(78,0) <<NOT NULL>>
         stored_at : TIMESTAMP <<NOT NULL>>
     }
 
@@ -34,7 +34,7 @@ package "Transaction & Audit Store (TTXDB / AuditDB)" {
         tx_id : TEXT <<FK, NOT NULL>>
         enrollment_id : TEXT
         token_type : TEXT <<NOT NULL>>
-        amount : BIGINT <<NOT NULL>>
+        amount : NUMERIC(78,0) <<NOT NULL>>
         stored_at : TIMESTAMP <<NOT NULL>>
     }
 
@@ -65,7 +65,7 @@ package "Token Store (TokenDB)" {
         * tx_id : TEXT <<PK, NOT NULL>>
         * idx : INT <<PK, NOT NULL>>
         --
-        amount : BIGINT <<NOT NULL>>
+        amount : NUMERIC(78,0) <<NOT NULL>>
         token_type : TEXT <<NOT NULL>>
         quantity : TEXT <<NOT NULL>>
         issuer_raw : BYTEA

docs/imgs/storage_db.puml

@@ -12,19 +12,29 @@ The storage layer is built on a provider-based architecture that supports multip
 
 The Fabric Token SDK storage is organized into logical databases, each serving a specific role in the transaction lifecycle and identity management.
 
+### Amount Storage Strategy
+
+**All token amounts** across the storage layer are stored as `NUMERIC(78, 0)` in the database, supporting arbitrary precision integers up to 78 digits. This design choice enables:
+- Representation of token amounts exceeding the uint64 maximum value (2^64-1 ≈ 1.8×10^19)
+- Support for tokens with high precision or extremely large supply
+- Consistent handling of amounts across all tables (Tokens, Transactions, Movements)
+
+The SDK uses Go's `*big.Int` type throughout the codebase to handle these large values, with automatic conversion between database NUMERIC values and in-memory big.Int representations via the `BigInt` scanner type.
+
 ### Transaction & Audit Store (TTXDB / AuditDB)
 These tables track the lifecycle of token requests from assembly to finality. `AuditDB` uses the same schema but is isolated for compliance reporting.
 
 *   **Requests**: Tracks high-level token request state. Contains marshaled requests, current status (Pending, Confirmed, Deleted), and application/public metadata.
-*   **Transactions**: Records individual actions (Issue, Transfer, Redeem) within a request, including sender/recipient IDs and amounts.
-*   **Movements**: Aggregates net value changes per enrollment ID. Used to efficiently calculate balances and history.
+*   **Transactions**: Records individual actions (Issue, Transfer, Redeem) within a request, including sender/recipient IDs and amounts (stored as `NUMERIC(78, 0)`).
+*   **Movements**: Aggregates net value changes per enrollment ID (amounts stored as `NUMERIC(78, 0)`). Used to efficiently calculate balances and history.
 *   **Validations**: Stores cryptographic validation metadata produced during the request verification phase.
 *   **Endorsements**: Collects digital signatures from participants and auditors required for transaction finality.
 
 ### Token Store (TokenDB)
 This store serves as the authoritative registry for all tokens (UTXOs) known to the node.
 
 *   **Tokens**: The core UTXO registry. Stores token identifiers, amounts, types, ownership info, and ledger-specific state.
+    *   **Amount Storage**: Token amounts are stored as `NUMERIC(78, 0)` in the database, supporting arbitrary precision integers up to 78 digits. This enables representation of token amounts that exceed the uint64 maximum value (2^64-1 ≈ 1.8×10^19). The SDK uses Go's `*big.Int` type throughout the codebase to handle these large values, with automatic conversion between database NUMERIC values and in-memory big.Int representations.
 *   **TokenOwners**: A mapping table linking specific tokens to wallet identifiers for fast lookups.
 *   **PublicParameters**: A cache for the network's cryptographic public parameters and their hashes.
 *   **TokenCertifications**: Stores third-party certifications for tokens, often required by privacy-preserving drivers.

docs/services/storage.md

@@ -9,7 +9,6 @@ package views
 import (
 	"encoding/json"
 	"fmt"
-	"strconv"
 
 	"github.com/hyperledger-labs/fabric-smart-client/platform/common/utils/assert"
 	"github.com/hyperledger-labs/fabric-smart-client/platform/view/view"
@@ -45,7 +44,7 @@ func (b *BalanceView) Call(context view.Context) (interface{}, error) {
 		return nil, err
 	}
 
-	return Balance{Quantity: strconv.FormatUint(balance, 10), Type: b.Type}, nil
+	return Balance{Quantity: balance.String(), Type: b.Type}, nil
 }
 
 type BalanceViewFactory struct{}

integration/token/dvp/views/balance.go

@@ -7,6 +7,8 @@ SPDX-License-Identifier: Apache-2.0
 package views
 
 import (
+	"math/big"
+
 	"github.com/hyperledger-labs/fabric-smart-client/platform/common/utils/assert"
 	"github.com/hyperledger-labs/fabric-smart-client/platform/view/view"
 	"github.com/hyperledger-labs/fabric-token-sdk/token"
@@ -44,7 +46,7 @@ func (a *AcceptCashView) Call(context view.Context) (interface{}, error) {
 		}
 		balance, err := ttx.MyWallet(context, token.WithTMSID(tx.TMSID())).Balance(context.Context(), ttx.WithType(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)
+		assert.True(balance.Cmp(big.NewInt(3000)) <= 0, "cannot have more than 3000 unspent quantity for type [%s]", output.Type)
 	}
 
 	// If everything is fine, the recipient accepts and sends back her signature.

integration/token/fungible/views/accept.go

@@ -67,8 +67,8 @@ func (b *BalanceView) Call(context view.Context) (interface{}, error) {
 		if err != nil {
 			return nil, err
 		}
-		if sum.ToBigInt().Uint64() != balance {
-			return nil, errors.Errorf("balance doesn't match [%d]!=[%d]", balance, sum.ToBigInt().Uint64())
+		if sum.ToBigInt().Cmp(balance) != 0 {
+			return nil, errors.Errorf("balance doesn't match [%s]!=[%s]", balance.String(), sum.Decimal())
 		}
 	}
 

integration/token/fungible/views/balance.go

@@ -8,7 +8,6 @@ package views
 
 import (
 	"encoding/json"
-	"strconv"
 
 	"github.com/hyperledger-labs/fabric-smart-client/platform/common/utils/assert"
 	"github.com/hyperledger-labs/fabric-smart-client/platform/common/utils/collections/iterators"
@@ -67,7 +66,7 @@ func (b *BalanceView) Call(context view.Context) (interface{}, error) {
 	assert.NoError(err, "failed to compute the sum of the htlc expired tokens")
 
 	return BalanceResult{
-		Quantity: strconv.FormatUint(balance, 10),
+		Quantity: balance.String(),
 		Locked:   lockedSum.Decimal(),
 		Expired:  expiredSum.Decimal(),
 		Type:     b.Type,