Skip to main content

User Stories

Actors​

ActorDescription
AnonymousVisitor without a connected wallet — browse, view markets, vaults, leaderboard, build order previews (cannot submit)
TraderConnected wallet user — deposit margin, trade, manage vaults, deposit into vaults
Keeper BotAutomated bot that monitors positions and executes liquidations. Permissionless — anyone can run one
AdminMulti-sig address (any N-of-M wallet or governance system). Controls protocol parameters
DeveloperThird-party integrating with the SDK or API

Shared Stories​

US-WALLET-01 — Connect and disconnect wallet​

As a User (Anonymous or Trader) I want to connect my Solana wallet or disconnect to end my session So that I can access platform features or switch accounts

Acceptance criteria:

  • Wallet connection initiates the connection flow and transitions user to Trader state
  • Connection persists across page refreshes
  • Connected wallet address and SOL/USDC balance are displayed
  • Trader can disconnect at any time, clearing session data and returning to Anonymous state

US-SETTINGS-01 — View and change settings​

As a User (Anonymous or Trader) I want to open and change my language and block explorer preferences, and view risk disclosures, terms, and docs So that I can customise my experience and understand the protocol

Acceptance criteria:

  • Settings accessible to all users
  • Configurable: language preference, block explorer preference
  • Links to Terms of Use, Privacy Policy, and documentation are accessible

US-MARKETS-01 — Markets listing​

As a User (Anonymous or Trader) I want to see all available perp markets organised by sections and filters So that I can discover and compare markets before trading

Acceptance criteria:

  • Markets listing page is publicly accessible with sections: Recently Added, Top Gainers, Top Losers, Top Volume
  • Filters: All, Crypto, TradFi, Search input
  • Sub-filters within category: All, Pinned, L1, Top Gainers, Top Losers
  • Market table shows per market: name, max leverage, last price, mark price, 24H change %, funding rate annual %, open interest (USD and units), 24H volume, 24H range
  • Clicking a row navigates to the market's trade page

US-MARKETS-02 — Trade page​

As a User (Anonymous or Trader) I want to access the main trading page with chart, order book, and order placement tools So that I can analyse market conditions and execute trades

Acceptance criteria:

  • Trade page shows chart, order book depth, recent trades, and market statistics without wallet connection
  • Read-only: mark price, oracle price, funding rate, open interest, 24H volume
  • Market switcher available without going back to the listing
  • Anonymous can preview orders but cannot submit
  • Trader additionally has: order placement, cancellation, position management, estimated funding payment for own position size

US-VAULTS-01 — Browse vaults​

As a User (Anonymous or Trader) I want to browse vault categories, view vault details, and see performance data So that I can evaluate vaults before depositing

Acceptance criteria:

  • All vault categories (Protocol, Verified, Community) and featured vaults are publicly visible
  • Vault detail pages show: PnL, order history, TVL, track record, manager info, open positions, lockup period, performance fee
  • Vault detail page includes a Vault Activity Log showing admin events (freeze, unfreeze, deprecate) with timestamps
  • If the viewer is a depositor, a My Stats section also shows: vault position (current value), all-time earnings, unrealised earnings, total deposited, total withdrawn

US-ORDER-PREVIEW-01 — Build an order preview​

As a User (Anonymous or Trader) I want to configure an order and see a preview with estimated values So that I can simulate a trade before committing

Acceptance criteria:

  • User can select market, side, order type, quantity, and leverage
  • Preview shows: estimated liquidation price, margin required, order value, and fees (maker/taker)
  • Anonymous cannot submit — submit button requires connected wallet

US-PORTFOLIO-01 — View trader portfolio​

As a User (Anonymous or Trader) I want to view a trader's portfolio overview, balance, PnL, and activity So that I can evaluate their performance

Acceptance criteria:

  • Trader profile pages show: PnL, volume, equity, balance, and trade history without wallet connection
  • Connected trader can additionally view own personalised portfolio dashboard with filters

Trader​

Shared stories also apply to Traders.

Terms & Onboarding​

US-TRADER-01 — Accept terms on first connect​

As a Trader I want to review and accept the Terms of Use, Privacy Policy, and Cookie Policy when connecting my wallet for the first time So that I acknowledge the rules and risks of using the protocol

Acceptance criteria:

  • First-time wallet connection requires accepting terms before any trading features are accessible
  • User must sign an off-chain message with their wallet (e.g. "I accept Terms of Use, Privacy Policy, and Cookie Policy for Artifi at [timestamp]")
  • Declining rejects the connection
  • Acceptance is stored per wallet address — returning wallets do not need to accept again

Deposits & Withdrawals​

