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).
  • State: owned by the components installed inside the entity. The entity itself is a container; the components hold the actual data.
  • Execution: when an activation arrives addressed to the entity, the runtime dispatches it to the targeted component, or to the default account component if no target is specified.
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. The state that on Ethereum lives inside a single token contract (mapping every address to its balance) instead lives inside each holder’s own entity, in their own component instance. There is no shared global storage.

​
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 unit of parallel execution. Activations targeting entity A do not block activations targeting entity B. The runtime processes them concurrently, on different shards if their entities are placed on different shards. This is why a busy entity does not slow the rest of the chain. See Parallel execution.