# [<img src="https://i.imgur.com/pG1DDRr.png" height="100px" width="140px" alt="">](https://www.youtube.com/watch?v=5AAbrmLOV8k)**Allocator Contribution Guidelines**

###### This is a short guide on how to effectively contribute to Olympus DAO with the Allocator team.
###### This hackmd doc will be kept updated.

## Summary

* **Step 1: Communication**
* **Step 2: Familiarization**
* **Step 3: Claim a task**
* **Step 4: Working environment**

- **Add. 1: Understanding `allocated`, `gain` and `loss`**
- **Add. 2: Understanding deposits and ids**

## Steps

### Step 1: Communication

1. Get into contact with someone from the smart contracts team if you haven't already.
2. Gain Discord access if you haven't already.
3. Say `gm`.
4. Skim through the allocator channel (currently `#allocator-rework`).

Contact people:

- **friΞd#8371** (on discord) / **mirru2532** (on [github](https://github.com/mirru2532))

---
### Step 2: Familiarization

Read through all of the contracts to understand how the system works!

| Contract | Description|
| --- | --- |
| [TreasuryExtender](https://github.com/OlympusDAO/olympus-contracts/blob/allocators/contracts/TreasuryExtender.sol) | Contract which communicates with the treasury. Allocator reports its own state to this contract. Allocator retrieves data from this contract regarding latest information about its own state which needs to be updated. |
| [ITreasuryExtender](https://github.com/OlympusDAO/olympus-contracts/blob/allocators/contracts/interfaces/ITreasuryExtender.sol) | Interface for the above. |
| [BaseAllocator](https://github.com/OlympusDAO/olympus-contracts/blob/allocators/contracts/types/BaseAllocator.sol) | Base contract used for developing an allocator. Implement specified functions. If unsure about meaning ask in Discord channel. |
| [IAllocator](https://github.com/OlympusDAO/olympus-contracts/blob/allocators/contracts/interfaces/IAllocator.sol) | Interface for the above. |
| [OlympusAccessControlledV2](https://github.com/mirru2532/olympus-contracts/blob/main/contracts/types/OlympusAccessControlledV2.sol) | Access contract with modifiers for the above. |
| [CurveConvexAllocator](https://github.com/OlympusDAO/olympus-contracts/blob/allocators/contracts/allocators/CurveConvexAllocator.sol) | Sample allocator implementation (not deployed / reviewed yet but mostly complete). It showcases a lot of stuff. Important are lines 63 - 186. |
| [Old allocators](https://github.com/OlympusDAO/olympus-contracts/tree/allocators/contracts/allocators/old-allocators) | If an older version for the same protocol you want to work on exists, check out the old Allocator for it. |

---

### Step 3: Projects board

Once you have finished the above, visit the projects board of the contract team, find an Allocator which nobody is working on, claim it, and develop.

- [Olympus Contracts Tasks Board](https://github.com/orgs/OlympusDAO/projects/2)

Drop in the above mentioned allocator channel in the Discord and say you're claiming it, so we know what you're doing. Drop any questions you want to ask. We're here to help each other because we're internet degens.

---

### Step 4: Working environment

**Fork** the Olympus DAO Contracts repository and **[work on this branch.](https://github.com/OlympusDAO/olympus-contracts/tree/allocators)**

Work in the `/contracts/allocators` folder and when ready submit a PR to the (important) `allocators` branch. Add someone for review, say some of the above contact people.

---
## Addendums

### Add. 1: Understanding `allocated`, `gain` and `loss`

- **`allocated`**: `allocated` at any point represents either the total amount which has been `allocated` by the extender to the allocator, or less than that, because a loss was incurred. In essence, `allocated` should never grow and if there is negative fluctuations, only drop.

- **`loss`**: `loss` represents the loss incurred by negative fluctuations in the token balance of the allocator. Small fluctuations are to be ignored, but large fluctuations are suspicious. `loss` + `allocated` should always equal the exact total amount which was deposited into the allocator. Note, that there is a `loss limit`, if the loss limit is reached, the allocator will deactivate. In essence:
* Set the `loss limit` to an amount which is unnacceptable to lose, say 50%.
* Set a threshold for fluctuations above which you will report a loss. Exceeding this threshold should indicate danger / unwanted behaviour. If `loss < lossThreshold` then set `loss = 1` because this will trigger the loss event while giving a negligible change.
* Implement `_deactivate(bool panic)` such that it properly reacts to a breach of the loss limit / deactivation. Do not be shy to add extra variables + setters to properly control behaviour. This is all dependent on protocol.
* **Keep in mind that the system should essentially allow an automatic deactivation when a list of allocators is updated without the necessity to go through each allocator and inspect whether the behaviour is proper. It's an extra security layer.**

* **`gain`**: `gain` represents the amount of tokens earned by the allocator. It is incremented each update as `amountAllocated - former_allocated - former_gain = gain`. `amountAllocated` is a getter and should represented the currently most exact amount allocated, while the former two should be the state of the former update. Note that you can't misattribute `gain` through `allocated` decrementation by `loss` due to the fact that the sum of the former is _always_ equal to the amount that was deposited at that time.

---

### Add. 2: Understanding deposits and ids

Essentially as single Allocator contract may be registered **multiple times** with the **Extender**. This represents different tokens being deposited in the same Allocator contract. The `id` then represents the the Allocators index in the `allocators` array in the Extender contract, which can be translated via `tokenIds` to the token's id inside the `_tokens` array.

---