Each supported denomination has a dedicated Liquidity Providers’ Pool (LPP) instance that handles all borrow requests and repayments in that currency. The LPP calculates a fixed interest rate for each loan, tracks the total principal and interest due, and maintains records of all active loans. An LPP operates exclusively in its native currency - called the Liquidity Pool’s Native (LPN) denomination - and does not interact with other assets.

A factory contract creates all margin positions, with one such factory deployed per integrated market. Each factory is connected to a single LPP, and by extension, to a single native currency - the Liquidity Pool’s Native (LPN) asset, which can be either a stablecoin or a volatile token. For instance, if a user wants to borrow USDC to go long, they must submit a request to the factory linked to the LPP that uses USDC as its LPN.

The factory smart contract is configured with a set of parameters that define the behavior and constraints of the margin positions it creates:

A mathematical representation of “liability covered”:

Example:

If the position value drops to 200 USDC:
→ Liability becomes 150 / 200 = 0.75 (still within limit)

If it drops further to 165 USDC:
→ Liability becomes 150 / 165 ≈ 0.91
→ This exceeds the max liability of 0.90, breaking the invariant.

Once the invariant is violated, the position is flagged for liquidation.

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 this collateral:

The resulting asset determines the final size of the position. For long positions, the target asset is typically a volatile token, while 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 create such contracts, and this is verified during contract creation.

Each position contract stores a fixed set of parameters upon creation:

ℹ️ These values are defined in the factory configuration and remain unchanged for the lifetime of the position. Any updates to a factory's configuration via governance proposals would only affect new positions opened after the change.

The maximum borrowable amount is computed based on the initial liability ratio and the provided collateral, using the following formula:

Where:

ℹ️ 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 initiates a loan request to the corresponding Liquidity Providers’ Pool (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. The formula used is:

Where:

Let’s assume the following values:

ℹ️ Then, add the protocol interest rate (e.g., 4%) on top:

Once the rate is calculated, the LPP transfers the borrowed amount directly to the margin position’s smart contract address. The debt must be fully settled for the position to be closed.

Each time a loan is issued, the Liquidity Providers’ Pool (LPP) stores key data associated with the position:

A simplified step-by-step overview of the margin position opening process is illustrated in the diagram below.

4. Cross-Chain Interactions
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 perform actions such as staking, sending tokens, or voting, but unlike traditional accounts, it does not rely on private key signatures. Instead, it is controlled via the Inter-Blockchain Communication (IBC) protocol by a designated controller account - in this case, the margin position contract instance deployed on the Nolus chain.

To complete ICA registration, an IBC acknowledgment (ACK) must be received to confirm the successful delivery of the registration message. If the acknowledgment is not returned in time, a timeout is triggered, and the protocol automatically retries the operation in the next block.

Once the ICA is successfully registered, the next step is to initiate a cross-chain asset transfer. This “transfer out” moves both the collateral and the loan amount from the position contract to the host chain via an established IBC channel. Like registration, this step also requires acknowledgment before proceeding.

After the funds arrive on the host chain, a swap is performed to obtain the desired asset. Once the swap is complete, the margin position is officially opened.

ℹ️ ICA channels are unordered by default. If an action times out, the channel remains open—this design significantly reduces the load on relayer providers responsible for managing cross-chain operations between Nolus and supported networks.

5. Opened
Once the margin position is activated, it enters the “Open” state. From this point forward, two primary actions can occur: the borrower either repays the debt or the position undergoes liquidation.

If the user initiates repayment using the same asset as the loan’s LPN (e.g., USDC for a USDC-denominated loan), the outstanding amount is reduced immediately.

If repayment is made in a different asset (e.g., ATOM), the following steps take place:

If the position still holds unpaid principal or interest after this process, it remains active.

Alternatively, the position may be liquidated, either partially or in full, based on its liability state. In both cases:

If the liquidation is partial, the position remains active. Full liquidation results in the debt being marked as repaid.

6. Debt Covered
Once the total debt, including all interest and principal, has been either fully repaid or liquidated, the position status changes from "Open" to "Paid".

At this point, the user can close the position by transferring the remaining assets to their own wallet. Once this transfer is completed and acknowledged, the position’s status updates to "Closed".

The diagram below illustrates the complete state flow of a margin position - from creation through activation, repayment, or liquidation, and final closure.

The status of any margin position can be queried at any time. There are four possible states:

The following data points are returned when querying a position:

Users can query the factory contract to estimate potential loan terms based on a given collateral amount. This quote helps preview what a margin position would look like if opened under current conditions.

⚠️ Note: The quoted parameters may change by the time the position is opened, as they depend on the real-time utilization of the corresponding LPP, which directly affects the interest rate.

The returned quote includes:

When repaying an active position, the protocol follows a strict repayment order to ensure all dues are handled correctly. The repayment amount is applied in the following sequence:

If the user repays the debt manually or partially closes the position using funds held within the position contract, the outstanding liabilities are settled accordingly, but any remaining balance must be claimed manually. In this case, the borrower must initiate a Claim action to withdraw the leftover margin from the contract.
​

However, if the position is fully closed - either via full repayment or full liquidation - the protocol automatically performs all necessary settlements:

This ensures a seamless experience in full close scenarios, while maintaining control and flexibility in partial settlement cases.

In a market close, the entire position is closed using only the funds already held within the position contract - no external capital is required from the borrower. This flow is typically triggered by the user or the protocol when the position needs to be fully settled on-chain, using the available collateral and loaned assets.

In a partial close, the borrower uses only the assets within the position to settle part or all of the outstanding debt. Unlike a full close, this does not automatically close the position. If the repayment covers the entire debt, the user must manually claim any excess funds remaining in the contract. This approach is useful when the borrower chooses to unwind part of the position without injecting external capital.