# paxosglobal/eth-balance-checker architecture

> Architecture diagram of the GitHub repository paxosglobal/eth-balance-checker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paxosglobal/eth-balance-checker
- Repository: https://github.com/paxosglobal/eth-balance-checker

## Overview

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: [`src/index.ts`](https://github.com/paxosglobal/eth-balance-checker/blob/master/src/index.ts) (Index API), [`src/common.ts`](https://github.com/paxosglobal/eth-balance-checker/blob/master/src/common.ts) (Shared logic), [`contracts`](https://github.com/paxosglobal/eth-balance-checker/tree/master/contracts) (BalanceChecker), [`src/web3.ts`](https://github.com/paxosglobal/eth-balance-checker/blob/master/src/web3.ts) (Web3 adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offchain["Off-chain library"]
  node_index["Index API<br/>ts entrypoint<br/>[index.ts]"]
  node_common["Shared logic<br/>ts core<br/>[common.ts]"]
  node_web3["Web3 adapter<br/>ts adapter<br/>[web3.ts]"]
  node_ethers["Ethers adapter<br/>ts adapter<br/>[ethers.ts]"]
end

subgraph group_onchain["On-chain contract"]
  node_checker["BalanceChecker<br/>solidity contract"]
  node_migrations["Migrations<br/>truffle deploy"]
  node_contract_test["Contract tests<br/>test suite"]
end

subgraph group_tooling["Build and artifacts"]
  node_abi_artifacts["ABI artifacts<br/>published abi set"]
  node_src_abis["ABI source<br/>source abi import"]
  node_export_abi["ABI export<br/>node script<br/>[export-abi.js]"]
  node_package_json["Package config<br/>npm manifest<br/>[package.json]"]
  node_truffle["Truffle config<br/>tool config<br/>[truffle-config.js]"]
  node_tsconfig["TypeScript config<br/>tool config<br/>[tsconfig.json]"]
end

node_consumer["Consumer app<br/>external consumer"]
node_rpc[("RPC endpoint<br/>external network")]

node_consumer -->|"uses API"| node_index
node_index -->|"re-exports"| node_common
node_index -->|"exposes"| node_web3
node_index -->|"exposes"| node_ethers
node_web3 -->|"shares logic"| node_common
node_ethers -->|"shares logic"| node_common
node_web3 -->|"loads ABI"| node_abi_artifacts
node_ethers -->|"loads ABI"| node_abi_artifacts
node_common -->|"calls contract"| node_checker
node_checker -->|"executes on"| node_rpc
node_consumer -.->|"reads balances"| node_rpc
node_migrations -->|"deploys"| node_checker
node_contract_test -->|"verifies"| node_checker
node_export_abi -->|"publishes"| node_abi_artifacts
node_src_abis -->|"feeds"| node_export_abi
node_package_json -->|"scripts"| node_export_abi
node_package_json -->|"builds with"| node_tsconfig
node_truffle -->|"configures"| node_migrations

click node_checker "https://github.com/paxosglobal/eth-balance-checker/tree/master/contracts"
click node_migrations "https://github.com/paxosglobal/eth-balance-checker/tree/master/migrations"
click node_contract_test "https://github.com/paxosglobal/eth-balance-checker/blob/master/test/BalanceCheckerTest.js"
click node_index "https://github.com/paxosglobal/eth-balance-checker/blob/master/src/index.ts"
click node_common "https://github.com/paxosglobal/eth-balance-checker/blob/master/src/common.ts"
click node_web3 "https://github.com/paxosglobal/eth-balance-checker/blob/master/src/web3.ts"
click node_ethers "https://github.com/paxosglobal/eth-balance-checker/blob/master/src/ethers.ts"
click node_abi_artifacts "https://github.com/paxosglobal/eth-balance-checker/tree/master/abis"
click node_src_abis "https://github.com/paxosglobal/eth-balance-checker/tree/master/src/abis"
click node_export_abi "https://github.com/paxosglobal/eth-balance-checker/blob/master/scripts/export-abi.js"
click node_package_json "https://github.com/paxosglobal/eth-balance-checker/blob/master/package.json"
click node_truffle "https://github.com/paxosglobal/eth-balance-checker/blob/master/truffle-config.js"
click node_tsconfig "https://github.com/paxosglobal/eth-balance-checker/blob/master/tsconfig.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_common,node_web3,node_ethers toneBlue
class node_checker,node_migrations,node_contract_test toneAmber
class node_abi_artifacts,node_src_abis,node_export_abi,node_package_json,node_truffle,node_tsconfig toneMint
class node_consumer,node_rpc toneNeutral
```

## Components

### Off-chain library

TypeScript package and client adapters used by consumers.

- [Index API](https://github.com/paxosglobal/eth-balance-checker/blob/master/src/index.ts): ts entrypoint · Primary package entry point that re-exports the public API. · `src/index.ts`
- [Shared logic](https://github.com/paxosglobal/eth-balance-checker/blob/master/src/common.ts): ts core · Common balance-query and result-normalization logic. · `src/common.ts`
- [Web3 adapter](https://github.com/paxosglobal/eth-balance-checker/blob/master/src/web3.ts): ts adapter · web3.js integration for the balance-checking API. · `src/web3.ts`
- [Ethers adapter](https://github.com/paxosglobal/eth-balance-checker/blob/master/src/ethers.ts): ts adapter · ethers.js integration for the balance-checking API. · `src/ethers.ts`

### On-chain contract

Solidity contract and deployment path for balance aggregation.

- [BalanceChecker](https://github.com/paxosglobal/eth-balance-checker/tree/master/contracts): solidity contract · On-chain aggregation contract that returns many balances in one call. · `contracts`
- [Migrations](https://github.com/paxosglobal/eth-balance-checker/tree/master/migrations): truffle deploy · Truffle migration scripts that deploy the contract stack. · `migrations`
- [Contract tests](https://github.com/paxosglobal/eth-balance-checker/blob/master/test/BalanceCheckerTest.js): test suite · Solidity behavior verification for BalanceChecker. · `test/BalanceCheckerTest.js`

### Build and artifacts

Packaging, ABI export, and repository-level build configuration.

- [ABI artifacts](https://github.com/paxosglobal/eth-balance-checker/tree/master/abis): published abi set · Distributable contract ABI files consumed by the library and clients. · `abis`
- [ABI source](https://github.com/paxosglobal/eth-balance-checker/tree/master/src/abis): source abi import · Source-side ABI copies used during packaging. · `src/abis`
- [ABI export](https://github.com/paxosglobal/eth-balance-checker/blob/master/scripts/export-abi.js): node script · Copies Solidity ABI outputs into the published package layout. · `scripts/export-abi.js`
- [Package config](https://github.com/paxosglobal/eth-balance-checker/blob/master/package.json): npm manifest · Build scripts, entry points, and package metadata. · `package.json`
- [Truffle config](https://github.com/paxosglobal/eth-balance-checker/blob/master/truffle-config.js): tool config · Contract build and deployment configuration. · `truffle-config.js`
- [TypeScript config](https://github.com/paxosglobal/eth-balance-checker/blob/master/tsconfig.json): tool config · Compiler settings for the distributable library. · `tsconfig.json`

### Other components

- **Consumer app**: external consumer · Application using the balance query API.
- **RPC endpoint**: external network · Blockchain node endpoint for the target EVM chain.

## Connections

- 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.
