Skip to main content
An entity is the addressable unit on the Grid. Every wallet, every agent, every service you interact with on the chain is an entity. Entities hold state and execute work in response to incoming activations.

​
What an entity is

An entity has three things:
  • An identity: an EntityID derived from the hash of a public key. The holder of the matching private key authorizes activations on the entity. The entity is encoded as a bech32m address (the grd@… strings you see in the CLI and RPC).
  • Components: entity is a container of components; each component is a logic-and-state module installed inside the entity.
  • Execution: an entity is the smallest unit of execution. An entity processes one activation at a time, and that activation can span the execution of a few components.
There is no separate “contract address” construct on the Grid. A wallet, an agent, a merchant, and a token issuer are all entities. They differ only in which components they install, not in what kind of thing they are.

​
Coming from Ethereum

The closest analogue to an entity is an Ethereum account, but the Grid is built for distributed state. For example, on Ethereum a token usually keeps a single global balances map inside the token contract; here, each holder’s balance typically lives in the holder’s own entity, inside that holder’s component instance—so token state is naturally spread across many entities rather than centralized in one contract.

​
One entity, many components

A single entity can hold many components. A wallet entity might hold:
  • A separate token-holder component for each stablecoin the user holds.
  • An agent-related component (for example, recording what an agent is allowed to spend on the user’s behalf).
Each component owns its own slice of the entity’s state and is addressed by an index inside the entity. See Address format for how a component’s index is encoded into the address.

​
Why entities matter for performance

Entities are the execution unit and can be executed in parallel. Activations targeting entity A do not block activations targeting entity B. The runtime can process them concurrently. This is why a busy entity does not slow the rest of the chain. See Parallel execution.