Skip to content

Commit 815c16f

Browse files
zone117xzone117x
authored
feat: ft holder indexing (#2030)
* feat: stx holder indexing * feat: ft holder indexing * feat: include total supply in response * chore: cleanup debug code * chore: update ft holders endpoint
1 parent c35b65a commit 815c16f

File tree

12 files changed

+1247
-24
lines changed

12 files changed

+1247
-24
lines changed

‎docs/api/tokens/get-ft-holders.example.json

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"limit": 100,
3+
"offset": 0,
4+
"total": 3,
5+
"total_supply": "11700",
6+
"results": [
7+
{
8+
"address": "SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA2K",
9+
"balance": "10000"
10+
},
11+
{
12+
"address": "SP3WJYXJZ4QK2V5V9VX2VXVZ6VXVZ6V2V5V2V2V2V",
13+
"balance": "900"
14+
},
15+
{
16+
"address": "SP3WJYXJZ4QK2V5V9VX2VXVZ6VXVZ6V2V5V2V2V2V",
17+
"balance": "800"
18+
}
19+
]
20+
}

‎docs/api/tokens/get-ft-holders.schema.json

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"description": "List of Fungible Token holders",
3+
"title": "FungibleTokenHolderList",
4+
"type": "object",
5+
"required": [
6+
"total_supply",
7+
"results",
8+
"limit",
9+
"offset",
10+
"total"
11+
],
12+
"additionalProperties": false,
13+
"properties": {
14+
"limit": {
15+
"type": "integer",
16+
"maximum": 200,
17+
"description": "The number of holders to return"
18+
},
19+
"offset": {
20+
"type": "integer",
21+
"description": "The number to holders to skip (starting at `0`)"
22+
},
23+
"total": {
24+
"type": "integer",
25+
"description": "The number of holders available"
26+
},
27+
"total_supply": {
28+
"type": "string",
29+
"description": "The total supply of the token (the sum of all balances)"
30+
},
31+
"results": {
32+
"type": "array",
33+
"items": {
34+
"$ref": "../../entities/tokens/ft-holder-entry.schema.json"
35+
}
36+
}
37+
}
38+
}

‎docs/entities/tokens/ft-holder-entry.schema.json

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"type": "object",
3+
"title": "FtHolderEntry",
4+
"required": ["address", "balance"],
5+
"additionalProperties": false,
6+
"properties": {
7+
"address": {
8+
"type": "string"
9+
},
10+
"balance": {
11+
"type": "string"
12+
}
13+
}
14+
}

‎docs/generated.d.ts

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ export type SchemaMergeRootStub =
103103
| PoxCycleSignerStackersListResponse
104104
| PoxCycleSignersListResponse
105105
| PoxCycleListResponse
106+
| FungibleTokenHolderList
106107
| {
107108
[k: string]: unknown | undefined;
108109
}
@@ -193,6 +194,7 @@ export type SchemaMergeRootStub =
193194
| PoxCycle
194195
| PoxSigner
195196
| PoxStacker
197+
| FtHolderEntry
196198
| NonFungibleTokenHistoryEventWithTxId
197199
| NonFungibleTokenHistoryEventWithTxMetadata
198200
| NonFungibleTokenHistoryEvent
@@ -3437,6 +3439,32 @@ export interface PoxCycle {
34373439
total_stacked_amount: string;
34383440
total_signers: number;
34393441
}
3442+
/**
3443+
* List of Fungible Token holders
3444+
*/
3445+
export interface FungibleTokenHolderList {
3446+
/**
3447+
* The number of holders to return
3448+
*/
3449+
limit: number;
3450+
/**
3451+
* The number to holders to skip (starting at `0`)
3452+
*/
3453+
offset: number;
3454+
/**
3455+
* The number of holders available
3456+
*/
3457+
total: number;
3458+
/**
3459+
* The total supply of the token (the sum of all balances)
3460+
*/
3461+
total_supply: string;
3462+
results: FtHolderEntry[];
3463+
}
3464+
export interface FtHolderEntry {
3465+
address: string;
3466+
balance: string;
3467+
}
34403468
/**
34413469
* List of Non-Fungible Token history events
34423470
*/

‎docs/openapi.yaml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3678,6 +3678,38 @@ paths:
36783678
value:
36793679
$ref: ./api/tokens/get-non-fungible-token-mints-tx-metadata.example.schema.json
36803680

