cyotee/reliquary-deployment

Reliquary Deployment & Usage

Deployment Approaches

1. Direct Deployment (Tests / Development)

Reliquary is a standard non-Diamond contract. Deploy it directly with new:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import {Reliquary} from "@crane/contracts/protocols/staking/reliquary/v1/Reliquary.sol";
import {LinearCurve} from "@crane/contracts/protocols/staking/reliquary/v1/curves/LinearCurve.sol";
import {MockERC20} from "@crane/contracts/test/mocks/MockERC20.sol";

contract MyReliquaryDeploy {
    function deploy() external {
        // 1. Deploy reward token (any ERC20)
        MockERC20 rewardToken = new MockERC20("Reward", "RWD", 18);

        // 2. Deploy Reliquary — deployer gets DEFAULT_ADMIN_ROLE
        Reliquary reliquary = new Reliquary({
            _rewardToken: address(rewardToken),
            _emissionRate: 1e18,       // 1 reward token per second
            _name: "Reliquary Deposit",
            _symbol: "RELIC"
        });

        // 3. Fund Reliquary with reward tokens (must have balance to pay rewards)
        rewardToken.mint(address(this), 1_000_000e18);
        rewardToken.transfer(address(reliquary), 1_000_000e18);

        // 4. Deploy a curve for the pool
        LinearCurve curve = new LinearCurve({
            _slope: 100,                // multiplier increases by 100 per second
            _minMultiplier: 365 days * 100  // f(0) = 365e5 (no lock = 100% annual boost)
        });

        // 5. Approve Reliquary to spend pool token (for addPool bootstrap)
        MockERC20 poolToken = new MockERC20("Pool", "POOL", 18);
        poolToken.mint(address(this), 1_000_000e18);
        poolToken.approve(address(reliquary), type(uint256).max);

        // 6. Add pool — triggers 1 wei bootstrap deposit (caller must hold + approve 1 wei)
        reliquary.addPool({
            _allocPoint: 100,
            _poolToken: address(poolToken),
            _rewarder: address(0),           // or address of ParentRollingRewarder
            _curve: curve,
            _name: "My Pool",
            _nftDescriptor: address(0),
            _allowPartialWithdrawals: true,
            _to: address(this)               // receives the bootstrap 1 wei Relic
        });

        // 7. Create a Relic and deposit actual tokens
        poolToken.approve(address(reliquary), type(uint256).max);
        uint256 relicId = reliquary.createRelicAndDeposit({
            _to: address(this),
            _poolId: 0,
            _amount: 1000e18
        });
    }
}

2. Deterministic Deployment (Crane Create3Factory)

For production with deterministic addresses, use Crane's Create3Factory:

// Deploy Reliquary deterministically via Create3Factory
ICreate3FactoryProxy create3Factory = ...; // from InitDevService.initEnv()

bytes memory initArgs = abi.encode(
    address(rewardToken),   // _rewardToken
    1e18,                   // _emissionRate
    "Reliquary Deposit",     // _name
    "RELIC"                 // _symbol
);

// Salt derived from type name (Crane convention)
bytes32 salt = keccak256(abi.encode("Reliquary"));

address reliquaryAddr = create3Factory.deploy(
    type(Reliquary).creationCode,
    initArgs,
    salt
);
vm.label(reliquaryAddr, "Reliquary");

---

Adding a Pool

Prerequisites

Before calling addPool, the caller must:

1. Have DEFAULT_ADMIN_ROLE on Reliquary
2. Hold at least 1 unit of the pool token
3. Have approved Reliquary to spend that 1 unit

// Approve and add pool
IERC20(poolToken).approve(address(reliquary), type(uint256).max);
reliquary.addPool({
    _allocPoint: 100,
    _poolToken: address(poolToken),
    _rewarder: address(0),
    _curve: curve,
    _name: "ETH/USDC LP",
    _nftDescriptor: nftDescriptor,
    _allowPartialWithdrawals: true,
    _to: address(dao)      // DAO receives the bootstrap Relic
});

Pool with Rolling Rewarder

// 1. Deploy ParentRollingRewarder first (its owner will manage children)
ParentRollingRewarder rewarder = new ParentRollingRewarder();

// 2. Add pool with rewarder — Reliquary calls rewarder.initialize(poolId)
reliquary.addPool({
    _allocPoint: 100,
    _poolToken: address(poolToken),
    _rewarder: address(rewarder),
    _curve: curve,
    _name: "My Pool",
    _nftDescriptor: address(0),
    _allowPartialWithdrawals: true,
    _to: address(this)
});

// 3. As rewarder owner: create a child for each reward token
address child = rewarder.createChild(address(rewardToken));

// 4. Fund the child — owner approves and calls fund()
IERC20(rewardToken).approve(child, type(uint256).max);
RollingRewarder(child).fund(100_000e18);

// 5. Optionally set distribution period before funding
RollingRewarder(child).updateDistributionPeriod(30 days);

---

User Operations

Deposit into Existing Relic

