Skip to content

Latest commit

 

History

History
81 lines (59 loc) · 5.73 KB

UManager.md

File metadata and controls

81 lines (59 loc) · 5.73 KB

uManager and Merkle-Based Permission System Guide

uManagers are used to allow actions of functionSigs of a target contract, in behalf of the BoringVault. We will briefly explain here how to add a new uManager.

1. Key Components

ManagerWithMerkleVerification: Verifies strategist actions using Merkle proofs for secure BoringVault management. The leaves define what actions are possible, the Merkle root summarizes these permissions, and the ManagerWithMerkleVerification takes proofs and uses the root to verify and allow actions.

uManager: Micro-manager contract enforcing additional checks and custom logic for specific operations.

RolesAuthority: Manages system-wide roles and permissions.

BoringVault: The managed vault contract holding and managing assets.

MerkleTreeHelper: Functions to add target functions as leafs to the Markle tree.

Micro-Managers: Or uManagers, uses Merkle proofs to verify and execute actions with the target cotnracts securely, ensuring each operation on the target is authorized and recorded correctly in the MerkleTree.

CreateSuperSymbioticLRTMerkleRoot.s.sol: Generates leaves and Merkle root for specific actions. This has to later be manually added into the managermerkle contract. DeploySymbioticUManager.s.sol: Deploys and configures the uManager, a contract for creating the Merkle root and being able to run target functions against it.

Merkle Tree Structure:

  • Leaves: Individual permissions/actions
    • Composition: keccak256(abi.encodePacked(decodersAndSanitizer, target, valueIsNonZero, selector, argumentAddress_0, ..., argumentAddress_N))
    • Each leaf represents a specific allowed action
  • Tree: Hierarchical structure of leaves
  • Root: Single hash representing the entire tree

2. Adding a New uManager

  1. Create src/micro-managers/YourCustomUManager.sol: 
    contract YourCustomUManager is BaseUManager {
    // Your custom logic here
}
  2. Implement custom checks and functionality.
  3. Create src/base/DecodersAndSanitizers/Protocols/YourCustomDecoderAndSanitizer.sol. You will have to select what functions you are targeting.
  4. If required, create src/base/DecodersAndSanitizers/YourDeploymentDecoderAndSanitizer.sol, this aims to solve and route similarly named target gunctions.
  5. In test/resources/MerkleTreeHelper/MerkleTreeHelper.sol create functions to add target functions of the new contract as leaves to the Merkle tree. For instance, _addYourCustomApproveAndDepositLeaf function. You will also need to add this function to the create root or uManager deployer script.
  6. Create a new uManager in src/micro-managers/YourUManager.sol. You will have to create a function to provide proofs for each of the functions you added to YourCustomDecoderAndSanitizer. For each function you will have to provide manageProofs (bytes32[][]), decodersAndSanitizers (address[]), targets (address[]), values (uint256[]).

3. Setup for deployment

  1. Update test/resources/ChainValues.sol:

    • Add new deployer address
    • Replace relevant addresses (dev0, dev1, underlying tokens, vaults, etc.)

  2. Update or take inspiration from script/MerkleRootCreation/Sepolia/CreateSepoliaSuzakuMerkleRoot.s.sol and sniper script: script/DeploySepoliaSuzakuUManager.s.sol:

    • Replace relevant addresses and new point to new Decoder contracts
    • Manage JSON files: to prevent overwriting previous files, delete or rename SuperSuzakuStrategistLeafs.json and sepoliaSuzakuSniperLeafs.json
    • Modify the tokens section to use the correct MerkleTreeHelper.sol function to add the leaf.
    • Modify the tokens section if new or more target contracts are used.
    • Modify the size of the tree's and number of leafs added, depending on the number of contracts you're interacting with.

  3. Configure permissions (either through contracts or withing the script):

    • Ensure uManager has a specific role
    • This role should have permission to call manageVaultWithMerkleVerification
    • This has to be done through the rolesAuthoriy contract

4. Post-Deployment Setup

  • If using DeploySepoliaSuzakuUManager with sniper:

    • Add MerkleRoot located in leafs/sepoliaSuzakuSniperLeafs.json to the ManagerWithMerkleVerification contract, with strategist as the uManager address. This can be done with setManageRoot(strategist, newRoot) function.
    • Actions can be made through the uManager contract.

  • If using leafs/CreateSepoliaSuzakuMerkleRoot.json:

    • Add MerkleRoot located in leafs/SuperSuzakuStrategistLeafs to the ManagerWithMerkleVerification contract , with strategist as an EOA address. This can be done with setManageRoot(strategist, newRoot) function.
    • To perform any action you will have to interact with the ManagerWithMerkleVerification through the manageVaultWithMerkleVerification function. To generate a proof you can use the script generate_proof.py.

  • Updating Permissions: Call setManageRoot(strategist, newRoot) on ManagerWithMerkleVerification.

5. Update a running deployment with a new uManager

  1. Perform the previous actions by adding the new DecoderAndSanitzier and uManager contracts.
  2. Re-launch your BoringVault Deploy script, you can update configureDeployment configuration to not do unnecesary tasks. You may only need the deployCotnracts section.
  3. Update DecoderAndSanitizer version in resources/ContractNames.sol, script/MerkleRootCreation/Sepolia/CreateSepoliaSuzakuMerkleRoot.s.sol and script/DeploySepoliaSuzakuUManager.s.sol.
  4. Update test/resources/ChainValues.sol with the new addresses.
  5. Re-create MerkleRoot, or launch the new uManager
  6. Add the Root with the setManageRoot(strategist, newRoot) function. in the ManagerWithMerkleVerification contract
  7. Setup permissions.