feat: add dual-token vault system with principal and yield tokens, including interfaces and libraries for token management

Author: maxencerb

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "lib/forge-std"]
 	path = lib/forge-std
 	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/solady"]
+	path = lib/solady
+	url = https://github.com/vectorized/solady

README.md

@@ -1,7 +1,7 @@
 ```txt                                                                                                                          █████   
-                                                      ░░███    
-  ███████    ████████     █████ ████    ████████      ███████  
- ███░░███   ░░███░░███   ░░███ ░███    ░░███░░███    ░░░███░   
+                                                     ░░███    
+ ███████    ████████     █████ ████    ████████      ███████  
+███░░███   ░░███░░███   ░░███ ░███    ░░███░░███    ░░░███░   
 ░███ ░███    ░███ ░░░     ░███ ░███     ░███ ░███      ░███    
 ░███ ░███    ░███         ░███ ░███     ░███ ░███      ░███ ███
 ░░███████    █████        ░░████████    ████ █████     ░░█████ 
@@ -13,4 +13,50 @@
 
 <p align="center" style="font-size: smaller;">
   <i>(wip)</i>
-</p>
+</p>
+
+## Principal and Yield Token Vaults
+
+The vault system implements a dual-token structure separating principal and yield:
+
+### Deposit Phase
+
+When depositing into the vault, users receive two types of shares:
+- **Principal Shares (PT)**: Equal to the amount of assets deposited
+- **Yield Shares (YT)**: Equal to the expected yield amount
+
+**Example**: Depositing 1,000,000 USDC with an expected 10% return:
+- Receive: 1,000,000 PT + 100,000 YT
+
+During the deposit phase, withdrawals are locked (`canWithdraw = false`).
+
+### Redemption Phase
+
+Once the vault receives assets and unlocks redemption (`canWithdraw = true`), the value of each share type is determined by the total assets in the vault.
+
+#### Redemption Formula
+
+```
+principalAssets = min(totalAssets, principalTokenSupply)
+yieldAssets = totalAssets - principalAssets
+
+pricePerPrincipalShare = principalAssets / principalTokenSupply
+pricePerYieldShare = yieldAssets / yieldTokenSupply
+```
+
+#### Redemption Examples
+
+Given: 1,000,000 PT and 100,000 YT outstanding
+
+| Total Assets | Principal Assets | Yield Assets | PT Price | YT Price |
+|--------------|------------------|--------------|----------|----------|
+| 900,000      | 900,000          | 0            | 0.9      | 0        |
+| 1,000,000    | 1,000,000        | 0            | 1.0      | 0        |
+| 1,050,000    | 1,000,000        | 50,000       | 1.0      | 0.5      |
+| 1,200,000    | 1,000,000        | 200,000      | 1.0      | 2.0      |
+
+**Key Properties:**
+- Principal holders are prioritized: they receive up to 1:1 redemption of their shares
+- Yield holders receive any assets beyond the principal supply
+- If total assets < principal supply, principal holders share the loss proportionally
+- If total assets > principal supply, yield holders capture all upside

foundry.lock

@@ -4,5 +4,11 @@
       "name": "v1.11.0",
       "rev": "8e40513d678f392f398620b3ef2b418648b33e89"
     }
+  },
+  "lib/solady": {
+    "tag": {
+      "name": "v0.1.26",
+      "rev": "acd959aa4bd04720d640bf4e6a5c71037510cc4b"
+    }
   }
 }

foundry.toml

@@ -3,4 +3,10 @@ src = "src"
 out = "out"
 libs = ["lib"]
 
+[fmt]
+tab_width = 2
+
+[lint]
+ignore = ["test/**/*"]
+
 # See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

lib/solady

@@ -2,18 +2,18 @@
 pragma solidity ^0.8.13;
 
 import {Script} from "forge-std/Script.sol";
-import {Request} from "../src/request/Request.sol";
+// import {Request} from "../src/request/Request.sol";
 
 contract RequestScript is Script {
-    Request public request;
+  // Request public request;
 
-    function setUp() public {}
+  function setUp() public {}
 
-    function run() public {
-        vm.startBroadcast();
+  function run() public {
+    vm.startBroadcast();
 
-        request = new Request();
+    // request = new Request();
 
-        vm.stopBroadcast();
-    }
+    vm.stopBroadcast();
+  }
 }

script/Request.s.sol

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.20;
+
+/// @title IRequest
+/// @notice Interface for handling token consumption, repayment, and validation logic in a request system.
+/// @dev This is the interface expected to intereact with the position manager to:
+/// - Account for remaining debt
+/// - Consume and repay the request token
+/// - Validate the request token and the consumer address
+interface IRequest {
+  /**
+   * @notice Consumes a specified amount of the request token and sends it to the given receiver address.
+   * @dev After a repayment has been initiated, no further consumption can take place.
+   * Requirements and expected state transitions are implementation-specific.
+   * @dev The amount of consumed tokens should not be greater than the principal assets amount.
+   * @param amount The amount of the request token to consume.
+   * @param receiver The address that will receive the consumed tokens.
+   */
+  function consume(uint256 amount, address receiver) external;
+
+  /**
+   * @notice Repays a specified amount of the request token.
+   * @dev This operation records repayment against the outstanding balance.
+   * After any call to {repay}, no further consumption is allowed.
+   * Only callable if full repayment has not yet been validated.
+   * It should pull from the caller's balance.
+   * @param amount The amount of the request token to repay.
+   */
+  function repay(uint256 amount) external;
+
+  /**
+   * @notice Validates and finalizes the state that the full repayment of the request token has been made.
+   * @dev This function locks the contract against further repayments or consumptions,
+   * and may enable a new phase in the workflow. Only callable if the amount repaid
+   * matches the total amount required.
+   */
+  function validateFullRepayment() external;
+
+  /**
+   * @notice Returns the total amount of principal tokens that have been consumed.
+   * @return The total amount of principal tokens that have been consumed.
+   */
+  function principalSupply() external view returns (uint256);
+
+  /**
+   * @notice Returns the total amount of principal assets that have been repaid.
+   * @return The total amount of principal assets that have been repaid.
+   */
+  function principalAssets() external view returns (uint256);
+
+  /**
+   * @notice Returns the total amount of yield tokens that have been consumed.
+   * @return The total amount of yield tokens that have been consumed.
+   */
+  function yieldSupply() external view returns (uint256);
+
+  /**
+   * @notice Returns the total amount of yield assets that have been repaid.
+   * @return The total amount of yield assets that have been repaid.
+   */
+  function yieldAssets() external view returns (uint256);
+
+  /**
+   * @notice Returns the address of the ERC-20 token underlying this request.
+   * @dev The returned address should reference the token contract used for consumption and repayment.
+   * @return token The address of the request token used by this contract.
+   */
+  function token() external view returns (address token);
+
+  /**
+   * @notice Returns the address of the consumer of this request.
+   * @return consumer The address of the consumer of this request.
+   */
+  function consumer() external view returns (address consumer);
+}

src/core/interfaces/IRequest.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2;
+
+/// @dev Interface of the ERC20 standard as defined in the EIP.
+/// @dev This includes the optional name, symbol, and decimals metadata.
+interface IERC20 {
+  /// @dev Emitted when `value` tokens are moved from one account (`from`) to another (`to`).
+  event Transfer(address indexed from, address indexed to, uint256 value);
+
+  /// @dev Emitted when the allowance of a `spender` for an `owner` is set, where `value`
+  /// is the new allowance.
+  event Approval(address indexed owner, address indexed spender, uint256 value);
+
+  /// @notice Returns the amount of tokens in existence.
+  function totalSupply() external view returns (uint256);
+
+  /// @notice Returns the amount of tokens owned by `account`.
+  function balanceOf(address account) external view returns (uint256);
+
+  /// @notice Moves `amount` tokens from the caller's account to `to`.
+  function transfer(address to, uint256 amount) external returns (bool);
+
+  /// @notice Returns the remaining number of tokens that `spender` is allowed
+  /// to spend on behalf of `owner`
+  function allowance(address owner, address spender) external view returns (uint256);
+
+  /// @notice Sets `amount` as the allowance of `spender` over the caller's tokens.
+  /// @dev Be aware of front-running risks: https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
+  function approve(address spender, uint256 amount) external returns (bool);
+
+  /// @notice Moves `amount` tokens from `from` to `to` using the allowance mechanism.
+  /// `amount` is then deducted from the caller's allowance.
+  function transferFrom(address from, address to, uint256 amount) external returns (bool);
+
+  /// @notice Returns the name of the token.
+  function name() external view returns (string memory);
+
+  /// @notice Returns the symbol of the token.
+  function symbol() external view returns (string memory);
+
+  /// @notice Returns the decimals places of the token.
+  function decimals() external view returns (uint8);
+}