# Developer Docs
To faciliate the fast changing needs of DeFi we create a vault that can grow with us into any direction we require. The goal is to create a vault that has absolute flexibility of what protocols to interact with and how but still remains easy to manage and save us on developing new strategies for each protocol out there.
For users the vault abstracts away the complexity of interacting with multiple protocols and allows them to deposit and withdraw with a single interface. They wont need to chase new protocols or rebalance as all this complexity is abstracted away.
## Architecture
The main contract is the `OracleVault` which uses a `Safe` to hold and manage assets. We use a `PushOracle` to keep track of the value of the assets held in the `Safe` and set the price of the vault shares.
The `OracleVault` follows the [ERC7540](https://eips.ethereum.org/EIPS/eip-7540) standard. Deposits are instantaneous but withdrawals are processed asynchronously.
The `PushOracle` is controlled by the `OracleVaultController` which has permissioned `keepers` to update the price of the `PushOracle`. Price updates are expected to happen in regular intervals. If a price update is significantly larger/smaller than the previous price we will update the price but pause the vault immediately to prevent any losses. The same goes for a drawdown from the latest high water mark. This ensures that price manipulations or temporary issues wont lead to a loss of funds for the vault or user.
The `Safe` is controlled by `managers` which can either be bots, ai agents or humans. All transactions are verified by a `TransactionGuard`-module and we have a seprate `SafeController`-module to remove malicious or inactive managers and even liquidate the `Safe` if needed. The `TransactionGuard` allows us to allow which contracts and functions `managers` can call. Later we will also add limits and decode and sanitize calls to increase security further.
`TransactionGuard` and `SafeController` both use a hook pattern to allow us to update and add additional functionality later
## Sequence Diagrams
### Deposit
Deposits only have one state. On deposit the user sends funds to the `Vault` which in turn sends it to the `Safe`. The `Vault` than mints shares to the user.
## Withdraw
\
Withdrawals are processed asynchronously. Thefore we have multiple states of a withdrawal.
First a user requests a withdrawal by sending shares to the `Vault`. This is the `pending`-state. In which a withdrawal was started but not yet completed.
In the second step that request has to get fulfilled. By sending assets to the `Vault` and burning the users shares. Now the user has `claimable assets`. This is the `fulfilled`-state. The user has their shares burned but their assets reserved though these still need to be claimed.
Lastly the user can call `withdraw()` on the `Vault` to get their funds. This is the `completed`-state. Here the user simply claims and receives their assets.
## Scope
```
├── src
│ ├── vaults
│ │ └── multisig
│ │ └── phase1
│ │ ├── AsyncVault.sol
│ │ ├── BaseControlledAsyncRedeem.sol
│ │ ├── BaseERC7540.sol
│ │ └── OracleVault.sol
│ └── peripheral
| └── oracles
| ├── adapter
│ │ └── pushOracle
│ │ └── PushOracle.sol
│ └── OracleVaultController.sol
```
At this point we expect the manager to be a trusted permissioned actor which is why we wont include any contracts of the `SafeController`-module just yet.
For `TransactionGuard` we use the `ScopeGuard`-module by zodiac which has been extensively tested and is battle tested.
## Known Issues / Securuty Considerations
A lot of the security assumptions come down to proper configuration and key management / operational security.
A malicious owner of the `OracleVaultController` or `TransactionGuard` can rug the vault and the users funds. So we need to ensure the highest level of security to keep access to the keys as limited and safe as possible.
Additionally a poorly set up `TransactionGuard` can lead to a rug pull of the vault. Verifiying and maybe even auditing the deployment is crucial here.
Idle `managers` can also stale the withdrawal process since they will need to process and fulfill withdrawals. To incentivise fulfilling we can configure a `withdrawalIncentive` which will be paid out to the manager that fulfills the withdrawal.
Lastly `setLimits` on the `AsyncVault` can lock user deposits if set too high. This can lead to a situation where a user cannot withdraw their funds even though they deposited successfully. E.g. If there wasnt a `minAmount` initially and we set the `minAmount` to a value lower than the deposit amount of certain users they wont be able to withdraw without adding more funds to the vault which might not be possible.
## Deployment
To deploy a new OracleVault we need to set up an `PushOracle` and an `OracleVaultController`. The `PushOracle` needs to be nominated and the owner accepted by the `OracleVaultController`. This can be done using `VaultOracle.s.sol`.
Set up a Safe via its app and add the agreed manager as a signer.
Now its time to deploy the `OracleVault`. The `OracleVault` needs to be added to the `OracleVaultController` and we should probably add a `keeper` on it aswell to update the price of the vault regularly. This can be done using `OracleVault.s.sol`.
To ensure the `VaultRouter` can pull funds from the Safe max-approve the `asset` to the `OracleVault`.
Lastly its recommended to set limits on the `OracleVaultController` after the vault gets deployed. To ensure that the vault wont get paused with every little price fluctuation. Simply use the script `SetVaultOracleLimits.s.sol` for it.
### Frontend Integration
To add the vault to the frontend add a new entry in `vaults/[chainId].json`. Make sure it has the the type `safe-vault-v1` and the `safe` address is correct. Than add it aswell to `vaults/tokens/[chainId].json`.
For the oracle to work you need to configure `vaults/safe/[chainId].json` and add all the assets we want to track with their price spreading. (Look at `vaults/safe/42161.json` for an example)
In `strategies/safe/[chainId].json` add the vault with all the strategies its allowed to use and their agreed allocations. (Look at `strategies/safe/42161.json` for an example)
## Further Improvement
* Add transaction verification and sanitization for all messages and transactions of the `Safe`. Managers should only be able to call previously whitelisted functions with appropriate parameters. This safeguards against rug pulls and allocations into assets that users didnt agree to.
* Futher improve and decentralie the Oracle. This could be done via zkTLS and the DeBank API to allow anyone to post the price of the vault via zkProofs.
* Add a liquidation mechanism for the `Safe` in case of drawdowns or problematic managers.
* Allow anyone to become a manager permissionlessly by simply providing a higher rate to the users and posting a certain security bond.
---
# 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.vaultcraft.io/products/v2-safe-smart-vaults/developer-docs.md?ask=
```
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.