# Investor Registry

## Overview

The Investor Registry (<mark style="color:red;">`InvestorRegistry.sol`</mark>) is used to store and retrieve information on investors. It is also extended to include functionality like checking if investors are allowed using the rules engine. Like most registries, it makes use of the eternal storage pattern to store information, and since it is a user registry, inherits the base user registry. In this case the Investor Registry uses the investor's Ids to store their associated data.

## Investor

Investors are the end users of KAIO. They have an associated dealer, and a wallet address. Additional wallet addresses can be added afterwards.

### Creating Investor

* **Function**: `addInvestor(bytes32 _senderRole, bytes32 _investorId, address _wallet, bytes32 _dealerId)`
* **Purpose**: Creates a new Investor in the KAIO system.
* **Parameters**:
  * `bytes32 _senderRole`: Role of the sender.
  * `bytes32 _investorId`: Id of the investor to create.
  * `address _wallet`: Wallet associated to be associated with investor.
  * `bytes32 _dealerId`: Id of the dealer the investor will be assigned to.
* **Validation Checks**:
  * Checks the investor Id is not 0.
  * Ensures the caller has the proper role.
  * Makes sure the investor does not already exist.
  * Checks the caller is the investor's dealer (only if the caller is a dealer).
* **Behavior**:
  * Creates the new investor, with the associated wallet and dealer.
  * Emits a `NewInvestorAdded` event, signaling the investor has been added.
* **Example**:

  ```solidity
  addInvestor(0xDealerRole, 0xInvestorId, 0xInvestorAddress, 0xDealerId);
  ```

### Getting Investor's Dealer

* **Function**: `getDealer(bytes32 _investorId)`
* **Purpose**: Returns the dealer an investor is assigned to.
* **Parameters**:
  * `bytes32 _investorId`: Id of the investor.
* **Return Values:**
  * `bytes32`: Id of the dealer.
* **Example**:

  ```solidity
  getDealer(0xInvestorId);
  ```

## Allowlist

Allowlist functions enable checking investor's for access to specific operations, dependent on static and dynamic conditions, making use of the rule engines. Static checks are cached for efficiency when possible (if no data was updated).

### Restrict/Un-Restrict Investor

* **Function**: `setInvestorRestriction(bytes32 _senderRole, bytes32 _investorId, bytes32 _instrumentId, bool _restrict)`
* **Purpose**: Updates the investor's restriction for a given instrument. Investors can't access instruments they have been manually restricted from.
* **Parameters**:
  * `bytes32 _senderRole`: Role of the sender.
  * `bytes32 _investorId`: Id of the investor to restrict.
  * `bytes32 _instrumentId`: Id of the instrument to restrict the investor from.
  * `bool _restrict`: Indicates if the investor restriction should be applied or lifted.
* **Validation Checks**:
  * Checks the caller has access to call the function.
* **Behavior**:
  * Restricts or un-resctricts the investor.
  * Emits a `InvestorRestrictionUpdated` event, signaling the investor restriction has changed.
* **Example**:

  ```solidity
  setInvestorRestriction(0xRole, 0xInvestorId, 0xInstrumentId, true);
  ```

### Check Restriction

* **Function**: `isInvestorRestricted(bytes32 _investorId, bytes32 _instrumentId)`
* **Purpose**: Returns if an investor is restricted from a given instrument.
* **Parameters**:
  * `bytes32 _investorId`: Id of the investor.
  * `bytes32 _instrumentId`: Id of the instrument.
* **Return Values:**
  * `bool`: Indicates if the investor is restricted from the instrument.
* **Example**:

  ```solidity
  isInvestorRestricted(0xInvestorId, 0xInstrumentId);
  ```

### Checking for Allowed Investor

* **Function**: `checkInvestorAllowed(bytes32 _investorId, bytes32 _instrumentId)`
* **Purpose**: Checks if an investor is allowed to interact with a given instrument.
* **Parameters**:
  * `bytes32 _investorId`: Id of the investor.
  * `bytes32 _instrumentId`: Id of the instrument.
* **Validation Checks**:
  * Makes sure the investor's dealer is allowed in the instrument.
  * Ensures the investor is not restricted from the instrument.
  * Checks universal/KAIO restrictions in the dealer rules engine.
  * Checks instrument restrictions in the instrument's rule engine.
  * Checks dealer restrictions in the dealer rules engine.
* **Behavior**:
  * Reverts if investor is not allowed in the instrument.
* **Example**:

  ```solidity
  checkInvestorAllowed(0xInvestorId, 0xInstrumentId);
  ```

### Checking for Allowed Investor (Funds)

* **Function**: `checkInvestorAllowedFunds(bytes32 _investorId, bytes32 _instrumentId, uint256 _amount)`
* **Purpose**: Checks if an investor is allowed to interact with a given instrument with certain amount of settlement tokens.
* **Parameters**:
  * `bytes32 _investorId`: Id of the investor.
  * `bytes32 _instrumentId`: Id of the instrument.
  * `uint256 _amount`: Amount of settlement tokens used.
* **Validation Checks**:
  * Makes sure the investor's dealer is allowed in the instrument.
  * Ensures the investor is not restricted from the instrument.
  * Checks universal/KAIO restrictions in the dealer rules engine.
  * Checks instrument restrictions in the instrument's rule engine.
  * Checks dealer restrictions in the dealer rules engine.
  * Checks universal/KAIO restrictions for settlement tokens in the dealer rules engine.
  * Checks instrument restrictions for settlement tokens in the instrument's rule engine.
  * Checks dealer restrictions for settlement tokens in the dealer rules engine.
