Skip to content

fix(explorer): fix token holder count for high-volume tokens like PathUSD #789

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
decofe wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix(explorer): fix token holder count for high-volume tokens like PathUSD #789

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8a0da45
fix(explorer): fix token holder count for high-volume tokens like Pat…
decofe Mar 27, 2026
f568d4d
fix(explorer): add pagination to handle tokens with >10k unique holders
decofe Mar 27, 2026
eaf2d02
fix(explorer): revert pagination - LIMIT/OFFSET breaks tidx CTE queries
decofe Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 97 additions & 57 deletions apps/explorer/src/lib/server/tempo-queries.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,8 @@ type QueryWithWhere<TQuery> = TQuery & {

export type TokenHolderBalance = { address: string; balance: bigint }

type TokenHolderAggregationRow = {
from: string
to: string
type HolderAggregationRow = {
holder: string
tokens: string | number | bigint
}

Expand All @@ -40,41 +39,52 @@ function sortTokenHolderBalances(
.sort((a, b) => (b.balance > a.balance ? 1 : -1))
}

function aggregateTokenHolderBalances(
rows: TokenHolderAggregationRow[],
): TokenHolderBalance[] {
const balances = new Map<string, bigint>()

for (const row of rows) {
const tokens = BigInt(row.tokens)
if (row.to !== zeroAddress) {
balances.set(row.to, (balances.get(row.to) ?? 0n) + tokens)
}
if (row.from !== zeroAddress) {
balances.set(row.from, (balances.get(row.from) ?? 0n) - tokens)
}
}

return sortTokenHolderBalances(balances)
}

/**
* Fetches holder balances using two separate queries (received / sent) grouped
* by individual holder address instead of the (from, to) pair. This keeps the
* row count proportional to unique holders rather than unique transfer pairs,
* avoiding truncation by tidx's 10 000-row hard limit on high-volume tokens.
*/
export async function fetchTokenHolderBalances(
address: Address.Address,
chainId: number,
): Promise<TokenHolderBalance[]> {
const qb = QB(chainId).withSignatures([TRANSFER_SIGNATURE])
const transfers = (await qb
.selectFrom('transfer')
.select((eb) => [
eb.ref('from').as('from'),
eb.ref('to').as('to'),
eb.fn.sum('tokens').as('tokens'),
])
.where('address', '=', address)
.groupBy(['from', 'to'])
.execute()) as TokenHolderAggregationRow[]

return aggregateTokenHolderBalances(transfers)
const [receivedRows, sentRows] = await Promise.all([
qb
.selectFrom('transfer')
.select((eb) => [
eb.ref('to').as('holder'),
eb.fn.sum('tokens').as('tokens'),
])
.where('address', '=', address)
.where('to', '!=', zeroAddress)
.groupBy(['to'])
.execute() as Promise<HolderAggregationRow[]>,
qb
.selectFrom('transfer')
.select((eb) => [
eb.ref('from').as('holder'),
eb.fn.sum('tokens').as('tokens'),
])
.where('address', '=', address)
.where('from', '!=', zeroAddress)
.groupBy(['from'])
.execute() as Promise<HolderAggregationRow[]>,
])

const balances = new Map<string, bigint>()
for (const row of receivedRows) {
const holder = row.holder.toLowerCase()
balances.set(holder, (balances.get(holder) ?? 0n) + BigInt(row.tokens))
}
for (const row of sentRows) {
const holder = row.holder.toLowerCase()
balances.set(holder, (balances.get(holder) ?? 0n) - BigInt(row.tokens))
}

return sortTokenHolderBalances(balances)
}

export async function fetchTokenHoldersCountRows(
Expand All @@ -85,42 +95,72 @@ export async function fetchTokenHoldersCountRows(
if (addresses.length === 0) return []

const qb = QB(chainId).withSignatures([TRANSFER_SIGNATURE])
const transfers = (await qb
.selectFrom('transfer')
.select((eb) => [
eb.ref('address').as('address'),
eb.ref('from').as('from'),
eb.ref('to').as('to'),
eb.fn.sum('tokens').as('tokens'),
])
.where('address', 'in', addresses)
.groupBy(['address', 'from', 'to'])
.execute()) as Array<{
address: string
from: string
to: string
tokens: string | number | bigint
}>

const [receivedRows, sentRows] = await Promise.all([
qb
.selectFrom('transfer')
.select((eb) => [
eb.ref('address').as('address'),
eb.ref('to').as('holder'),
eb.fn.sum('tokens').as('tokens'),
])
.where('address', 'in', addresses)
.where('to', '!=', zeroAddress)
.groupBy(['address', 'to'])
.execute() as Promise<
Array<{
address: string
holder: string
tokens: string | number | bigint
}>
>,
qb
.selectFrom('transfer')
.select((eb) => [
eb.ref('address').as('address'),
eb.ref('from').as('holder'),
eb.fn.sum('tokens').as('tokens'),
])
.where('address', 'in', addresses)
.where('from', '!=', zeroAddress)
.groupBy(['address', 'from'])
.execute() as Promise<
Array<{
address: string
holder: string
tokens: string | number | bigint
}>
>,
])

const balancesByToken = new Map<string, Map<string, bigint>>()

for (const row of transfers) {
for (const row of receivedRows) {
const token = row.address.toLowerCase()
let tokenBalances = balancesByToken.get(token)
if (!tokenBalances) {
tokenBalances = new Map<string, bigint>()
balancesByToken.set(token, tokenBalances)
}
const holder = row.holder.toLowerCase()
tokenBalances.set(
holder,
(tokenBalances.get(holder) ?? 0n) + BigInt(row.tokens),
)
}

const tokens = BigInt(row.tokens)
if (row.to !== zeroAddress) {
const to = row.to.toLowerCase()
tokenBalances.set(to, (tokenBalances.get(to) ?? 0n) + tokens)
}
if (row.from !== zeroAddress) {
const from = row.from.toLowerCase()
tokenBalances.set(from, (tokenBalances.get(from) ?? 0n) - tokens)
for (const row of sentRows) {
const token = row.address.toLowerCase()
let tokenBalances = balancesByToken.get(token)
if (!tokenBalances) {
tokenBalances = new Map<string, bigint>()
balancesByToken.set(token, tokenBalances)
}
const holder = row.holder.toLowerCase()
tokenBalances.set(
holder,
(tokenBalances.get(holder) ?? 0n) - BigInt(row.tokens),
)
}

return addresses.map((address) => {
Expand Down
35 changes: 10 additions & 25 deletions apps/explorer/test/tempo-queries.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -330,18 +330,13 @@ describe('tempo-queries', () => {

it('fetchTokenHolderBalances aggregates holders from raw transfer rows', async () => {
mockQueryBuilder.setResponses([
// received query (GROUP BY to)
[
{
from: '0x0000000000000000000000000000000000000000',
to: '0xaaaa',
tokens: '10',
},
{
from: '0xaaaa',
to: '0xbbbb',
tokens: '4',
},
{ holder: '0xaaaa', tokens: '10' },
{ holder: '0xbbbb', tokens: '4' },
],
// sent query (GROUP BY from)
[{ holder: '0xaaaa', tokens: '4' }],
])

await expect(
Expand All @@ -354,23 +349,13 @@ describe('tempo-queries', () => {

it('fetchTokenHolderBalances aggregates incoming and outgoing balances', async () => {
mockQueryBuilder.setResponses([
// received query (GROUP BY to)
[
{
from: '0x1111',
to: '0x0000000000000000000000000000000000000000',
tokens: '5',
},
{
from: '0x0000000000000000000000000000000000000000',
to: '0x1111',
tokens: '10',
},
{
from: '0x0000000000000000000000000000000000000000',
to: '0x2222',
tokens: '3',
},
{ holder: '0x1111', tokens: '10' },
{ holder: '0x2222', tokens: '3' },
],
// sent query (GROUP BY from)
[{ holder: '0x1111', tokens: '5' }],
])

const balances = await fetchTokenHolderBalances(
Expand Down
Loading