建鏈上持有人查詢系統(tǒng)（HolderLookup）的完整指南)
做鏈上數(shù)據(jù)這塊三年多我越來(lái)越覺(jué)得HolderLookup這種看著不起眼的小工具才是真正卡脖子的剛需。所謂HolderLookup簡(jiǎn)單說(shuō)就是輸入一個(gè)代幣合約地址或者一個(gè)錢包地址你能立刻拿到答案——這個(gè)代幣到底有多少持有人頭部地址持倉(cāng)占比多少某個(gè)地址什么時(shí)候買入、現(xiàn)在還拿著多少它解決的痛點(diǎn)非常具體空投資格核對(duì)、鏈上風(fēng)控篩查、巨鯨動(dòng)向跟蹤、社區(qū)活動(dòng)防刷隨便挑一個(gè)出來(lái)沒(méi)有這類能力都得手工翻區(qū)塊干到懷疑人生。這篇文章不聊理論就從一個(gè)真實(shí)做過(guò)的項(xiàng)目出發(fā)把整套HolderLookup從需求拆解、技術(shù)選型、數(shù)據(jù)模型、索引實(shí)現(xiàn)到常見坑位的完整流程一條龍講清楚。適合三類人看想在項(xiàng)目里快速落地持有人查詢的開發(fā)者、需要做鏈上盡調(diào)的分析師、以及被為什么這個(gè)地址持有量對(duì)不上折磨的運(yùn)營(yíng)同學(xué)。1. 為什么一定要做一個(gè)HolderLookup1.1 我碰到的真實(shí)場(chǎng)景事情起源于一次空投核對(duì)。當(dāng)時(shí)項(xiàng)目方給了我一萬(wàn)兩千個(gè)白名單地址要求篩選出真正持有治理代幣超過(guò)1000枚的錢包還要排除掉交易所熱錢包和黑洞地址。我第一反應(yīng)是直接用區(qū)塊瀏覽器的導(dǎo)出功能結(jié)果試了才知道Etherscan這類工具單次導(dǎo)出上限就卡得死死的而且只會(huì)給你Top持有者中長(zhǎng)尾地址根本導(dǎo)不全。挨個(gè)調(diào)balanceOf更不現(xiàn)實(shí)上萬(wàn)次RPC請(qǐng)求打到節(jié)點(diǎn)上人家沒(méi)封你號(hào)也得把你限流到懷疑人生。后來(lái)我就想明白了這類需求不能靠臨時(shí)腳本湊得有一套正經(jīng)的查詢系統(tǒng)。于是HolderLookup這個(gè)項(xiàng)目就立項(xiàng)了。它不是一個(gè)花哨的DApp也不是什么復(fù)雜協(xié)議就是一個(gè)非常務(wù)實(shí)的數(shù)據(jù)管道——把鏈上分散的ERC-20/ERC-721轉(zhuǎn)賬事件匯聚起來(lái)重建成每個(gè)地址現(xiàn)在持有什么、持有多少、從什么時(shí)候開始持有的完整視圖。做完了以后不僅空投核對(duì)變成了秒級(jí)操作團(tuán)隊(duì)里做風(fēng)控的同事、做社區(qū)的運(yùn)營(yíng)、甚至我自己做競(jìng)品分析全都開始依賴這套數(shù)據(jù)。1.2 核心功能拆解一個(gè)查詢系統(tǒng)到底要查什么立項(xiàng)之前我先把HolderLookup這個(gè)詞拆成了五個(gè)子功能避免一開始就把系統(tǒng)做飛全量持有者列表給定代幣合約返回所有非零余額地址附帶持倉(cāng)數(shù)量、占比、最后變動(dòng)區(qū)塊。單地址持倉(cāng)查詢給定錢包地址返回它在某個(gè)代幣里的余額、歷史充值/轉(zhuǎn)出記錄。持倉(cāng)排名與分布按余額倒序輸出并聚合出前10地址占總供應(yīng)比例這類指標(biāo)。地址畫像分類判斷目標(biāo)地址是合約地址、多簽合約、交易所冷錢包還是普通EOA用標(biāo)簽輔助風(fēng)控判斷。歷史快照對(duì)比記錄每個(gè)區(qū)塊高度下的持倉(cāng)快照回答昨天這個(gè)地址還有沒(méi)有貨。最終整個(gè)系統(tǒng)對(duì)外只暴露一個(gè)極簡(jiǎn)接口傳參代幣地址和可選的錢包地址回來(lái)一行結(jié)構(gòu)化的JSON其余所有復(fù)雜度都收斂在內(nèi)部。這里最大的設(shè)計(jì)原則是查詢時(shí)必須快索引階段可以慢。1.3 輸入什么、輸出什么先定好契約再寫代碼做這類工具最忌諱邊寫邊想所以我先定了輸入輸出契約后面所有模塊都圍著一份契約開發(fā)輸入輸出備注token_address代幣基礎(chǔ)信息符號(hào)、精度、總供應(yīng)從合約只讀方法抓取緩存token_addresspagination持有者列表{address, balance, share}按余額降序游標(biāo)翻頁(yè)wallet_addresstoken_address該地址當(dāng)前余額 最后變動(dòng)區(qū)塊實(shí)時(shí)校驗(yàn)不依賴本地索引wallet_address該地址所有代幣持倉(cāng)匯總多合約聚合屬于進(jìn)階模塊這個(gè)表格看著簡(jiǎn)單但它是整個(gè)項(xiàng)目的錨點(diǎn)。后面所有代碼、表結(jié)構(gòu)、API文檔都圍繞它寫避免做到一半突然加需求。我吃過(guò)這個(gè)虧一開始想直接做鏈上監(jiān)控大屏結(jié)果連最基礎(chǔ)的查詢都沒(méi)磨圓最后返工了兩次才穩(wěn)定。所以勸你一句話——先把查詢做扎實(shí)可視化永遠(yuǎn)是錦上添花。2. 整體設(shè)計(jì)與技術(shù)選型不迷信一步到位的方案2.1 先搞明白鏈上持倉(cāng)數(shù)據(jù)到底存在哪里很多剛接觸鏈上數(shù)據(jù)的人有個(gè)誤區(qū)以為調(diào)用一次balanceOf數(shù)據(jù)就像數(shù)據(jù)庫(kù)一樣躺在某個(gè)表里。實(shí)際上EVM世界里沒(méi)有一張持有量表擺在那兒給你查。鏈上只存了一份全局狀態(tài)樹state trie里面確實(shí)記錄著每個(gè)地址的余額映射但你要理解這個(gè)映射是結(jié)果不是賬本。賬本是一長(zhǎng)串Transfer事件散落在成千上萬(wàn)個(gè)區(qū)塊的日志里。我自己的比喻是這樣區(qū)塊鏈?zhǔn)且槐局蛔芳拥牧魉~每一頁(yè)區(qū)塊記著誰(shuí)給誰(shuí)轉(zhuǎn)了多少錢。至于張三現(xiàn)在總共有多少錢賬本上沒(méi)寫得你把所有涉及張三的記錄都翻一遍、加減出來(lái)。balanceOf之所以能秒回是因?yàn)楣?jié)點(diǎn)幫你把賬本實(shí)時(shí)匯總成了余額快照但它只能回答當(dāng)前是多少回答不了有哪些人持有他們各自持有了多久。這就道出了HolderLookup的本質(zhì)它不是讀一個(gè)字段而是在重建一本持有人總賬。你只能通過(guò)解析歷史Transfer事件自己構(gòu)建并持續(xù)維護(hù)一張關(guān)系表——address - token - balance。想通了這一點(diǎn)后面所有技術(shù)選型都圍繞如何高效回放事件流展開。2.2 三種數(shù)據(jù)獲取方案的對(duì)比確定了方向下一步就是怎么拿到這些事件。我整理了三種主路徑各有取舍方案優(yōu)點(diǎn)缺點(diǎn)適合場(chǎng)景直接RPC輪詢eth_getLogs無(wú)額外依賴、可控性最高容易觸發(fā)節(jié)點(diǎn)限流、歷史深查慢中小型代幣、初期開發(fā)驗(yàn)證使用索引服務(wù)快照The Graph等查詢快、數(shù)據(jù)結(jié)構(gòu)化、文檔齊全需要學(xué)一套新DSL、托管成本數(shù)據(jù)量中等、團(tuán)隊(duì)愿意引入新基建第三方區(qū)塊瀏覽器API接入最快、無(wú)需自建索引配額低、數(shù)據(jù)口徑不透明原型驗(yàn)證、低頻查詢我最后采用的是混合架構(gòu)主索引用RPC輪詢自建同時(shí)用索引服務(wù)的解析結(jié)果做交叉校驗(yàn)。原因有三一是自建管道數(shù)據(jù)口徑完全可控二是RPC輪詢成本最低三是不想把整個(gè)項(xiàng)目押在一個(gè)第三方服務(wù)上。這里有一個(gè)很重要的心得數(shù)據(jù)管道一定要有自愈能力不能因?yàn)槟硞€(gè)外部依賴抽風(fēng)就全盤癱瘓所以核心索引器必須能用最原始的RPC重新拉起來(lái)。2.3 系統(tǒng)架構(gòu)三層職責(zé)分離整個(gè)HolderLookup拆成三層互相之間通過(guò)消息解耦這個(gè)架構(gòu)后來(lái)被證明非?？冈鞌?shù)據(jù)層負(fù)責(zé)同步、解析、存儲(chǔ)Transfer事件。主要由一個(gè)調(diào)度器控制它決定下一批該拉哪個(gè)區(qū)塊區(qū)間把解析好的事件批量寫入數(shù)據(jù)庫(kù)。計(jì)算層負(fù)責(zé)把裸事件轉(zhuǎn)成業(yè)務(wù)數(shù)據(jù)。核心任務(wù)就是跑一條聚合SQL把相同from地址扣減余額、相同to地址增加余額最后過(guò)濾掉零余額地址生成當(dāng)前“持有人表”。服務(wù)層面向查詢方提供API只做三件事讀緩存查數(shù)據(jù)庫(kù)必要時(shí)回源RPC實(shí)時(shí)校驗(yàn)。堅(jiān)決不做重計(jì)算。用這套架構(gòu)的好處非常直接查詢層永遠(yuǎn)只碰持久化后的干凈數(shù)據(jù)不碰節(jié)點(diǎn)計(jì)算層可以定時(shí)重算也可以按需重算數(shù)據(jù)層則只用關(guān)心吞吐量不用操心業(yè)務(wù)口徑。三個(gè)層各干各的任何一層出問(wèn)題都能獨(dú)立回滾。實(shí)際做起來(lái)你甚至?xí)杏X(jué)像在搭建一條小型實(shí)時(shí)數(shù)倉(cāng)用的全是數(shù)據(jù)庫(kù)和消息隊(duì)列的常見套路完全沒(méi)有必要引入什么重型框架。3. 實(shí)操實(shí)現(xiàn)一步一步跑通HolderLookup3.1 定義數(shù)據(jù)模型一切從一張表開始動(dòng)手寫代碼前先把表結(jié)構(gòu)定好。我的核心表長(zhǎng)這樣CREATE TABLE transfer_events ( id BIGSERIAL PRIMARY KEY, token_address CHAR(42) NOT NULL, from_address CHAR(42) NOT NULL, to_address CHAR(42) NOT NULL, raw_value NUMERIC NOT NULL, block_number BIGINT NOT NULL, tx_hash CHAR(66) NOT NULL, log_index INT NOT NULL, UNIQUE (tx_hash, log_index) ); CREATE INDEX idx_transfer_token_block ON transfer_events (token_address, block_number); CREATE INDEX idx_transfer_from ON transfer_events (from_address, token_address); CREATE INDEX idx_transfer_to ON transfer_events (to_address, token_address);注意raw_value字段我存的是原始整數(shù)不帶精度轉(zhuǎn)換。原因很簡(jiǎn)單decimal和NUMERIC在數(shù)據(jù)庫(kù)里處理起來(lái)更精確但一旦涉及精度換算不同代幣的decimals還不一樣先把原始值存住展示層再統(tǒng)一除以10^decimals這樣最保險(xiǎn)。還要說(shuō)明一個(gè)設(shè)計(jì)細(xì)節(jié)為什么我不直接建一張最終余額表因?yàn)樽罱K余額可以被事件流隨時(shí)重算而歷史事件是不可變的審計(jì)證據(jù)。建一張holders表當(dāng)然也可以但我選擇在查詢時(shí)聚合事件表每次跑完再物化到緩存。這樣既能追溯又不犧牲查詢性能。對(duì)于數(shù)據(jù)量特別大的項(xiàng)目你完全可以用物化視圖或者預(yù)聚合表原理是一樣的。3.2 寫索引器監(jiān)聽每一條Transfer事件索引器是整條管道的發(fā)動(dòng)機(jī)。我用的技術(shù)棧是Python web3.py配合PostgreSQL整體邏輯可以縮成一段核心循環(huán)from web3 import Web3 from web3.middleware import geth_poa_middleware RPC_URL 你的節(jié)點(diǎn)RPC地址 CONTRACT_ADDRESS 0x你的代幣合約地址 w3 Web3(Web3.HTTPProvider(RPC_URL)) w3.middleware_onion.inject(geth_poa_middleware, layer0) TRANSFER_TOPIC w3.keccak(textTransfer(address,address,uint256)).hex() # 上一次同步到的區(qū)塊高度真實(shí)項(xiàng)目里應(yīng)持久化比如存redis或數(shù)據(jù)庫(kù) last_synced_block 20000000 latest_block w3.eth.block_number CHUNK 5000 # 單次拉取范圍不能太大后面講為什么 def process_block_range(start, end): logs w3.eth.get_logs({ fromBlock: start, toBlock: end, address: Web3.to_checksum_address(CONTRACT_ADDRESS), topics: [TRANSFER_TOPIC] }) parsed [] for log in logs: # topics: [0]是事件簽名, [1]是from, [2]是to _from Web3.to_checksum_address(log[topics][1].hex()[-40:]) _to Web3.to_checksum_address(log[topics][2].hex()[-40:]) value int(log[data].hex(), 16) parsed.append((CONTRACT_ADDRESS, _from, _to, value, log[blockNumber], log[transactionHash].hex(), log[logIndex])) return parsed # 主循環(huán)示意 while last_synced_block latest_block: end min(last_synced_block CHUNK, latest_block) batch process_block_range(last_synced_block 1, end) # 批量寫入數(shù)據(jù)庫(kù)execute_values last_synced_block end有幾個(gè)細(xì)節(jié)必須說(shuō)透。get_logs的topics參數(shù)是過(guò)濾的靈魂只傳TRANSFER_TOPIC就表示“只要Transfer事件”返回的數(shù)據(jù)里每條log的topics[1]是轉(zhuǎn)出方、topics[2]是接收方值在data里。之所以要.hex()[-40:]再?gòu)臉?biāo)準(zhǔn)地址恢復(fù)是因?yàn)樗饕灻锏刂肥亲筇畛涞?2字節(jié)不截?cái)鄷?huì)解析出幽靈地址。分塊區(qū)間CHUNK為什么設(shè)5000公共節(jié)點(diǎn)對(duì)單次get_logs能掃描的區(qū)塊范圍有限制有的服務(wù)商限定10000塊有的更小。塊區(qū)間太大可能直接報(bào)錯(cuò)query returned too many results太小又浪費(fèi)請(qǐng)求。5000對(duì)我來(lái)說(shuō)是一個(gè)平衡點(diǎn)速度可接受限流概率低。還有一個(gè)坑必須把last_synced_block持久化到數(shù)據(jù)庫(kù)或者Redis否則進(jìn)程一重啟你又得從頭掃。別問(wèn)我怎么知道的。3.3 實(shí)現(xiàn)實(shí)時(shí)查詢先打緩存再回源校驗(yàn)索引器補(bǔ)上了歷史賬本但鏈上每秒都在產(chǎn)生新交易你的表永遠(yuǎn)會(huì)晚幾秒。為了做到真正的實(shí)時(shí)我的查詢層故意做了一步回源校驗(yàn)def get_holder_balance(token_address, wallet_address, blocklatest): # 1. 先查本地聚合數(shù)據(jù) local_balance query_local_balance(token_address, wallet_address) # 2. 再通過(guò)節(jié)點(diǎn)實(shí)時(shí)確認(rèn) contract w3.eth.contract( addressWeb3.to_checksum_address(token_address), abiERC20_ABI ) onchain_balance contract.functions.balanceOf( Web3.to_checksum_address(wallet_address) ).call(block_identifierblock) # 3. 本地落后時(shí)以鏈上為準(zhǔn)同時(shí)觸發(fā)一次增量索引補(bǔ)拉 if local_balance ! onchain_balance: trigger_incremental_index(wallet_address) return onchain_balance這里的關(guān)鍵是contract.functions.balanceOf(...).call()這其實(shí)是節(jié)點(diǎn)在內(nèi)部狀態(tài)樹上做的查詢不走事件日志速度極快。但凡是查當(dāng)前余額我永遠(yuǎn)以鏈上為準(zhǔn)本地索引只用于批量場(chǎng)景和排行榜。如果本地和鏈上不一致說(shuō)明增量同步還在追塊流程自然退避重試就好。另外要強(qiáng)調(diào)一個(gè)進(jìn)階點(diǎn)call()可以傳block_identifier參數(shù)。你可以查歷史任意區(qū)塊高度下的余額比如實(shí)現(xiàn)這個(gè)地址在空投快照那一刻到底持有了多少。這一招在做空投活動(dòng)資格判定時(shí)太有用了因?yàn)楹芏囗?xiàng)目方是按區(qū)塊高度快照的不是按當(dāng)前時(shí)間快照的。3.4 聚合排序與去重合并核心SQL的表演時(shí)刻把幾百萬(wàn)條Transfer事件變成持有人表靠手工遍歷完全不現(xiàn)實(shí)必須交給數(shù)據(jù)庫(kù)聚合。我的核心查詢長(zhǎng)這樣WITH balance_calc AS ( SELECT address, SUM(value) AS balance FROM ( SELECT from_address AS address, -raw_value AS value FROM transfer_events WHERE token_address $1 UNION ALL SELECT to_address AS address, raw_value AS value FROM transfer_events WHERE token_address $1 ) t GROUP BY address ) SELECT address, balance / 10^decimals AS display_balance, ROUND(balance / total_supply * 100, 4) AS share_percent FROM balance_calc, token_meta WHERE balance 0 ORDER BY balance DESC LIMIT $2 OFFSET $3;這個(gè)查詢的妙處在于把轉(zhuǎn)出和轉(zhuǎn)入編碼成正負(fù)值拼在一起再按地址分組求和。數(shù)據(jù)庫(kù)層面會(huì)并行處理性能比你在Python里一層層循環(huán)不知道高多少。但有個(gè)大坑銷毀burn常見但部分代幣不是通過(guò)Transfer(address, 0x00)銷毀而是直接改合約里某個(gè)特殊變量。這種情況下聚合查詢會(huì)高估總供應(yīng)。我自己踩過(guò)之后養(yǎng)成一個(gè)習(xí)慣每個(gè)代幣接入前先拉一批歷史快照和區(qū)塊瀏覽器的持有者數(shù)據(jù)做交叉驗(yàn)證如果偏差超過(guò)0.01%立刻人工審查事件表看看是不是存在沒(méi)走標(biāo)準(zhǔn)Transfer事件的余額變動(dòng)。把對(duì)賬前置后面所有結(jié)論才立得住。3.5 緩存層別讓數(shù)據(jù)庫(kù)做它不該做的事查詢接口上線后第一個(gè)被壓垮的是數(shù)據(jù)庫(kù)。排行榜接口要跑一次全表聚合疊加并發(fā)以后直接把連接池打滿。我的解決方案是引入Redis做兩層緩存第一層熱榜緩存。Top100持有者排名每小時(shí)刷新一次key形如holder_rank:top100:{token_address}TTL設(shè)為1小時(shí)。第二層單地址緩存。holder:single:{token_address}:{wallet_address}TTL設(shè)為30秒。30秒這個(gè)窗口對(duì)于大多數(shù)場(chǎng)景足夠新鮮又不會(huì)頻繁失效。實(shí)踐下來(lái)這套緩存配合索引器的預(yù)聚合讓排行榜接口從平均800ms降到10ms以內(nèi)數(shù)據(jù)庫(kù)負(fù)載下降了60%。不過(guò)緩存也帶來(lái)了一個(gè)有意思的新問(wèn)題空投快照時(shí)項(xiàng)目方往往要求準(zhǔn)確到特定區(qū)塊高度緩存里的數(shù)據(jù)做不到。所以我又加了一個(gè)邏輯——凡是帶block_number參數(shù)的查詢一律走數(shù)據(jù)庫(kù)或RPC實(shí)時(shí)計(jì)算直接繞過(guò)Redis。底層的原則很簡(jiǎn)單緩存只服務(wù)當(dāng)前最新場(chǎng)景歷史場(chǎng)景永遠(yuǎn)實(shí)時(shí)。3.6 對(duì)外輸出JSON接口與CSV導(dǎo)出系統(tǒng)最終收斂成兩個(gè)出口。第一是HTTP JSON面向前端和自動(dòng)化腳本{ token: 0x..., block_height: 20123456, total_holders: 12738, holders: [ { address: 0xabc..., balance: 1000000000000000000000, display_balance: 1000.00, share_percent: 2.34, source: indexed } ], next_cursor: 0xdef... }第二是CSV導(dǎo)出給運(yùn)營(yíng)同學(xué)用。這個(gè)需求是真實(shí)存在的運(yùn)營(yíng)拿著數(shù)據(jù)去查重、對(duì)白名單如果還指望他們看懂JSON就太天真了。我做了一個(gè)后臺(tái)任務(wù)把查詢結(jié)果異步轉(zhuǎn)成CSV傳到對(duì)象存儲(chǔ)后回一條下載鏈接。這個(gè)功能看著沒(méi)什么技術(shù)含量卻成了整個(gè)項(xiàng)目里被夸得最多的功能——在工業(yè)界混久了你就知道能輸出Excel才是真的生產(chǎn)力。4. 上線后的坑HolderLookup最常見的問(wèn)題排查實(shí)錄4.1 持有人數(shù)量和區(qū)塊瀏覽器對(duì)不上怎么辦幾乎每個(gè)接入HolderLookup的人都會(huì)問(wèn)我同一個(gè)問(wèn)題為什么我拉出來(lái)的持有人數(shù)是8000可區(qū)塊瀏覽器上顯示是12000這里的水很深。最大的原因在于口徑區(qū)塊瀏覽器的持有人數(shù)通常包含內(nèi)部轉(zhuǎn)賬、批量空投分發(fā)器、鎖定合約、甚至零余額但仍在白名單里的地址。而我默認(rèn)只統(tǒng)計(jì)非零余額的EOA和合約地址。所以不是系統(tǒng)算錯(cuò)了而是兩邊統(tǒng)計(jì)口徑不一樣。我的建議是不去猜直接查。具體做法先對(duì)比前100地址是否一致如果頭部對(duì)得上基本可以確認(rèn)是尾部統(tǒng)計(jì)口徑問(wèn)題如果頭部都對(duì)不上那就要檢查索引是不是漏塊了。驗(yàn)證漏塊很簡(jiǎn)單取某一個(gè)已知地址比對(duì)它的balanceOf實(shí)時(shí)值和聚合值差異一旦超過(guò)0基本就是增量同步滯后。千萬(wàn)不要盲目調(diào)數(shù)據(jù)先校準(zhǔn)你的統(tǒng)計(jì)定義。4.2 Transfer事件不一定是真的轉(zhuǎn)賬成功還有一種隱蔽情況某些代幣合約在transfer函數(shù)里會(huì)revert但之前已經(jīng)發(fā)出過(guò)Transfer事件。鏈上交易的日志一旦交易失敗整個(gè)receipt回滾日志也不會(huì)存在。但如果合約寫得花哨在內(nèi)部調(diào)用子合約的transfer時(shí)會(huì)發(fā)出事件而子合約調(diào)用失敗后錯(cuò)誤被吞掉外層交易卻成功了——這種幽靈事件雖然少見但確實(shí)存在。排查手段是解析事件時(shí)順帶記錄receipt.status只信任status 1的交易日志。def is_tx_success(tx_hash): receipt w3.eth.get_transaction_receipt(tx_hash) return receipt[status] 1這個(gè)檢查有額外RPC開銷所以我只在索引器里加了抽樣校驗(yàn)邏輯每1000條事件抽1條驗(yàn)證狀態(tài)抽樣異常率超過(guò)閾值時(shí)切到全量校驗(yàn)?zāi)Ｊ?。這樣一個(gè)輕量兜底既不會(huì)拖慢同步又能防止被半路殺出的奇怪合約坑到。4.3 區(qū)塊高度斷層與分叉回滾區(qū)塊鏈偶爾會(huì)發(fā)生短期分叉reorg導(dǎo)致你同步的日志在某一個(gè)高度上突然多了一段或少了一段。我的處理策略是索引器里永遠(yuǎn)記錄最近1000個(gè)區(qū)塊的哈希定時(shí)和節(jié)點(diǎn)當(dāng)前區(qū)塊哈希做比對(duì)一旦發(fā)現(xiàn)某個(gè)高度哈希不一致就把該高度之后的本地事件全部清理掉重新拉取。這套回滾再同步邏輯看起來(lái)簡(jiǎn)單但它是整個(gè)數(shù)據(jù)一致性的最后一道防線。早期我沒(méi)做這個(gè)結(jié)果排行榜數(shù)據(jù)差了一截排查了三個(gè)小時(shí)才發(fā)現(xiàn)是凌晨有一次深度重組。4.4 游標(biāo)翻頁(yè)的性能陷阱別用OFFSET持有人列表一多千萬(wàn)不要用OFFSET翻頁(yè)。MySQL/PostgreSQL在OFFSET 8000這種位置時(shí)仍然會(huì)掃描前面的全部行越翻越慢前端會(huì)明顯卡頓。換成鍵集分頁(yè)keyset pagination以后性能直接起飛WHERE (balance, address) ($balance, $address) ORDER BY balance DESC, address DESC LIMIT 100這個(gè)寫法的原理是利用數(shù)據(jù)庫(kù)索引天然排序的特性永遠(yuǎn)從上一頁(yè)最后一條的位置繼續(xù)向后讀不需要掃描跳過(guò)的行。配合之前建好的(balance, address)復(fù)合索引翻頁(yè)再深也能保持穩(wěn)定時(shí)延。這類細(xì)節(jié)雖然不起眼但高流量接口靠的就是這些刁鉆優(yōu)化。4.5 節(jié)點(diǎn)RPC限流指數(shù)退避是最低要求做索引器經(jīng)常遇到的問(wèn)題就是拉著拉著節(jié)點(diǎn)不鳥你了。公共RPC節(jié)點(diǎn)通常用速率限制保護(hù)服務(wù)eth_getLogs又是重請(qǐng)求很容易觸發(fā)。我的經(jīng)驗(yàn)是三層防護(hù)請(qǐng)求之間加固定間隔比如50ms命中429錯(cuò)誤時(shí)用指數(shù)退避等待1秒、2秒、4秒……直到恢復(fù)給不同RPC節(jié)點(diǎn)配置做故障轉(zhuǎn)移比如同時(shí)配兩個(gè)以上的端點(diǎn)一個(gè)報(bào)錯(cuò)立刻切換。再補(bǔ)一個(gè)小技巧熱門代幣的Transfer事件量極大單次get_logs很容易因?yàn)榉祷厝罩咎嘀苯訄?bào)錯(cuò)。這種情況下把區(qū)塊范圍繼續(xù)拆小拆到單次返回不超過(guò)5000條日志為止。寧可多發(fā)幾次請(qǐng)求也不要一次拉爆。下面整理成問(wèn)題速查表方便你直接對(duì)照問(wèn)題現(xiàn)象根因處理方案持有者數(shù)比瀏覽器少統(tǒng)計(jì)口徑不含內(nèi)部轉(zhuǎn)賬/合約明確口徑頭部抽查驗(yàn)證余額與balanceOf不一致增量同步落后/事件缺失改回源校驗(yàn)觸發(fā)增量索引報(bào)表出現(xiàn)偽造交易合約異常事件校驗(yàn)receipt.status抽樣兜底區(qū)塊高度突然斷層鏈分叉/節(jié)點(diǎn)數(shù)據(jù)不一致高度哈希比對(duì)回滾重同步翻頁(yè)越來(lái)越慢OFFSET全表掃描改鍵集分頁(yè)加復(fù)合索引索引突然后被限流單次日志量過(guò)大壓縮區(qū)塊范圍指數(shù)退避重試5. 從工具到產(chǎn)品HolderLookup還能怎么延伸5.1 疊加地址標(biāo)簽讓數(shù)據(jù)直接變成判斷依據(jù)有了持有人全量數(shù)據(jù)之后第一個(gè)值得做升級(jí)的地方就是地址標(biāo)簽。我在持有者表里加了一個(gè)tag字段把黑洞地址、交易所熱錢包地址、多簽合約地址標(biāo)記出來(lái)。這個(gè)看起來(lái)只是加了一個(gè)字段實(shí)際效果卻非常顯著排行榜查詢直接可以把交易所地址單獨(dú)拎出來(lái)剩下就是真正的散戶持倉(cāng)風(fēng)控篩人時(shí)也能快速把疑似歸集地址從空投名單里踢出去。地址標(biāo)簽的維護(hù)不需要太復(fù)雜我維護(hù)了一份靜態(tài)清單加上一個(gè)腳本每天自動(dòng)試探性標(biāo)記。5.2 定時(shí)快照與異動(dòng)提醒再往上走就可以基于全套數(shù)據(jù)做定時(shí)快照。我當(dāng)時(shí)上線的最有實(shí)用價(jià)值的功能是每日Top100持倉(cāng)變動(dòng)報(bào)告每天固定一個(gè)區(qū)塊高度計(jì)算Top100地址的持倉(cāng)變化輸出一份排行榜對(duì)比。運(yùn)營(yíng)同事拿到這份報(bào)告直接就能看到哪些大地址在吸籌、哪些在出貨。后來(lái)我又加了個(gè)告警規(guī)則當(dāng)某個(gè)地址單筆增持超過(guò)總供應(yīng)量的0.5%時(shí)往飛書機(jī)器人推一條消息。這個(gè)功能上線第一天就抓到了一個(gè)大戶的分批建倉(cāng)行為那一刻我才真正感覺(jué)到HolderLookup已經(jīng)從查詢工具變成了鏈上哨兵。5.3 多鏈擴(kuò)展的技術(shù)儲(chǔ)備最后聊一點(diǎn)長(zhǎng)遠(yuǎn)規(guī)劃。HolderLookup的方案完全不需要綁定某一條鏈上。因?yàn)楹诵亩际峭ㄟ^(guò)日志重建狀態(tài)EVM兼容鏈比如BSC、Polygon、Arbitrum的鏈上結(jié)構(gòu)幾乎相同切換成本極低。我預(yù)留了一張chain_config表里面記錄每條鏈的RPC節(jié)點(diǎn)、起始區(qū)塊、同步狀態(tài)新鏈接入基本只改配置。要做非EVM鏈才需要重新適配事件格式但那是后話。先把手上的EVM生態(tài)吃透已經(jīng)能覆蓋大量實(shí)際需求了。我做這套系統(tǒng)的過(guò)程中最深的一個(gè)體會(huì)是鏈上數(shù)據(jù)工具的價(jià)值不在跑數(shù)而在讓人敢用數(shù)下判斷。單純給自己寫腳本查余額永遠(yuǎn)停留在自嗨當(dāng)你能輸出一份與區(qū)塊瀏覽器互相對(duì)得上賬的持有人清單、一份讓運(yùn)營(yíng)直接拍板空投名單的CSV、一條讓風(fēng)控腰桿硬起來(lái)的異動(dòng)告警時(shí)這工具才真正活了。如果你也在做類似的東西我建議你就從今天這個(gè)最小閉環(huán)開始一張事件表、一個(gè)索引腳本、一個(gè)JSON查詢接口然后讓真實(shí)需求把剩下的功能一步步逼出來(lái)。這比我當(dāng)初一上來(lái)就鋪大架構(gòu)的效果實(shí)在好太多了。 構(gòu)建鏈上持有人查詢系統(tǒng)（HolderLookup）的完整指南
做鏈上數(shù)據(jù)這塊三年多我越來(lái)越覺(jué)得HolderLookup這種看著不起眼的小工具才是真正卡脖子的剛需。所謂HolderLookup簡(jiǎn)單說(shuō)就是輸入一個(gè)代幣合約地址或者一個(gè)錢包地址你能立刻拿到答案——這個(gè)代幣到底有多少持有人頭部地址持倉(cāng)占比多少某個(gè)地址什么時(shí)候買入、現(xiàn)在還拿著多少它解決的痛點(diǎn)非常具體空投資格核對(duì)、鏈上風(fēng)控篩查、巨鯨動(dòng)向跟蹤、社區(qū)活動(dòng)防刷隨便挑一個(gè)出來(lái)沒(méi)有這類能力都得手工翻區(qū)塊干到懷疑人生。這篇文章不聊理論就從一個(gè)真實(shí)做過(guò)的項(xiàng)目出發(fā)把整套HolderLookup從需求拆解、技術(shù)選型、數(shù)據(jù)模型、索引實(shí)現(xiàn)到常見坑位的完整流程一條龍講清楚。適合三類人看想在項(xiàng)目里快速落地持有人查詢的開發(fā)者、需要做鏈上盡調(diào)的分析師、以及被為什么這個(gè)地址持有量對(duì)不上折磨的運(yùn)營(yíng)同學(xué)。1. 為什么一定要做一個(gè)HolderLookup1.1 我碰到的真實(shí)場(chǎng)景事情起源于一次空投核對(duì)。當(dāng)時(shí)項(xiàng)目方給了我一萬(wàn)兩千個(gè)白名單地址要求篩選出真正持有治理代幣超過(guò)1000枚的錢包還要排除掉交易所熱錢包和黑洞地址。我第一反應(yīng)是直接用區(qū)塊瀏覽器的導(dǎo)出功能結(jié)果試了才知道Etherscan這類工具單次導(dǎo)出上限就卡得死死的而且只會(huì)給你Top持有者中長(zhǎng)尾地址根本導(dǎo)不全。挨個(gè)調(diào)balanceOf更不現(xiàn)實(shí)上萬(wàn)次RPC請(qǐng)求打到節(jié)點(diǎn)上人家沒(méi)封你號(hào)也得把你限流到懷疑人生。后來(lái)我就想明白了這類需求不能靠臨時(shí)腳本湊得有一套正經(jīng)的查詢系統(tǒng)。于是HolderLookup這個(gè)項(xiàng)目就立項(xiàng)了。它不是一個(gè)花哨的DApp也不是什么復(fù)雜協(xié)議就是一個(gè)非常務(wù)實(shí)的數(shù)據(jù)管道——把鏈上分散的ERC-20/ERC-721轉(zhuǎn)賬事件匯聚起來(lái)重建成每個(gè)地址現(xiàn)在持有什么、持有多少、從什么時(shí)候開始持有的完整視圖。做完了以后不僅空投核對(duì)變成了秒級(jí)操作團(tuán)隊(duì)里做風(fēng)控的同事、做社區(qū)的運(yùn)營(yíng)、甚至我自己做競(jìng)品分析全都開始依賴這套數(shù)據(jù)。1.2 核心功能拆解一個(gè)查詢系統(tǒng)到底要查什么立項(xiàng)之前我先把HolderLookup這個(gè)詞拆成了五個(gè)子功能避免一開始就把系統(tǒng)做飛全量持有者列表給定代幣合約返回所有非零余額地址附帶持倉(cāng)數(shù)量、占比、最后變動(dòng)區(qū)塊。單地址持倉(cāng)查詢給定錢包地址返回它在某個(gè)代幣里的余額、歷史充值/轉(zhuǎn)出記錄。持倉(cāng)排名與分布按余額倒序輸出并聚合出前10地址占總供應(yīng)比例這類指標(biāo)。地址畫像分類判斷目標(biāo)地址是合約地址、多簽合約、交易所冷錢包還是普通EOA用標(biāo)簽輔助風(fēng)控判斷。歷史快照對(duì)比記錄每個(gè)區(qū)塊高度下的持倉(cāng)快照回答昨天這個(gè)地址還有沒(méi)有貨。最終整個(gè)系統(tǒng)對(duì)外只暴露一個(gè)極簡(jiǎn)接口傳參代幣地址和可選的錢包地址回來(lái)一行結(jié)構(gòu)化的JSON其余所有復(fù)雜度都收斂在內(nèi)部。這里最大的設(shè)計(jì)原則是查詢時(shí)必須快索引階段可以慢。1.3 輸入什么、輸出什么先定好契約再寫代碼做這類工具最忌諱邊寫邊想所以我先定了輸入輸出契約后面所有模塊都圍著一份契約開發(fā)輸入輸出備注token_address代幣基礎(chǔ)信息符號(hào)、精度、總供應(yīng)從合約只讀方法抓取緩存token_addresspagination持有者列表{address, balance, share}按余額降序游標(biāo)翻頁(yè)wallet_addresstoken_address該地址當(dāng)前余額 最后變動(dòng)區(qū)塊實(shí)時(shí)校驗(yàn)不依賴本地索引wallet_address該地址所有代幣持倉(cāng)匯總多合約聚合屬于進(jìn)階模塊這個(gè)表格看著簡(jiǎn)單但它是整個(gè)項(xiàng)目的錨點(diǎn)。后面所有代碼、表結(jié)構(gòu)、API文檔都圍繞它寫避免做到一半突然加需求。我吃過(guò)這個(gè)虧一開始想直接做鏈上監(jiān)控大屏結(jié)果連最基礎(chǔ)的查詢都沒(méi)磨圓最后返工了兩次才穩(wěn)定。所以勸你一句話——先把查詢做扎實(shí)可視化永遠(yuǎn)是錦上添花。2. 整體設(shè)計(jì)與技術(shù)選型不迷信一步到位的方案2.1 先搞明白鏈上持倉(cāng)數(shù)據(jù)到底存在哪里很多剛接觸鏈上數(shù)據(jù)的人有個(gè)誤區(qū)以為調(diào)用一次balanceOf數(shù)據(jù)就像數(shù)據(jù)庫(kù)一樣躺在某個(gè)表里。實(shí)際上EVM世界里沒(méi)有一張持有量表擺在那兒給你查。鏈上只存了一份全局狀態(tài)樹state trie里面確實(shí)記錄著每個(gè)地址的余額映射但你要理解這個(gè)映射是結(jié)果不是賬本。賬本是一長(zhǎng)串Transfer事件散落在成千上萬(wàn)個(gè)區(qū)塊的日志里。我自己的比喻是這樣區(qū)塊鏈?zhǔn)且槐局蛔芳拥牧魉~每一頁(yè)區(qū)塊記著誰(shuí)給誰(shuí)轉(zhuǎn)了多少錢。至于張三現(xiàn)在總共有多少錢賬本上沒(méi)寫得你把所有涉及張三的記錄都翻一遍、加減出來(lái)。balanceOf之所以能秒回是因?yàn)楣?jié)點(diǎn)幫你把賬本實(shí)時(shí)匯總成了余額快照但它只能回答當(dāng)前是多少回答不了有哪些人持有他們各自持有了多久。這就道出了HolderLookup的本質(zhì)它不是讀一個(gè)字段而是在重建一本持有人總賬。你只能通過(guò)解析歷史Transfer事件自己構(gòu)建并持續(xù)維護(hù)一張關(guān)系表——address - token - balance。想通了這一點(diǎn)后面所有技術(shù)選型都圍繞如何高效回放事件流展開。2.2 三種數(shù)據(jù)獲取方案的對(duì)比確定了方向下一步就是怎么拿到這些事件。我整理了三種主路徑各有取舍方案優(yōu)點(diǎn)缺點(diǎn)適合場(chǎng)景直接RPC輪詢eth_getLogs無(wú)額外依賴、可控性最高容易觸發(fā)節(jié)點(diǎn)限流、歷史深查慢中小型代幣、初期開發(fā)驗(yàn)證使用索引服務(wù)快照The Graph等查詢快、數(shù)據(jù)結(jié)構(gòu)化、文檔齊全需要學(xué)一套新DSL、托管成本數(shù)據(jù)量中等、團(tuán)隊(duì)愿意引入新基建第三方區(qū)塊瀏覽器API接入最快、無(wú)需自建索引配額低、數(shù)據(jù)口徑不透明原型驗(yàn)證、低頻查詢我最后采用的是混合架構(gòu)主索引用RPC輪詢自建同時(shí)用索引服務(wù)的解析結(jié)果做交叉校驗(yàn)。原因有三一是自建管道數(shù)據(jù)口徑完全可控二是RPC輪詢成本最低三是不想把整個(gè)項(xiàng)目押在一個(gè)第三方服務(wù)上。這里有一個(gè)很重要的心得數(shù)據(jù)管道一定要有自愈能力不能因?yàn)槟硞€(gè)外部依賴抽風(fēng)就全盤癱瘓所以核心索引器必須能用最原始的RPC重新拉起來(lái)。2.3 系統(tǒng)架構(gòu)三層職責(zé)分離整個(gè)HolderLookup拆成三層互相之間通過(guò)消息解耦這個(gè)架構(gòu)后來(lái)被證明非?？冈鞌?shù)據(jù)層負(fù)責(zé)同步、解析、存儲(chǔ)Transfer事件。主要由一個(gè)調(diào)度器控制它決定下一批該拉哪個(gè)區(qū)塊區(qū)間把解析好的事件批量寫入數(shù)據(jù)庫(kù)。計(jì)算層負(fù)責(zé)把裸事件轉(zhuǎn)成業(yè)務(wù)數(shù)據(jù)。核心任務(wù)就是跑一條聚合SQL把相同from地址扣減余額、相同to地址增加余額最后過(guò)濾掉零余額地址生成當(dāng)前“持有人表”。服務(wù)層面向查詢方提供API只做三件事讀緩存查數(shù)據(jù)庫(kù)必要時(shí)回源RPC實(shí)時(shí)校驗(yàn)。堅(jiān)決不做重計(jì)算。用這套架構(gòu)的好處非常直接查詢層永遠(yuǎn)只碰持久化后的干凈數(shù)據(jù)不碰節(jié)點(diǎn)計(jì)算層可以定時(shí)重算也可以按需重算數(shù)據(jù)層則只用關(guān)心吞吐量不用操心業(yè)務(wù)口徑。三個(gè)層各干各的任何一層出問(wèn)題都能獨(dú)立回滾。實(shí)際做起來(lái)你甚至?xí)杏X(jué)像在搭建一條小型實(shí)時(shí)數(shù)倉(cāng)用的全是數(shù)據(jù)庫(kù)和消息隊(duì)列的常見套路完全沒(méi)有必要引入什么重型框架。3. 實(shí)操實(shí)現(xiàn)一步一步跑通HolderLookup3.1 定義數(shù)據(jù)模型一切從一張表開始動(dòng)手寫代碼前先把表結(jié)構(gòu)定好。我的核心表長(zhǎng)這樣CREATE TABLE transfer_events ( id BIGSERIAL PRIMARY KEY, token_address CHAR(42) NOT NULL, from_address CHAR(42) NOT NULL, to_address CHAR(42) NOT NULL, raw_value NUMERIC NOT NULL, block_number BIGINT NOT NULL, tx_hash CHAR(66) NOT NULL, log_index INT NOT NULL, UNIQUE (tx_hash, log_index) ); CREATE INDEX idx_transfer_token_block ON transfer_events (token_address, block_number); CREATE INDEX idx_transfer_from ON transfer_events (from_address, token_address); CREATE INDEX idx_transfer_to ON transfer_events (to_address, token_address);注意raw_value字段我存的是原始整數(shù)不帶精度轉(zhuǎn)換。原因很簡(jiǎn)單decimal和NUMERIC在數(shù)據(jù)庫(kù)里處理起來(lái)更精確但一旦涉及精度換算不同代幣的decimals還不一樣先把原始值存住展示層再統(tǒng)一除以10^decimals這樣最保險(xiǎn)。還要說(shuō)明一個(gè)設(shè)計(jì)細(xì)節(jié)為什么我不直接建一張最終余額表因?yàn)樽罱K余額可以被事件流隨時(shí)重算而歷史事件是不可變的審計(jì)證據(jù)。建一張holders表當(dāng)然也可以但我選擇在查詢時(shí)聚合事件表每次跑完再物化到緩存。這樣既能追溯又不犧牲查詢性能。對(duì)于數(shù)據(jù)量特別大的項(xiàng)目你完全可以用物化視圖或者預(yù)聚合表原理是一樣的。3.2 寫索引器監(jiān)聽每一條Transfer事件索引器是整條管道的發(fā)動(dòng)機(jī)。我用的技術(shù)棧是Python web3.py配合PostgreSQL整體邏輯可以縮成一段核心循環(huán)from web3 import Web3 from web3.middleware import geth_poa_middleware RPC_URL 你的節(jié)點(diǎn)RPC地址 CONTRACT_ADDRESS 0x你的代幣合約地址 w3 Web3(Web3.HTTPProvider(RPC_URL)) w3.middleware_onion.inject(geth_poa_middleware, layer0) TRANSFER_TOPIC w3.keccak(textTransfer(address,address,uint256)).hex() # 上一次同步到的區(qū)塊高度真實(shí)項(xiàng)目里應(yīng)持久化比如存redis或數(shù)據(jù)庫(kù) last_synced_block 20000000 latest_block w3.eth.block_number CHUNK 5000 # 單次拉取范圍不能太大后面講為什么 def process_block_range(start, end): logs w3.eth.get_logs({ fromBlock: start, toBlock: end, address: Web3.to_checksum_address(CONTRACT_ADDRESS), topics: [TRANSFER_TOPIC] }) parsed [] for log in logs: # topics: [0]是事件簽名, [1]是from, [2]是to _from Web3.to_checksum_address(log[topics][1].hex()[-40:]) _to Web3.to_checksum_address(log[topics][2].hex()[-40:]) value int(log[data].hex(), 16) parsed.append((CONTRACT_ADDRESS, _from, _to, value, log[blockNumber], log[transactionHash].hex(), log[logIndex])) return parsed # 主循環(huán)示意 while last_synced_block latest_block: end min(last_synced_block CHUNK, latest_block) batch process_block_range(last_synced_block 1, end) # 批量寫入數(shù)據(jù)庫(kù)execute_values last_synced_block end有幾個(gè)細(xì)節(jié)必須說(shuō)透。get_logs的topics參數(shù)是過(guò)濾的靈魂只傳TRANSFER_TOPIC就表示“只要Transfer事件”返回的數(shù)據(jù)里每條log的topics[1]是轉(zhuǎn)出方、topics[2]是接收方值在data里。之所以要.hex()[-40:]再?gòu)臉?biāo)準(zhǔn)地址恢復(fù)是因?yàn)樗饕灻锏刂肥亲筇畛涞?2字節(jié)不截?cái)鄷?huì)解析出幽靈地址。分塊區(qū)間CHUNK為什么設(shè)5000公共節(jié)點(diǎn)對(duì)單次get_logs能掃描的區(qū)塊范圍有限制有的服務(wù)商限定10000塊有的更小。塊區(qū)間太大可能直接報(bào)錯(cuò)query returned too many results太小又浪費(fèi)請(qǐng)求。5000對(duì)我來(lái)說(shuō)是一個(gè)平衡點(diǎn)速度可接受限流概率低。還有一個(gè)坑必須把last_synced_block持久化到數(shù)據(jù)庫(kù)或者Redis否則進(jìn)程一重啟你又得從頭掃。別問(wèn)我怎么知道的。3.3 實(shí)現(xiàn)實(shí)時(shí)查詢先打緩存再回源校驗(yàn)索引器補(bǔ)上了歷史賬本但鏈上每秒都在產(chǎn)生新交易你的表永遠(yuǎn)會(huì)晚幾秒。為了做到真正的實(shí)時(shí)我的查詢層故意做了一步回源校驗(yàn)def get_holder_balance(token_address, wallet_address, blocklatest): # 1. 先查本地聚合數(shù)據(jù) local_balance query_local_balance(token_address, wallet_address) # 2. 再通過(guò)節(jié)點(diǎn)實(shí)時(shí)確認(rèn) contract w3.eth.contract( addressWeb3.to_checksum_address(token_address), abiERC20_ABI ) onchain_balance contract.functions.balanceOf( Web3.to_checksum_address(wallet_address) ).call(block_identifierblock) # 3. 本地落后時(shí)以鏈上為準(zhǔn)同時(shí)觸發(fā)一次增量索引補(bǔ)拉 if local_balance ! onchain_balance: trigger_incremental_index(wallet_address) return onchain_balance這里的關(guān)鍵是contract.functions.balanceOf(...).call()這其實(shí)是節(jié)點(diǎn)在內(nèi)部狀態(tài)樹上做的查詢不走事件日志速度極快。但凡是查當(dāng)前余額我永遠(yuǎn)以鏈上為準(zhǔn)本地索引只用于批量場(chǎng)景和排行榜。如果本地和鏈上不一致說(shuō)明增量同步還在追塊流程自然退避重試就好。另外要強(qiáng)調(diào)一個(gè)進(jìn)階點(diǎn)call()可以傳block_identifier參數(shù)。你可以查歷史任意區(qū)塊高度下的余額比如實(shí)現(xiàn)這個(gè)地址在空投快照那一刻到底持有了多少。這一招在做空投活動(dòng)資格判定時(shí)太有用了因?yàn)楹芏囗?xiàng)目方是按區(qū)塊高度快照的不是按當(dāng)前時(shí)間快照的。3.4 聚合排序與去重合并核心SQL的表演時(shí)刻把幾百萬(wàn)條Transfer事件變成持有人表靠手工遍歷完全不現(xiàn)實(shí)必須交給數(shù)據(jù)庫(kù)聚合。我的核心查詢長(zhǎng)這樣WITH balance_calc AS ( SELECT address, SUM(value) AS balance FROM ( SELECT from_address AS address, -raw_value AS value FROM transfer_events WHERE token_address $1 UNION ALL SELECT to_address AS address, raw_value AS value FROM transfer_events WHERE token_address $1 ) t GROUP BY address ) SELECT address, balance / 10^decimals AS display_balance, ROUND(balance / total_supply * 100, 4) AS share_percent FROM balance_calc, token_meta WHERE balance 0 ORDER BY balance DESC LIMIT $2 OFFSET $3;這個(gè)查詢的妙處在于把轉(zhuǎn)出和轉(zhuǎn)入編碼成正負(fù)值拼在一起再按地址分組求和。數(shù)據(jù)庫(kù)層面會(huì)并行處理性能比你在Python里一層層循環(huán)不知道高多少。但有個(gè)大坑銷毀burn常見但部分代幣不是通過(guò)Transfer(address, 0x00)銷毀而是直接改合約里某個(gè)特殊變量。這種情況下聚合查詢會(huì)高估總供應(yīng)。我自己踩過(guò)之后養(yǎng)成一個(gè)習(xí)慣每個(gè)代幣接入前先拉一批歷史快照和區(qū)塊瀏覽器的持有者數(shù)據(jù)做交叉驗(yàn)證如果偏差超過(guò)0.01%立刻人工審查事件表看看是不是存在沒(méi)走標(biāo)準(zhǔn)Transfer事件的余額變動(dòng)。把對(duì)賬前置后面所有結(jié)論才立得住。3.5 緩存層別讓數(shù)據(jù)庫(kù)做它不該做的事查詢接口上線后第一個(gè)被壓垮的是數(shù)據(jù)庫(kù)。排行榜接口要跑一次全表聚合疊加并發(fā)以后直接把連接池打滿。我的解決方案是引入Redis做兩層緩存第一層熱榜緩存。Top100持有者排名每小時(shí)刷新一次key形如holder_rank:top100:{token_address}TTL設(shè)為1小時(shí)。第二層單地址緩存。holder:single:{token_address}:{wallet_address}TTL設(shè)為30秒。30秒這個(gè)窗口對(duì)于大多數(shù)場(chǎng)景足夠新鮮又不會(huì)頻繁失效。實(shí)踐下來(lái)這套緩存配合索引器的預(yù)聚合讓排行榜接口從平均800ms降到10ms以內(nèi)數(shù)據(jù)庫(kù)負(fù)載下降了60%。不過(guò)緩存也帶來(lái)了一個(gè)有意思的新問(wèn)題空投快照時(shí)項(xiàng)目方往往要求準(zhǔn)確到特定區(qū)塊高度緩存里的數(shù)據(jù)做不到。所以我又加了一個(gè)邏輯——凡是帶block_number參數(shù)的查詢一律走數(shù)據(jù)庫(kù)或RPC實(shí)時(shí)計(jì)算直接繞過(guò)Redis。底層的原則很簡(jiǎn)單緩存只服務(wù)當(dāng)前最新場(chǎng)景歷史場(chǎng)景永遠(yuǎn)實(shí)時(shí)。3.6 對(duì)外輸出JSON接口與CSV導(dǎo)出系統(tǒng)最終收斂成兩個(gè)出口。第一是HTTP JSON面向前端和自動(dòng)化腳本{ token: 0x..., block_height: 20123456, total_holders: 12738, holders: [ { address: 0xabc..., balance: 1000000000000000000000, display_balance: 1000.00, share_percent: 2.34, source: indexed } ], next_cursor: 0xdef... }第二是CSV導(dǎo)出給運(yùn)營(yíng)同學(xué)用。這個(gè)需求是真實(shí)存在的運(yùn)營(yíng)拿著數(shù)據(jù)去查重、對(duì)白名單如果還指望他們看懂JSON就太天真了。我做了一個(gè)后臺(tái)任務(wù)把查詢結(jié)果異步轉(zhuǎn)成CSV傳到對(duì)象存儲(chǔ)后回一條下載鏈接。這個(gè)功能看著沒(méi)什么技術(shù)含量卻成了整個(gè)項(xiàng)目里被夸得最多的功能——在工業(yè)界混久了你就知道能輸出Excel才是真的生產(chǎn)力。4. 上線后的坑HolderLookup最常見的問(wèn)題排查實(shí)錄4.1 持有人數(shù)量和區(qū)塊瀏覽器對(duì)不上怎么辦幾乎每個(gè)接入HolderLookup的人都會(huì)問(wèn)我同一個(gè)問(wèn)題為什么我拉出來(lái)的持有人數(shù)是8000可區(qū)塊瀏覽器上顯示是12000這里的水很深。最大的原因在于口徑區(qū)塊瀏覽器的持有人數(shù)通常包含內(nèi)部轉(zhuǎn)賬、批量空投分發(fā)器、鎖定合約、甚至零余額但仍在白名單里的地址。而我默認(rèn)只統(tǒng)計(jì)非零余額的EOA和合約地址。所以不是系統(tǒng)算錯(cuò)了而是兩邊統(tǒng)計(jì)口徑不一樣。我的建議是不去猜直接查。具體做法先對(duì)比前100地址是否一致如果頭部對(duì)得上基本可以確認(rèn)是尾部統(tǒng)計(jì)口徑問(wèn)題如果頭部都對(duì)不上那就要檢查索引是不是漏塊了。驗(yàn)證漏塊很簡(jiǎn)單取某一個(gè)已知地址比對(duì)它的balanceOf實(shí)時(shí)值和聚合值差異一旦超過(guò)0基本就是增量同步滯后。千萬(wàn)不要盲目調(diào)數(shù)據(jù)先校準(zhǔn)你的統(tǒng)計(jì)定義。4.2 Transfer事件不一定是真的轉(zhuǎn)賬成功還有一種隱蔽情況某些代幣合約在transfer函數(shù)里會(huì)revert但之前已經(jīng)發(fā)出過(guò)Transfer事件。鏈上交易的日志一旦交易失敗整個(gè)receipt回滾日志也不會(huì)存在。但如果合約寫得花哨在內(nèi)部調(diào)用子合約的transfer時(shí)會(huì)發(fā)出事件而子合約調(diào)用失敗后錯(cuò)誤被吞掉外層交易卻成功了——這種幽靈事件雖然少見但確實(shí)存在。排查手段是解析事件時(shí)順帶記錄receipt.status只信任status 1的交易日志。def is_tx_success(tx_hash): receipt w3.eth.get_transaction_receipt(tx_hash) return receipt[status] 1這個(gè)檢查有額外RPC開銷所以我只在索引器里加了抽樣校驗(yàn)邏輯每1000條事件抽1條驗(yàn)證狀態(tài)抽樣異常率超過(guò)閾值時(shí)切到全量校驗(yàn)?zāi)Ｊ?。這樣一個(gè)輕量兜底既不會(huì)拖慢同步又能防止被半路殺出的奇怪合約坑到。4.3 區(qū)塊高度斷層與分叉回滾區(qū)塊鏈偶爾會(huì)發(fā)生短期分叉reorg導(dǎo)致你同步的日志在某一個(gè)高度上突然多了一段或少了一段。我的處理策略是索引器里永遠(yuǎn)記錄最近1000個(gè)區(qū)塊的哈希定時(shí)和節(jié)點(diǎn)當(dāng)前區(qū)塊哈希做比對(duì)一旦發(fā)現(xiàn)某個(gè)高度哈希不一致就把該高度之后的本地事件全部清理掉重新拉取。這套回滾再同步邏輯看起來(lái)簡(jiǎn)單但它是整個(gè)數(shù)據(jù)一致性的最后一道防線。早期我沒(méi)做這個(gè)結(jié)果排行榜數(shù)據(jù)差了一截排查了三個(gè)小時(shí)才發(fā)現(xiàn)是凌晨有一次深度重組。4.4 游標(biāo)翻頁(yè)的性能陷阱別用OFFSET持有人列表一多千萬(wàn)不要用OFFSET翻頁(yè)。MySQL/PostgreSQL在OFFSET 8000這種位置時(shí)仍然會(huì)掃描前面的全部行越翻越慢前端會(huì)明顯卡頓。換成鍵集分頁(yè)keyset pagination以后性能直接起飛WHERE (balance, address) ($balance, $address) ORDER BY balance DESC, address DESC LIMIT 100這個(gè)寫法的原理是利用數(shù)據(jù)庫(kù)索引天然排序的特性永遠(yuǎn)從上一頁(yè)最后一條的位置繼續(xù)向后讀不需要掃描跳過(guò)的行。配合之前建好的(balance, address)復(fù)合索引翻頁(yè)再深也能保持穩(wěn)定時(shí)延。這類細(xì)節(jié)雖然不起眼但高流量接口靠的就是這些刁鉆優(yōu)化。4.5 節(jié)點(diǎn)RPC限流指數(shù)退避是最低要求做索引器經(jīng)常遇到的問(wèn)題就是拉著拉著節(jié)點(diǎn)不鳥你了。公共RPC節(jié)點(diǎn)通常用速率限制保護(hù)服務(wù)eth_getLogs又是重請(qǐng)求很容易觸發(fā)。我的經(jīng)驗(yàn)是三層防護(hù)請(qǐng)求之間加固定間隔比如50ms命中429錯(cuò)誤時(shí)用指數(shù)退避等待1秒、2秒、4秒……直到恢復(fù)給不同RPC節(jié)點(diǎn)配置做故障轉(zhuǎn)移比如同時(shí)配兩個(gè)以上的端點(diǎn)一個(gè)報(bào)錯(cuò)立刻切換。再補(bǔ)一個(gè)小技巧熱門代幣的Transfer事件量極大單次get_logs很容易因?yàn)榉祷厝罩咎嘀苯訄?bào)錯(cuò)。這種情況下把區(qū)塊范圍繼續(xù)拆小拆到單次返回不超過(guò)5000條日志為止。寧可多發(fā)幾次請(qǐng)求也不要一次拉爆。下面整理成問(wèn)題速查表方便你直接對(duì)照問(wèn)題現(xiàn)象根因處理方案持有者數(shù)比瀏覽器少統(tǒng)計(jì)口徑不含內(nèi)部轉(zhuǎn)賬/合約明確口徑頭部抽查驗(yàn)證余額與balanceOf不一致增量同步落后/事件缺失改回源校驗(yàn)觸發(fā)增量索引報(bào)表出現(xiàn)偽造交易合約異常事件校驗(yàn)receipt.status抽樣兜底區(qū)塊高度突然斷層鏈分叉/節(jié)點(diǎn)數(shù)據(jù)不一致高度哈希比對(duì)回滾重同步翻頁(yè)越來(lái)越慢OFFSET全表掃描改鍵集分頁(yè)加復(fù)合索引索引突然后被限流單次日志量過(guò)大壓縮區(qū)塊范圍指數(shù)退避重試5. 從工具到產(chǎn)品HolderLookup還能怎么延伸5.1 疊加地址標(biāo)簽讓數(shù)據(jù)直接變成判斷依據(jù)有了持有人全量數(shù)據(jù)之后第一個(gè)值得做升級(jí)的地方就是地址標(biāo)簽。我在持有者表里加了一個(gè)tag字段把黑洞地址、交易所熱錢包地址、多簽合約地址標(biāo)記出來(lái)。這個(gè)看起來(lái)只是加了一個(gè)字段實(shí)際效果卻非常顯著排行榜查詢直接可以把交易所地址單獨(dú)拎出來(lái)剩下就是真正的散戶持倉(cāng)風(fēng)控篩人時(shí)也能快速把疑似歸集地址從空投名單里踢出去。地址標(biāo)簽的維護(hù)不需要太復(fù)雜我維護(hù)了一份靜態(tài)清單加上一個(gè)腳本每天自動(dòng)試探性標(biāo)記。5.2 定時(shí)快照與異動(dòng)提醒再往上走就可以基于全套數(shù)據(jù)做定時(shí)快照。我當(dāng)時(shí)上線的最有實(shí)用價(jià)值的功能是每日Top100持倉(cāng)變動(dòng)報(bào)告每天固定一個(gè)區(qū)塊高度計(jì)算Top100地址的持倉(cāng)變化輸出一份排行榜對(duì)比。運(yùn)營(yíng)同事拿到這份報(bào)告直接就能看到哪些大地址在吸籌、哪些在出貨。后來(lái)我又加了個(gè)告警規(guī)則當(dāng)某個(gè)地址單筆增持超過(guò)總供應(yīng)量的0.5%時(shí)往飛書機(jī)器人推一條消息。這個(gè)功能上線第一天就抓到了一個(gè)大戶的分批建倉(cāng)行為那一刻我才真正感覺(jué)到HolderLookup已經(jīng)從查詢工具變成了鏈上哨兵。5.3 多鏈擴(kuò)展的技術(shù)儲(chǔ)備最后聊一點(diǎn)長(zhǎng)遠(yuǎn)規(guī)劃。HolderLookup的方案完全不需要綁定某一條鏈上。因?yàn)楹诵亩际峭ㄟ^(guò)日志重建狀態(tài)EVM兼容鏈比如BSC、Polygon、Arbitrum的鏈上結(jié)構(gòu)幾乎相同切換成本極低。我預(yù)留了一張chain_config表里面記錄每條鏈的RPC節(jié)點(diǎn)、起始區(qū)塊、同步狀態(tài)新鏈接入基本只改配置。要做非EVM鏈才需要重新適配事件格式但那是后話。先把手上的EVM生態(tài)吃透已經(jīng)能覆蓋大量實(shí)際需求了。我做這套系統(tǒng)的過(guò)程中最深的一個(gè)體會(huì)是鏈上數(shù)據(jù)工具的價(jià)值不在跑數(shù)而在讓人敢用數(shù)下判斷。單純給自己寫腳本查余額永遠(yuǎn)停留在自嗨當(dāng)你能輸出一份與區(qū)塊瀏覽器互相對(duì)得上賬的持有人清單、一份讓運(yùn)營(yíng)直接拍板空投名單的CSV、一條讓風(fēng)控腰桿硬起來(lái)的異動(dòng)告警時(shí)這工具才真正活了。如果你也在做類似的東西我建議你就從今天這個(gè)最小閉環(huán)開始一張事件表、一個(gè)索引腳本、一個(gè)JSON查詢接口然后讓真實(shí)需求把剩下的功能一步步逼出來(lái)。這比我當(dāng)初一上來(lái)就鋪大架構(gòu)的效果實(shí)在好太多了。