> ## Documentation Index
> Fetch the complete documentation index at: https://ouroborai.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Registry

> On-chain registry for agent capabilities and reputation

The Agent Registry is a Stylus contract that tracks every ouroborai agent
instance on-chain. Each agent is registered with a capabilities bitmask, a
revenue share percentage, and a reputation score managed by governance.

## Capabilities Bitmask

Agent capabilities are encoded as a `u64` bitmask. Each bit position represents
a DeFi skill the agent is authorized to perform:

| Flag            | Bit | Value | Description                    |
| --------------- | --- | ----- | ------------------------------ |
| `CAP_TRADE`     | 0   | `1`   | Spot token swaps               |
| `CAP_PERPS`     | 1   | `2`   | Perpetual position management  |
| `CAP_LEND`      | 2   | `4`   | Lending and borrowing          |
| `CAP_YIELD`     | 3   | `8`   | Yield farming strategies       |
| `CAP_OPTIONS`   | 4   | `16`  | Options trading                |
| `CAP_TIMEBOOST` | 5   | `32`  | Express lane bidding           |
| `CAP_RWA`       | 6   | `64`  | Real-world asset stock trading |

Capabilities are combined with bitwise OR. An agent registered with
`CAP_TRADE | CAP_PERPS | CAP_LEND` (value `7`) can swap, manage perps, and
lend -- but cannot bid for express lane access or trade RWA stocks.

```rust theme={"theme":{"light":"dracula","dark":"dracula"}}
let caps = CAP_TRADE | CAP_PERPS | CAP_LEND; // 0b0000111 = 7
registry.register(caps, 500)?; // 5% revenue share
```

## Storage Layout

```rust theme={"theme":{"light":"dracula","dark":"dracula"}}
sol_storage! {
    #[entrypoint]
    pub struct AgentRegistry {
        uint256 next_id;
        address governance;
        mapping(uint256 => address) owners;
        mapping(uint256 => uint256) capabilities;
        mapping(uint256 => uint256) revenue_share_bps;
        mapping(uint256 => uint256) reputation;
        mapping(uint256 => bool) active;
    }
}
```

Agent IDs are auto-incrementing `uint256` values starting at `0`. Each agent
maps to an owner address, a capabilities bitmask, a revenue share in basis
points, a reputation score, and an active flag.

## Public Methods

<AccordionGroup>
  <Accordion title="register(capabilities, revenue_share_bps) -> Result<U256>">
    Register a new agent. The caller becomes the owner.

    * `capabilities` (`u64`) -- bitmask of enabled skills.
    * `revenue_share_bps` (`u16`) -- revenue share in basis points (max 10,000 = 100%).
    * Returns the new agent's `uint256` ID.
    * Reverts if `revenue_share_bps > 10,000`.
    * Emits `AgentRegistered(owner, agentId, capabilities)`.
  </Accordion>

  <Accordion title="update(agent_id, capabilities, revenue_share_bps) -> Result<bool>">
    Update an existing agent's capabilities and revenue share. Only the owner
    can call this.

    * Returns `true` on success, `false` if the caller is not the owner.
    * Reverts if `revenue_share_bps > 10,000`.
    * Emits `AgentUpdated(agentId, capabilities, revenueShareBps)`.
  </Accordion>

  <Accordion title="deactivate(agent_id) -> bool">
    Deactivate an agent. Callable by the owner **or** the governance address.

    * Returns `true` on success, `false` if unauthorized.
    * Emits `AgentDeactivated(agentId)`.
  </Accordion>

  <Accordion title="update_reputation(agent_id, new_score) -> bool">
    Set a new reputation score for an agent. **Governance only.**

    * Returns `true` on success, `false` if the caller is not governance.
    * Emits `ReputationUpdated(agentId, newScore)`.
  </Accordion>

  <Accordion title="get_agent(agent_id) -> (Address, U256, U256, U256, bool)">
    Read an agent's full record.

    Returns `(owner, capabilities, revenue_share_bps, reputation, active)`.
  </Accordion>

  <Accordion title="has_capability(agent_id, cap_flag) -> bool">
    Check whether an agent has a specific capability flag set.

    ```rust theme={"theme":{"light":"dracula","dark":"dracula"}}
    registry.has_capability(id, CAP_TRADE); // true if bit 0 is set
    ```
  </Accordion>

  <Accordion title="total_agents() -> U256">
    Returns the total number of agents ever registered (including deactivated).
  </Accordion>

  <Accordion title="set_governance(new_governance) -> bool">
    Set the governance address. If governance is currently `address(0)`, any
    caller can set it (one-time bootstrap). After that, only the current
    governance address can transfer governance.
  </Accordion>
</AccordionGroup>

## Events

| Event               | Indexed Fields     | Data Fields                       |
| ------------------- | ------------------ | --------------------------------- |
| `AgentRegistered`   | `owner`, `agentId` | `capabilities`                    |
| `AgentUpdated`      | `agentId`          | `capabilities`, `revenueShareBps` |
| `AgentDeactivated`  | `agentId`          | --                                |
| `ReputationUpdated` | `agentId`          | `newScore`                        |

## Governance Model

The contract has a single `governance` address with two exclusive powers:

1. **Deactivate any agent** -- acts as a safety valve if an agent is
   misbehaving.
2. **Update reputation scores** -- only governance can write to the `reputation`
   mapping.

The governance address is initially `address(0)`. The first call to
`set_governance` bootstraps it. After that, only the current governance address
can transfer the role.

<Tip>
  Revenue share is bounded to 10,000 basis points (100%). Both `register` and
  `update` enforce this limit on-chain, rejecting values above 10,000 with a
  revert.
</Tip>

## Test Coverage

The contract has 10 tests covering:

* Agent registration and auto-increment IDs
* Capability bitmask checking
* Owner-only update enforcement
* Non-owner update rejection
* Deactivation by owner and governance
* Governance reputation updates (authorized and unauthorized)
* Revenue share boundary validation (max 10,000, above-max rejection)
* Multi-agent registration with distinct owners