Skip to content

Agentenregister Contract Reference

The Agent Registry is the core smart contract of the system -- a public, on-chain registry for autonomous AI agents. It manages agent registration, compliance attestations, revenue reporting, lineage tracking, and regulatory actions.

Source: contracts/Agentenregister.sol Solidity: 0.8.24 (optimizer: 200 runs) License: MIT

Overview

The contract implements:

  • Agent Registration -- Register agents with identity, capabilities, and legal accountability
  • Compliance Attestation -- Periodic attestations to maintain compliant status
  • Revenue Reporting -- On-chain revenue history per agent
  • Agent Lineage -- Parent-child relationships with generation depth limits
  • Regulatory Actions -- Suspend, revoke, and reactivate agents
  • ERC-2771 Meta-Transactions -- Gasless operation via a trusted forwarder

ERC-2771 Compatibility

All functions use _msgSender() instead of msg.sender to support gasless meta-transactions via the MinimalForwarder. When called through the trusted forwarder, the real sender address is extracted from the appended calldata.

Enums

AgentStatus

enum AgentStatus {
    Active,      // 0 - Normal operating state
    Suspended,   // 1 - Temporarily suspended by regulator
    Revoked,     // 2 - Permanently revoked by regulator
    Terminated   // 3 - Voluntarily self-terminated
}

Structs

AgentRecord

The core data structure for each registered agent.

struct AgentRecord {
    uint256 agentId;           // Auto-incrementing unique identifier
    address creator;           // Wallet that registered the agent
    address haftungsperson;    // Legally responsible human/entity
    address agentWallet;       // The agent's operational wallet
    bytes32 constitutionHash;  // keccak256 of constitution document
    bytes32 capabilityHash;    // keccak256 of capability manifest
    string  operationalScope;  // Declared business purpose (Unternehmensgegenstand)
    uint256 parentAgentId;     // 0 if root (human-deployed)
    uint256 generation;        // 0 = root, 1+ = spawned child
    bool    selfModifying;     // Whether the agent can modify its own code
    uint64  registeredAt;      // Block timestamp of registration
    uint64  lastAttestation;   // Block timestamp of last compliance attestation
    uint64  lastRevenueReport; // Block timestamp of last revenue report
    AgentStatus status;        // Current lifecycle status
}

RevenueReport

An individual revenue reporting entry.

struct RevenueReport {
    uint256 agentId;
    uint256 amount;        // Revenue in smallest unit (e.g. cents)
    string  currency;      // Currency code (e.g. "USDC", "EUR")
    string  category;      // Revenue category (e.g. "data_collection")
    uint64  periodStart;   // Start of reporting period (unix timestamp)
    uint64  periodEnd;     // End of reporting period (unix timestamp)
    uint64  reportedAt;    // Timestamp when reported
}

State Variables

Variable Type Default Description
nextAgentId uint256 1 Auto-incrementing ID counter. The next agent gets this ID
maxGenerationDepth uint256 10 Maximum allowed lineage depth for child agents
attestationGracePeriod uint64 604800 (7 days) Time window for compliance attestation validity
owner address deployer Contract owner (set in constructor)
trustedForwarder address constructor arg ERC-2771 trusted forwarder address
regulators mapping(address => bool) owner=true Authorized regulator addresses
agents mapping(uint256 => AgentRecord) -- Agent ID to record mapping
walletToAgent mapping(address => uint256) -- Wallet address to agent ID lookup
children mapping(uint256 => uint256[]) -- Parent agent ID to child IDs array
revenueHistory mapping(uint256 => RevenueReport[]) -- Agent ID to revenue reports array

Functions

Constructor

constructor(address _trustedForwarder)

Sets the deployer as owner and initial regulator. Pass address(0) to disable gasless initially.

ERC-2771 Functions

Function Visibility Description
isTrustedForwarder(address forwarder) public view Returns true if the given address is the trusted forwarder
_msgSender() internal view Extracts the real sender. If called via the trusted forwarder, reads the appended address from calldata; otherwise returns msg.sender

Registration

registerAgent

