Merge pull request #1105 from oasisprotocol/ptrus/feature/na-holders

api/runtime/tokens: Omit num_holders and num_transfers if unknown

Author: ptrus

.changelog/1105.feature.md

@@ -0,0 +1,4 @@
+api/runtime/tokens: Omit num_holders and num_transfers if unknown
+
+Tokens that emit no events (like BitUSD) will omit num_holders and
+num_transfers instead of returning zeroes.

analyzer/queries/queries.go

@@ -866,28 +866,30 @@ var (
 	// NOTE: Passing a 0 for last_mutate round causes that field to not be updated, effectively signalling
 	//       "this upsert does not create a need for a subsequent download of info from the EVM runtime".
 	RuntimeEVMTokenDeltaUpsert = `
-    INSERT INTO chain.evm_tokens AS old (runtime, token_address, total_supply, num_transfers, last_mutate_round)
-      VALUES ($1, $2, $3, $4, $5)
+    INSERT INTO chain.evm_tokens AS old (runtime, token_address, total_supply, num_transfers, likely_no_events, last_mutate_round)
+      VALUES ($1, $2, $3, $4, $5, $6)
     ON CONFLICT (runtime, token_address) DO UPDATE SET
       total_supply = old.total_supply + $3,
       num_transfers = old.num_transfers + $4,
-      last_mutate_round = GREATEST(old.last_mutate_round, $5)`
+      likely_no_events = excluded.likely_no_events AND old.likely_no_events,
+      last_mutate_round = GREATEST(old.last_mutate_round, $6)`
 
 	RuntimeFastSyncEVMTokenDeltaInsert = `
-    INSERT INTO todo_updates.evm_tokens AS old (runtime, token_address, total_supply, num_transfers, last_mutate_round)
-      VALUES ($1, $2, $3, $4, $5)`
+    INSERT INTO todo_updates.evm_tokens AS old (runtime, token_address, total_supply, num_transfers, likely_no_events, last_mutate_round)
+      VALUES ($1, $2, $3, $4, $5, $6)`
 
 	RuntimeEVMTokenRecompute = `
-    INSERT INTO chain.evm_tokens AS old (runtime, token_address, total_supply, num_transfers, last_mutate_round)
+    INSERT INTO chain.evm_tokens AS old (runtime, token_address, total_supply, num_transfers, likely_no_events, last_mutate_round)
     (
-      SELECT runtime, token_address, SUM(total_supply) AS total_supply, SUM(num_transfers) AS num_transfers, MAX(last_mutate_round) AS last_mutate_round
+      SELECT runtime, token_address, SUM(total_supply) AS total_supply, SUM(num_transfers) AS num_transfers, BOOL_AND(likely_no_events) AS likely_no_events, MAX(last_mutate_round) AS last_mutate_round
       FROM todo_updates.evm_tokens
       WHERE runtime = $1
       GROUP BY runtime, token_address
     )
     ON CONFLICT (runtime, token_address) DO UPDATE SET
       total_supply = old.total_supply + excluded.total_supply,
       num_transfers = old.num_transfers + excluded.num_transfers,
+      likely_no_events = old.likely_no_events AND excluded.likely_no_events,
       last_mutate_round = GREATEST(old.last_mutate_round, excluded.last_mutate_round)`
 
 	// Upserts a new EVM token with information that was downloaded from the EVM runtime (as opposed to dead-reckoned).

analyzer/runtime/runtime.go

@@ -127,6 +127,7 @@ func registerEVMTokenAddress(batch *storage.QueryBatch, runtime common.Runtime,
 		addr,
 		0,
 		0,
+		true,
 		0,
 	)
 
@@ -525,13 +526,13 @@ func (m *processor) queueDbUpdates(batch *storage.QueryBatch, data *BlockData) {
 			// In slow-sync mode, directly update or dead-reckon values.
 			batch.Queue(
 				queries.RuntimeEVMTokenDeltaUpsert,
-				m.runtime, addr, totalSupplyChange, numTransfersChange, lastMutateRound,
+				m.runtime, addr, totalSupplyChange, numTransfersChange, false, lastMutateRound,
 			)
 		} else {
 			// In fast-sync mode, just record the intent to update the values.
 			batch.Queue(
 				queries.RuntimeFastSyncEVMTokenDeltaInsert,
-				m.runtime, addr, totalSupplyChange, numTransfersChange, lastMutateRound,
+				m.runtime, addr, totalSupplyChange, numTransfersChange, false, lastMutateRound,
 			)
 		}
 	}

api/spec/v1.yaml

@@ -3626,7 +3626,7 @@ components:
 
     EvmToken:
       type: object
-      required: [contract_addr, eth_contract_addr, num_holders, type, is_verified]
+      required: [contract_addr, eth_contract_addr, type, is_verified]
       properties:
         contract_addr:
           type: string
@@ -3675,11 +3675,15 @@ components:
           format: int64
           description: |
             The total number of transfers of this token.
