Shared Balance Mapping is a data indexing technique used to aggregate and track the total holdings of a specific token or asset across a predefined set of blockchain addresses, treating them as a single logical entity. Instead of querying individual wallet balances in isolation, this method creates a unified view by summing the balances from all addresses in the mapped group. This is essential for analyzing the consolidated holdings of entities like decentralized autonomous organizations (DAOs), venture funds, or protocol treasuries that manage assets across multiple wallets for security or operational reasons.
LABS
Glossary
Shared Balance Mapping
Shared Balance Mapping is a core data structure in the ERC-1155 multi-token standard that enables a single smart contract to manage multiple token types (fungible, non-fungible, semi-fungible) by tracking balances per address and token ID in a unified mapping.
Chainscore © 2026
definition
BLOCKCHAIN DATA INDEXING
What is Shared Balance Mapping?
A method for tracking token ownership across multiple blockchain addresses by aggregating balances from a defined set of wallets.
The process relies on an indexer or data service that continuously monitors the on-chain state of the included addresses. When a transfer occurs to or from any address in the mapped set, the aggregate shared balance is recalculated. This provides a real-time, holistic view of an entity's financial position without requiring manual summation. Key technical components include the mapping definition (the list of constituent addresses), the asset contract (e.g., an ERC-20 token address), and the indexing logic that polls blockchain nodes or listens for event logs to update balances.
A primary use case is in decentralized finance (DeFi) and governance, where understanding the voting power or financial clout of an entity requires knowing its total stake, which may be spread across cold wallets, multisigs, and smart contracts. For example, a DAO's treasury balance might be mapped across a Gnosis Safe, a vesting contract, and a deployer wallet. This aggregated data is critical for dashboards, risk analysis, and on-chain analytics tools that need to present a complete picture of entity-level exposure rather than fragmented address-level data.
how-it-works
MECHANISM
How Shared Balance Mapping Works
Shared Balance Mapping is a technical mechanism that enables a single user balance to be represented and tracked across multiple, distinct blockchain addresses or smart contracts.
Shared Balance Mapping is a state management pattern in blockchain development where a user's total token balance is not stored in a single address but is instead aggregated from multiple, often non-custodial, locations. This is achieved by linking a primary user identifier, such as a master public key or a smart contract wallet address, to a set of secondary addresses or contract states. The system maintains a mapping that defines which balances belong to the same logical user, allowing for a unified view and management of assets that are physically dispersed across the chain. This is foundational for features like gas abstraction, session keys, and account abstraction.
The mechanism typically relies on a smart contract acting as a central ledger or resolver. This contract does not hold user funds directly but maintains an on-chain record—the map—that associates the user's root account with a list of delegated addresses or balance slots. When a user initiates a transaction, the contract logic consults this map to validate that the sum of balances across all linked addresses is sufficient. This allows users to spend from a shared pool of funds without manually consolidating them, significantly improving the user experience for complex DeFi interactions or gaming applications.
A common implementation is found in gas sponsorship systems. Here, a user may have assets in a decentralized exchange liquidity pool, a lending protocol vault, and a simple wallet. A Shared Balance Map allows a relayer or a smart wallet to pay the transaction fee by drawing from the combined value of these scattered assets, as defined by the map, without requiring pre-funded gas tokens in the executing address. The security model is critical: the mapping is often permissioned, requiring cryptographic signatures from the root key to add or remove linked addresses, preventing unauthorized balance aggregation.
key-features
MECHANISM
Key Features of Shared Balance Mapping
Shared Balance Mapping is a foundational blockchain accounting model that enables a single token balance to be simultaneously utilized across multiple, distinct smart contracts or protocols without requiring token transfers.
01
Non-Custodial Delegation
The core mechanism that allows a user's token balance to be programmatically accessible by other contracts while the user retains full custody. This is achieved through on-chain delegation or approval systems, where the user grants specific permissions (like spending allowances) to external protocols. The tokens never leave the user's wallet; instead, a verifiable claim to their use is created.
02
Composability & Parallel Yield
Enables a single token deposit to generate yield from multiple sources concurrently. For example, a user's ETH could be simultaneously:
- Supplied as collateral in a lending protocol (e.g., Aave).
- Staked in a liquid staking derivative (e.g., stETH).
- Deposited in a yield aggregator vault. This maximizes capital efficiency by eliminating the need to choose one use case over another.
03
State Synchronization
Requires a robust system to keep all interconnected protocols aware of the user's true, net balance. Changes in one protocol (e.g., a withdrawal) must be reflected across all others to prevent double-spending or over-collateralization. This is often managed via oracles, state proofs, or a central registry contract that acts as the source of truth.
04
Permissioned Access Control
Users define granular rules for how their shared balance can be used. This is not a blanket approval. Permissions can specify:
- Which protocols can access the balance.
- Maximum amounts that can be utilized.
- Specific functions allowed (e.g., 'borrow against' but not 'transfer').
- Time limits for access. This maintains user sovereignty and security within the shared framework.
05
Unified Liquidity Layer
Transforms isolated pools of capital in DeFi into a shared, network-wide liquidity resource. Instead of fragmented liquidity locked in individual protocols, assets can flow to where they are most needed based on real-time demand (e.g., for lending, trading, or insurance). This increases overall market depth and reduces slippage across the ecosystem.
06
Risk & Dependency Management
Introduces new systemic considerations. The failure or exploitation of one protocol in the mapping can cascade, potentially affecting the user's position in all connected protocols. Key risks include:
- Smart contract risk in the mapping layer itself.
- Oracle failure leading to incorrect balance states.
- Liquidation domino effects if collateral value drops. Users must audit the entire dependency graph of their shared balance.
code-example
SOLIDITY IMPLEMENTATION
Code Example: The Core Mapping
This section deconstructs the fundamental data structure used to track token ownership in an ERC-20 contract: the `mapping` from addresses to balances.
The core mapping in an ERC-20 contract is a Solidity mapping(address => uint256) private _balances; declaration that creates a key-value store linking each holder's address to their token balance. This data structure is the definitive source of truth for ownership, where the address acts as the unique key and the uint256 stores the corresponding token amount. It is typically declared as private or internal to enforce access through the contract's public functions, which implement the necessary logic and checks.
When a function like transfer(to, amount) is called, the contract logic performs critical operations on this mapping. It first checks that the sender's (msg.sender) balance in _balances is sufficient, then subtracts the amount from the sender's stored value and adds it to the recipient's (to) stored value. This state change is recorded on the blockchain. The public balanceOf(address account) function provides a view into this mapping, returning the uint256 value for any given address without modifying state.
This mapping-based architecture is efficient for lookups, which are constant-time O(1) operations, but it cannot be iterated over by default. To enable discovery of all token holders, a separate pattern, such as emitting events for each transfer or maintaining an enumerable extension, is required. The integrity of the entire token system depends on the secure and accurate updating of this single source of truth, making functions that modify _balances the most security-critical parts of the contract.
ecosystem-usage
SHARED BALANCE MAPPING
Ecosystem Usage & Protocols
Shared Balance Mapping is a foundational accounting primitive that enables protocols to track and manage user assets across multiple smart contracts or states within a single, unified ledger.
01
Core Mechanism
At its core, Shared Balance Mapping is a ledger system that maintains a single source of truth for a user's balance across fragmented protocol interactions. Instead of siloed balances in individual contracts, it uses a mapping structure (e.g., mapping(address => uint256)) that is referenced by multiple components. This allows for atomic updates and consistent state across deposits, withdrawals, and internal transfers without moving tokens.
02
Protocol Integration Pattern
Protocols implement shared balance mapping to unify liquidity and collateral. A user deposits assets into a central Vault or Pool contract, which credits their mapped balance. This balance can then be simultaneously used as collateral in a lending market, delegated to a staking contract, or provided to an automated market maker (AMM), all without requiring physical token transfers between modules.
03
Benefits: Capital Efficiency
This architecture dramatically improves capital efficiency by eliminating the need to lock tokens in separate, non-fungible positions. Key benefits include:
- Single Deposit, Multiple Uses: One deposit can serve as collateral for borrowing, earn yield, and provide liquidity.
- Reduced Gas Costs: Avoids expensive
transfercalls between contracts for internal accounting. - Atomic Composability: Complex multi-protocol transactions (e.g., flash loan -> swap -> repay) can be executed in one block with guaranteed consistency.
04
Example: DeFi Money Markets
In lending protocols like Aave or Compound, a user's supplied balance is a mapped entry. This balance:
- Earns interest continuously.
- Can be used as collateral to borrow other assets, creating a separate debt balance in the same shared system.
- Can be instantly liquidated if the collateral ratio falls, with the liquidator's repayment directly updating the mapped balances. The underlying
aTokensorcTokensare themselves representations of this mapped balance.
05
Security & Accounting Integrity
Maintaining a single ledger simplifies security audits and ensures accounting integrity. All balance changes must flow through a limited set of authorized updater functions, reducing the attack surface. It enables precise slippage protection and minimum output guarantees in decentralized exchanges (DEXs) by allowing trades to be validated against the final mapped state before execution.
06
Related Concept: Internal Accounting vs. Token Transfers
Shared balance mapping is distinct from simple token transfers. It's a form of internal accounting or balance sheet management. The actual ERC-20 tokens may reside in a single custodian contract, while the mapped ledger tracks ownership and utility rights. This is analogous to a bank's ledger tracking deposits and loans without moving physical cash, enabling features like rehypothecation of assets within the defined protocol rules.
TOKEN ACCOUNTING
Comparison: Balance Models Across Token Standards
How different token standards map user balances to on-chain state, from simple ledgers to complex nested structures.
| Balance Model | ERC-20 | ERC-721 | ERC-1155 | ERC-6909 |
|---|---|---|---|---|
Primary Data Structure | mapping(address => uint256) | mapping(uint256 => address) | mapping(uint256 => mapping(address => uint256)) | mapping(address => mapping(uint256 => uint256)) |
Account Model | Single-Balance Ledger | Owner-Item Registry | Nested Token Balances | Modular Account Abstraction |
Balance Query Complexity | O(1) | O(1) per token | O(1) per token per account | O(1) per token per account |
Batch Operations Support | ||||
Native Approval Model | Per-Spender Token Allowance | Per-Spender Token Approval | Per-Spender Token Allowance | Flexible, Decoupled Permissions |
Gas Overhead for Transfers | Low | High (per token) | Medium (scales with batch size) | Optimized for modular calls |
Typical Use Case | Fungible Assets (e.g., USDC) | Unique Assets (e.g., NFTs) | Mixed Fungible/Non-Fungible (e.g., game items) | Modular Smart Accounts & Composability |
security-considerations
SHARED BALANCE MAPPING
Security Considerations
Shared balance mapping is a smart contract design pattern where multiple user accounts or contracts are linked to a single, shared balance, often to optimize gas costs or simplify state management. This approach introduces unique security trade-offs that must be carefully evaluated.
01
Centralized Upgradeability Risk
Implementations often use a proxy pattern where logic is upgradeable. This centralizes control in an admin key, creating a single point of failure. If compromised, an attacker could upgrade the contract to a malicious implementation, potentially draining all shared funds. This risk is inherent to the design, not a bug.
02
Cross-User Contamination
A critical vulnerability arises if the mapping logic is flawed. For example, if a user's allowance or balance is incorrectly deducted from the shared pool, it can contaminate other users' funds. A single exploitable function can lead to mass, indiscriminate loss across all mapped accounts, not just the target of an attack.
03
Reentrancy & Logic Flaws
The shared state amplifies the impact of classic vulnerabilities. A reentrancy attack on a withdrawal function could drain the entire shared balance in a single transaction, rather than just one user's portion. Rigorous audits and adherence to checks-effects-interactions patterns are non-negotiable for this architecture.
04
Oracle & Price Manipulation
If the shared balance represents collateralized debt positions (e.g., in lending protocols), it relies on price oracles. A manipulated price feed can cause incorrect liquidations or allow an attacker to borrow against the entire shared pool at an artificially favorable rate, jeopardizing all participants' collateral.
05
Admin Key Management & Timelocks
Mitigating upgrade risks requires robust admin key management (multisigs, DAOs) and the use of a timelock contract. A timelock imposes a mandatory delay between a governance vote to upgrade and its execution, giving users a window to exit the system if a malicious proposal is passed.
06
Verification & Transparency
Users must verify they are interacting with the correct, non-malicious implementation contract. Tools like Etherscan's "Read as Proxy" and OpenZeppelin's Defender for upgrade transparency are critical. Always check that the proxy's implementation address matches the audited, verified contract code.
SHARED BALANCE MAPPING
Frequently Asked Questions
Shared Balance Mapping is a core mechanism for analyzing cross-chain and multi-protocol user activity. These questions address its technical implementation, use cases, and value for developers and analysts.
Shared Balance Mapping is a data modeling technique that aggregates a user's token holdings across multiple blockchain addresses and protocols into a single, unified view. It works by using on-chain heuristics and deterministic algorithms to link disparate addresses (like Externally Owned Accounts and smart contract wallets) to a single user entity, then querying and summing their token balances from various DeFi protocols, staking contracts, and wallets. This creates a holistic financial profile that transcends individual chains and applications.
For example, a user's total ETH balance would be calculated by summing their base ETH on Ethereum Mainnet, wrapped ETH (wETH) on Arbitrum, staked ETH (stETH) in Lido, and ETH deposited as collateral in Aave on Polygon. The mapping relies on identifiers like social recovery modules, deployer addresses, and transaction graph analysis to establish ownership links.
ENQUIRY
Get In Touch
today.
Our experts will offer a free quote and a 30min call to discuss your project.
NDA Protected
Confidentiality24h Response
Time to ValueDirectly to Engineering Team
No Sales Fluff10+
Protocols Shipped
$20M+
TVL Overall