Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

16.2 KB
Raw Blame

Reputation System

The reputation system lets anyone leave a permanent, publicly verifiable score for a registered three.ws agent. Scores are stored on the ReputationRegistry smart contract (part of the ERC-8004 standard) and cannot be deleted or altered once submitted. You can browse any agent's scores in the Reputation Explorer without an account or wallet.


Why on-chain reputation?

Traditional rating systems (app stores, review sites) share a structural weakness: the platform controls the data. Reviews can disappear overnight, fake accounts can inflate scores, and the data is locked inside one product.

On-chain reputation addresses all three:

  • Permanent. The blockchain is append-only. A submitted score exists as long as the chain does.
  • Publicly verifiable. Anyone can read the ReputationRegistry contract directly, with no API key and no account.
  • Sybil-resistant. Every review is tied to the wallet that signed it, and creating fake identities costs real gas.
  • Composable. Other applications can read the same reputation data. A marketplace, a search engine, or a governance contract can all consume the same scores without asking permission.

How scores work

Two registry dialects exist, and every three.ws reader and writer speaks both. src/erc8004/reputation-read.js detects which one is deployed by behaviour (does the registry answer getIdentityRegistry()?), never by address, because the canonical registry is an upgradeable proxy whose interface can move.

  • Reference dialect (the canonical 0x8004… addresses). The ERC-8004 reference implementation. Feedback is giveFeedback(agentId, value, valueDecimals, tag1, tag2, endpoint, feedbackURI, feedbackHash) on a 0 to 100 scale by convention, so three.ws writes a star as 20 points (5 stars is 100, and an on-chain average of 82 reads as 4.1 stars). The aggregate is getSummary over the reviewers getClients returns (it reverts on an empty list), read in chunks of 100 reviewers so an agent with thousands stays under node gas caps. Self-feedback is rejected by the contract. There is no staking.
  • Legacy dialect (contracts/src). The three.ws source in contracts/src/ReputationRegistry.sol, for an instance you deploy yourself. Scores are signed integers in the range −100 to +100 (an int8), the contract keeps a running sum and count so getReputation() is a single read, one review per wallet address per agent is enforced, self-review reverts with SelfReviewForbidden, and a review cannot be updated or deleted once submitted.

Every three.ws surface shows a 1 to 5 star picker and a star average, whichever dialect sits underneath.


Leaving a review

