How paxosglobal/eth-balance-checker works
1. What this repository is
- This repo packages a single-purpose Ethereum tooling stack: a smart contract plus a JavaScript/TypeScript client library for reading many ERC20 and native coin balances in one on-chain RPC call.
- The main runtime boundary is between off-chain code (the library) and on-chain code (the BalanceChecker contract).
2. Core on-chain subsystem
- contracts/ contains the Solidity contract(s), centered on BalanceChecker.sol.
- The contract is the aggregation engine: it receives arrays of addresses and token addresses, then returns balances for each pair using a single contract call rather than many separate RPC requests.
- The repo also includes contract ABIs in abis/, showing that the contract interface is treated as a distributable artifact, not just a build output.
3. Client library subsystem
- src/ contains the consumer-facing library, built in TypeScript.
- There are two parallel adapters:
- src/web3.ts for web3.js
- src/ethers.ts for ethers.js
- src/common.ts and src/index.ts provide shared logic and package entry points so both adapters expose the same balance-query API.
4. Data flow for balance lookups
- A consumer passes a provider, one or more addresses, and a list of token addresses.
- The library resolves the correct BalanceChecker contract address, calls the contract once, and maps the returned data into a nested balance object.
- Special case: passing "0x0" represents the native chain currency balance instead of an ERC20 token balance.
5. Output shape and API boundary
- The library is designed around two public query shapes:
- balances for one address across many tokens
- balances for many addresses across many tokens
- The outputs are normalized as string-valued balances keyed by token address, or by address then token address for the multi-address variant.
- This keeps the on-chain call format hidden behind a consistent off-chain API.
6. Multi-chain deployment model
- The README lists deployed contract addresses for many networks: Ethereum mainnet/testnets plus several EVM-compatible chains.
- The Options.contractAddress setting in the library is the architecture hook that lets the same client code target different chains or custom deployments.
- This means the package is not hardwired to one network; it is explicitly designed for cross-network contract reuse.
7. Build and artifact generation
- The repo has a two-part build:
- build:contract compiles Solidity with Truffle and exports ABI artifacts
- build:lib compiles TypeScript into distributable JS/typings
- scripts/export-abi.js is the bridge between the Solidity build and the published package artifacts, copying ABI files into a consumable format.
- This separates on-chain compilation concerns from library packaging concerns.
8. Testing boundary
- test/BalanceCheckerTest.js is the contract-level test suite, indicating that correctness is primarily validated against the Solidity behavior.
- There are no library tests yet (test:lib is present but unimplemented), so the most important verified subsystem is the smart contract itself.
9. Deployment and migration flow
- migrations/ contains Truffle migration scripts, so the contract deployment process follows the standard Truffle migration model.
- 1_initial_migrations.js and 2_deploy_contracts.js imply a deployment pipeline that initializes the migration framework and then deploys the BalanceChecker-related contracts.
10. Published package structure
- The repository is set up as an NPM package with compiled outputs, ABI files, and separate entry points for web3 and ethers.
- package.json, tsconfig.json, and the presence of generated ABIs indicate that the package is meant to be consumed directly by other apps, not just used as source.
11. External dependencies that matter architecturally
- The architecture depends on EVM-compatible chains, Truffle, TypeScript, and either web3.js or ethers.js on the client side.
- The contract is intended to be deployed across multiple networks, including L2s and non-Ethereum EVM chains, which is why contract address configuration is part of the API.
12. High-level diagram view
- At the center is the BalanceChecker Solidity contract on-chain.
- On the left are consumers using either the web3 adapter or ethers adapter from the TypeScript library.
- On the right are the blockchain RPC endpoints for the target network.
- Supporting the whole system are the ABI artifacts, build scripts, Truffle migrations, and contract tests that produce and validate the deployable package.
Main entry points: index.ts Index API · common.ts Shared logic · contracts BalanceChecker · web3.ts Web3 adapter
Components 15
Off-chain library
TypeScript package and client adapters used by consumers.
- Index API · Primary package entry point that re-exports the public API.
src/index.ts - Shared logic · Common balance-query and result-normalization logic.
src/common.ts - Web3 adapter · web3.js integration for the balance-checking API.
src/web3.ts - Ethers adapter · ethers.js integration for the balance-checking API.
src/ethers.ts
On-chain contract
Solidity contract and deployment path for balance aggregation.
- BalanceChecker · On-chain aggregation contract that returns many balances in one call.
contracts - Migrations · Truffle migration scripts that deploy the contract stack.
migrations - Contract tests · Solidity behavior verification for BalanceChecker.
test/BalanceCheckerTest.js
Build and artifacts
Packaging, ABI export, and repository-level build configuration.
- ABI artifacts · Distributable contract ABI files consumed by the library and clients.
abis - ABI source · Source-side ABI copies used during packaging.
src/abis - ABI export · Copies Solidity ABI outputs into the published package layout.
scripts/export-abi.js - Package config · Build scripts, entry points, and package metadata.
package.json - Truffle config · Contract build and deployment configuration.
truffle-config.js - TypeScript config · Compiler settings for the distributable library.
tsconfig.json
Other components
- Consumer app · Application using the balance query API.
- RPC endpoint · Blockchain node endpoint for the target EVM chain.
Connections 18
- Consumer app → Index API: uses API · Consumers call the package entry point.
- Index API → Shared logic: re-exports · Entry point centralizes shared balance-query logic.
- Index API → Web3 adapter: exposes · Public API includes the web3 adapter.
- Index API → Ethers adapter: exposes · Public API includes the ethers adapter.
- Web3 adapter → Shared logic: shares logic · Web3 adapter delegates core normalization and query flow.
- Ethers adapter → Shared logic: shares logic · Ethers adapter delegates core normalization and query flow.
- Web3 adapter → ABI artifacts: loads ABI · Web3 adapter uses the published contract ABI.
- Ethers adapter → ABI artifacts: loads ABI · Ethers adapter uses the published contract ABI.
- Shared logic → BalanceChecker: calls contract · Shared logic performs the single on-chain balance aggregation call.
- BalanceChecker → RPC endpoint: executes on · Contract queries are served through the target chain RPC endpoint.
- Consumer app → RPC endpoint: reads balances · The consumer ultimately depends on chain state returned by RPC.
- Migrations → BalanceChecker: deploys · Truffle migrations deploy the contract.
- Contract tests → BalanceChecker: verifies · Contract tests validate BalanceChecker behavior.
- ABI export → ABI artifacts: publishes · Build script exports ABI artifacts into package form.
- ABI source → ABI export: feeds · Source ABI copies are part of the packaging bridge.
- Package config → ABI export: scripts · Package scripts orchestrate ABI export and builds.
- Package config → TypeScript config: builds with · Package build uses the TypeScript compiler settings.
- Truffle config → Migrations: configures · Truffle config supports deployment scripts and contract build flow.