US-TRADER-06 — Deposit margin​

As a Trader I want to deposit USDC into the protocol as margin So that I have balance to use for trading

Acceptance criteria:

  • User specifies the amount to deposit
  • User can deposit the maximum amount available in their wallet
  • Deposit transfers USDC to the user's UserAccount on-chain
  • After confirmation, the user's protocol balance updates immediately
  • Transaction is rejected if wallet balance is insufficient
  • Network fee is shown before confirmation

US-TRADER-07 — Withdraw margin​

As a Trader I want to withdraw my margin from the protocol So that I can move funds back to my wallet

Acceptance criteria:

  • User can only withdraw available margin — amount not reserved for open positions or orders
  • Transaction is rejected if requested amount exceeds available margin
  • Oracle VAA is included in the transaction to validate that remaining margin covers open positions
  • Network fee is shown before confirmation

Orders​

US-TRADER-08 — Place an order​

As a Trader I want to place a market or limit order with my chosen risk settings So that I can execute trades on my terms

Acceptance criteria:

Common to all order types:

  • User must specify side (Long or Short), order type, and quantity
  • User can set leverage from 1x to max leverage configured per market
  • Before execution, preview shows: estimated liquidation price, margin required, order value (notional), and fees (maker/taker)
  • System reserves sufficient margin on order placement
  • Matching is attempted inline on-chain at the time of submission — no separate step required

Market order:

  • Executes immediately at best available prices, walking the book until filled
  • Any unfilled remainder is canceled

Limit order:

  • Rests on the book at the specified price with price-time priority
  • Remains open until filled or canceled

Post-Only (post-prototype):

  • Entered as maker only — rejected if it would cross an existing order
  • Prevents paying taker fee

IOC — Immediate-or-Cancel (post-prototype):

  • Like market but with a price cap/floor — canceled if the full size cannot be filled within the price limit

US-TRADER-09 — Cancel an open order​

As a Trader I want to cancel one of my open orders So that it is no longer resting on the book

Acceptance criteria:

  • User can cancel any of their own open orders
  • Cancel removes the slab entry and frees reserved margin
  • User can cancel all open orders for the current market at once

US-TRADER-10 — View open orders​

As a Trader I want to see all my currently open orders So that I can manage my active positions on the book

Acceptance criteria:

  • Shows all open orders with: timestamp, side, market, price, quantity, filled size
  • Orders grouped by market
  • Updates in real-time via WebSocket
  • Cancel is available per order
  • Sortable by time, price, size, side

Positions​

US-TRADER-11 — View positions​

As a Trader I want to see my open positions and PnL So that I can monitor my exposure

Acceptance criteria:

  • Shows all open positions with: market, size, entry price, mark price, liquidation price, margin, unrealised PnL
  • Updates in real-time via WebSocket

US-TRADER-12 — Close a position​

As a Trader I want to close one or all of my open positions So that I can realise PnL or reduce exposure

Acceptance criteria:

  • User can close a single position by submitting a market order of equal and opposite size
  • User can close all open positions at once
  • Closing frees the reserved margin and settles PnL to UserAccount
  • Closed position is recorded in trade history with realised PnL

US-TRADER-13 — View trade history​

As a Trader I want to see my past filled orders and closed positions So that I can review my trading performance

Acceptance criteria:

  • Shows: time, market, side, price, size, fee, realised PnL
  • Filterable by market, date range, side
  • Sortable by time, PnL, size
  • Exportable to CSV

US-TRADER-14 — View transaction history​

As a Trader I want to see all my deposits, withdrawals, and fee payments So that I can reconcile my account activity

Acceptance criteria:

  • Shows: type (deposit, withdrawal, fee, liquidation), amount, tx signature, timestamp
  • Each entry links to a block explorer
  • Filterable by type and date range

US-TRADER-15 — View order history​

As a Trader I want to see all my orders (filled, canceled, expired) So that I have a complete record of my order activity

Acceptance criteria:

  • Shows: time, market, side, price, size, filled %, status, order type
  • Filterable by status and market
  • Export available

US-TRADER-16 — View funding history​

As a Trader I want to see all funding rate payments I've paid or received So that I can track the cost of holding positions

Acceptance criteria:

  • Shows: time, market, funding rate, position size, payment amount
  • Positive = received, Negative = paid
  • Filterable by market and date range
  • Cumulative funding paid/received is accessible
  • Export available

Portfolio​

US-TRADER-17 — View portfolio overview​

As a Trader I want to see a dashboard with my overall account summary So that I can track my total performance at a glance

