API: add OnlineCirculation to GetSupply

daemon/algod/api/algod.oas2.json

@@ -5533,7 +5533,8 @@
         "required": [
           "online-money",
           "current_round",
-          "total-money"
+          "total-money",
+          "online-circulation"
         ],
         "properties": {
           "current_round": {
@@ -5544,6 +5545,10 @@
             "description": "OnlineMoney",
             "type": "integer"
           },
+          "online-circulation": {
+            "description": "OnlineCirculation as used by consensus, excluding expired accounts",
+            "type": "integer"
+          },
           "total-money": {
             "description": "TotalMoney",
             "type": "integer"

daemon/algod/api/algod.oas3.yml

@@ -934,6 +934,10 @@
                   "description": "Round",
                   "type": "integer"
                 },
+                "online-circulation": {
+                  "description": "OnlineCirculation as used by consensus, excluding expired accounts",
+                  "type": "integer"
+                },
                 "online-money": {
                   "description": "OnlineMoney",
                   "type": "integer"
@@ -945,6 +949,7 @@
               },
               "required": [
                 "current_round",
+                "online-circulation",
                 "online-money",
                 "total-money"
               ],
@@ -5493,6 +5498,10 @@
                       "description": "Round",
                       "type": "integer"
                     },
+                    "online-circulation": {
+                      "description": "OnlineCirculation as used by consensus, excluding expired accounts",
+                      "type": "integer"
+                    },
                     "online-money": {
                       "description": "OnlineMoney",
                       "type": "integer"
@@ -5504,6 +5513,7 @@
                   },
                   "required": [
                     "current_round",
+                    "online-circulation",
                     "online-money",
                     "total-money"
                   ],

daemon/algod/api/server/v2/handlers.go

@@ -112,6 +112,7 @@
 	LookupApplication(rnd basics.Round, addr basics.Address, aidx basics.AppIndex) (ledgercore.AppResource, error)
 	BlockCert(rnd basics.Round) (blk bookkeeping.Block, cert agreement.Certificate, err error)
 	LatestTotals() (basics.Round, ledgercore.AccountTotals, error)
+	OnlineCirculation(rnd basics.Round, voteRnd basics.Round) (basics.MicroAlgos, error)
 	BlockHdr(rnd basics.Round) (blk bookkeeping.BlockHeader, err error)
 	Wait(r basics.Round) chan struct{}
 	WaitWithCancel(r basics.Round) (chan struct{}, func())
