A practical data architecture for normalizing wallet charts across account-based and UTXO networks without erasing chain-specific meaning.
A multi-chain wallet chart is easy to describe and hard to model. The interface may promise one portfolio, but the underlying networks disagree about accounts, assets, transaction structure, finality, fees, token standards, and historical state. A design that flattens everything into “address, token, balance” becomes brittle. A design that preserves every chain-specific detail without a common layer becomes impossible to summarize.
The solution is a layered data model. Common entities support aggregation, while network adapters preserve native semantics and evidence. This guide lays out a practical model for chains, accounts, assets, positions, events, prices, and transfers. It also explains how to handle bridge movements, decimals, time, and confidence so that one chart can remain understandable without pretending that all networks behave alike.
A chain identifier should be stable, unambiguous, and separate from a marketing name. Chain names can collide, test networks can resemble main networks, and ecosystems can contain many execution environments. The CAIP-2 blockchain identifier specification is one established approach to representing blockchains with a namespace and reference. Whether or not a system adopts that exact format, the chart should use a canonical identifier internally.
Store human-readable names, native currency, explorer templates, finality assumptions, and adapter version as metadata attached to the identifier. Never join records by the label “mainnet” alone. A chain switch, fork, or migration should produce explicit mapping events rather than silently changing the meaning of old records.
An account record needs chain identifier, address or script descriptor, account type, scope source, and optional owner grouping. Account type may include externally controlled account, contract, token account, stake account, UTXO descriptor, program-derived address, or another chain-native category. Do not force UTXO wallets into an account schema that assumes one balance field. Instead, let the account reference the outputs or state objects from which balances are derived.
Owner grouping should be separate from account identity. One person can control several accounts, while one contract account may represent many users. A group can be user-supplied, wallet-supplied, or inferred. Store the method and confidence. This allows the portfolio view to aggregate known accounts while an investigative view can explore possible relationships without presenting them as verified ownership.
An asset record should combine chain, asset namespace or standard, contract or mint identifier, and a sub-identifier when needed. Native assets require a reserved identity rather than a fake contract address. Symbols, names, logos, decimals, and categories are metadata that can change or conflict. The immutable identity should remain available in every detail view and export.
Cross-chain exposure groups belong in a separate mapping table. Native ETH, wrapped ETH, liquid-staking tokens, and bridged ETH representations may all have ETH-related economic exposure, but they are not the same instrument. A group can connect them for risk analysis while preserving individual identity, issuer or protocol dependence, and redemption path.
Networks and token contracts store integer base units, while interfaces display decimal quantities. Keep the raw integer and declared decimals rather than storing only a floating-point number. Metadata errors can otherwise create dramatic valuation mistakes. When decimals change or a token migrates, record a versioned mapping and transformation event instead of rewriting history.
Portfolio calculations should use decimal or arbitrary-precision arithmetic. Rounding belongs at the display layer. The chart can show a concise quantity while an inspection panel reveals exact units. For assets with rebasing or share-based accounting, store both shares and derived underlying quantity with the conversion rate and timestamp used.
Each chain adapter can emit a common event envelope containing chain, transaction identifier, block or slot reference, time, status, fee, involved accounts, raw evidence pointer, and one or more normalized actions. Actions can include transfer, swap, mint, burn, approve, stake, borrow, repay, claim, deposit, or an unknown interaction. The raw payload remains authoritative; the normalized action is an interpretation with a parser version and confidence.
A single transaction can produce several actions. Group them into an economic event when they express one user intent, but retain the individual legs. This enables a readable timeline and exact reconciliation. Unknown actions should remain unknown. Forcing every event into a familiar category creates neat charts that are wrong in ways users cannot detect.
A position is an economic interpretation assembled from balances, protocol state, and events at a timestamp. It can represent a direct asset, lending supply, debt, pool share, stake, vault, derivative, or tokenized claim. Store the resolver, protocol version, underlying components, liabilities, valuation method, and evidence accounts. Positions are snapshots or time-indexed states, not timeless properties of a token.
The top-level portfolio should sum position net values according to explicit inclusion rules. Direct holdings that are already represented inside a resolved position must be excluded from the total to prevent double counting. When a resolver fails or becomes stale, fall back to visible direct assets and flag the coverage change instead of silently preserving an old derived value.
A bridge usually produces an outflow on one network and an inflow or claim on another. Without reconciliation, the time gap can look like a loss followed by a deposit. Match candidate events using bridge contracts, messages, amounts, assets, and time windows, then label the pair as a cross-chain transfer. Keep the bridge fee and any amount difference visible.
The received asset may not be identical to the source asset. It can be a wrapped claim with additional bridge risk. A multi-chain chart should offer two views: capital flow, where the matched bridge is internal to the portfolio, and instrument exposure, where the source and destination assets remain distinct. If the match is uncertain, present a suggested link rather than automatically rewriting flow history.
Networks produce timestamps and finality states differently. Store chain-native block references, observed time, and a normalized UTC timestamp. Historical charts should document when an event becomes included: first seen, confirmed, finalized, or another chain-specific threshold. Reorganizations or reverted transactions should create status updates rather than being deleted without trace.
Price observations need asset identity, quote currency, source, market, timestamp, and confidence. A price sampled every minute should not be paired with a balance sampled once daily without saying so. Use consistent valuation cutoffs for portfolio snapshots and preserve unpriced quantities. When multiple markets disagree materially, the system can show a range or source choice instead of hiding the divergence.
Every normalized field should be traceable to a source: raw node response, indexed event, verified token list, protocol resolver, user label, or external price feed. Store provenance and parser versions so historical results can be reproduced. Confidence is especially important for labels, owner clusters, bridge matches, and protocol interpretations. Direct onchain quantities may be certain while the meaning assigned to them is only probable.
The interface does not need to overwhelm readers with provenance on every screen. It can use compact status badges and reveal details on demand. What matters is that the data model supports the explanation. A multi-chain chart earns trust when a user can move from a portfolio total to the positions, events, assets, accounts, and raw evidence that produced it.
Multi-chain wallet charting works when common entities support aggregation and chain adapters preserve native meaning. Use canonical chain and asset identifiers, precise quantities, versioned event interpretations, resolvable positions, explicit bridge reconciliation, aligned timestamps, and pervasive provenance. Do not flatten away uncertainty. A flexible model can provide one coherent portfolio while still respecting the different rules beneath each network.
Category: Data Architecture
Learn how a useful wallet chart turns balances, transactions, allocation, and risk signals into a coherent visual story without confusing price movement with portfolio performance.
A practical framework for charting Ethereum accounts, ERC-20 balances, contract interactions, gas, staking, lending, and other onchain positions.
Understand Solana wallet charts through the network’s account model, token accounts, programs, instructions, fees, compressed assets, and high-frequency activity.