* **Behavior**:
  * Reverts if investor is not allowed in the instrument.
* **Example**:

  ```solidity
  checkInvestorAllowedFunds(0xInvestorId, 0xInstrumentId, 117);
  ```

### Checking for Allowed Investor (Tokens)

* **Function**: `checkInvestorAllowedTokens(bytes32 _investorId, bytes32 _instrumentId, uint256 _amount)`
* **Purpose**: Checks if an investor is allowed to interact with a given instrument with certain amount of security tokens.
* **Parameters**:
  * `bytes32 _investorId`: Id of the investor.
  * `bytes32 _instrumentId`: Id of the instrument.
  * `uint256 _amount`: Amount of security tokens used.
* **Validation Checks**:
  * Makes sure the investor's dealer is allowed in the instrument.
  * Ensures the investor is not restricted from the instrument.
  * Checks universal/KAIO restrictions in the dealer rules engine.
  * Checks instrument restrictions in the instrument's rule engine.
  * Checks dealer restrictions in the dealer rules engine.
  * Checks universal/KAIO restrictions for security tokens in the dealer rules engine.
  * Checks instrument restrictions for security tokens in the instrument's rule engine.
  * Checks dealer restrictions for security tokens in the dealer rules engine.
* **Behavior**:
  * Reverts if investor is not allowed in the instrument.
* **Example**:

  ```solidity
  checkInvestorAllowedTokens(0xInvestorId, 0xInstrumentId, 3608);
  ```

## Status

Information on the status of the investor is kept for purposes such as the allowlist cache or meeting restrictions in the rule engines. This status information can include data on the latest operations, or the latest investor updates.

### Updating Last Operation Timestamp

* **Function**: `updateInvestorLastOperationTimestamp(bytes32 _investorId, bytes32 _instrumentId, uint256 _lastTimestamp)`
* **Purpose**: Register the timestamp of the last operation done by an investor in a given instrument.
* **Parameters**:
  * `bytes32 _investorId`: Id of the investor.
  * `bytes32 _instrumentId`: Id of the instrument.
  * `uint256 _lastTimestamp`: Timestamp to register.
* **Validation Checks**:
  * Ensures the caller is the instrument in question (subscription book, redemption book, or security token contract).
* **Behavior**:
  * Registers the timestamp as the last operation done by the investor.
* **Example**:

  ```solidity
  updateInvestorLastOperationTimestamp(0xInvestorId, 0xInstrumentId, 1715000000);
  ```

### Getting Last Operation Timestamp

* **Function**: `getInvestorLastOperationTimestamp(bytes32 _investorId, bytes32 _instrumentId)`
* **Purpose**: Returns timestamp of the last operation done by the investor in the given instrument.
* **Parameters**:
  * `bytes32 _investorId`: Id of the investor.
  * `bytes32 _instrumentId`: Id of the instrument.
* **Return Values:**
  * `uint256`: Timestamp signaling last interaction.
* **Example**:

  ```solidity
  getInvestorLastOperationTimestamp(0xInvestorId, 0xInstrumentId);
  ```

### Reset Checked (Dealer Rules)

* **Function**: `resetCheckedSinceDealerRulesUpdate(bytes32 _dealerId)`
* **Purpose**: Resets the cached allowed status for investors when their dealer rules are updated.
* **Parameters**:
  * `bytes32 _dealerId`: Id of the dealer.
* **Validation Checks**:
  * Ensures the caller is the dealer rules engine.
* **Behavior**:
  * Registers there's been an update in the dealer's rules.
  * Emits a `ResetCheckedSinceDealerRulesUpdate` event, signaling dealer rules have been updated.
* **Example**:

  ```solidity
  resetCheckedSinceDealerRulesUpdate(0xDealerId);
  ```

### Reset Checked (Instrument Rules)

* **Function**: `resetCheckedSinceInstrumentRulesUpdate(bytes32 _instrumentId)`
* **Purpose**: Resets the cached allowed status for investors when the instrument rules are updated.
* **Parameters**:
  * `bytes32 _instrumentId`: Id of the instrument.
* **Validation Checks**:
  * Ensures the caller is the instrument's rules engine.
* **Behavior**:
  * Registers there's been an update in the instrument's rules.
  * Emits a `ResetCheckedSinceInstrumentRulesUpdate` event, signaling instrument rules have been updated.
* **Example**:

  ```solidity
  resetCheckedSinceInstrumentRulesUpdate(0xInstrumentId);
  ```

### Reset Checked (Jurisdiction)

* **Function**: `resetCheckedSinceJurisdictionUpdate()`
* **Purpose**: Resets the cached allowed status for investors when jurisdiction data is updated.
* **Validation Checks**:
  * Ensures the caller is jurisdiction registry.
* **Behavior**:
  * Registers there's been an update in jurisdiction data.
  * Emits a `ResetCheckedSinceJurisdictionUpdate` event, signaling jurisdiction data has been updated.
* **Example**:

  ```solidity
  resetCheckedSinceJurisdictionUpdate();
  ```


---

# 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.kaio.xyz/how-kaio-works/smart-contracts/registries/investor-registry.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.