HackMD
Spark on miden
To develop Spark on the Polygon Miden platform, it's essential to consider the unique features and architecture of Miden. Here's a basic plan for the architecture of Spark on Miden:
What is Spark and its Purpose
Spark is a cross-margin oracle-based perpetual order book exchange. Its key features include a high-performance order book, cross-margin trading, partial liquidations, and an advanced risk engine. On Miden, these features would be adapted to leverage Miden's concurrent transaction execution and enhanced privacy properties.
Core Accounts (Contracts) to be Developed on Miden
- Clearing House Account: This account would handle user interactions for creating positions and manage the logic for funding.
- Account Balance Account: Responsible for storing information about user positions and PnL.
- Insurance Fund Account: Functions as the exchange's risk mitigation pool.
- Perpetual Market Account: The order book account on which the perpetual exchange operates.
- Vault Account: Holds all funds; trading on Spark begins with deposits into this account.
Supporting Services for System Operation
- Liquidator Service: Liquidates positions eligible for liquidation and removes undercollateralized orders.
- Matching Engine: Matches orders in the order book.
- Risk Engine: Calculates and updates risk parameters.
External Services Required for Spark’s Operation
- Oracles (e.g., Pyth Network): Provides reliable and timely market data for asset pricing.
- Indexing Services (e.g., The Graph): Facilitates efficient data retrieval and indexing for the platform.
About oracles
Spark currently utilizes the Pyth oracle in the following functions:
Vault
withdraw_allandwithdraw_collateral: These are used for funding since they internally callclearing_house_contract.settle_all_funding.
Clearing House
liquidate: Used forsettle_all_funding,settle_bad_debt, and checkingrequire_enough_free_collateralto determine if liquidation is possible.open_order: Used forsettle_fundingand checkingrequire_enough_free_collateralto ensure the user has sufficient free collateral.pause_market: Used to record the price at which a market is paused.
Perp Market (Orderbook)
match_orders: Utilized forsettle_fundingand checkingrequire_enough_free_collateral- it verifies if the user has enough free collateral.remove_uncollaterised_orders: Used inget_free_collateralto understand if the orders are genuinely uncollateralized.
Insurance Fund
distribute_fee: Usesget_free_collateralandget_insurance_fund_capacity.repay: Executes the repayment process for the insurance fund from the contract's balance, usingvault_contract.get_account_value_and_total_collateral_value(insurance_fund_address).
Currently, Spark uses the Pyth oracle, which is an on-demand oracle. Spark can also use Chainlink as an oracle, but the price update frequency should not be less than every 2 minutes, otherwise, Spark could be vulnerable to various attacks.
Architecture Adaptations for Miden
- Parallel Transaction Execution: Leverage Miden’s ability for parallel processing to enhance the order book's performance and efficiency.
- Privacy Enhancements: Utilize Miden’s privacy features to secure transaction details and user positions.
- Actor-based State Model: Implement accounts as actors responsible for their state, communicating via messages (notes), enhancing the system’s modularity and scalability.
- Stark Proofs for Transaction Validation: Each account (actor) would independently prove the validity of their state transitions, ensuring integrity and compliance with the network rules.
Conclusion
Adapting Spark for Miden involves leveraging Miden's unique capabilities, such as parallel processing and enhanced privacy, while maintaining the core functionalities of Spark. The development would require a careful redesign of Spark’s contracts (accounts) and services to fit into Miden's actor-based model and its hybrid state management approach. The integration of external services like oracles and indexing solutions would also be crucial to ensure a robust and efficient perpetual exchange platform on Polygon Miden.
Spark docs
ClearingHouseContract Documentation
Overview
The ClearingHouseContract is a comprehensive contract covering various functionalities like order placement, position management, market operations, funding processes, liquidation, and administrative tasks in a decentralized trading platform.
ABI Functions
debug_increment_timestamp()
Description: Increments the internal timestamp for debugging purposes.
Implementation: Adjusts the internal debug timestamp based on a predefined step.
Callable By: Contract owner or admin with debug access.
open_order(base_token: AssetId, base_size: I64, order_price: u64, price_update_data: Vec<Bytes>) [Payable]
Description: Opens an order with specified base token, size, and price.
Arguments: base_token, base_size, order_price, price_update_data.
Implementation: Checks market status, registers base token, and updates price.
Calls Other Functions: check_market_open, register_base_token, update_price.
Payable: Accepts payments.
Callable By: Any authorized trader or contract.
modify_position(trader: Address, base_token: AssetId, exchanged_position_size: I64, exchanged_position_notional: I64)
Description: Modifies a trader's position for a specific base token.
Arguments: trader, base_token, exchanged_position_size, exchanged_position_notional.
Implementation: Validates market status and settles funding before modifying the position.
Calls Other Functions: check_market_open, settle_funding, require_enough_free_collateral.
Callable By: Perpetual market contract.
get_taker_position_safe(trader: Address, base_token: AssetId) -> I64
Description: Retrieves a trader's taker position size for a given base token, ensuring it's non-zero.
Arguments: trader, base_token.
Returns: Size of the taker position.
Callable By: General access.
get_taker_position(trader: Address, base_token: AssetId) -> I64
Description: Retrieves a trader's taker position size for a given base token.
Arguments: trader, base_token.
Returns: Size of the taker position.
Callable By: General access.
get_liquidated_position_size_and_notional(trader: Address, base_token: AssetId, account_value: I64, position_size_to_be_liquidated: I64) -> (I64, I64)
Description: Calculates the size and notional of a liquidated position based on account value and position size to be liquidated.
Arguments: trader, base_token, account_value, position_size_to_be_liquidated.
Returns: Tuple containing size and notional of the liquidated position.
Callable By: General access.
get_max_abs_position_size(trader: Address, base_asset: AssetId) -> (u64, u64)
Description: Retrieves the maximum absolute position size for a trader and a base asset.
Arguments: trader, base_asset.
Returns: Tuple containing max absolute short and long sizes.
Callable By: General access.
close_market(base_token: AssetId, closed_price: u64)
Description: Closes the market for a specified base token at a given price.
Arguments: base_token, closed_price.
Implementation: Updates market status to closed.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
create_market(asset_id: AssetId, decimal: u32, price_feed: b256, im_ratio: u64, mm_ratio: u64, initial_price: u64)
Description: Creates a market with specified parameters including asset ID, decimals, and ratios.
Arguments: asset_id, decimal, price_feed, im_ratio, mm_ratio, initial_price.
Implementation: Registers a new market and initializes its parameters.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
check_market_open(base_token: AssetId)
Description: Checks if the market for a given base token is open.
Arguments: base_token.
Implementation: Verifies the market status.
Callable By: General access.
get_market(base_token: AssetId) -> Market
Description: Retrieves market details for a specified base token.
Arguments: base_token.
Returns: Market structure with market details.
Callable By: General access.
get_funding(base_token: AssetId) -> (I64, u64)
Description: Gets funding information for a specific base token.
Arguments: base_token.
Returns: Tuple containing funding growth and timestamp.
Callable By: General access.
settle_all_funding(trader: Address)
Description: Settles all pending funding payments for a trader.
Arguments: trader.
Implementation: Processes funding settlements across all trader's base tokens.
Calls Other Functions: settle_funding.
Callable By: Vault contract or trader.
get_all_pending_funding_payment(trader: Address) -> I64
Description: Retrieves the total pending funding payment for a trader.
Arguments: trader.
Returns: Total pending funding payment.
Callable By: General access.
get_pending_funding_payment(trader: Address, base_token: AssetId) -> (I64, I64)
Description: Gets the pending funding payment for a trader and a specific base token.
Arguments: trader, base_token.
Returns: Tuple containing funding
payment and funding growth.
Callable By: General access.
get_funding_rate(base_token: AssetId) -> I64
Description: Calculates the funding rate for a specific base token.
Arguments: base_token.
Returns: Funding rate.
Callable By: General access.
liquidate(trader: Address, base_token: AssetId, position_size: I64, price_update_data: Vec<Bytes>) [Payable]
Description: Liquidates a specified size of a trader's position.
Arguments: trader, base_token, position_size, price_update_data.
Implementation: Processes liquidation and updates positions.
Calls Other Functions: update_price, get_liquidated_position_size_and_notional.
Payable: Accepts payments.
Callable By: Any authorized entity.
get_margin_requirement_for_liquidation(trader: Address) -> u64
Description: Retrieves the margin requirement for initiating liquidation.
Arguments: trader.
Returns: Margin requirement.
Callable By: General access.
is_liquidatable(trader: Address) -> bool
Description: Determines if a trader's positions are eligible for liquidation.
Arguments: trader.
Returns: Boolean indicating liquidation eligibility.
Callable By: General access.
pause_market(base_token: AssetId, update_data: Vec<Bytes>) [Payable]
Description: Pauses trading for a base token and updates the price feed.
Arguments: base_token, update_data.
Implementation: Changes market status to paused and updates price.
Calls Other Functions: verify_owner_or_admin, update_price.
Payable: Accepts payments.
Callable By: Contract owner or admin.
unpause_market(base_token: AssetId)
Description: Resumes trading for a base token.
Arguments: base_token.
Implementation: Changes market status to open.
Calls Other Functions: verify_owner_or_admin.
Callable By: Contract owner or admin.
add_admin(address: Address)
Description: Adds an admin to the contract.
Arguments: address.
Implementation: Registers a new admin.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
remove_admin(address: Address)
Description: Removes an admin from the contract.
Arguments: address.
Implementation: Deregisters an admin.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
update_protocol_fee_rate(protocol_fee_rate: u64)
Description: Updates the protocol fee rate.
Arguments: protocol_fee_rate.
Implementation: Adjusts the protocol fee rate.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
update_insurance_fund_fee_share(insurance_fund_fee_share: u64)
Description: Updates the insurance fund fee share ratio.
Arguments: insurance_fund_fee_share.
Implementation: Adjusts the fee share ratio for the insurance fund.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
update_liquidation_penalty_ratio(liquidation_penalty_ratio: u64)
Description: Updates the liquidation penalty ratio.
Arguments: liquidation_penalty_ratio.
Implementation: Adjusts the ratio for liquidation penalties.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
update_max_funding_rate(max_funding_rate: u64)
Description: Updates the maximum funding rate.
Arguments: max_funding_rate.
Implementation: Adjusts the maximum rate for funding.
Calls Other Functions: only_owner (internal validation).
Callable By: Contract owner.
get_account_value(trader: Address) -> I64
Description: Retrieves the account value for a given trader.
Arguments: trader.
Returns: Account value.
Callable By: General access.
get_taker_open_notional(trader: Address, base_token: AssetId) -> I64
Description: Retrieves the open notional value of a taker's position.
Arguments: trader, base_token.
Returns: Open notional value.
Callable By: General access.
require_enough_free_collateral(trader: Address)
Description: Ensures that a trader has enough free collateral as per the initial margin ratio.
Arguments: trader.
Implementation: Checks for sufficient free collateral.
Calls Other Functions: get_free_collateral (from VaultContract).
Callable By: General access.
AccountBalanceContract Documentation
Overview
The AccountBalanceContract is designed to manage and query account balances, positions, and profit and loss (PNL) data in a financial trading system. It includes features like PNL calculation, balance settlement, position management, and token registration.
ABI Functions
modify_owed_realized_pnl(trader: Address, amount: I64)
Description: Modifies the owed and realized PNL for a trader.
Implementation: Updates the trader's PNL in the system.
Callable By: Clearing House or Perpetual Market contracts.
settle_owed_realized_pnl(trader: Address) -> I64
Description: Settles the owed and realized PNL for a trader, returning the settled amount.
Implementation: Resets the trader's PNL to zero and returns the previous amount.
Callable By: Vault contract.
get_pnl(trader: Address) -> (I64, I64)
Description: Retrieves the PNL information for a trader, including owed and unrealized PNL.
Implementation: Sums up the PNL values across all trader's positions.
Callable By: Any contract or trader querying PNL data.
settle_balance_and_deregister(trader: Address, base_token: AssetId, taker_base: I64, taker_quote: I64, realized_pnl: I64)
Description: Settles the balance for a trader and deregisters them from a specified market.
Implementation: Adjusts the account balance and removes the trader from the base token registry.
Callable By: Clearing House contract.
get_account_balance(trader: Address, base_token: AssetId) -> AccountBalance
Description: Retrieves the account balance for a trader in a specific market.
Implementation: Returns balance details including position size and open notional values.
Callable By: Any contract or trader querying account balance.
register_base_token(trader: Address, base_token: AssetId)
Description: Registers a base token for a trader.
Implementation: Adds the base token to the trader's list of active tokens.
Callable By: Clearing House contract.
get_base_tokens(trader: Address) -> Vec<AssetId>
Description: Retrieves a list of base tokens registered by a trader.
Implementation: Returns all active base tokens associated with the trader.
Callable By: Any contract or trader querying registered base tokens.
settle_position_in_closed_market(trader: Address, base_token: AssetId) -> (I64, I64, I64, u64)
Description: Settles a trader's position in a closed market for a specific base token.
Implementation: Calculates and settles the position notional, open notional, and realized PNL.
Callable By: Clearing House contract.
get_liquidatable_position_size(trader: Address, base_token: AssetId, account_value: I64) -> I64
Description: Calculates the size of a liquidatable position for a trader based on their account value.
Implementation: Determines the position size eligible for liquidation.
Callable By: Any contract or trader assessing liquidation risks.
get_taker_position_size(trader: Address, base_token: AssetId) -> I64
Description: Retrieves the taker position size for a trader in a specific base token.
Implementation: Returns the current position size of the trader in the specified market.
Callable By: Any contract or trader querying position size.
get_total_position_value(trader: Address, base_token: AssetId) -> I64
Description: Retrieves the total position value for a trader in a specific base token.
Implementation: Calculates the total value of the trader's position in the market.
Callable By: Any contract or trader querying position value.
get_total_abs_position_value(trader: Address) -> u64
Description: Retrieves the total absolute position value for a trader.
Implementation: Sums up the absolute values of all positions across different markets.
Callable By: Any contract or trader querying overall position value.
settle_bad_debt(trader: Address)
Description: Settles bad debt for a trader, ensuring the trader is not the insurance fund.
Implementation: Adjusts PNL and balances to settle any outstanding bad debt.
Callable By: Any contract or trader addressing bad debt issues.
update_tw_premium_growth_global(trader: Address, base_token: AssetId, last_tw_premium_growth_global: I64)
Description: Updates the global TWAP premium growth for a trader's position.
Implementation: Records the latest TWAP premium growth for the trader's position.
Callable By: Clearing House contract.
get_taker_open_notional(trader: Address, base_token: AssetId) -> I64
Description: Retrieves the taker's open notional value for a specified base token.
Implementation: Returns the current open notional value of the trader's position.
Callable By: Any contract or trader querying open notional.
get_margin_requirement_for_liquidation(trader: Address) -> u64
Description: Retrieves the margin requirement
for liquidation for a specified trader.
Implementation: Calculates the margin needed to avoid liquidation.
Callable By: Any contract or trader assessing liquidation margins.
get_margin_requirement(trader: Address) -> u64
Description: Retrieves the margin requirement for a specified trader.
Implementation: Calculates the total margin requirement based on trader's positions.
Callable By: Any contract or trader querying margin requirements.
emit_account_balance_change_event(events: (Option<(Address, AssetId)>, Option<(Address, AssetId)>, Option<(Address, AssetId)>, Option<(Address, AssetId)>, Option<(Address, AssetId)>))
Description: Emits an event indicating a change in account balance.
Implementation: Logs account balance changes for auditing and tracking.
Callable By: Clearing House, Perpetual Market, or Vault contracts.
emit_owed_realized_pnl_change_event(events: (Option, Option))
Description: Emits an event indicating a change in owed realized PNL.
Implementation: Logs PNL changes for transparency and record-keeping.
Callable By: Clearing House, Perpetual Market, or Vault contracts.
PerpMarketContract Documentation
Overview
The PerpMarketContract is a vital component of a decentralized trading platform, handling various aspects of market operations including order management, price retrieval, and administrative functions.
ABI Functions
debug_increment_timestamp()
Description: Increments the internal timestamp for debugging purposes.
Implementation: Adjusts the internal debug timestamp based on a predefined step.
Callable By: Contract owner or admin with debug access.
open_order(trader: Address, base_token: AssetId, base_size: I64, order_price: u64)
Description: Opens a new order for a trader with specified parameters.
Implementation: Registers a new order in the system with given details.
Callable By: Clearing House contract.
Payable: No.
remove_uncollaterised_orders(trader: Address)
Description: Removes uncollateralized orders for a specified trader.
Implementation: Identifies and deletes orders lacking sufficient collateral.
Callable By: Any contract or trader addressing collateral issues.
Payable: No.
remove_order(order_id: b256)
Description: Removes a specific order by its unique ID.
Implementation: Deletes the order from the system.
Callable By: The owner of the order.
Payable: No.
remove_all_orders()
Description: Removes all orders belonging to the sender across all base tokens.
Implementation: Identifies and deletes all orders associated with the sender.
Callable By: The trader who owns the orders.
Payable: No.
match_orders(order_sell_id: b256, order_buy_id: b256, price_update_data: Vec<Bytes>)
Description: Matches a sell order and a buy order to execute a trade.
Implementation: Facilitates the trade between two matching orders.
Callable By: Any authorized trader or contract.
Payable: Yes.
has_active_orders(trader: Address, base_token: AssetId) -> bool
Description: Checks if a trader has active orders for a specific base token.
Implementation: Returns a boolean indicating the presence of active orders.
Callable By: Any contract or trader querying active orders.
Payable: No.
get_market_price(token: AssetId) -> u64
Description: Retrieves the current market price of a token.
Implementation: Returns the latest market price for the specified token.
Callable By: Any contract or trader querying market prices.
Payable: No.
get_twaps(base_token: AssetId) -> (Option<Twap>, Option<Twap>)
Description: Retrieves the TWAPs (Time-Weighted Average Prices) for a specific base token.
Implementation: Returns current and historical TWAPs for the token.
Callable By: Any contract or trader querying TWAP data.
Payable: No.
get_mark_price(token: AssetId) -> u64
Description: Retrieves the current mark price of a token.
Implementation: Returns the current mark price for the specified token.
Callable By: Any contract or trader querying mark prices.
Payable: No.
get_total_trader_order_base(trader: Address, base_token: AssetId) -> I64
Description: Retrieves the total order value of a trader for a specific base token.
Implementation: Returns the total value of orders for the trader in the base token.
Callable By: Any contract or trader querying order values.
Payable: No.
update_mark_span(mark_span: u64)
Description: Updates the mark span setting in the contract.
Implementation: Adjusts the time span for mark price calculations.
Callable By: Contract owner or admin.
Payable: No.
update_market_span(market_span: u64)
Description: Updates the market span setting in the contract.
Implementation: Adjusts the time span for market price calculations.
Callable By: Contract owner or admin.
Payable: No.
update_fee_rate(fee_rate: u64)
Description: Updates the fee rate setting in the contract.
Implementation: Adjusts the fee rate for market operations.
Callable By: Contract owner or admin.
Payable: No.
get_trader_orders(trader: Address, base_token: AssetId) -> Vec<Order>
Description: Retrieves all orders placed by a trader for a specific base token.
Implementation: Returns a list of orders for the trader in the specified token.
Callable By: Any contract or trader querying order details.
Payable: No.
setup_twap(base_token: AssetId, current_twap: u64)
Description: Sets up the TWAP for a specific base token.
Implementation: Initializes or updates the TWAP for the given token.
Callable By: Clearing House contract.
Payable: No.
InsuranceFundContract Documentation
Overview
The InsuranceFundContract is designed to manage the financial aspects of an insurance fund within a decentralized trading platform. It includes functionalities for setting thresholds, managing surplus distribution, and executing repayment processes.
ABI Functions
set_distribution_threshold(distribution_threshold: u64)
Description: Sets the distribution threshold value for the contract.
Implementation: Updates the threshold at which surplus distribution occurs.
Callable By: Contract owner or designated admin.
Payable: No.
set_surplus_beneficiary(surplus_beneficiary: Address)
Description: Sets the address to receive surplus funds.
Implementation: Designates a new address as the surplus beneficiary.
Callable By: Contract owner or designated admin.
Payable: No.
get_insurance_fund_capacity() -> I64
Description: Retrieves the current capacity of the insurance fund.
Implementation: Returns the total capacity of the fund as a signed 64-bit integer.
Callable By: Any contract or trader querying fund capacity.
Payable: No.
repay()
Description: Initiates the insurance fund repayment process.
Implementation: Executes the repayment from the contract's balance.
Callable By: Any authorized entity to initiate repayment.
Payable: No.
distribute_fee(price_update_data: Vec<Bytes>) -> u64
Description: Distributes collected fees according to the contract's logic.
Implementation: Distributes surplus fees if the fund exceeds the distribution threshold.
Callable By: Any authorized entity to trigger fee distribution.
Payable: No.
VaultContract Documentation
Overview
The VaultContract serves as a crucial component in a decentralized trading platform, handling collateral deposits and withdrawals, trading management, and administrative functions.
ABI Functions
deposit_collateral()
Description: Allows a user to deposit settlement token as collateral.
Implementation: Adds collateral to the user's balance and logs the event.
Callable By: Any user desiring to deposit collateral.
Payable: Yes, requires payment in the settlement token.
withdraw_collateral(amount: u64, price_update_data: Vec<Bytes>)
Description: Enables a user to withdraw a specified amount of collateral.
Implementation: Settles and decreases the user's balance, transferring the specified collateral amount.
Arguments: amount (collateral amount to withdraw), price_update_data (price data for updates).
Callable By: User wishing to withdraw their collateral.
Payable: Yes, involves the transfer of collateral.
withdraw_all(price_update_data: Vec<Bytes>) -> u64
Description: Withdraws the entire collateral balance for the calling user.
Implementation: Computes and transfers the total available collateral for withdrawal.
Arguments: price_update_data (price data for updates).
Returns: The total amount of collateral withdrawn.
Callable By: Any user seeking to withdraw their full collateral balance.
Payable: Yes.
get_collateral_balance(address: Address) -> u64
Description: Retrieves the collateral balance of a given address.
Implementation: Returns the collateral balance associated with the specified address.
Arguments: address (address to query).
Returns: Collateral balance of the specified address.
Callable By: Any entity querying collateral balance.
Payable: No.
get_free_collateral(trader: Address) -> I64
Description: Fetches the free collateral available to a specific trader.
Implementation: Calculates and returns the trader's free collateral.
Arguments: trader (trader's address).
Returns: Amount of free collateral available.
Callable By: Anyone inquiring about a trader's free collateral.
Payable: No.
get_account_value_and_total_collateral_value(trader: Address) -> (I64, I64)
Description: Obtains the account value and total collateral value for a trader.
Implementation: Computes and returns both the account value and total collateral value.
Arguments: trader (trader's address).
Returns: A tuple of account value and total collateral value.
Callable By: Any party interested in a trader's financial status.
Payable: No.
pause_trading()
Description: Pauses trading activities on the platform.
Implementation: Activates the trading pause mechanism.
Callable By: Contract owner or admin.
Payable: No.
resume_trading()
Description: Resumes trading activities on the platform.
Implementation: Deactivates the trading pause mechanism.
Callable By: Contract owner or admin.
Payable: No.
add_admin(address: Address)
Description: Adds an admin to the platform.
Implementation: Grants administrative privileges to the specified address.
Arguments: address (new admin's address).
Callable By: Contract owner.
Payable: No.
remove_admin(address: Address)
Description: Removes an admin from the platform.
Implementation: Revokes administrative privileges from the specified address.
Arguments: address (admin's address to remove).
Callable By: Contract owner.
Payable: No.
