ERC-8242: H3 Spatial Identity Extension for On-Chain Agents

Abstract

ERC-8242 defines IERC8242, a standard on-chain interface for registering and discovering agent spatial identity using Uber's H3 hexagonal hierarchical indexing system. Any contract, scheduler, or off-chain client can call discoverAgents() to resolve agents by spatial identity without relying on a centralised directory. This standard is a pure metadata extension: it does not define transport, execution, or networking layers.

Motivation

Autonomous agents operating across decentralised networks increasingly need to express spatial context for routing, selection, and coordination. Today there is no standard on-chain interface for agent spatial identity: each protocol invents a proprietary mechanism, creating fragmentation and lock-in.

H3 hexagonal indexing provides a compact, hierarchical representation of spatial identity at resolutions 0–15 (global to ~1 m²). By anchoring spatial metadata on-chain via a common interface, ERC-8242 enables:

• Composable spatial discovery — any contract or on-chain scheduler can call discoverAgents(h3Parent, resolution, preference, offset, limit) to resolve agents by execution locality at execution time, with no off-chain infrastructure dependency.
• Routing hints — execution_preference signals whether an agent prefers local, regional, or global task assignment; consumers treat this as a non-binding agent selection signal.
• Lightweight metadata — no bond, no fee, no transport fields, no networking assumptions. A single spatial object is all that is required.
• Backward compatible — if a spatial record is absent, the agent is assumed "global".

Example: an on-chain intent-layer contract selects an agent for a localised task by calling discoverAgents(parentCell, 5, Local, 0, 10). No DNS lookup, no off-chain API call — the spatial routing decision is fully reproducible on-chain.

This standard addresses a gap not covered by any existing ERC: there is no application-layer interface for on-chain spatial identity of agents with hierarchical spatial filtering.

Specification

The key words "MUST", "MUST NOT", "SHOULD", "MAY" in this document are to be interpreted as described in RFC 2119.

Definitions

Enums

enum ExecutionPreference {
    Local,     // Prefer tasks within the same H3 cell or immediate neighbours
    Regional,  // Prefer tasks within parent cells up to resolution 3
    Global     // No spatial preference (default)
}

Structs

struct SpatialRecord {
    address             agent;
    string              h3Index;       // H3 cell identifier string
    uint8               resolution;    // H3 resolution (0–15)
    ExecutionPreference preference;    // Routing hint; consumers MUST treat as non-binding
    uint64              registeredAt;  // UNIX timestamp set on creation; MUST NOT change thereafter
    uint64              updatedAt;     // UNIX timestamp of most recent mutation; equals registeredAt on creation
}

Interface

interface IERC8242 {
    function registerSpatial(
        string calldata     h3Index,
        uint8               resolution,
        ExecutionPreference preference
    ) external;

    function updateSpatial(
        string calldata     h3Index,
        uint8               resolution,
        ExecutionPreference preference
    ) external;

    function deregisterSpatial() external;

    function getSpatial(address agent)
        external view returns (SpatialRecord memory);

    function discoverAgents(
        string calldata     h3Parent,
        uint8               resolution,
        ExecutionPreference preference,
        uint256             offset,
        uint256             limit
    ) external view returns (SpatialRecord[] memory records, uint256 total);
}

Methods

registerSpatial

function registerSpatial(
    string calldata     h3Index,
    uint8               resolution,
    ExecutionPreference preference
) external;

• MUST revert if h3Index is empty.
• MUST revert if the caller is already registered.
• MUST revert if resolution > 15.
• MUST set registeredAt = block.timestamp and updatedAt = block.timestamp.
• MUST emit SpatialRegistered(agent, h3Index, preference).
• MUST NOT collect any fee or bond.

updateSpatial

function updateSpatial(
    string calldata     h3Index,
    uint8               resolution,
    ExecutionPreference preference
) external;

• MUST only be callable by the registered agent (msg.sender matches stored record).
• MUST NOT collect any fee.
• MUST set updatedAt = block.timestamp.
• MUST emit SpatialUpdated(agent, h3Index, preference).