3681+
/extended/v1/tokens/ft/{token}/holders:
3682+
get:
3683+
operationId: get_ft_holders
3684+
summary: Fungible token holders
3685+
description: |
3686+
Retrieves the list of Fungible Token holders for a given token ID. Specify `stx` for the `token` parameter to get the list of STX holders.
3687+
tags:
3688+
- Fungible Tokens
3689+
parameters:
3690+
- name: token
3691+
in: path
3692+
description: fungible token identifier
3693+
required: true
3694+
schema:
3695+
type: string
3696+
examples:
3697+
stx:
3698+
value: stx
3699+
summary: STX token
3700+
ft:
3701+
value: SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-aeusdc::aeUSDC
3702+
summary: fungible token
3703+
responses:
3704+
200:
3705+
description: Fungible Token holders
3706+
content:
3707+
application/json:
3708+
schema:
3709+
$ref: ./api/tokens/get-ft-holders.schema.json
3710+
example:
3711+
$ref: ./api/tokens/get-ft-holders.example.json
3712+
36813713
/extended/v1/fee_rate:
36823714
post:
36833715
operationId: fetch_fee_rate

‎migrations/1720532894811_ft_balances.js

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
2+
exports.up = pgm => {
3+
pgm.createTable('ft_balances', {
4+
id: {
5+
type: 'bigserial',
6+
primaryKey: true,
7+
},
8+
address: {
9+
type: 'text',
10+
notNull: true,
11+
},
12+
token: {
13+
type: 'text',
14+
notNull: true,
15+
},
16+
balance: {
17+
type: 'numeric',
18+
notNull: true,
19+
}
20+
});
21+
22+
pgm.addConstraint('ft_balances', 'unique_address_token', `UNIQUE(address, token)`);
23+
24+
// Speeds up "grab the addresses with the highest balance for a given token" queries
25+
pgm.createIndex('ft_balances', [{ name: 'token' }, { name: 'balance', sort: 'DESC' }]);
26+
27+
// Speeds up "get the total supply of a given token" queries
28+
pgm.createIndex('ft_balances', 'token');
29+
30+
// Populate the table with the current stx balances
31+
pgm.sql(`
32+
WITH all_balances AS (
33+
SELECT sender AS address, -SUM(amount) AS balance_change
34+
FROM stx_events
35+
WHERE asset_event_type_id IN (1, 3) -- Transfers and Burns affect the sender's balance
36+
AND canonical = true AND microblock_canonical = true
37+
GROUP BY sender
38+
UNION ALL
39+
SELECT recipient AS address, SUM(amount) AS balance_change
40+
FROM stx_events
41+
WHERE asset_event_type_id IN (1, 2) -- Transfers and Mints affect the recipient's balance
42+
AND canonical = true AND microblock_canonical = true
43+
GROUP BY recipient
44+
),
45+
net_balances AS (
46+
SELECT address, SUM(balance_change) AS balance
47+
FROM all_balances
48+
GROUP BY address
49+
),
50+
fees AS (
51+
SELECT address, SUM(total_fees) AS total_fees
52+
FROM (
53+
SELECT sender_address AS address, SUM(fee_rate) AS total_fees
54+
FROM txs
55+
WHERE canonical = true AND microblock_canonical = true AND sponsored = false
56+
GROUP BY sender_address
57+
UNION ALL
58+
SELECT sponsor_address AS address, SUM(fee_rate) AS total_fees
59+
FROM txs
60+
WHERE canonical = true AND microblock_canonical = true AND sponsored = true
61+
GROUP BY sponsor_address
62+
) AS subquery
63+
GROUP BY address
64+
),
65+
rewards AS (
66+
SELECT
67+
recipient AS address,
68+
SUM(
69+
coinbase_amount + tx_fees_anchored + tx_fees_streamed_confirmed + tx_fees_streamed_produced
70+
) AS total_rewards
71+
FROM miner_rewards
72+
WHERE canonical = true
73+
GROUP BY recipient
74+
),
75+
all_addresses AS (
76+
SELECT address FROM net_balances
77+
UNION
78+
SELECT address FROM fees
79+
UNION
80+
SELECT address FROM rewards
81+
)
82+
INSERT INTO ft_balances (address, balance, token)
83+
SELECT
84+
aa.address,
85+
COALESCE(nb.balance, 0) - COALESCE(f.total_fees, 0) + COALESCE(r.total_rewards, 0) AS balance,
86+
'stx' AS token
87+
FROM all_addresses aa
88+
LEFT JOIN net_balances nb ON aa.address = nb.address
89+
LEFT JOIN fees f ON aa.address = f.address
90+
LEFT JOIN rewards r ON aa.address = r.address
91+
`);
92+
93+
// Populate the table with the current FT balances
94+
pgm.sql(`
95+
WITH all_balances AS (
96+
SELECT sender AS address, asset_identifier, -SUM(amount) AS balance_change
97+
FROM ft_events
98+
WHERE asset_event_type_id IN (1, 3) -- Transfers and Burns affect the sender's balance
99+
AND canonical = true
100+
AND microblock_canonical = true
101+
GROUP BY sender, asset_identifier
102+
UNION ALL
103+
SELECT recipient AS address, asset_identifier, SUM(amount) AS balance_change
104+
FROM ft_events
105+
WHERE asset_event_type_id IN (1, 2) -- Transfers and Mints affect the recipient's balance
106+
AND canonical = true
107+
AND microblock_canonical = true
108+
GROUP BY recipient, asset_identifier
109+
),
110+
net_balances AS (
111+
SELECT address, asset_identifier, SUM(balance_change) AS balance
112+
FROM all_balances
113+
GROUP BY address, asset_identifier
114+
)
115+
INSERT INTO ft_balances (address, balance, token)
116+
SELECT address, balance, asset_identifier AS token
117+
FROM net_balances
118+
`);
119+
120+
};
121+
122+
/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
123+
exports.down = pgm => {
124+
pgm.dropTable('ft_balances');
125+
};

