Skip to main content

Admin User Stories - Prototype (Backoffice)

Scope​

This document covers the admin backoffice app, a separate internal tool for protocol operators. These features are not part of the main trading app.

Actors​

ActorDescription
AdminHolder of the admin address in GlobalConfig. Can be a regular wallet (prototype) or a multi-sig (production). The program only checks the signer matches - it has no knowledge of what controls that address

Monitoring​

US-ADMIN-00 - View protocol dashboard​

As an Admin I want to see a read-only overview of the protocol state So that I can monitor health and spot issues before acting

Acceptance criteria:

  • Shows current GlobalConfig values: fee rates, max leverage, oracle limits, min vault lockup period, protocol paused status
  • Lists all markets with: status (active/paused/deprecated), open interest, 24H volume, current funding rate
  • Lists all vaults with: status, TVL, manager address
  • Shows Liquidation Vault TVL and recent insolvent liquidation events
  • Shows accrued protocol fees pending collection
  • No write actions from this view

Protocol Config​

US-ADMIN-01 - Update protocol parameters​

As an Admin I want to update protocol-wide parameters So that the protocol can be configured and maintained

Acceptance criteria:

  • update_global_config updates: fee rates, max leverage, oracle staleness limits, liquidation fee, min vault lockup period, vault creation fee
  • Signed by the admin address
  • Changes take effect immediately

US-ADMIN-02 - Transfer admin authority​

As an Admin I want to transfer the admin address to a new wallet or multi-sig So that I can migrate to a new governance setup

Acceptance criteria:

  • transfer_admin sets pending_admin
  • accept_admin must be signed by pending_admin to complete
  • Current admin retains control until accepted
  • Two-step prevents accidentally locking out the protocol

US-ADMIN-03 - Collect protocol fees​

As an Admin I want to collect accrued vault creation fees So that revenue is transferred to the protocol treasury

Acceptance criteria:

  • collect_fees transfers fees to the treasury account in GlobalConfig
  • Event publicly visible on-chain

Markets​

US-ADMIN-04 - Add a market​

As an Admin I want to list a new perpetual market So that traders can open positions on new assets

Acceptance criteria:

  • initialize_market creates the market with: symbol, Pyth price feed ID, tick size, lot size, initial margin %, maintenance margin %, funding interval, max position size
  • Pre-allocates the order book slab (fixed size, not resizable after creation)
  • Market appears in the trading app without a frontend redeploy

US-ADMIN-05 - Update a market​

As an Admin I want to update parameters on an existing market So that I can adjust risk limits or fix misconfiguration

Acceptance criteria:

  • update_market updates any market parameter: tick size, lot size, funding interval, max position size, margin requirements, price feed ID
  • Changes take effect on the next user interaction

US-ADMIN-06 - Pause and unpause a market​

As an Admin I want to pause a specific market So that I can respond to an oracle failure or unusual market conditions

Acceptance criteria:

  • pause_market halts new orders and position opens for the market
  • Existing positions, cancels, and withdrawals still allowed during pause
  • unpause_market resumes normal operation
  • Pause status shown in the trading app

US-ADMIN-07 - Deprecate a market​

As an Admin I want to deprecate a market permanently So that I can sunset a market that is no longer supported

Acceptance criteria:

  • deprecate_market marks the market as deprecated
  • Only close and cancel allowed after deprecation - no new orders
  • Deprecated markets shown as closed in the trading app

Emergency​

US-ADMIN-08 - Soft freeze the protocol​

As an Admin I want to halt all new activity across all markets and vaults So that I can respond to an incident while still allowing users to exit

Acceptance criteria:

  • pause_protocol blocks new orders, deposits, position opens, and vault_withdraw across all markets and vaults
  • withdraw_margin remains available, traders can always recover their personal margin from UserAccount
  • unpause_protocol resumes normal operation
  • Soft freeze status shown prominently in the trading app

US-ADMIN-09 - Hard freeze the protocol​

As an Admin I want to halt all activity including withdrawals So that I can contain an active exploit where withdrawals are the attack vector

Acceptance criteria:

  • hard_freeze_protocol blocks all instructions across all markets and vaults, including withdrawals
  • Only used as a last resort, prefer soft freeze for routine incidents
  • unfreeze_protocol resumes all operations
  • Hard freeze status shown prominently in the trading app with a distinct warning (more severe than soft freeze)

Vaults​

US-ADMIN-10 - Force freeze a vault​

As an Admin I want to force freeze any vault regardless of the manager So that I can halt a vault that is behaving suspiciously

Acceptance criteria:

  • force_freeze_vault blocks new deposits and new orders from the vault manager
  • Existing depositors can still withdraw
  • Manager cannot override an admin freeze
  • Freeze event visible in the Vault Activity Log on the trading app

US-ADMIN-11 - Lift a force freeze​

As an Admin I want to lift a force freeze from a vault So that normal operation can resume after the issue is resolved

Acceptance criteria:

  • force_unfreeze_vault restores the vault to its previous state
  • Lift event visible in the Vault Activity Log

US-ADMIN-12 - Deprecate a vault​

As an Admin I want to permanently deprecate a vault So that it can be wound down with no new activity

Acceptance criteria:

  • deprecate_vault marks the vault as deprecated
  • Only withdrawals allowed after deprecation, no new deposits or positions
  • Vault shown as deprecated in the trading app
  • Manager cannot reverse deprecation

Liquidation Vault​

The Liquidation Vault is one of two protocol-owned system vaults. It covers insolvent positions when a liquidated account's collateral is insufficient to cover the loss. The admin manages it as the vault manager - no special instructions, it uses the same vault_deposit / vault_withdraw mechanism as any other vault.

US-ADMIN-13 - Monitor Liquidation Vault​

As an Admin I want to see the current Liquidation Vault balance and recent draws So that I can monitor protocol solvency

Acceptance criteria:

  • Backoffice shows current TVL of the Liquidation Vault (read from Vault PDA via RPC)
  • Lists recent insolvent liquidation events where the vault absorbed a shortfall (visible on-chain)

US-ADMIN-14 - Deposit into the Liquidation Vault​

As an Admin I want to add USDC to the Liquidation Vault So that the protocol can cover insolvent liquidations

Acceptance criteria:

  • Admin calls deposit_margin to move USDC from wallet to UserAccount, then vault_deposit into the Liquidation Vault
  • Vault TVL updates immediately after confirmation
  • Event visible on-chain

US-ADMIN-15 - Withdraw from the Liquidation Vault​

As an Admin I want to withdraw excess USDC from the Liquidation Vault So that surplus can be moved to the protocol treasury

Acceptance criteria:

  • Admin calls vault_withdraw as vault manager to burn shares and return USDC to UserAccount, then withdraw_margin to wallet
  • Rejected if now < last_deposit_time + lockup_period
  • Event visible on-chain