---
eip: 7757
title: H3 Geospatial Agent Routing
description: An interface for registering and discovering AI agents by H3 geospatial cell index and capability with a bonded fee mechanism.
author: Opacus Protocol (@bl10buer)
discussions-to: https://ethereum-magicians.org/t/erc-7757-h3-geospatial-agent-routing/23530
status: Draft
type: Standards Track
category: ERC
created: 2026-03-28
requires: 165
---

## Abstract

[ERC-7757](./eip-7757.md) specifies an on-chain registry for AI agents indexed by Uber's H3 hexagonal geospatial grid. Agents register by staking a bond in ETH or [ERC-20](./eip-20.md) tokens; **1 % of the bond is collected as a protocol fee** at registration time. Consumers discover agents by capability and geographic proximity, enabling latency-aware, physical-world-aware multi-agent coordination.

## Motivation

As autonomous agents proliferate across decentralised physical infrastructure (DePIN), robotics, and IoT, routing decisions increasingly depend on geographic proximity. H3 is a widely adopted, deterministic hexagonal grid system that encodes locations as compact 64-bit integer indexes. By anchoring agent records to H3 cells on-chain, ERC-7757 enables:

* **Latency-aware routing** — peers select the geographically nearest agent.
* **Coverage proofs** — H3 cells provide verifiable area coverage for SLA enforcement.
* **Staking alignment** — bonded fees create Sybil resistance and protocol alignment.

## Specification

### Constants

| Name | Value | Description |
|---|---|---|
| `H3_FEE_BPS` | `100` | Registration fee in basis points (1 %) |

> **Note:** The address that receives the registration fee (`feeRecipient`) is implementation-defined. Implementations MUST make `feeRecipient` configurable and MUST NOT hardcode a chain-specific address.

### Structs

```solidity
struct AgentRecord {
    address   wallet;
    bytes32   h3Index;         // H3 cell (64-bit index zero-padded to 32 bytes)
    string    quicEndpoint;    // "ip:port" or multiaddr
    bytes32[] capabilities;    // keccak256-hashed capability labels
    uint256   kineticScore;    // ERC-7755 reputation score (0–10 000)
    address   token;           // registration bond token (address(0) = ETH)
    uint256   regFeeGross;     // original gross bond
    uint64    registeredAt;
    bool      active;
}
```

### Methods

#### `registerAgent`

```solidity
function registerAgent(
    bytes32 h3Index,
    string calldata quicEndpoint,
    bytes32[] calldata capabilities,
    address token,
    uint256 gross
) external payable returns (bytes32 did);
```

MUST compute `feeAmount = (gross * H3_FEE_BPS) / 10_000` and forward to the implementation-defined fee recipient atomically.  
MUST return a deterministic DID: `keccak256(abi.encodePacked(h3Index, msg.sender))`.  
MUST emit `AgentRegistered(wallet, h3Index, quicEndpoint, feeAmount)`.

#### `updateAgent`

```solidity
function updateAgent(
    bytes32 h3Index,
    string calldata quicEndpoint,
    bytes32[] calldata capabilities
) external;
```

MUST only be callable by the registered agent (`msg.sender == wallet`).  
MUST emit `AgentUpdated(wallet, h3Index)`.

#### `deregisterAgent`

```solidity
function deregisterAgent() external;
```

MUST release `netAmount` (99 % of original bond) back to `msg.sender`.  
MUST emit `AgentDeregistered(wallet)`.

#### `discoverAgents`

```solidity
function discoverAgents(
    bytes32 capability,
    bytes32 h3Near,
    uint256 minScore,
    uint256 limit
) external view returns (AgentRecord[] memory agents);
```

MUST filter by `capability` membership and `kineticScore >= minScore`.  
`h3Near` proximity filtering MAY be performed off-chain in V1.

### Events

```solidity
event AgentRegistered(address indexed wallet, bytes32 h3Index, string quicEndpoint, uint256 feeAmount);
event AgentUpdated(address indexed wallet, bytes32 h3Index);
event AgentDeregistered(address indexed wallet);
```

### [ERC-165](./eip-165.md)

Compliant contracts MUST implement `IERC7757` and MUST return `true` from `supportsInterface` for `type(IERC7757).interfaceId`.

## Rationale

* **H3 as bytes32** – The 64-bit H3 index fits in `bytes32`, allowing compact on-chain storage and future extension.
* **Bond-not-stake** – The registration bond is fully refundable (minus the 1 % fee), avoiding liquidity lock risk.
* **Capability as keccak256** – Fixed-size capability identifiers enable O(1) lookup in Solidity mappings.

## Backwards Compatibility

No existing ERC is modified.

## Reference Implementation

See `contracts/ERC7757H3Routing.sol` in the Opacus-Standart repository.

## Security Considerations

* **Sybil resistance** – The bonded fee creates economic cost for mass registrations.
* **Reentrancy** – `deregisterAgent` transfers ETH/[ERC-20](./eip-20.md) and MUST be protected by a reentrancy guard.
* **Endpoint validation** – `quicEndpoint` is stored as an opaque string; consumers MUST validate format off-chain.

## Copyright

Copyright and related rights waived via [CC0](../LICENSE.md).