Opening a position

To open a new margin position, the user interacts with the appropriate factory contract and provides collateral. The maximum borrowable amount is determined by the collateral and the configured initial liability ratio (e.g., 60%).

1. Collateral deposit

The user initiates a position by submitting collateral to the factory. There are three ways to provide it:

• Directly in the target asset. If the collateral matches the desired final asset of the position (e.g., a volatile token for longs, a stablecoin for shorts), no swap is required.
• In the LPN currency. The collateral is swapped via an integrated DEX (e.g., Osmosis) into the target asset.
• In a different volatile asset. The collateral is also swapped via the DEX into the target asset.

The resulting asset determines the final size of the position. For long positions, the target asset is typically a volatile token; for short positions, it's a stablecoin.

2. Position creation

Upon receiving the collateral, the factory instantiates a new position contract. Only the factory has permission to do so, and this is verified during contract creation.

Each position contract stores a fixed set of parameters at creation: the borrower's address, the loan currency (LPN), the initial interest period, the max and healthy liability ratios, the initial LTV, the liability reevaluation interval, the annual protocol interest, the LPP address, and the next interest due date.

The maximum borrowable amount is computed from the initial liability ratio and the provided collateral:

loan = initial_liability × (loan + collateral)
loan = (initial_liability × collateral) / (1 - initial_liability)

The total position size is the swapped sum of the borrowed amount and the collateral.

3. Loan request

Once the margin position contract is created, it requests a loan from the corresponding LPP. As a security measure, the LPP first verifies that the caller is a valid position contract created by the factory.

The LPP determines a fixed loan interest rate based on current pool utilization and the size of the requested loan:

Quoted Loan Interest Rate = Base Rate + (Utilization Factor / Optimal Utilization) × Add-on Rate

Where the utilization factor is Utilization / Idle Assets Portion, the base rate is the LPP-defined minimum, and the add-on rate is a slope parameter that adjusts sensitivity beyond the base.

Worked example with utilization 60%, base rate 8%, add-on rate 2%, optimal utilization 70%:

Quoted Loan Interest Rate = 8% + (1.5 / 0.7) × 2% ≈ 12.29%

The protocol interest rate (e.g., 4%) is added on top:

Effective Fixed Interest Rate = 12.29% + 4% = 16.29%

Nolus caps the rate above the optimal utilization threshold - in this example, the maximum utilization factor becomes ~2.33, capping the borrower's effective rate at ~18.67%.

Once the rate is calculated, the LPP transfers the borrowed amount directly to the position contract. The LPP records the loan with the position address, principal due in LPN, the fixed annual interest rate, and a timestamp updated on every interest payment.

4. Cross-chain setup

Once the borrowed funds are deposited into the position contract, an Interchain Account (ICA) is opened on the target host network (e.g., Osmosis). An ICA behaves like a standard account on the host chain - it can stake, send tokens, or vote - but it's controlled via IBC from a designated controller account on Nolus, in this case the position contract.

ICA registration requires an IBC acknowledgment to confirm the message landed. If it times out, the protocol automatically retries the next block.

After registration, a "transfer out" moves both the collateral and the loan amount from the position contract to the host chain via the established IBC channel. Like registration, this step requires acknowledgment before proceeding. Once the funds arrive on the host chain, the swap into the target asset runs. When that completes, the position is officially open.

5. Active

Once activated, the position is in the Opened state. From here on, two things can happen: the borrower repays the debt, or the position undergoes liquidation.

If the user repays with the same asset as the loan's LPN (e.g., USDC for a USDC-denominated loan), the outstanding amount is reduced immediately. Repayment in a different asset goes through an ICA transfer, a host-chain swap into LPN, and an IBC bridge back to Nolus, with acknowledgments at each step.

Liquidation can be partial or full. In both cases, position assets are swapped to the owed LPN on the host chain and bridged back. A partial liquidation leaves the position active; a full liquidation marks the debt as repaid.

6. Settlement

Once the total debt - principal and interest - is fully repaid or liquidated, the position status changes from Opened to Paid. The user then closes the position by transferring the remaining assets to their wallet. Once that transfer is acknowledged, the position transitions to Closed.