// Approve Reliquary to spend your pool tokens
IERC20(poolToken).approve(address(reliquary), type(uint256).max);

// Deposit and harvest rewards in one transaction
reliquary.deposit({
    _amount: 500e18,
    _relicId: 1,
    _harvestTo: address(this)  // non-zero = harvest too
});

Create New Relic + Deposit

uint256 relicId = reliquary.createRelicAndDeposit({
    _to: address(this),
    _poolId: 0,
    _amount: 1000e18
});

Withdraw + Harvest

reliquary.withdraw({
    _amount: 200e18,
    _relicId: 1,
    _harvestTo: address(this)  // harvests rewards while withdrawing
});

Harvest Only (No Deposit/Withdraw)

reliquary.update({
    _relicId: 1,
    _harvestTo: address(this)   // non-zero address triggers harvest
});

Split a Relic

// Requires allowPartialWithdrawals == true for this pool
uint256 newId = reliquary.split({
    _relicId: 1,
    _amount: 100e18,
    _to: address(otherPerson)
});

Merge Two Relics

// Both relics must be in the same pool
reliquary.merge({
    _fromId: 2,
    _toId: 1   // burns fromId, moves all amount into toId
});

Burn Empty Relic

// Can only burn if amount == 0 AND no pending rewards
reliquary.burn(relicId);

---

Using Deposit Helpers

For pools with ERC4626 vault or Reaper vault poolTokens, use the helpers instead of direct Reliquary calls.

ERC4626 Vault Pool

// Deploy helper
DepositHelperERC4626 helper = new DepositHelperERC4626({
    _reliquary: reliquary,
    _weth: address(weth)
});

// Approve helper to pull underlying (e.g., USDC)
IERC20(underlying).approve(address(helper), type(uint256).max);

// Create relic + deposit underlying (helper converts to vault shares, deposits to Reliquary)
uint256 relicId = helper.createRelicAndDeposit{value: 0}(0, amount);

// Withdraw — optionally as ETH
helper.withdraw(amount, relicId, harvest, withdrawAsETH);

// Deposit ETH directly
uint256 relicId = helper.createRelicAndDeposit{value: 1 ether}(0, 1 ether);

Reaper Vault Pool

DepositHelperReaperVault helper = new DepositHelperReaperVault({
    _reliquary: reliquary,
    _weth: address(weth)
});

// Approve underlying token
IERC20(underlying).approve(address(helper), type(uint256).max);

// Deposit
(uint256 relicId, uint256 shares) = helper.createRelicAndDeposit(0, amount);

// Withdraw underlying (optionally as ETH)
helper.withdraw(amount, relicId, harvest, asETH);

---

Important Constraints

Reward Funding

Reliquary pays rewards from its own balance. If rewardToken.balanceOf(reliquary) < pendingReward, users receive less than shown in pendingReward(). Keep Reliquary funded by topping up its balance periodically.

Partial Withdrawals

If allowPartialWithdrawals == false:

• Users cannot withdraw less than their full position
• split() and shift() are disabled

Pool Token Restrictions

• Pool token cannot be the reward token (reverts in addPool)
• Pool token totalSupply() must be ≤ 100e9 ether

Curve Constraints

• curve.getFunction(0) must be > 0
• 10-year projection must not overflow: emissionRate * 10years * ACC_REWARD_PRECISION * curve.getFunction(10years) checked at addPool time

Max Pools

Pool IDs are uint8 — maximum 255 pools per Reliquary.

---

Testing Pattern (Crane)

Use TestBase_Reliquary for tests:

contract MyReliquaryTest is TestBase_Reliquary {
    function testDeposit() public {
        // Inherits: reliquary, linearCurve, rewardToken, poolToken, etc.
        // setUp() already: deploys Reliquary, adds pool 0 with linearCurve
        
        uint256 relicId = _createAndDeposit(0, 1000e18);
        assertEq(reliquary.getPositionForId(relicId).amount, 1000e18);
    }
}

For ERC4626/Reaper vault pools, extend TestBase_Reliquary:

contract MyERC4626PoolTest is TestBase_Reliquary {
    DepositHelperERC4626 helper;
    IERC4626 vault;
    MockERC20 oath;
    WETH9 weth;

    function setUp() public override {
        TestBase_Reliquary.setUp();
        
        oath = new MockERC20("Oath", "OATH", 18);
        Reliquary r = new Reliquary(address(oath), 1e17, "Rel", "REL");
        reliquary = IReliquary(address(r));
        
        weth = new WETH9();
        vault = new ERC4626Mock(address(weth), "Vault", "VLT", 18);
        linearCurve = new LinearCurve(100, 365 days * 100);
        
        // ... add pool with vault as poolToken
    }
}

---

See Also

• skill:reliquary-architecture — conceptual model, curves, rewarders
• contracts/protocols/staking/reliquary/v1/test/bases/TestBase_Reliquary.sol — test deployment pattern
• contracts/protocols/staking/reliquary/v1/helpers/ — helper contracts for ERC4626/Reaper/BPT pools