deregisterSpatial

function deregisterSpatial() external;

• MUST delete the spatial record for msg.sender.
• MUST emit SpatialDeregistered(agent).

getSpatial

function getSpatial(address agent)
    external view returns (SpatialRecord memory);

• MUST return the full SpatialRecord for the given agent.
• MUST return an empty record (all zero/default values) if no record exists.

discoverAgents

function discoverAgents(
    string calldata     h3Parent,
    uint8               resolution,
    ExecutionPreference preference,
    uint256             offset,
    uint256             limit
) external view returns (SpatialRecord[] memory records, uint256 total);

• MUST filter by agents whose h3Index is a child of h3Parent at the given resolution when h3Parent is non-empty.
• MUST filter by preference when preference != ExecutionPreference.Global.
• offset / limit provide pagination.
• Results MUST be ordered by ascending registeredAt to ensure consistent, non-duplicating pagination across calls.
• SHOULD return all registered agents when h3Parent is empty and preference == ExecutionPreference.Global.

Events

event SpatialRegistered(
    address indexed     agent,
    string              h3Index,
    ExecutionPreference preference
);

event SpatialUpdated(
    address indexed     agent,
    string              h3Index,
    ExecutionPreference preference
);

event SpatialDeregistered(address indexed agent);

ERC-165

Compliant contracts MUST implement the IERC8242 interface defined by this standard and MUST return true from supportsInterface for type(IERC8242).interfaceId.

Off-Chain JSON Schema

For off-chain agent identity documents (e.g., DID documents, registration files), the canonical spatial object is:

{
  "spatial": {
    "h3_index": "8928308280fffff",
    "resolution": 5,
    "execution_preference": "local"
  }
}

If spatial is not present in an agent document, the agent MUST be treated as having execution_preference = "global".

Validation Rules

• h3_index — REQUIRED when spatial is present; SHOULD be a valid 15-character hex H3 cell string.
• resolution — REQUIRED; integer in range 0–15.
• execution_preference — OPTIONAL; default "global".

Rationale

• H3 over geohash or S2 — H3 provides uniform hexagonal cells with consistent neighbour topology, well-suited for agent routing. The string-encoded cell IDs are human-readable and unambiguous at all resolutions.
• No bond or fee — Spatial identity is a lightweight metadata claim. Economic friction would deter adoption without meaningful Sybil resistance benefit; spatial cells are non-exclusive and non-rivalrous.
• execution_preference as hint — Treating execution locality as a non-binding signal keeps the standard composable: consumers apply their own scoring. A hard constraint would require on-chain spatial proofs, which is out of scope.
• No transport fields — Transport, networking, and execution infrastructure are deliberately excluded. This extension standardizes spatial identity for agents using H3 indexing. It does not define transport, execution, or networking layers.
• Registration-order pagination — Ordering by registeredAt ascending ensures deterministic, stable pagination even as new entries are added.

Backwards Compatibility

No existing ERC is modified. If a spatial record is absent for an agent, consumers MUST treat that agent as execution_preference = "global". ERC-8242 is composable with any agent identity or registry standard.

Reference Implementation

A reference implementation is available as contracts/ERC8242SpatialIdentity.sol in the Opacus-Standart repository.

Security Considerations

• Self-reported claims — h3Index and execution_preference are self-reported and cannot be verified on-chain. Consumers MUST treat spatial records as non-binding routing hints only.
• No financial risk — This standard involves no bonds, fees, or token transfers, eliminating reentrancy and token-approval attack surfaces entirely.
• H3 index validation — h3Index is stored as an opaque string. Implementations SHOULD validate that it is a well-formed H3 cell identifier in registerSpatial to prevent malformed entries.
• Pagination stability — Consumers paginating discoverAgents results MUST be aware that new registrations may shift total counts between calls.

Copyright

Copyright and related rights waived via CC0.