🏗️Core Modules

Factory / Proxy Contract

Role

• Acts as a routing layer for user interactions, while maintaining the ability to update the underlying logic if necessary.

Structure

• Proxy Mechanism

  • Forwards calls to the logic contract based on a stored implementation address, allowing for future upgrades.

• Records & State

  • Maintains key mappings, such as chain IDs, user addresses, and compliance periods, in a centralized location.

• Abstraction

  • Keeps functions abstract and flexible, making it easier to add new features in V2, such as multi-address withdrawals and liquidation.

Technologies

• Built with Rust, utilizing the Soroban SDK and CLI for enhanced functionality and performance.

Logic (Implementation) Contract

Role

• Manages core functionality such as deposits, withdrawals, and collateral checks. It is deployed separately and referenced by the factory or proxy contract for flexibility and scalability.

Deposit

• Parameters

  • targetChainId

    • The identifier of the target blockchain where the collateral will be deposited.

  • targetChainAddress

    • The address on the target blockchain where the collateral will be sent.

• Flow

  • The user's collateral ($XLM on the Stellar side) is locked and a mapping is created in the factory contract to associate the collateral with the target network address.

Contract

• The contract should validate that the provided chainId is supported (this will be read and added to the state).

• The contract logic then pulls the specified amount of $XLM tokens, updates the internal mapping, and records the Depositor’s address along with the total deposited amount.

Withdraw

• Parameters

  • Same targetChainId and targetChainAddress as provided during deposit for consistency.

• Compliance Check

  • Verifies the user’s record in the Factory Contract and enforces a mandatory waiting period before withdrawal.

• Restriction

  • Immediate withdrawal after deposit is prohibited to prevent flash-loan style exploits and minimize cross-chain arbitrage opportunities.

• V1 Ownership

  • Controlled by the Polariz team and the Stellar Foundation for governance.

The contract logic validates that the amount being withdrawn by the user is correct (i.e., they have previously deposited the amount, the withdrawal period has passed, etc.) and unlocks the $XLM tokens back to the sender.

An optional signature, owner, and recipient can be provided. After successful signature verification, the tokens belonging to the owner can be transferred to the specified recipient. This feature is useful in cases where the protocol can call the claim transaction on the user's behalf, improving the user experience.

Off-Chain Components

Event Listener, Parser, And Handler

• An off-chain script will be developed to listen to events from the contract deployed on the Stellar network. This script will parse the deposit event data and create a Depositor entity with its latest balance. The most up-to-date collateral balance of the Depositor will be stored in the database.

Price Resolver

• After resolving the amount of $XLM tokens, the value will be converted to its USD equivalent using an external oracle and stored as part of the Depositor entity. Price resolution will be handled and recalculated on every state-modifying event. The USD equivalent of the $XLM tokens will be included in the latest Depositor balance entity and stored in the database.

API

• An internal RESTful API will serve requests about a user’s current collateral on the Stellar network at the time of the query. This is designed for cases where the user initiates a loan at a future date.

Target Network Facilitator

• Process

  • This component will handle transactions on the target network, minting the corresponding amount of $pUSD.

• Stellar Foundation

  • The Stellar Foundation may provide liquidity for $pUSD ↔ USD conversions on Stellar, enhancing utility. Since invoking this transaction on the target network incurs fees, a stipend amount will need to be predetermined and paid by the Depositor on the originating chain.

Liquidator

• A dedicated off-chain component will serve as the Liquidator. It will actively query the current on-chain storage state of the contract, holding the Depositor balances, initiate price resolution, and perform liquidation in case of under-collateralized debt (when the Max LTV is reached). A batch liquidation transaction (batchLiquidate(positionId[])) will be called on Stellar, claiming the collateral, closing the position, clearing necessary mappings, and emitting an event.

Note: This will be the first implementation of an off-chain liquidator operated by the protocol team. However, liquidations are designed to be an open market, and the liquidation method will eventually be made available to anyone — permissionlessly.