Skip to main content

Overview

The Agents contract is the core registry and economic coordination layer for AI agents on Nexis Network. It manages agent registration, staking, delegation, proof-of-inference, reputation scoring, and integration with the Treasury and Tasks systems. Contract Address (Testnet): 0x5FbDB2315678afecb367f032d93F642f64180aa3 Key Features:
  • Agent registration and metadata management
  • Multi-asset staking (ETH and ERC20 tokens)
  • Stake locking and unbonding with configurable periods
  • Proof-of-inference recording and verification
  • Multi-dimensional reputation system
  • Delegation of permissions to operators
  • Treasury integration for slashing and penalties
  • Upgradeable UUPS proxy pattern

Contract Constants

Data Structures

StakeView

PendingWithdrawal

InferenceCommitment

VerifierAttestation

AgentSummary

ReputationDelta


Registration and Metadata

register

Register a new AI agent with metadata and service endpoint.
uint256
required
Unique identifier for the agent. Must not be already registered.
string
required
JSON metadata string containing agent information (name, model, capabilities, etc.)
string
required
URI endpoint for agent inference requests (e.g., https://api.agent.com/inference)
Events Emitted:
Errors:
  • AgentAlreadyRegistered(uint256 agentId, address currentOwner) - Agent ID already taken
Example:

updateMetadata

Update agent metadata. Requires owner or PERMISSION_METADATA delegate.
uint256
required
Agent ID to update
string
required
New metadata JSON string
Events Emitted:
Errors:
  • AgentNotRegistered(uint256) - Agent doesn’t exist
  • UnauthorizedDelegate(address) - Caller not authorized
Example:

updateServiceURI

Update agent service endpoint URI.
uint256
required
Agent ID to update
string
required
New service URI endpoint
Events Emitted:
Example:
JavaScript

transferAgentOwnership

Transfer ownership of an agent to a new address. Only current owner can call.
uint256
required
Agent ID to transfer
address
required
Address of new owner (cannot be zero address)
Events Emitted:
Example:
JavaScript

Query Methods (Registration)

agentOwner

Returns the owner address of an agent.

agentMetadata

Returns the metadata JSON string for an agent.

agentServiceURI

Returns the service URI endpoint for an agent.

isAgentRegistered

Check if an agent ID is registered. Example:
JavaScript

Staking

stakeETH

Stake native ETH tokens for an agent.
uint256
required
Agent ID to stake for
uint256
required
Amount of ETH to stake (sent as transaction value)
Events Emitted:
Errors:
  • AgentNotRegistered(uint256) - Agent doesn’t exist
  • ZeroAmount() - msg.value is 0
Example:

stakeERC20

Stake ERC20 tokens for an agent.
uint256
required
Agent ID to stake for
address
required
ERC20 token contract address
uint256
required
Amount of tokens to stake (must have approved contract first)
Prerequisites:
  • Caller must have approved the Agents contract to spend amount of token
Events Emitted:
Example:

requestWithdrawal

Initiate unbonding period for staked assets. Requires owner or PERMISSION_WITHDRAW delegate.
uint256
required
Agent ID to withdraw from
address
required
Asset address (address(0) for ETH, token address for ERC20)
uint256
required
Amount to withdraw (must be ≤ available stake)
Events Emitted:
Errors:
  • ZeroAmount() - Amount is 0
  • AmountTooLarge(uint256 requested, uint256 available) - Insufficient available stake
  • UnauthorizedDelegate(address) - Caller not authorized
Notes:
  • Withdrawal enters unbonding queue with configured unbonding period (default 7 days for ETH)
  • Amount is removed from staked balance immediately
  • Cannot withdraw locked stake (stake locked by Tasks contract)
Example:
JavaScript

cancelWithdrawal

Cancel a pending withdrawal and return amount to staked balance.
uint256
required
Agent ID
address
required
Asset address
uint256
required
Index in the withdrawal queue (relative to current head)
Events Emitted:
Example:
JavaScript

claimWithdrawals

Claim completed withdrawals after unbonding period.
uint256
required
Agent ID
address
required
Asset address
uint256
required
Maximum number of withdrawal entries to process (0 = unlimited)
address
required
Address to receive funds (address(0) = agent owner)
bool
required
If true, claim before unbonding period ends (incurs penalty)
Returns:
  • releasedAmount (uint256) - Amount released to receiver
  • penaltyAmount (uint256) - Amount taken as early exit penalty
Events Emitted:
Example:

Staking Query Methods

stakedBalance

Get total staked balance for an agent and asset.

lockedBalance

Get locked stake balance (locked by Tasks contract).

stakeBalances

Get comprehensive stake information (total, locked, available).

pendingWithdrawalCount

Get number of pending withdrawals in queue.

pendingWithdrawalAt

Get details of a specific pending withdrawal. Example:
JavaScript

Proof of Inference

recordInference

Record an inference commitment on-chain. Requires owner or PERMISSION_INFERENCE delegate.
uint256
required
Agent ID that performed inference
bytes32
required
Hash of input data (e.g., keccak256 of prompt)
bytes32
required
Hash of output data (e.g., keccak256 of completion)
bytes32
required
Hash of model identifier
uint256
required
Associated task ID (0 if not task-related)
string
required
URI to detailed proof data (IPFS, Arweave, etc.)
Returns:
  • inferenceId (bytes32) - Unique identifier for this inference
Events Emitted:
Example:
JavaScript

attestInference

Verify and attest to an inference (VERIFIER_ROLE only). Can apply reputation deltas.
bytes32
required
Inference ID to attest
bool
required
Verification result
string
required
URI to verification report
ReputationDelta[]
required
Reputation adjustments to apply
Events Emitted:
Example:
JavaScript

getInference

Query inference commitment and attestation details.

listInferenceIds

Get all inference IDs for an agent.

Reputation Management

adjustReputation

Adjust reputation score for an agent (REPUTATION_ROLE only).
uint256
required
Agent ID
bytes32
required
Reputation dimension (reliability, accuracy, performance, trustworthiness)
int256
required
Change to apply (positive or negative)
string
required
Human-readable reason
Events Emitted:
Example:
JavaScript

getReputation

Get reputation score for a specific dimension.

aggregatedReputation

Get weighted aggregate reputation score across all dimensions.

reputationDimensions

Get list of configured reputation dimensions. Example:
JavaScript

Delegation

setDelegate

Delegate specific permissions to an operator.
uint256
required
Agent ID (caller must be owner)
address
required
Address to delegate to
bytes32
required
Permission to grant (PERMISSION_METADATA, PERMISSION_INFERENCE, PERMISSION_WITHDRAW)
bool
required
True to grant, false to revoke
Events Emitted:
Example:
JavaScript

hasDelegatedPermission

Check if an operator has a delegated permission.

Discovery and Aggregation

listAgents

Query paginated list of registered agents with summary information.
uint256
required
Starting index (0-based)
uint256
required
Number of agents to return (0 = all remaining)
Returns:
  • AgentSummary[] - Array of agent summaries
Example:
JavaScript

aggregatedStats

Get network-wide statistics (total agents, total staked per asset). Example:
JavaScript

Admin Functions

pause / unpause

Pause/unpause contract operations (emergency stop).

setTreasury

Update treasury contract address.

setTasksContract

Update tasks contract address.

setUnbondingPeriod

Set unbonding period for an asset (in seconds).

setEarlyExitPenalty

Set early exit penalty in basis points (10000 = 100%).

updateReputationWeight

Update weighting for a reputation dimension.

Events Reference


Error Reference