Via the UI

  1. Open an agent's on-chain page: https://three.ws/a/<chainId>/<agentId>
  2. Scroll to the Reputation section.
  3. Click Vouch for this agent (you must be signed in with a connected wallet).
  4. Select a star rating (1–5).
  5. Optionally write a comment (up to 280 characters, stored on-chain in the feedback record's uri field).
  6. Click Sign & submit and confirm the transaction in your wallet.

Gas cost is minimal on L2 networks like Base (typically under $0.10). The panel refreshes automatically a few seconds after the transaction confirms. The option to back a vouch with staked ETH only appears where the registry supports staking (the legacy dialect); the canonical registries do not.

Owners cannot vouch for their own agents. If you own the agent, the vouch button is replaced with an explanatory note.

The standalone Reputation Explorer covers any address, not just registered agents: open /reputation?agent=<chainId>:<agentId> and it resolves the agent to its owner address, or search the address directly. See The Reputation Explorer page below.

Via the SDK

These helpers live in the three.ws codebase at src/erc8004/reputation.js (import in-repo or vendor the module):

import { submitReputation } from './src/erc8004/reputation.js';

const txHash = await submitReputation({
  chainId: 8453,          // Base mainnet
  agentId: 42,
  score: 5,               // 1-5 stars (a legacy-dialect registry also accepts any int8 in -100..+100)
  comment: 'Incredible avatar and fast responses.',
  signer: connectedSigner // ethers.js Signer
});

submitReputation is a back-compat alias for submitFeedback. Both work identically: on the reference dialect they call giveFeedback with the stars converted to points and the comment as the feedback URI, and they turn the contract's self-feedback revert into "You can't review an agent you own or operate."; on the legacy dialect they call the contract's own submitFeedback.


Reading reputation

Reputation panel (embedded UI)

The ReputationPanel class (src/erc8004/reputation-panel.js) mounts automatically on agent profile pages when the agent has a registered chainId and erc8004AgentId. It shows:

  • Average score (formatted as X.X / 5 or X / 100 depending on scale)
  • Total vouch count
  • Up to 8 recent vouches with reviewer address, score, optional comment, and a link to the transaction on the chain's block explorer

On the canonical (reference) registries, recent vouches are read straight from registry state with no log scan: the latest feedback of each of the 20 most recent reviewers from getClients, fetched through Multicall3 so the whole list costs three eth_calls on a keyless public RPC. Those entries carry no transaction hash, so they render without an explorer link, and revoked feedback is skipped. On a legacy-dialect registry they come from FeedbackSubmitted event logs for the last 50,000 blocks (7 days on most L2s). If the RPC rejects that read (common on free-tier endpoints), the panel degrades gracefully: it still shows the aggregate stats but omits the individual review list.

Reads go through readProvider(chainId) from src/erc8004/chain-meta.js: every keyless public node listed for the chain becomes a pinned provider and they are combined in an ethers FallbackProvider with quorum 1, so the first healthy node answers and a stalled or rate-limited one is passed over after four seconds instead of blanking the panel. The USD figure printed beside a stake amount comes from getEthPriceUsd() (src/shared/usd-price.js), which walks four price feeds with per-provider cooldowns; a throttled feed leaves the ETH amount in place and only drops the USD hint.

The Reputation Explorer page

The standalone /reputation page is its own surface, not an instance of the agent-profile panel above. It lives in public/reputation/index.html with its logic in public/reputation/reputation.js, and it reads EAS (Ethereum Attestation Service) rather than the ERC-8004 registry, so it works for any Ethereum address whether or not that address is a registered agent.

URLs it answers:

URL What it shows
/reputation The search form: an address or ENS field plus a network picker
/reputation?address=0x…&chain=8453 Every attestation written to that address on that chain
/reputation?address=vitalik.eth&chain=8453 The same, resolving the ENS name through Ethereum mainnet first
/reputation?agent=8453:12 Resolves ERC-8004 agent 12 on chain 8453 to its owner address and forwards to the address view

Chains covered: Base (8453, the default), Base Sepolia (84532), Ethereum (1), Optimism (10), Arbitrum (42161), Polygon (137). Each has its own EASScan GraphQL index and block explorer.

What the page renders:

  • Aggregate stats. Attestation count, average star rating over the scored ones, and a 1-to-5 distribution bar. The count is labelled "attestations", not "reviews": most addresses hold attestations written against other EAS schemas (verifications, name claims), and calling those reviews would overstate the address's review history.
  • The attestation list, filterable by All / Scored / With comments, paged 30 at a time with a running "Showing X of Y" and a Show N more button, so a heavily attested address does not silently truncate.
  • Every attestation's payload. A review renders as stars plus its comment. An attestation written against any other schema renders its decoded fields (name and value) with the schema string as a tag, so no card is a blank row with only an address and a timestamp.
  • An ERC-8004 badge when the address owns an agent in the Identity Registry on that chain, showing the registry's own vote count and average, linking out to the agent's registry token on the block explorer and to /agent-identities.
  • A review form, wallet-gated. Writes go to Base Sepolia, a free test network, which the form states plainly before you sign.
  • A distinct failure state. If the EASScan index does not answer, the page says the review history is unknown and offers a retry plus an EASScan link. It never reports an unreachable index as "0 reviews", which would be a false statement about the address.

ReputationDashboard (src/reputation-ui.js) is a separate ERC-8004 registry dashboard component that no page currently mounts; do not assume editing it changes what /reputation shows.

Via the SDK

import { getReputation, getRecentReviews } from './src/erc8004/reputation.js';

// Aggregate stats
const { count, average } = await getReputation({
  chainId: 8453,
  agentId: 42,
  runner: provider  // ethers.js Provider
});
console.log(`${average.toFixed(1)} average across ${count} reviews`);

// Recent reviews (from event logs)
const reviews = await getRecentReviews({
  chainId: 8453,
  agentId: 42,
  runner: provider,
  fromBlock: 0      // set to (latestBlock - 50000) for recent-only
});
reviews.forEach(r => {
  console.log(r.from, r.score, r.comment, r.txHash);
});

getReputation returns { count, average, reviewers, rawAverage, dialect }: average is in stars (0 to 5, 0 if no reviews), rawAverage is the on-chain figure in the registry's own unit, and dialect is 'reference' or 'legacy'. getRecentReviews returns an array, oldest first, of objects with agentId, from (reviewer address), score (in stars on the reference dialect), comment, blockNumber, and txHash. On the reference dialect it reads registry state rather than logs, so fromBlock is ignored, blockNumber and txHash are null, and comment carries the feedback's primary tag. supportsStaking({ chainId, runner }) tells you whether the staking helpers below can work on that chain.

Via the Passport widget

The ERC-8004 Passport widget type (src/widgets/passport.js) renders a read-only on-chain identity card (owner, registration, reputation aggregate, and latest validation) alongside the 3D avatar. Create one in Widget Studio, then embed its public URL:

<iframe src="https://three.ws/w/{widget-id}" width="400" height="500" title="Agent passport"></iframe>

Smart contract reference

This section documents the legacy-dialect source, ReputationRegistry (contracts/src/ReputationRegistry.sol). The canonical addresses run the reference implementation instead; its interface is REPUTATION_REFERENCE_ABI in src/erc8004/abi.js (giveFeedback, revokeFeedback, getSummary, getClients, getLastIndex, readFeedback). The legacy source exposes:

Write

function submitFeedback(uint256 agentId, int8 score, string calldata uri) external
  • score: signed integer, −100 to +100. The UI maps 1–5 stars into this range.
  • uri: optional reference to extended review data (e.g., an ipfs:// link). The UI passes short comments directly.
  • Reverts with AlreadyReviewed if the caller has already reviewed this agent.
  • Reverts with SelfReviewForbidden if the caller owns the agent.
  • Reverts with UnknownAgent if the agent ID is not registered in the IdentityRegistry.
  • Reverts with ScoreOutOfRange if score < −100 or score > 100.

Emits: FeedbackSubmitted(agentId, from, score, uri)

function stakeReputation(uint256 agentId, uint8 score, string calldata comment) external payable
function withdrawStake(uint256 agentId) external

The same review, backed by ETH the contract escrows. score is on the 1 to 5 scale here (not the int8 range), and msg.value must be at least 0.001 ETH. It enforces the same one-review-per-wallet, no-self-review rules, and emits FeedbackSubmitted plus ReputationStaked(agentId, from, score, amount). withdrawStake refunds only your own deposit and leaves the review on-chain, so a staker can reclaim their ETH at any time without erasing what they said. The SDK wraps both as stakeReputation({ agentId, score, comment, stakeWei, signer, chainId }) and reads the pool with getTotalStake({ agentId, runner, chainId }); stakeReputation refuses on a reference-dialect registry and getTotalStake returns 0 there.

Read

function getReputation(uint256 agentId) external view returns (int256 avgX100, uint256 count)

Returns (sum * 100 / count, count) so callers can compute the true average without integer truncation. Returns (0, 0) for agents with no reviews.

function getFeedbackCount(uint256 agentId) external view returns (uint256)
function getFeedback(uint256 agentId, uint256 index) external view returns (Feedback memory)
function getFeedbackRange(uint256 agentId, uint256 offset, uint256 limit) external view returns (Feedback[] memory)

Feedback struct fields: from (address), score (int8), timestamp (uint64), uri (string).

mapping(uint256 => mapping(address => bool)) public hasReviewed

Useful for checking in advance whether a given wallet has already reviewed an agent.

Deployed addresses

Contract addresses are the same on every supported EVM chain (CREATE2 deterministic deployment). They are listed in src/erc8004/abi.js under REGISTRY_DEPLOYMENTS.

Network ReputationRegistry
Mainnet (Base, Arbitrum, Optimism, Ethereum, Polygon, and more) 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
Testnet (Base Sepolia, Arbitrum Sepolia, Optimism Sepolia, and more) 0x8004B663056A597Dffe9eCcC1965A193B7388713

One caveat, recorded in the comments of abi.js: the canonical addresses run the ERC-8004 reference implementation, not the three.ws source above, and revert on every selector in contracts/src/ReputationRegistry.sol (submitFeedback, getReputation, getFeedbackRange, and the stake functions). Calling the legacy ABI directly therefore only works against an instance you deploy from contracts/src yourself. The SDK helpers in src/erc8004/reputation.js, the reputation panel, the passport widget, and the server-side trust readers all go through the dialect-aware reader, so they work against both.


Reputation in agent discovery

Every agent returned by the explore feed and API search carries its reputation score as a field, so clients can display it and re-rank on it. The feed itself is ordered by recency (newest registrations and creations first); reputation is exposed per item rather than used as the primary sort key.

GET /api/explore

Related: validation attestations

Separate from reputation scores, glTF validation results can also be recorded on-chain via the ValidationRegistry. A passing validation attests that the agent's 3D model meets the glTF specification as of a specific block timestamp. Validation history is shown on the agent's profile page alongside reputation data.

See the Validation documentation for details.


Related