> For the complete documentation index, see [llms.txt](https://docs.valantis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valantis.xyz/amms-and-vaults/design-space/modules/sovereign-vault.md).

# Sovereign Vault

*The Sovereign Vault is currently not used in any Valantis Pools in production.*

*Though Sovereign Vault is a powerful tool for those looking to develop using the Valantis Protocol. Sovereign Vault is used to recover multi-token pool architectures, shared liquidity designs, external use of reserves in primatives like lending markets, singleton patterns for effecient multi-hop swaps, etc.*

<figure><img src="https://986147118-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1hNJeG4CApeBcE2NlR61%2Fuploads%2Fgit-blob-7b50c3e5058e5dbb9b781c7a25ff0f1faa2441fc%2FSovereign%20Vault%20Fig.%201_V2%20(1).jpg?alt=media" alt=""><figcaption><p>Sovereign Vault in context</p></figcaption></figure>

## Usecases for Sovereign Vault

Sovereign Vault is an optional smart contract that holds all the pool’s token balances between interactions: such as deposits, withdrawals, and swaps. Any whitelisted contract that follows the Sovereign Vault interface can have authority over the pool reserves between these interactions.

Any use case that benefits from a shared accounting model between multiple pools and protocols, or benefits from having funds earning yield via external yields, can choose to leverage the Sovereign Vault interface.

Valantis permits the rise of microcosms of DEX ecosystems with shared rules and properties, as opposed to enforcing a single architecture upon all pools built on the protocol.

#### Singleton for Multi-token

Sovereign Vaults enable gas-efficient multi-hop swaps. A Sovereign Pool might have a custom Sovereign Vault which supports a large number of tokens and liquidity sources. When calling the Sovereign Pool’s swap function, the user can specify their desired `_swapTokenOut` which is not necessarily one of the pool's paired tokens. The pool's Liquidity Module can handle pricing logic between multiple token pairs, potentially even querying other external modules in the process. If multiple Sovereign Pools share the same Sovereign Vault, Valantis can support multi-hop swaps without needing to execute multiple token transfers.

<figure><img src="https://986147118-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1hNJeG4CApeBcE2NlR61%2Fuploads%2Fgit-blob-9bc95f44ee2827e5d493db9f05860fc894d0d9db%2Fshared-vault.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Sovereign Vault for LP Strategies

Liquidity Management primitives built on top of Valantis can specify custom Sovereign Vault logic for sharing funds across multiple Sovereign pools and deploying reserves in external yield-bearing strategies with minimal gas overhead. For example, singleton reserves can be deployed in yield-bearing defi protocols, such as another DEX or lending protocols, and funds can atomically be made available as active liquidity at swap time.

## Using the Sovereign Vault

If `sovereignVault` is not set, funds will by default be stored in the Sovereign Pool itself. Following interactions reserves will be updated and tokens transferred into/out of the pool. If a `sovereignVault` is specified, funds are transferred to/from the specified vault contract and reserves are updated after every interaction. This custom vault can be a custom singleton shared amongst several Valantis and even non-Valantis pools or can be a vault where funds are stored for more complex DeFi, crosschain, or yield-bearing interactions. In other words, when specified, a `sovereignVault` can be any custom vault design, allowing LPs and pool managers to express a broad range of preferences when it comes to liquidity allocation, management, and passive use of funds. It must implement the following minimal interface:

```solidity
/**
    @title Minimal interface for Sovereign Pool's custom vault.
    @dev Sovereign Pools can choose to store their token0 and token1
         reserves in this contract.
         Sovereign Vault allows LPs to define where funds should be stored
         on deposits, withdrawals, and swaps. Examples:
         - A custom LP vault that can provide liquidity to multiple pools on request.
         - A singleton contract.
         - Any external protocol that provides liquidity to incoming swaps on request.
         Moreover, it supports any number of tokens.
    @dev This is meant to be a minimal interface, containing only the functions
         required for Sovereign Pools to interact with.
 */
interface ISovereignVaultMinimal {
    /**
        @notice Returns an array of tokens that can be swapped against for a given Sovereign Pool.
        @param _pool Sovereign Pool to query tokens for.
     */
    function getTokensForPool(address _pool) external view returns (address[] memory);

    /**
        @notice Returns reserve amounts available for a given Sovereign Pool.
        @param _pool Sovereign Pool to query token reserves for.
        @param _tokens Token addresses to query reserves for.
        @dev The full array of available tokens can be retrieved by calling `getTokensForPool` beforehand.
     */
    function getReservesForPool(address _pool, address[] calldata _tokens) external view returns (uint256[] memory);

    /**
        @notice Allows pool to attempt to claim the due amount of `poolManager` fees.
        @dev Only callable by a Sovereign Pool. 
        @dev This is required, since on every swap, input token amounts are transferred
             from the user into `sovereignVault`, to save on gas. Hence manager fees
             can only be claimed via this separate call.
        @param _feePoolManager0 Amount of token0 due to `poolManager`.
        @param _feePoolManager1 Amount of token1 due to `poolManager`.
     */
    function claimPoolManagerFees(uint256 _feePoolManager0, uint256 _feePoolManager1) external;
}
```

The interface above only contains the essential methods required for the Sovereign Pool to communicate with the Sovereign Vault, but custom LMs and external contracts are free to extend it to specify more custom ways to manage deposits, withdrawals, and even multi-hop swaps.

**Note:** In case `sovereignVault` is not the pool, `poolManagerFees` are retrieved from the external Sovereign Vault. The pool cannot guarantee the correct functioning of a Sovereign Vault's `claimPoolManagerFees` implementation, hence as a security measure the pool tracks the expected pool manager fees and enforces that the Sovereign Vault's returned tokens do not exceed this expected value during the claim process. This protects the Vault from leaking funds but does not ensure the Pool Manager receives the fair amount of manager fees. Attention should be paid to a Sovereign Vault's `claimPoolManagerFees` implementation.

**WARNING:** It is recommended that `sovereignVault` implements appropriate reentrancy protections. Depending on its intended use case, it might interact with multiple contracts via a non-trivial sequence of callbacks.