Acceptance criteria:

  • Shows: 30D PnL, 30D volume, max drawdown (30D), total equity, perps account equity
  • Sub-views: Balance, Positions, Open Orders, Trade History, Order History, Funding History, Deposits/Withdrawals
  • 7D / 30D / All time filter applies across all sub-views

US-TRADER-18 — View balance details​

As a Trader I want to see my available balance, margin used, and equity breakdown So that I know how much capital I can trade with

Acceptance criteria:

  • Shows: total equity, perps account equity, available balance, margin used
  • Deposit and Withdraw functionality accessible from this view

Account​

US-TRADER-19 — Switch trading account​

As a Trader I want to switch between my personal trading account and my vault account So that I can trade with either my own margin or pooled depositor capital

Acceptance criteria:

  • Account switcher shows: Personal Account and Vault Account (if managing one)
  • Switching updates all market-dependent data: orders, positions, balance, history
  • When using vault account, all trades are attributed to the vault on-chain
  • Switching does not affect open orders or positions of the previous account

Vaults — Depositor​

US-TRADER-20 — Deposit into a vault​

As a Trader I want to deposit USDC into a vault So that my capital is managed by the vault strategy and I earn a share of the PnL

Acceptance criteria:

  • Any trader with a connected wallet can deposit into any active vault
  • Vault program mints shares proportional to current NAV at time of deposit
  • Deposit updates last_deposit_time on-chain — this is used to enforce the lockup period
  • Deposit is rejected if vault is frozen or deprecated
  • Deposit is rejected if below vault's min_deposit
  • Risk disclaimer shown before first deposit

US-TRADER-21 — Withdraw from a vault​

As a Trader I want to withdraw my share from a vault So that I can realise gains or exit

Acceptance criteria:

  • Withdrawal burns vault shares and returns USDC proportional to current NAV
  • Withdrawal is rejected if now < last_deposit_time + vault.lockup_period
  • UI shows the exact date and time when withdrawal becomes available (based on last deposit)
  • Depositing additional funds resets the lockup countdown
  • Performance fee is deducted from profits before USDC is returned to depositor

Vaults — Manager​

US-TRADER-22 — Create a vault​

As a Trader I want to create a vault by specifying its parameters So that I can attract depositors and trade pooled capital

Acceptance criteria:

Basic info:

  • Manager sets vault name and description

Financial parameters:

  • Manager enters initial deposit amount (seeds the vault — zero-capital vaults not allowed)
  • Manager sets performance fee % (fixed at creation, immutable after)
  • Manager sets minimum deposit for depositors
  • Manager sets lockup period in days (must be >= protocol minimum, displayed in UI)

Review & creation:

  • Summary screen shows: vault name, description, initial deposit, performance fee, lockup period, min deposit
  • Total required displayed: initial deposit + vault creation fee (defined by protocol)
  • On confirm, vault is assigned a unique PDA and is visible across the protocol immediately
  • Vault is created with type "User"
  • A trader can only manage one vault at a time

US-TRADER-23 — Trade using vault funds​

As a Trader I want to place, cancel, and settle orders on the CLOB using my vault's authority So that I can execute my strategy with pooled depositor capital

Acceptance criteria:

  • Trader switches to vault account before placing orders
  • When trading as vault, margin and position accounting use vault equity
  • All trade types available: limit, market (post-only and IOC post-prototype)
  • Every trade is publicly visible on-chain with vault attribution
  • Manager cannot withdraw vault funds directly to their own wallet

US-TRADER-24 — View vault performance​

As a Trader I want to see my vault's PnL, trade history, and depositor activity in real-time So that I can manage my strategy and communicate results to depositors

Acceptance criteria:

  • Shows: total equity, PnL, PnL %, trade count, win rate, max drawdown
  • Trade history: every trade executed by the vault with PnL attribution
  • Depositor activity: deposits and withdrawals with timestamps
  • Performance fee earned (cumulative and available to claim)
  • High-water mark tracker

US-TRADER-25 — Claim performance fee​

As a Trader (vault manager) I want to claim my accrued performance fee So that I am compensated for managing the vault

Acceptance criteria:

  • Fee is only claimable if vault equity exceeds the previous high-water mark
  • After claiming, high-water mark is updated to equity at claim time
  • Claimed fee is transferred to the manager's wallet
  • Fee claim is publicly visible on-chain

US-TRADER-26 — Freeze and unfreeze vault​

As a Trader (vault manager) I want to freeze my vault to temporarily disable deposits So that I can halt inflows during adverse conditions

Acceptance criteria:

  • Freeze disables new deposits; existing depositors can still withdraw
  • Opening new positions remains at manager's discretion
  • Manager can unfreeze to resume deposits
  • Freeze/unfreeze events are visible in the Vault Activity Log

