# Shares and Components

## Shares

`Shares` is the central contract for an Onyx instance. It is:

* an ERC20 tokenized representation of all portfolio holdings
* a registry of the "value asset" (e.g., "USD") used for all reporting (e.g., share value)
* a registry of roles (owner and admins)
* a registry of primary "components" (e.g., handlers for fees, valuation, deposits, redemptions)
* a safe for ERC20 token flows for deposits, redemptions, and fees

There is one `Shares` contract per Onyx instance.

## Components

"Components" are contracts that are associated with a specific `Shares` deployment, and can be thought of as belonging to that instance.

### Structure

The only requirement of all components is that they are proxies that implement `IComponentProxy`. This interface provides a `.SHARES()` getter to query which `Shares` instance it belongs to.

Most component implementation contracts inherit a `ComponentsHelpersMixin` to  assist with parsing common values from its proxy's associated Shares instance.

Note: All components know which Shares they are *meant* to belong to (though there is no on-chain validation of this when admins set components)

### Core Components (set on \`Shares\`)

#### \`IValueHandler\`

`IValueHandler` is responsible for value-related reporting and conversions. For example:

* calculate, store, and report share price
* convert the "value asset" to/from other assets (e.g., quoting share price in different assets)

There is one `IValueHandler` contract per Onyx instance.

#### \`IFeeHandler\`

`IFeeHandler` is responsible for tracking and settling any fees.

There is one `IFeeHandler` contract per Onyx instance.

#### \`ISharesTransferValidator\`

`ISharesTransferValidator` is responsible for validating that a specific transfer of Onyx shares is allowed (to whom, from whom, for what amount).

To allow all transfers: leave unset (i.e., `address(0)`) 

To disallow all transfers: set to any arbitrary address that does not have the required callback, e.g., `address(1)``   `   

There is one `ISharesTransferValidator` contract per Onyx instance.

#### Deposit Handlers

Deposit handlers are accounts that are allowed to perform actions related to deposits, e.g., minting shares and triggering entrance fee settlement.

Deposit handlers can be EOAs or Component contracts.

There can be multiple per Onyx instance.

#### Redeem Handlers

Redeem handlers are accounts that are allowed to perform actions related to redemptions, e.g., burning shares, withdrawing assets, and triggering exit fee settlement.

Redeem handlers can be EOAs or Component contracts.

There can be multiple per Onyx instance.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enzyme.finance/onyx-protocol/architecture/shares-and-components.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.