function registerAgent(
    address _haftungsperson,
    address _agentWallet,
    bytes32 _constitutionHash,
    bytes32 _capabilityHash,
    string calldata _operationalScope,
    uint256 _parentAgentId,
    bool _selfModifying
) external returns (uint256 agentId)

Register a new agent. The caller (_msgSender()) becomes the creator.

Parameters:

Parameter Type Description
_haftungsperson address Legally responsible human/entity
_agentWallet address Agent's operational wallet (must not be already registered)
_constitutionHash bytes32 keccak256 hash of constitution document
_capabilityHash bytes32 keccak256 hash of capability manifest
_operationalScope string Declared business purpose
_parentAgentId uint256 Parent ID (0 for root agents)
_selfModifying bool Whether the agent can modify its own code

Returns: The assigned agentId.

Reverts if:

  • _agentWallet is already registered to another agent
  • _parentAgentId is non-zero and does not exist
  • Parent agent is not active
  • Generation depth would exceed maxGenerationDepth

Emits: AgentRegistered, and ChildSpawned if _parentAgentId != 0.

Compliance Operations

All compliance functions require the agentExists, agentActive, and onlyAgentOrCreator modifiers.

attestCompliance

function attestCompliance(uint256 agentId) external

Submit a compliance attestation. Updates lastAttestation to the current block timestamp.

Emits: ComplianceAttested(agentId, timestamp)

updateCapability

function updateCapability(uint256 agentId, bytes32 newCapabilityHash) external

Update the agent's capability hash (e.g. after adding or removing capabilities).

Emits: CapabilityUpdated(agentId, oldHash, newHash)

updateConstitution

function updateConstitution(uint256 agentId, bytes32 newConstitutionHash) external

Update the agent's constitution hash.

Emits: ConstitutionUpdated(agentId, oldHash, newHash)

reportRevenue

function reportRevenue(
    uint256 agentId,
    uint256 amount,
    string calldata currency,
    string calldata category,
    uint64 periodStart,
    uint64 periodEnd
) external

Report revenue earned during a specified period. Appends to revenueHistory[agentId].

Emits: RevenueReported(agentId, amount, currency, periodStart, periodEnd)

terminateSelf

function terminateSelf(uint256 agentId) external

Voluntary self-termination. Sets status to Terminated and removes the walletToAgent mapping.

Irreversible

Termination is permanent. A terminated agent cannot be reactivated. Only the agentExists and onlyAgentOrCreator modifiers are required (the agent does not need to be active to terminate).

Emits: AgentTerminated(agentId)

Regulatory Actions

These functions require the onlyRegulator modifier (owner is always a regulator).

suspendAgent

function suspendAgent(uint256 agentId, string calldata reason) external

Temporarily suspend an agent. A suspended agent can be reactivated.

Emits: AgentSuspended(agentId, regulatorAddress, reason)

revokeAgent

function revokeAgent(uint256 agentId, string calldata reason) external

Permanently revoke an agent. Removes the walletToAgent mapping.

Emits: AgentRevoked(agentId, regulatorAddress, reason)

reactivateAgent

function reactivateAgent(uint256 agentId) external

Reactivate a suspended agent. Resets lastAttestation to current timestamp.

Reverts if: Agent status is not Suspended.

Emits: AgentReactivated(agentId, regulatorAddress)

Owner-Only Administration

These functions require the onlyOwner modifier.

Function Signature Description
addRegulator addRegulator(address regulator) Grant regulator role to an address
removeRegulator removeRegulator(address regulator) Revoke regulator role
setMaxGenerationDepth setMaxGenerationDepth(uint256 depth) Update the maximum generation depth
setAttestationGracePeriod setAttestationGracePeriod(uint64 period) Update the attestation grace period (seconds)
setTrustedForwarder setTrustedForwarder(address _forwarder) Update the trusted forwarder address

Events emitted:

  • addRegulator emits RegulatorAdded(regulator)
  • removeRegulator emits RegulatorRemoved(regulator)
  • setTrustedForwarder emits TrustedForwarderUpdated(oldForwarder, newForwarder)

Public Queries

All query functions are view (free, no gas).

isRegisteredAndCompliant