Keeper Bot​

US-KEEPER-01 — Monitor for liquidatable positions​

As a Keeper I want to continuously monitor open positions and detect which ones fall below maintenance margin So that I can identify liquidation opportunities

Acceptance criteria:

  • Keeper fetches all open Position accounts via getProgramAccounts or account subscriptions
  • For each position, calculates current margin ratio using latest oracle mark price from Hermes
  • Identifies positions where margin_ratio < maintenance_margin
  • Liquidation candidates are queued for execution

US-KEEPER-02 — Execute a liquidation​

As a Keeper I want to submit a liquidation transaction for an underwater position So that I earn the liquidation fee and the protocol remains solvent

Acceptance criteria:

  • Keeper fetches a fresh VAA from Hermes
  • Keeper submits liquidate_position with: VAA, position account, user account, keeper wallet as fee recipient
  • Program verifies on-chain that the margin ratio is genuinely below maintenance threshold at the VAA price
  • Program closes the position at mark price and credits the liquidation fee to the keeper's wallet
  • If position is insolvent (equity < 0), the insurance fund covers the shortfall
  • Any remaining collateral after the fee is returned to the user
  • Liquidation is publicly visible on-chain

US-KEEPER-04 — Trigger funding settlement​

As a Keeper I want to call settle_funding for each active market after each funding interval So that funding payments are applied regularly

Acceptance criteria:

  • Keeper calls settle_funding periodically (e.g. every hour)
  • If called before the funding interval has elapsed, the instruction is a no-op — no double payments
  • The funding_interval is read from the Market account; last_funding_timestamp is read from FundingState
  • If the keeper misses an interval, funding accumulates and is applied lazily on the next user interaction

Admin​

US-ADMIN-01 — Upgrade a program​

As a Protocol Admin I want to deploy an upgraded program version So that I can fix bugs or add features

Acceptance criteria:

  • Upgrade requires multi-sig approval
  • Upgrade is atomic — if it fails, the previous version remains
  • Open orders and positions survive the upgrade

US-ADMIN-02 — Update protocol parameters​

As a Protocol Admin I want to adjust fee rates, max leverage, oracle staleness limits, and vault parameters So that the protocol can respond to market conditions

Acceptance criteria:

  • Parameters updated via update_global_config instruction signed by the admin address
  • Configurable: taker/maker fee rates, max leverage, oracle max_age, max_conf_ratio, liquidation_fee, min_vault_lockup_period, vault_creation_fee
  • Changes take effect immediately (timelock to be added before mainnet)

US-ADMIN-03 — Add or update a market​

As a Protocol Admin I want to list a new perp market or update an existing one So that the protocol supports additional trading pairs or updated risk parameters

Acceptance criteria:

  • initialize_market: creates a new market with oracle feed, margin requirements, funding interval, max position size
  • update_market: updates any market parameter
  • Market appears in the UI without requiring a frontend redeploy
  • Market creation requires multi-sig approval

US-ADMIN-04 — Pause and unpause a market or the whole protocol​

As a Protocol Admin I want to pause trading on a specific market or all markets So that I can contain a security incident

Acceptance criteria:

  • pause_market: halts new orders and position opens for a market; existing positions and cancellations still allowed
  • unpause_market: resumes normal operation
  • pause_protocol: emergency halt of all instructions across all markets
  • unpause_protocol: resumes after emergency halt
  • Withdrawals remain available during pause

US-ADMIN-05 — Freeze and unfreeze a specific vault​

As a Protocol Admin I want to freeze or unfreeze any vault regardless of the manager So that I can respond to suspicious activity or security incidents

Acceptance criteria:

  • force_freeze_vault: immediately freezes a vault — new deposits blocked, manager cannot open new positions, existing depositors can withdraw
  • force_unfreeze_vault: lifts the admin-imposed freeze
  • The vault manager cannot override an admin freeze
  • Freeze/unfreeze events are visible in the Vault Activity Log with an "Admin Action" label

US-ADMIN-06 — Deprecate a vault​

As a Protocol Admin I want to mark a vault as deprecated So that it can be wound down gracefully

Acceptance criteria:

  • deprecate_vault: marks vault as deprecated — only withdrawals allowed, no new deposits or positions
  • Depositors can still withdraw their full share
  • Deprecated status is visible in the UI

US-ADMIN-07 — Transfer admin authority​

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

Acceptance criteria:

  • transfer_admin initiates a two-step transfer by setting pending_admin
  • accept_admin must be signed by the pending_admin address to complete the transfer
  • Until accepted, the current admin retains full control
  • Transfer event is publicly visible on-chain