Priime at ETHOnline 2026

/// Compose the plan for opening a fresh recursive-loop position at the
/// composer's target leverage.
///
/// Sequence (five steps, one strike):
///   1. USDC.approve(router, usdc_amount)
///   2. router.exactInputSingle(USDC -> USDe, amountOutMinimum = min_usde_out)
///   3. USDe.approve(morpho, min_usde_out)
///   4. morpho.supplyCollateral(marketParams, min_usde_out, vault, "")
///   5. morpho.borrow(marketParams, target_borrow_usdc, 0, vault, vault)
///
/// `target_borrow_usdc` lands so post-strike measured leverage
/// = collateral / (collateral - debt) = target_leverage_bps / 10_000. Anyone
/// running the same TWAP + config produces identical bytes; Morpho's own
/// LLTV guard rejects the borrow at execution if the oracle disagrees.
#[allow(clippy::too_many_arguments)]
pub fn plan_open_position(
    vault: Address,
    usdc: Address,
    usde: Address,
    morpho: Address,
    swap_router: Address,
    pool_fee: u32,
    market_params: (Address, Address, Address, Address, U256),
    usdc_amount: U256,
    twap_price_1e24: U256,
    slippage_bps: u32,
    target_leverage_bps: u32,
    deadline_secs: u64,
) -> PlanBuild {
    let min_usde_out = swap_min_usde_out(usdc_amount, twap_price_1e24, slippage_bps);

    // Borrow amount lands us at target leverage.
    // debt = collateral * (L-1) / L; collateral_value ~= min_usde_out * 1e-12
    let target_l = U256::from(target_leverage_bps);
    let collateral_value_usdc = min_usde_out / U256::from(1_000_000_000_000u64);
    let borrow_usdc = if target_leverage_bps > 10_000 {
        collateral_value_usdc * (target_l - U256::from(10_000u16)) / target_l
    } else {
        U256::ZERO
    };

    let (loan_token, collateral_token, oracle, irm, lltv) = market_params;
    let m = MorphoMarketParams {
        loanToken: loan_token,
        collateralToken: collateral_token,
        oracle,
        irm,
        lltv,
    };

    let mut plan = PlanBuild::empty(deadline_secs);

    // 1. approve USDC to router
    plan.push(
        usdc,
        approveCall {
            spender: swap_router,
            amount: usdc_amount,
        }
        .abi_encode(),
    );

    fn run_cycle(trigger_time_secs: u64) -> Result<Vec<u8>, String> {
        // Belt-and-suspenders against a composer that offers dials the
        // component cannot honor. Loop-server's config validator has the
        // canonical enforcement; this catches any config that reaches wasm
        // with a knob we cannot attest against.
        refuse_unimplemented()?;

        let vault = cfg_address("vault_address")?;
        let market_id: FixedBytes<32> = cfg("market_id")?
            .parse()
            .map_err(|e| format!("bad market_id: {e}"))?;
        let lltv: U256 = cfg("lltv")?.parse().map_err(|e| format!("bad lltv: {e}"))?;
        let usdc = cfg_address("usdc_address")?;
        let usde = cfg_address("usde_address")?;
        let oracle = cfg_address("oracle_address")?;
        let irm = cfg_address("irm_address")?;

        let targets = ReadTargets {
            morpho: cfg_address("morpho_address")?,
            market_id,
            market_params: (usdc, usde, oracle, irm, lltv),
            irm,
            pool: cfg_address("pool_address")?,
            usdc,
            vault,
            twap_window_secs: u32::try_from(cfg_u64("twap_window_secs")?).map_err(|_| {
                "twap_window_secs exceeds u32 (observe secondsAgos is uint32)".to_string()
            })?,
            inputs_block_lag: cfg_u64("inputs_block_lag")?,
        };

        let s = fetch_state(rpc_url()?, &targets, trigger_time_secs)?;

        if s.market_last_update == 0 || s.market_last_update > s.block_timestamp {
            return Err(format!(
                "market lastUpdate {} incoherent with block timestamp {}",
                s.market_last_update, s.block_timestamp
            ));
        }
        let elapsed = s.block_timestamp - s.market_last_update;

        let accrued = nav::accrued_total_borrow(s.total_borrow_assets, s.borrow_rate_wad, elapsed);
        let debt = nav::borrow_assets_up(s.borrow_shares, accrued, s.total_borrow_shares);

        // Read the strategist's per-knob invariants and fail the cycle when
        // the measured observation breaches them. Each check is skipped when
        // the vault is not in a state the invariant applies to (no debt, no
        // NAV, no policy declared), so a freshly published vault attests
        // deterministically before any strategist action has landed.
        if let Some(raw) = cfg_opt("applied_leverage") {
            let configured_bps = nav::parse_decimal_bps(&raw)?;
            // 25% tolerance band: 2.5x published lets the position sit in
            // [1.875x, 3.125x] before the cycle refuses.
            nav::check_applied_leverage_drift(obs.leverage_bps, configured_bps, 2_500, debt)?;
        }
        if let Some(raw) = cfg_opt("hf_deleverage_bps") {
            let deleverage_bps: u32 = raw
                .trim()
                .parse()
                .map_err(|e| format!("bad hf_deleverage_bps in config: {e}"))?;
            if nav::check_deleverage_threshold(obs.ltv_bps, deleverage_bps, debt, lltv)? {
                breach_flags |= nav::BREACH_DELEVERAGE;
            }
        }
        if let Some(raw) = cfg_opt("reserve_fraction") {
            let floor_bps = nav::parse_decimal_bps(&raw)?;
            nav::check_reserve_floor(obs.reserve_bps, floor_bps, value)?;
        }
        if let Some(raw) = cfg_opt("compound_cadence_hours") {
            let cadence_hours: u32 = raw
                .trim()
                .parse()
                .map_err(|e| format!("bad compound_cadence_hours in config: {e}"))?;
            // Six-hour grace: a missed cron beat does not immediately kill
            // an otherwise healthy vault.
            nav::check_compound_cadence(obs.hours_since_update, cadence_hours, 6)?;
        }

        // Fold every guard's verdict into the observations bag so the vault
        // contract can decode `breachFlags != 0` and stop taking new
        // deposit / redeem requests (roadmap P00 #13). Non-fatal: the strike
        // still attests, downstream verifiers still see every reading.
        obs.breach_flags = breach_flags;

        // Compose the on-chain action plan the vault will dispatch after
        // NAV settlement. On breach we force an empty plan: the position
        // has drifted past what the strategist configured, and continuing
        // to lever up (or emit any other loop action) against a live guard
        // would be a lie of omission. Plan-deleverage lands in P1 #4 and
        // will replace the empty plan with an unwind step.
        let plan = if breach_flags != 0 {
            nav::PlanBuild::empty(s.block_timestamp)
        } else {
            build_action_plan(&s, debt, value, twap_price, price)?
        };

/// Fail the cycle when the market has not accrued within the strategist's
/// compound cadence. `grace_hours` is added to the configured cadence so a
/// missed cron beat does not immediately kill the vault. A cadence of zero
/// disables the check (no policy declared).
pub fn check_compound_cadence(
    hours_since_update: u32,
    cadence_hours: u32,
    grace_hours: u32,
) -> Result<(), String> {
    if cadence_hours == 0 {
        return Ok(());
    }
    let ceiling = cadence_hours.saturating_add(grace_hours);
    if hours_since_update > ceiling {
        return Err(format!(
            "compound_overdue: {hours_since_update} hours since market update, cadence {cadence_hours} h (+ {grace_hours} h grace)"
        ));
    }
    Ok(())
}

/**
 * What one firing carries: the WHOLE lane weight.
 *
 * Outside R15's [0.05, 0.25] move cap by construction, and cleared by name.
 * `applyMove` still clamps it to the room the source actually has, so a lane
 * already at zero moves nothing and the decision records what moved.
 */
export const FLOOR_PAIR_MOVE_WEIGHT = 1;

/**
 * The weekly turnover ceiling, in percent of the book.
 *
 * 100 admits ONE full move per week and refuses the second, which is the
 * budget doing its job rather than the budget being switched off: the
 * evaluator refuses a firing it cannot fund and never sizes it down.
 */
export const FLOOR_PAIR_TURNOVER_PCT_WEEK = 100;

/**
 * ══ A SWITCH HOLDS ONE LANE, AND THIS IS WHO HOLDS IT ════════════════════
 *
 * On this pair the allocation is NOT a dial and NOT an even split. The
 * mechanism evacuates a lane and rebuilds it, so between firings the book is
 * entirely in one lane; a 50/50 seat drawn on the plate, published onto the
 * record and printed in the instrument's Allocation row described a portfolio
 * this machine is never in. It also made every printed move size a half-move:
 * the replay's own first decision reads `50.0pp` out of a 100% rule, because
 * the lane it evacuated only held half the book to begin with.
 *
 * WHICH LANE, and it is a measurement rather than a preference. At publish the
 * loop holds the book, unless the pair's own published rates TODAY already
 * clear the bar for the floor, in which case seating the loop would publish a
 * vault whose first act is to leave the lane it was seated in. That is the
 * whole rule, and the bar it asks with is the shipped one.
 *
 * `todayPair` is the caller's, because this module is a leaf with one import
 * and `router-history` reaches `templates` and back to `graph-ops`, which
 * imports this file: resolving the capture here would close a cycle of exactly
 * the shape F6 already cost this package once. `lib/canvas/floor-pair-seat.ts`
 * is the one module that resolves it, and every surface reads that.
 */
export type FloorPairHolder = "loop" | "floor";

/**
 * The lane the rule holds, given the pair's published rates today.
 *
 * A missing or unpriced side seats the LOOP: the loop is the lane the vault is
 * composed around, and an absent measurement is not evidence for leaving it.
 */
export function floorPairSeat(
  todayPair: { readonly loop: number | null; readonly floor: number | null } | null,
  bar: number,
): FloorPairHolder {
  const loop = todayPair?.loop ?? null;
  const floor = todayPair?.floor ?? null;
  if (loop === null || floor === null) return "loop";
  return floor - loop >= bar ? "floor" : "loop";
}

dataSources:
  - kind: ethereum
    name: PriimeVaultFactory
    network: base
    source:
      abi: PriimeVaultFactory
      address: "0xa3cbA56ECC2F6684abf3D5a0Fd2C93D030849aBF"
      startBlock: 51230370
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Vault
      abis:
        - name: PriimeVaultFactory
          file: ./abis/PriimeVaultFactory.json
      eventHandlers:
        - event: VaultCreated(indexed address,indexed address,indexed
            address,address,address,uint256)
          handler: handleVaultCreated
      file: ./src/priime-vault-factory.ts
templates:
  - kind: ethereum
    name: PriimeVaultInstance
    network: base
    source:
      abi: PriimeVault
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Vault
        - Strike
        - DepositRequest
        - RedeemRequest
        - DepositFulfilled
        - RedeemFulfilled
        - DepositRefunded
        - PlanExecution
        - PlanRejection
        - Deleverage
        - ExecuteCall
        - VaultDailyMetric
      abis:
        - name: PriimeVault
          file: ./abis/PriimeVault.json
      eventHandlers:
        - event: NavUpdated(indexed
            bytes20,uint256,uint256,uint256,bytes32,uint32,uint32,uint32,uint32,uint32,uint16)
          handler: handleNavUpdated
        - event: DepositRequest(indexed address,indexed address,indexed
            uint256,address,uint256)
          handler: handleDepositRequest
        - event: RedeemRequest(indexed address,indexed address,indexed
            uint256,address,uint256)
          handler: handleRedeemRequest
        - event: DepositRequestFulfilled(indexed address,uint256,uint256)
          handler: handleDepositRequestFulfilled
        - event: RedeemRequestFulfilled(indexed address,uint256,uint256)
          handler: handleRedeemRequestFulfilled
        - event: DepositRequestRefunded(indexed address,uint256)
          handler: handleDepositRequestRefunded
        - event: Executed(indexed address,bytes)
          handler: handleExecuted
        - event: PlanExecuted(indexed bytes32,uint256)
          handler: handlePlanExecuted
        - event: PlanRejected(indexed bytes32,bytes)
          handler: handlePlanRejected

        // 3. Swap USDe -> USDC through the pinned Uniswap V3 pool.
        //    `minUsdcOut` is the operator quorum's slippage floor,
        //    computed off the same TWAP the strike attests; the swap
        //    reverts if the pool has moved outside that window between
        //    the operator's read and this call. SwapRouter02 drops the
        //    per-swap `deadline`; the whole plan step is atomic in one
        //    tx so the pool state at call time is the state the quorum
        //    priced against.
        IERC20(collateralToken).forceApprove(swapRouter, collateralOut);
        uint256 usdcOut = IUniswapV3SwapRouter02(swapRouter)
            .exactInputSingle(
                IUniswapV3SwapRouter02.ExactInputSingleParams({
                    tokenIn: collateralToken,
                    tokenOut: asset(),
                    fee: poolFee,
                    recipient: address(this),
                    amountIn: collateralOut,
                    amountOutMinimum: minUsdcOut,
                    sqrtPriceLimitX96: 0
                })
            );

        if (usdcOut < minUsdcOut) revert DeleverageSlippage(usdcOut, minUsdcOut);

        // 4. Grant Morpho the allowance it needs to pull the flashloan back.
        //    `safeTransferFrom` inside `flashLoan` consumes it exactly.
        IERC20(asset()).forceApprove(address(morpho), assets);

        emit Deleveraged(assets, collateralOut, usdcOut);