ERC-7757: H3 Geospatial Agent Routing

Abstract

ERC-7757 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 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

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

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

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

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

function deregisterAgent() external;

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

discoverAgents

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

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

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 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.