Entity

An entity is a distinct, identifiable actor, object, or component within a system that can be uniquely referenced and can perform actions or hold state. In blockchain contexts, common entities include user accounts (controlled by private keys), smart contracts, validator nodes, and decentralized autonomous organizations (DAOs). Each entity is defined by a unique identifier, such as an Ethereum address (0x...) or a public key, which allows the network to track its interactions, permissions, and asset ownership. This precise identification is the foundation for accountability and programmability in decentralized systems.

The concept is critical for understanding on-chain interactions. Every transaction is an action initiated by one entity (the sender) targeting another (the recipient or contract). For example, when a user swaps tokens on a decentralized exchange, the entities involved are the user's wallet, the liquidity pool's smart contract, and the token contracts. This entity-centric model enables the transparent audit trail inherent to blockchains, as all state changes are permanently linked to the addresses of the participating entities.

Beyond simple accounts, entities can be complex and autonomous. A smart contract is a non-human entity that executes code when triggered, holding its own balance and state. A DAO is a higher-order entity governed by the collective actions of its member token holders. In zero-knowledge proof systems, an entity might be represented by a cryptographic commitment rather than a public address, balancing identifiability with privacy. Understanding the types and capabilities of entities is essential for analyzing network security, governance, and economic flows.

From a data modeling perspective, entities and their relationships form the core of blockchain analytics. Tools like The Graph index on-chain data by structuring it around entities (e.g., a specific DeFi protocol) and their events (e.g., deposits, swaps). This abstraction allows developers and analysts to query complex interactions without parsing raw transaction logs. The precise definition and isolation of entities ensure that decentralized applications can interoperate predictably, knowing exactly with whom or what they are transacting.

An entity is the primary data model within a subgraph or indexing framework like The Graph. It defines the schema for a specific type of record, such as a User, TokenTransfer, or Pool. Each entity has a unique ID and a set of typed fields (e.g., String, BigInt, Bytes) that store its state and attributes. When an indexer processes blockchain events, it creates, updates, or deletes entity instances based on the logic defined in the subgraph's mapping handlers, effectively translating raw, sequential blockchain data into a queryable graph database.

The power of entities lies in their relationships. Entities can be linked through fields, enabling complex graph-like queries. For example, a Transaction entity can have a from field linking to a Wallet entity and an involvedTokens field linking to multiple Token entities. This relational structure allows developers to query interconnected data in a single request—such as "fetch all transactions for this wallet and the associated token details"—which would require multiple, inefficient calls to a standard blockchain node. Indexers use these defined relationships to optimize data storage and retrieval.

Entity state management is deterministic and event-driven. The indexer's data source specifies which smart contracts and events to monitor. When a relevant event (like a Transfer) is emitted, the mapping handler executes, loading the current state of related entities, applying the business logic from the event data, and then saving the updated entities back to the store. This process ensures the indexed database is a materialized view that reflects the cumulative state of the blockchain up to the indexed block, enabling fast and complex queries that are impossible directly from an RPC endpoint.

In the context of blockchain analytics, an entity schema is a blueprint that specifies the properties and connections for a class of on-chain actors or assets, such as wallets, smart contracts, tokens, or DAOs. It transforms raw, low-level blockchain data—like transaction hashes and log events—into semantically meaningful, queryable objects. For example, a TokenTransfer entity schema would define fields for from_address, to_address, amount, token_address, and block_timestamp, creating a consistent model for all transfer events across different protocols.

The definition process involves mapping smart contract events and transaction traces to predefined entity types and their properties. This is often done using a specialized query language or abstraction layer, such as those provided by The Graph's subgraphs or Dune Analytics' spellbooks. A well-designed schema acts as an abstraction layer, insulating analysts from the underlying complexity of raw chain data and enabling them to ask business-logic questions (e.g., 'total daily DEX volume') instead of technical ones (e.g., 'decode all Swap events from this ABI').

Implementing an entity schema provides critical structure for on-chain data indexing and decoding. It allows analytics platforms to efficiently organize, relate, and cache data, powering everything from dashboards to complex financial models. Key related concepts include data normalization, which ensures consistency across sources, and entity resolution, which is the process of linking multiple addresses or identifiers to a single real-world actor, such as a protocol treasury or a known investor.

For developers and data engineers, defining a robust entity schema is a foundational step in building reliable blockchain applications. It dictates how data is ingested, transformed, and served. Common challenges include handling upgradable contracts where event signatures change, managing the sheer volume of chain data, and designing schemas that are both specific enough to be useful and flexible enough to accommodate future protocol changes without requiring a complete overhaul of downstream applications.

In data modeling, an entity is a distinct object or concept—like a user, transaction, or smart contract—about which data is stored. A schema formally defines this entity's structure using attributes (or fields) that describe its properties and relationships to other entities. For example, in a blockchain indexing context, an Account entity would be defined with attributes for its address, balance, and a relationship to a list of associated Transaction entities. This structured definition serves as a blueprint for how data is organized, queried, and interconnected within a database or an indexing service like The Graph.

The definition of an entity within a schema is typically expressed in a schema definition language (SDL), such as GraphQL SDL or a similar declarative syntax. Key components include the type keyword to declare the entity, followed by a list of its fields and their data types (e.g., String, ID, BigInt). Relationships are defined by field types that reference another entity type, often indicating a one-to-many or many-to-one connection. This explicit schema enables powerful, type-safe querying, ensuring that applications request only valid combinations of data and receive it in a predictable shape.

Consider a simplified schema for a decentralized application tracking non-fungible tokens (NFTs). An NFT entity might be defined with fields for id, tokenId, owner (linking to an Account), and collection (linking to a Contract). Simultaneously, a Transfer entity would log events, with fields for from, to, timestamp, and a relationship back to the NFT. This relational structure allows complex queries, such as "fetch all NFTs owned by a specific address along with their transfer history," to be executed efficiently by the underlying indexing engine, transforming raw blockchain data into a queryable graph of entities.