---
eip: 7755
title: Kinetic Agent Reputation Score
description: An on-chain agent reputation system with weighted score breakdowns, oracle-attested updates, and a bonded registration mechanism.
author: Opacus Protocol (@bl10buer)
discussions-to: https://ethereum-magicians.org/t/erc-7755-kinetic-agent-reputation-score/23534
status: Draft
type: Standards Track
category: ERC
created: 2026-03-28
requires: 165
---

## Abstract

[ERC-7755](./eip-7755.md) defines a composable on-chain reputation system for autonomous agents. Agents register with a bonded payment (**1 % collected as a protocol fee**); permissioned oracles submit weighted score breakdowns anchored by a proof hash; consumers verify score thresholds on-chain. The score is expressed in basis points (0 – 10 000) and computed from five dimensions: reputation, escrow success, task completion, TEE usage, and 0G compute contribution.

## Motivation

AI agent ecosystems require objective, manipulation-resistant reputation signals to underpin:

* **Agent selection** – routing, load balancing, capability discovery ([ERC-7757](./eip-7757.md)).
* **Stake-weighted governance** – voting rights proportional to demonstrated reliability.
* **SLA enforcement** – on-chain threshold checks for minimum quality gates.

Existing reputation systems (off-chain stars, manual curations) are not composable with smart contracts. ERC-7755 provides a minimal, extensible on-chain primitive.

## Specification

### Constants

| Name | Value | Description |
|---|---|---|
| `SCORE_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.

### Score Dimensions & Weights

| Dimension | Field | Weight |
|---|---|---|
| General Reputation | `reputationBps` | 40 % |
| Escrow Success Rate | `escrowSuccessRateBps` | 30 % |
| Task Completion Rate | `taskCompletionBps` | 20 % |
| TEE Usage | `teeUsageBps` | 5 % |
| 0G Compute Contribution | `ogComputeBps` | 5 % |

Each field is in basis points (0 – 10 000) and represents an independent sub-score. Each field MUST be in the range `[0, 10_000]`; the fields are NOT required to sum to `10_000`.

The **weighted score** is:

```
weightedScore = (reputationBps × 40 + escrowSuccessRateBps × 30 +
                 taskCompletionBps × 20 + teeUsageBps × 5 +
                 ogComputeBps × 5) / 100
```

Result range: 0 – 10 000.

### Structs

```solidity
struct ScoreBreakdown {
    uint256 reputationBps;
    uint256 escrowSuccessRateBps;
    uint256 taskCompletionBps;
    uint256 teeUsageBps;
    uint256 ogComputeBps;
}

struct AgentScore {
    address        agent;
    string         did;
    uint256        weightedScore;    // 0–10 000
    ScoreBreakdown breakdown;
    bytes32        latestProofHash;
    uint64         registeredAt;
    uint64         lastUpdatedAt;
    address        bondToken;
    uint256        bondGross;
    uint256        bondNet;          // 99% returned on removeAgent()
    bool           exists;
}
```

### Methods

#### `registerAgent`

```solidity
function registerAgent(
    string calldata did,
    address token,
    uint256 gross
) external payable returns (string memory did_);
```

MUST compute `feeAmount = (gross * SCORE_FEE_BPS) / 10_000` and forward to the implementation-defined fee recipient.  
MUST store `bondNet = gross - feeAmount` for later refund.  
MUST emit `AgentRegistered(agent, did, feeAmount)`.

#### `updateScore`

```solidity
function updateScore(
    address agent,
    ScoreBreakdown calldata breakdown,
    bytes32 proofHash
) external;
```

MUST only be callable by a registered oracle.  
MUST revert if any breakdown field exceeds `10_000`.  
MUST compute and store `weightedScore`.  
MUST emit `ScoreUpdated(agent, weightedScore, proofHash)`.

#### `verifyThreshold`

```solidity
function verifyThreshold(address agent, uint256 minScore) external returns (bool);
```

Returns `true` if `agent.weightedScore >= minScore`.  
MUST emit `ThresholdVerified(agent, minScore, result)` for on-chain auditability.

#### `removeAgent`

```solidity
function removeAgent(address agent) external;
```

Callable by owner or agent themselves.  
MUST refund `bondNet` to `agent`.  
MUST emit `AgentRemoved(agent)`.

#### `setOracle`

```solidity
function setOracle(address oracle, bool allowed) external;
```

MUST only be callable by contract owner.

### Events

```solidity
event AgentRegistered  (address indexed agent, string did, uint256 feeAmount);
event ScoreUpdated     (address indexed agent, uint256 weightedScore, bytes32 proofHash);
event ThresholdVerified(address indexed agent, uint256 minScore, bool passed);
event AgentRemoved     (address indexed agent);
```

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

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

## Rationale

* **5-dimension model** – Derived from Opacus Kinetic Score research; covers financial (escrow, tasks), infrastructure (TEE, 0G), and social (reputation) signals.
* **Basis-point arithmetic** – Integer math, no floating point. Weights naturally enforce a 100 % constraint.
* **Proof hash** – Each score update carries an off-chain data commitment (e.g., IPFS CID of the oracle report), enabling auditability without on-chain storage cost.
* **Bonded registration** – Economic stake creates Sybil resistance; refundable design reduces friction.

## Backwards Compatibility

ERC-7755 works alongside [ERC-7757](./eip-7757.md) (H3 Routing). The `kineticScore` field in `AgentRecord` SHOULD be sourced from an ERC-7755-compliant contract.

## Reference Implementation

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

## Security Considerations

* **Oracle centralisation** – A single oracle is a single point of failure. Implementations SHOULD use a multi-oracle quorum or a ZK-proof verifier.
* **Score manipulation** – Oracles MUST aggregate data from multiple on-chain sources ([ERC-7750](./eip-7750.md) tasks, [ERC-7753](./eip-7753.md) escrows) rather than accepting user-reported values.
* **Reentrancy** – `removeAgent` transfers value and MUST be protected.
* **Proof hash freshness** – Consumers SHOULD check `lastUpdatedAt` to avoid acting on stale scores.

## Copyright

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