+
+            May be omitted if the number of transfers cannot be known (e.g. private ERC20 tokens such as BitUSD).
         num_holders:
           type: integer
           format: int64
           description: |
             The number of addresses that have a nonzero balance of this token.
+
+            May be omited if the number of holders cannot be known (e.g. private ERC20 tokens such as BitUSD).
           example: 123
         ref_swap:
           allOf: [$ref: '#/components/schemas/EvmTokenSwap']

storage/client/client.go

@@ -2251,6 +2251,7 @@ func (c *StorageClient) RuntimeTokens(ctx context.Context, runtime common.Runtim
 		var t EvmToken
 		var addrPreimage []byte
 		var tokenType common.TokenType
+		var likelyNoEvents bool
 		var refSwapPairAddr *string
 		var refSwap apiTypes.EvmTokenSwap
 		var refSwapPairEthAddr []byte
@@ -2270,6 +2271,7 @@ func (c *StorageClient) RuntimeTokens(ctx context.Context, runtime common.Runtim
 			&tokenType,
 			&t.NebyDerivedPrice,
 			&t.NumHolders,
+			&likelyNoEvents,
 			&refSwapPairAddr,
 			&refSwapPairEthAddr,
 			&refSwap.FactoryAddress,
@@ -2291,6 +2293,12 @@ func (c *StorageClient) RuntimeTokens(ctx context.Context, runtime common.Runtim
 		); err2 != nil {
 			return nil, wrapError(err2)
 		}
+		// If token emits no events (e.g. was added via `additional_evm_token_addresses` and doesn't emit events),
+		// we cannot know the number of holders or transfers, so emit those fields.
+		if likelyNoEvents {
+			t.NumHolders = nil
+			t.NumTransfers = nil
+		}
 
 		t.IsVerified = (t.VerificationLevel != nil)
 		t.EthContractAddr = EthChecksumAddrFromBarePreimage(addrPreimage)

storage/client/queries/queries.go

@@ -1221,6 +1221,7 @@ func EVMTokens(rawNames *[]string, args *[]interface{}) string {
 			tokens.token_type AS type,
 			tokens.neby_derived_price,
 			COALESCE(holders.cnt, 0) AS num_holders,
+			tokens.likely_no_events,
 			ref_swap_pair_creations.pair_address AS ref_swap_pair_address,
 			eth_preimage(ref_swap_pair_creations.pair_address) AS ref_swap_pair_address_eth,
 			ref_swap_pair_creations.factory_address AS ref_swap_factory_address,

storage/migrations/01_runtimes.up.sql

@@ -337,6 +337,10 @@ CREATE TABLE chain.evm_tokens
 
   num_transfers UINT63 NOT NULL DEFAULT 0,
 
+  -- Tokens that likely emit no events and were only added via `additional_evm_token_addresses` will have this set to TRUE.
+  -- This signals that num_transfers/num_holders values cannot be obtained.
+  -- likely_no_events BOOLEAN NOT NULL DEFAULT FALSE, -- Added in 46_runtime_evm_tokens_no_events.up.sql.
+
   -- Block analyzer bumps this when it sees the mutable fields of the token
   -- change (e.g. total supply) based on dead reckoning.
   last_mutate_round UINT63 NOT NULL DEFAULT 0,

storage/migrations/04_fast_sync_temp_tables.up.sql

@@ -26,6 +26,9 @@ CREATE TABLE todo_updates.evm_tokens( -- Tracks updates to chain.evm_tokens(last
   token_address oasis_addr NOT NULL,
   total_supply NUMERIC(1000,0) NOT NULL DEFAULT 0,
   num_transfers UINT63 NOT NULL DEFAULT 0,
+  -- Tokens that likely emit no events and were only added via `additional_evm_token_addresses` will have this set to TRUE.
+  -- This signals that num_transfers/num_holders values cannot be obtained.
+  -- likely_no_events BOOLEAN NOT NULL DEFAULT FALSE, -- Added in 46_runtime_evm_tokens_no_events.up.sql.
   last_mutate_round UINT63 NOT NULL
 );
 -- Added in 09_fast_sync_temp_transaction_status_updates.up.sql.

storage/migrations/46_runtime_evm_tokens_no_events.up.sql

@@ -0,0 +1,7 @@
+BEGIN;
+
+ALTER TABLE chain.evm_tokens ADD COLUMN IF NOT EXISTS likely_no_events BOOLEAN NOT NULL DEFAULT FALSE;
+
+ALTER TABLE todo_updates.evm_tokens ADD COLUMN IF NOT EXISTS likely_no_events BOOLEAN NOT NULL DEFAULT FALSE;
+
+COMMIT;

tests/e2e_regression/eden_2025/expected/sapphire_token_by_name.body

@@ -7,8 +7,6 @@
       "is_verified": true,
       "name": "BitUSDs",
       "neby_derived_price": "30.025448675228444259",
-      "num_holders": 0,
-      "num_transfers": 0,
       "ref_token": {
         "decimals": 18,
         "name": "Wrapped ROSE",