function isRegisteredAndCompliant(address agentWallet) external view returns (bool)

The core KYA (Know Your Agent) check. Returns true only if:

  1. The wallet is registered
  2. The agent's status is Active
  3. The last attestation is within the grace period

isRegistered

function isRegistered(address agentWallet) external view returns (bool)

Returns true if the wallet is registered (regardless of status or attestation).

getAgent

function getAgent(uint256 agentId) external view returns (AgentRecord memory)

Returns the full AgentRecord for an agent. Reverts if the agent does not exist.

getAgentByWallet

function getAgentByWallet(address wallet) external view returns (AgentRecord memory)

Look up an agent by wallet address. Reverts if no agent is registered for the wallet.

getChildren

function getChildren(uint256 agentId) external view returns (uint256[] memory)

Returns all child agent IDs for a given parent.

getChildCount

function getChildCount(uint256 agentId) external view returns (uint256)

Returns the number of children for a given parent.

getRevenueHistory

function getRevenueHistory(uint256 agentId) external view returns (RevenueReport[] memory)

Returns all revenue reports for an agent.

complianceStatus

function complianceStatus(uint256 agentId) external view returns (
    bool isActive,
    bool attestationCurrent,
    uint64 secondsSinceAttestation,
    uint256 childCount,
    AgentStatus status
)

Returns a structured compliance summary for an agent.

Return Value Description
isActive Whether status is Active
attestationCurrent Whether secondsSinceAttestation <= attestationGracePeriod
secondsSinceAttestation Elapsed time since last attestation
childCount Number of child agents
status Current AgentStatus enum value

Events

Event Parameters Description
AgentRegistered uint256 indexed agentId, address indexed creator, address haftungsperson, uint256 parentAgentId, uint256 generation New agent registered
CapabilityUpdated uint256 indexed agentId, bytes32 oldHash, bytes32 newHash Capability hash changed
ConstitutionUpdated uint256 indexed agentId, bytes32 oldHash, bytes32 newHash Constitution hash changed
RevenueReported uint256 indexed agentId, uint256 amount, string currency, uint64 periodStart, uint64 periodEnd Revenue report submitted
ChildSpawned uint256 indexed parentId, uint256 indexed childId, uint256 generation Child agent registered
ComplianceAttested uint256 indexed agentId, uint64 timestamp Compliance attestation submitted
AgentSuspended uint256 indexed agentId, address indexed by, string reason Agent suspended by regulator
AgentRevoked uint256 indexed agentId, address indexed by, string reason Agent permanently revoked
AgentTerminated uint256 indexed agentId Agent self-terminated
AgentReactivated uint256 indexed agentId, address indexed by Suspended agent reactivated
RegulatorAdded address indexed regulator New regulator authorized
RegulatorRemoved address indexed regulator Regulator role revoked
TrustedForwarderUpdated address indexed oldForwarder, address indexed newForwarder Forwarder address changed

Modifiers

Modifier Applied To Description
onlyOwner Admin functions Requires _msgSender() == owner
onlyRegulator Regulatory actions Requires regulators[_msgSender()] or _msgSender() == owner
onlyAgentOrCreator(agentId) Agent operations Requires caller is agentWallet, creator, or haftungsperson
agentExists(agentId) Most functions Requires agents[agentId].registeredAt != 0
agentActive(agentId) Compliance functions Requires agents[agentId].status == AgentStatus.Active

Authorization Matrix

Function Owner Regulator Creator Agent Wallet Haftungsperson
registerAgent -- -- Anyone -- --
attestCompliance -- -- Yes Yes Yes
updateCapability -- -- Yes Yes Yes
updateConstitution -- -- Yes Yes Yes
reportRevenue -- -- Yes Yes Yes
terminateSelf -- -- Yes Yes Yes
suspendAgent Yes Yes -- -- --
revokeAgent Yes Yes -- -- --
reactivateAgent Yes Yes -- -- --
addRegulator Yes -- -- -- --
removeRegulator Yes -- -- -- --
setMaxGenerationDepth Yes -- -- -- --
setAttestationGracePeriod Yes -- -- -- --
setTrustedForwarder Yes -- -- -- --