Search for online accounts

api/error_messages.go

@@ -38,6 +38,8 @@ const (
 	ErrMultipleBoxes                   = "multiple application boxes found for this app id and box name, please contact us, this shouldn't happen"
 	ErrFailedLookingUpBoxes            = "failed while looking up application boxes"
 	errMultiAcctRewind                 = "multiple accounts rewind is not supported by this server"
+	errOnlineOnlyRewind                = "simultaneously rewinding and searching for online accounts is not supported"
+	errOnlineOnlyDeleted               = "simultaneously searching for online and deleted accounts is not supported"
 	errRewindingAccount                = "error while rewinding account"
 	errLookingUpBlockForRound          = "error while looking up block for round"
 	errBlockHeaderSearch               = "error while searching for block headers"

api/handlers.go

@@ -415,6 +415,14 @@ func (si *ServerImplementation) SearchForAccounts(ctx echo.Context, params gener
 		return badRequest(ctx, errMultiAcctRewind)
 	}
 
+	// Input validations related to the "online-only" parameter
+	if params.Round != nil && boolOrDefault(params.OnlineOnly) {
+		return badRequest(ctx, errOnlineOnlyRewind)
+	}
+	if boolOrDefault(params.OnlineOnly) && boolOrDefault(params.IncludeAll) {
+		return badRequest(ctx, errOnlineOnlyDeleted)
+	}
+
 	var spendingAddrBytes []byte
 	if params.AuthAddr != nil {
 		spendingAddr, err := sdk.DecodeAddress(*params.AuthAddr)
@@ -435,6 +443,7 @@ func (si *ServerImplementation) SearchForAccounts(ctx echo.Context, params gener
 		EqualToAuthAddr:      spendingAddrBytes,
 		IncludeDeleted:       boolOrDefault(params.IncludeAll),
 		MaxResources:         si.opts.MaxAPIResourcesPerAccount,
+		OnlineOnly:           boolOrDefault(params.OnlineOnly),
 	}
 
 	if params.Exclude != nil {

api/indexer.oas2.json

@@ -81,12 +81,14 @@
           {
             "type": "integer",
             "description": "Include results for the specified round. For performance reasons, this parameter may be disabled on some configurations. Using application-id or asset-id filters will return both creator and opt-in accounts. Filtering by include-all will return creator and opt-in accounts for deleted assets and accounts. Non-opt-in managers are not included in the results when asset-id is used.",
-
             "name": "round",
             "in": "query"
           },
           {
             "$ref": "#/parameters/application-id"
+          },
+          {
+            "$ref": "#/parameters/online-only"
           }
         ],
         "responses": {
@@ -2972,6 +2974,12 @@
       "in": "query",
       "x-algorand-format": "base64"
     },
+    "online-only": {
+      "type": "boolean",
+      "description": "When this is set to true, return only accounts whose participation status is currently online.",
+      "name": "online-only",
+      "in": "query"
+    },
     "rekey-to": {
       "type": "boolean",
       "description": "Include results which include the rekey-to field.",

api/indexer.oas3.yml

@@ -221,6 +221,14 @@
         },
         "x-algorand-format": "base64"
       },
+      "online-only": {
+        "description": "When this is set to true, return only accounts whose participation status is currently online.",
+        "in": "query",
+        "name": "online-only",
+        "schema": {
+          "type": "boolean"
+        }
+      },
       "proposers": {
         "description": "Accounts marked as proposer in the block header's participation updates. This parameter accepts a comma separated list of addresses.",
         "explode": false,
@@ -2644,6 +2652,14 @@
             "schema": {
               "type": "integer"
             }
+          },
+          {
+            "description": "When this is set to true, return only accounts whose participation status is currently online.",
+            "in": "query",
+            "name": "online-only",
+            "schema": {
+              "type": "boolean"
+            }
           }
         ],
         "responses": {

idb/idb.go

@@ -304,6 +304,11 @@ type AccountQueryOptions struct {
 	// return any accounts with this auth addr
 	EqualToAuthAddr []byte
 
+	// OnlineOnly, when set to true, indicates that only accounts that are online should be returned.
+	//
+	// When set to false, this parameter is ignored (i.e. it becomes a no-op).
+	OnlineOnly bool
+
 	// Filter on accounts with current balance greater than x
 	AlgosGreaterThan *uint64
 	// Filter on accounts with current balance less than x.
@@ -326,7 +331,7 @@ type AccountQueryOptions struct {
 	// MaxResources is the maximum combined number of AppParam, AppLocalState, AssetParam, and AssetHolding objects allowed.
 	MaxResources uint64
 
-	// IncludeDeleted indicated whether to include deleted Assets, Applications, etc within the account.
+	// IncludeDeleted indicates whether to include deleted Assets, Applications, etc within the account.
 	IncludeDeleted bool
 
 	Limit uint64

idb/postgres/postgres.go

@@ -2031,6 +2031,9 @@ func (db *IndexerDb) buildAccountQuery(opts idb.AccountQueryOptions, countOnly b
 		whereArgs = append(whereArgs, encoding.Base64(opts.EqualToAuthAddr))
 		partNumber++
 	}
+	if opts.OnlineOnly {
+		whereParts = append(whereParts, "a.account_data->>'onl' IS NOT NULL and (a.account_data->>'onl') = '1'")
+	}
 	query = `SELECT a.addr, a.microalgos, a.rewards_total, a.created_at, a.closed_at, a.deleted, a.rewardsbase, a.keytype, a.account_data FROM account a`
 	if opts.HasAssetID != 0 {
 		// inner join requires match, filtering on presence of asset