@@ -961,14 +962,28 @@
 func (v2 *Handlers) GetSupply(ctx echo.Context) error {
 	latest, totals, err := v2.Node.LedgerForAPI().LatestTotals()
 	if err != nil {
-		err = fmt.Errorf("GetSupply(): round %d, failed: %v", latest, err)
+		err = fmt.Errorf("GetSupply(): round %d, LatestTotals failed: %v", latest, err)
+		return internalError(ctx, err, errInternalFailure, v2.Log)
+	}
+
+	params, err := v2.Node.LedgerForAPI().ConsensusParams(latest)
+	if err != nil {
+		err = fmt.Errorf("GetSupply(): round %d, ConsensusParams failed: %v", latest, err)
+		return internalError(ctx, err, errInternalFailure, v2.Log)
+	}
+
+	brnd := agreement.BalanceRound(latest, params)
+	onlineCirculation, err := v2.Node.LedgerForAPI().OnlineCirculation(brnd, latest)
+	if err != nil {
+		err = fmt.Errorf("GetSupply(): round %d, OnlineCirculation failed: %v", latest, err)
 		return internalError(ctx, err, errInternalFailure, v2.Log)
 	}
 
 	supply := model.SupplyResponse{
-		CurrentRound: uint64(latest),
-		TotalMoney:   totals.Participating().Raw,
-		OnlineMoney:  totals.Online.Money.Raw,
+		CurrentRound:      uint64(latest),
+		TotalMoney:        totals.Participating().Raw,
+		OnlineMoney:       totals.Online.Money.Raw,
+		OnlineCirculation: onlineCirculation.Raw,
 	}
 
 	return ctx.JSON(http.StatusOK, supply)

daemon/algod/api/server/v2/test/handlers_resources_test.go

@@ -154,6 +154,9 @@ func (l *mockLedger) BlockCert(rnd basics.Round) (blk bookkeeping.Block, cert ag
 func (l *mockLedger) LatestTotals() (rnd basics.Round, at ledgercore.AccountTotals, err error) {
 	panic("not implemented")
 }
+func (l *mockLedger) OnlineCirculation(rnd, voteRnd basics.Round) (basics.MicroAlgos, error) {
+	panic("not implemented")
+}
 func (l *mockLedger) BlockHdr(rnd basics.Round) (bookkeeping.BlockHeader, error) {
 	blk, err := l.Block(rnd)
 	if err != nil {

daemon/algod/api/server/v2/test/handlers_test.go

@@ -83,6 +83,11 @@ func setupMockNodeForMethodGetWithShutdown(t *testing.T, status node.StatusRepor
 	numTransactions := 1
 	offlineAccounts := true
 	mockLedger, rootkeys, _, stxns, releasefunc := testingenv(t, numAccounts, numTransactions, offlineAccounts)
+	return setupTestForMethodGetWithMockLedger(t, mockLedger, rootkeys, stxns, status, devmode, shutdown, releasefunc)
+}
+
+// setupTestForMethodGetWithMockLedger allows for providing a custom mockLedger for testing
+func setupTestForMethodGetWithMockLedger(t *testing.T, mockLedger *data.Ledger, rootkeys []account.Root, stxns []transactions.SignedTxn, status node.StatusReport, devmode bool, shutdown chan struct{}, releasefunc func()) (v2.Handlers, echo.Context, *httptest.ResponseRecorder, []account.Root, []transactions.SignedTxn, func()) {
 	mockNode := makeMockNode(mockLedger, t.Name(), nil, status, devmode)
 	handler := v2.Handlers{
 		Node:     mockNode,
@@ -544,10 +549,38 @@ func TestGetSupply(t *testing.T) {
 	partitiontest.PartitionTest(t)
 	t.Parallel()
 
-	handler, c, _, _, _, releasefunc := setupTestForMethodGet(t, cannedStatusReportGolden)
+	a := require.New(t)
+	opts := testEnvOptions{
+		numAccounts:     3,
+		numTransactions: 1,
+		offlineAccounts: true,
+		// Make one online account expire early (at round 50)
+		numExpiredOnline:     1,
+		expiredVoteLastValid: 50,
+		accountBalances:      []uint64{500_000, 300_000, 200_000},
+	}
+	mockLedger, rootkeys, _, stxns, releasefunc := testingenvWithOptions(t, opts)
+	shutdown := make(chan struct{})
+	handler, c, rec, _, _, _ := setupTestForMethodGetWithMockLedger(t, mockLedger, rootkeys, stxns, cannedStatusReportGolden, false, shutdown, releasefunc)
 	defer releasefunc()
+	insertRounds(a, handler, 375)
 	err := handler.GetSupply(c)
 	require.NoError(t, err)
+	require.Equal(t, 200, rec.Code)
+	var supplyResponse model.SupplyResponse
+	a.NoError(json.Unmarshal(rec.Body.Bytes(), &supplyResponse))
+	t.Logf("Total Money: %d, Online Money: %d, Online Circulation: %d",
+		supplyResponse.TotalMoney, supplyResponse.OnlineMoney, supplyResponse.OnlineCirculation)
+
+	a.Equal(uint64(375), supplyResponse.CurrentRound)
+	a.Equal(uint64(1_000_000), supplyResponse.TotalMoney)
+	a.Equal(uint64(800_000), supplyResponse.OnlineMoney)
+	a.Equal(uint64(300_000), supplyResponse.OnlineCirculation)
+
+	totals, err := mockLedger.Totals(basics.Round(supplyResponse.CurrentRound))
+	a.NoError(err)
+	a.Equal(totals.Participating().Raw, supplyResponse.TotalMoney)
+	a.Equal(totals.Online.Money.Raw, supplyResponse.OnlineMoney)
 }
 
 func TestGetStatus(t *testing.T) {
@@ -1130,7 +1163,14 @@ func TestSimulateTransaction(t *testing.T) {
 	// prepare node and handler
 	numAccounts := 5
 	offlineAccounts := true
-	mockLedger, roots, _, _, releasefunc := testingenvWithBalances(t, 999_998, 999_999, numAccounts, 1, offlineAccounts)
+	opts := testEnvOptions{
+		numAccounts:     numAccounts,
+		numTransactions: 1,
+		offlineAccounts: offlineAccounts,
+		minMoneyAtStart: 999_998,
+		maxMoneyAtStart: 999_999,
+	}
+	mockLedger, roots, _, _, releasefunc := testingenvWithOptions(t, opts)
 	defer releasefunc()
 	dummyShutdownChan := make(chan struct{})
 	mockNode := makeMockNode(mockLedger, t.Name(), nil, cannedStatusReportGolden, false)

daemon/algod/api/server/v2/test/helpers.go

@@ -231,13 +231,39 @@
 
 var proto = config.Consensus[protocol.ConsensusFuture]
 
+// testEnvOptions defines customizable options for the testing environment
+type testEnvOptions struct {
+	numAccounts          int      // Number of accounts to create
+	numTransactions      int      // Number of transactions to create
+	offlineAccounts      bool     // Whether to make some accounts offline
+	minMoneyAtStart      int      // Minimum starting money (used if accountBalances is nil)
+	maxMoneyAtStart      int      // Maximum starting money (used if accountBalances is nil)
+	numExpiredOnline     int      // Number of online accounts to expire early
+	expiredVoteLastValid uint64   // VoteLastValid to use for expired online accounts
+	accountBalances      []uint64 // Optional: specific balance for each account (length must match numAccounts if provided)
+}
+
 func testingenv(t testing.TB, numAccounts, numTxs int, offlineAccounts bool) (*data.Ledger, []account.Root, []account.Participation, []transactions.SignedTxn, func()) {
-	minMoneyAtStart := 100000  // min money start
-	maxMoneyAtStart := 1000000 // max money start
-	return testingenvWithBalances(t, minMoneyAtStart, maxMoneyAtStart, numAccounts, numTxs, offlineAccounts)
+	opts := testEnvOptions{
+		numAccounts:     numAccounts,
+		numTransactions: numTxs,
+		offlineAccounts: offlineAccounts,
+		minMoneyAtStart: 100000,
+		maxMoneyAtStart: 1000000,
+	}
+	return testingenvWithOptions(t, opts)
 }
 
-func testingenvWithBalances(t testing.TB, minMoneyAtStart, maxMoneyAtStart, numAccounts, numTxs int, offlineAccounts bool) (*data.Ledger, []account.Root, []account.Participation, []transactions.SignedTxn, func()) {
+// testingenvWithOptions creates a test environment with customizable options
+func testingenvWithOptions(t testing.TB, opts testEnvOptions) (*data.Ledger, []account.Root, []account.Participation, []transactions.SignedTxn, func()) {
+	numAccounts := opts.numAccounts
+	numTxs := opts.numTransactions
+	offlineAccounts := opts.offlineAccounts
+	minMoneyAtStart := opts.minMoneyAtStart
+	maxMoneyAtStart := opts.maxMoneyAtStart
+	numExpiredOnline := opts.numExpiredOnline
+	expiredVoteLastValid := opts.expiredVoteLastValid
+
 	P := numAccounts               // n accounts
 	TXs := numTxs                  // n txns
 	transferredMoney := 100        // max money/txn
@@ -284,7 +310,12 @@
 		roots[i] = root
 		parts[i] = part.Participation
 
-		startamt := basics.MicroAlgos{Raw: uint64(minMoneyAtStart + (gen.Int() % (maxMoneyAtStart - minMoneyAtStart)))}
+		var startamt basics.MicroAlgos
+		if i < len(opts.accountBalances) {
+			startamt = basics.MicroAlgos{Raw: opts.accountBalances[i]}
+		} else {
+			startamt = basics.MicroAlgos{Raw: uint64(minMoneyAtStart + (gen.Int() % (maxMoneyAtStart - minMoneyAtStart)))}
+		}
 		short := root.Address()
 
 		if offlineAccounts && i > P/2 {
@@ -293,6 +324,12 @@
 			data := basics_testing.MakeAccountData(basics.Online, startamt)
 			data.SelectionID = parts[i].VRFSecrets().PK
 			data.VoteID = parts[i].VotingSecrets().OneTimeSignatureVerifier
+			if numExpiredOnline > 0 && i < numExpiredOnline {
+				if expiredVoteLastValid == 0 {
+					expiredVoteLastValid = 50 // default if zero
+				}
+				data.VoteLastValid = basics.Round(expiredVoteLastValid)
+			}
 			genesis[short] = data
 		}
 		part.Close()