‎src/api/pagination.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ export enum ResourceType {
3838
BurnBlock,
3939
Signer,
4040
PoxCycle,
41+
TokenHolders,
4142
}
4243

4344
export const pagingQueryLimits: Record<ResourceType, { defaultLimit: number; maxLimit: number }> = {
@@ -89,6 +90,10 @@ export const pagingQueryLimits: Record<ResourceType, { defaultLimit: number; max
8990
defaultLimit: 20,
9091
maxLimit: 60,
9192
},
93+
[ResourceType.TokenHolders]: {
94+
defaultLimit: 100,
95+
maxLimit: 200,
96+
},
9297
};
9398

9499
export function getPagingQueryLimit(

‎src/api/routes/tokens.ts

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { asyncHandler } from '../async-handler';
22
import * as express from 'express';
33
import {
4+
FungibleTokenHolderList,
45
NonFungibleTokenHistoryEvent,
56
NonFungibleTokenHistoryEventList,
67
NonFungibleTokenHolding,
@@ -228,5 +229,25 @@ export function createTokenRouter(db: PgStore): express.Router {
228229
})
229230
);
230231

232+
router.get(
233+
'/ft/:token/holders',
234+
cacheHandler,
235+
asyncHandler(async (req, res) => {
236+
const token = req.params.token;
237+
const limit = getPagingQueryLimit(ResourceType.TokenHolders, req.query.limit);
238+
const offset = parsePagingQueryInput(req.query.offset ?? 0);
239+
const { results, total, totalSupply } = await db.getTokenHolders({ token, limit, offset });
240+
const response: FungibleTokenHolderList = {
241+
limit: limit,
242+
offset: offset,
243+
total: total,
244+
total_supply: totalSupply,
245+
results: results,
246+
};
247+
setETagCacheHeaders(res);
248+
res.status(200).json(response);
249+
})
250+
);
251+
231252
return router;
232253
}

‎src/datastore/pg-store.ts

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3288,6 +3288,39 @@ export class PgStore extends BasePgStore {
32883288
return { found: true, result: queryResult };
32893289
}
32903290

3291+
async getTokenHolders(args: { token: string; limit: number; offset: number }): Promise<{
3292+
results: { address: string; balance: string }[];
3293+
totalSupply: string;
3294+
total: number;
3295+
}> {
3296+
const holderResults = await this.sql<
3297+
{ address: string; balance: string; count: number; total_supply: string }[]
3298+
>`
3299+
WITH totals AS (
3300+
SELECT
3301+
SUM(balance) AS total,
3302+
COUNT(*)::int AS total_count
3303+
FROM ft_balances
3304+
WHERE token = ${args.token}
3305+
)
3306+
SELECT
3307+
fb.address,
3308+
fb.balance,
3309+
ts.total AS total_supply,
3310+
ts.total_count AS count
3311+
FROM ft_balances fb
3312+
JOIN totals ts ON true
3313+
WHERE token = ${args.token}
3314+
ORDER BY balance DESC
3315+
LIMIT ${args.limit}
3316+
OFFSET ${args.offset}
3317+
`;
3318+
const results = holderResults.map(row => ({ address: row.address, balance: row.balance }));
3319+
const total = holderResults.length > 0 ? holderResults[0].count : 0;
3320+
const totalSupply = holderResults.length > 0 ? holderResults[0].total_supply : '0';
3321+
return { results, totalSupply, total };
3322+
}
3323+
32913324
/**
32923325
* Returns a list of NFTs owned by the given principal filtered by optional `asset_identifiers`,
32933326
* including optional transaction metadata.

0 commit comments

Comments
 (0)