Trust Model

The different roles played by the various actors that use Crystal and the privileges they have.

Crystal's core contracts are permissionless, immutable, and non-custodial: privileged parties can tune parameters within hard-coded limits and curate which markets are shown to users, but cannot move user funds, alter existing orders, or change core market logic.

Actors

Governance: the single privileged protocol administrator (the gov address; also the contract owner, since onlyOwner is defined as msg.sender == gov). Canonical Deployers: addresses elevated by Governance that are permitted to deploy canonical (vetted) markets. Market Creators: anyone; market creation is permissionless. Markets they create are non-canonical unless the creator is also a canonical deployer. Fee Recipient: the address that receives protocol fees, set by Governance. Referrers: addresses supplied in trade calldata that earn a share of the protocol fee on that trade. Market Makers: users who place and cancel resting limit orders. Traders: users who place market orders and router swaps. Liquidity Providers: users who deposit into a market's AMM and hold its ERC20 liquidity token. Routers / Integrators / Forwarders: contracts or frontends that route orders; a user may explicitly approve a forwarder to act on their behalf. Vault Governance: the administrator of the Vault Factory (gov on CrystalVaultFactory), which sets factory-wide bounds. Vault Owners: strategists who deploy and manage an individual vault. Vault Depositors: users who deposit into a vault in exchange for ERC20 vault shares.

Roles and Permissions

Governance (gov)

Can: transfer governance (changeGov); set the protocol fee recipient (changeFeeRecipient); set the referral fee commission, capped at 50% of the protocol fee (changeRefFeeCommission); set the fee-claim window, minimum 1 day (changeFeeClaimDuration); add and remove canonical deployers; change any market's taker fee, maker rebate, minimum size, AMM-enabled flag, and canonical status (changeMarketParams); change any market's creator and creator fee split (changeMarketCreatorFee); update global launchpad parameters (changeLaunchpadParams); claim fees left unclaimed past the fee-claim window (executeClaimExpiredFees). Cannot: set any market fee above the 10% protocol maximum; modify, cancel, or seize existing orders; move, freeze, or withdraw user deposits, balances, or LP positions; change a market's immutable parameters (scale factor, tick size, max price, market type, token pair) — those require deploying a new market; set referral commission or creator fee split above 50% of the fee; upgrade, pause, or alter deployed contract logic (contracts are immutable).

Canonical Deployers

Can: deploy canonical markets with vetted parameters; change the parameters of markets they themselves created (requires being both a canonical deployer and that market's creator). Cannot: exceed the 10% fee cap; change markets they did not create (only Governance can); elevate other canonical deployers; touch user funds or existing orders.

Market Creators (anyone)

Can: permissionlessly deploy a market for any token pair with chosen parameters; reassign their market's creator address (which receives the creator fee split); earn the creator fee split on their market's taker fees. Cannot: mark a market canonical, or change its taker fee / maker rebate / minimum size, unless also a canonical deployer; exceed fee caps; affect other markets, existing orders, or user funds.

Fee Recipient, Referrers, and Creators (passive)

Can: accrue and claim their share of protocol, referral, or creator fees as claimable balances (claimFees). Referrers earn only when their address is included in a trade's calldata. Cannot: exercise any control over markets, orders, liquidity, or user funds — these roles are purely economic.

Market Makers, Traders, and Liquidity Providers (users)

Can: place and cancel their own limit orders (makers); place market orders and swaps (traders); add and remove AMM liquidity (LPs); grant a single token approval to the exchange covering all markets. Cannot: access another user's funds or orders; bypass a market's minimum size, maximum price, or tick-size constraints.

Forwarders / Integrators

Can: place or manage orders on behalf of a user who has explicitly approved them (approveForwarder). Cannot: act for users who have not approved them; the user can revoke at any time (removeForwarder).

Vault Governance (Vault Factory gov)

Can: transfer factory governance; set factory-wide bounds — maximum order cap, maximum lockup, global minimum deposit, and per-token minimum deposit. Cannot: access or move assets in any individual vault; override a vault owner's management of their vault; touch exchange-level markets or funds.

Vault Owners (strategists)

Can: deploy a vault and act as its strategist; manage strategy — select or refresh the market, set the order cap, lockup, max shares, and decrease-on-withdraw behavior; place the vault's orders; claim the vault's fees (paid to the owner); close the vault. Cannot: exceed factory-set bounds; reduce their own stake below the required minimum owner share (more than 5% of outstanding shares) except when closing the vault, which keeps the strategist aligned with depositors; seize depositor funds — withdrawals are pro-rata by share.

Vault Depositors

Can: deposit for ERC20 vault shares and withdraw pro-rata, subject to the vault's lockup. Cannot: direct the vault's strategy — that authority belongs to the vault owner.

Operations

Privileged actions are ordinary on-chain function calls made by the relevant governance address, and the contracts themselves do not enforce a timelock on parameter changes — a change takes effect as soon as its transaction is included. Their impact is bounded instead by hard-coded, in-contract limits rather than by delay.

Market parameters (taker fee, maker rebate, minimum size, AMM toggle, canonical status) are changed via changeMarketParams, callable by Governance for any market, or by a market's creator if that creator is a canonical deployer. Creator/fee-split changes go through changeMarketCreatorFee. In-contract checks enforce the 10% fee ceiling, the ≤50% split cap, minimum-size validity, and tick alignment, so an out-of-bounds change reverts rather than applying.

Protocol-level settings (fee recipient, referral commission, fee-claim window, launchpad parameters, and the canonical-deployer set) are Governance-only.

Vault settings split cleanly: factory-wide bounds are set by Vault Governance, while per-vault settings are initiated by the vault owner and routed through the factory to the vault — so the factory is the single mediating entrypoint for vault administration.

Delay-gated operations do exist for a few non-parameter actions: closing an inactive market (queueCloseInactiveMarket → executeCloseInactiveMarket) and claiming expired fees (queueClaimExpiredFees → executeClaimExpiredFees) follow a queue-then-execute pattern governed by the fee-claim window.

Because the contracts are immutable and non-custodial, the blast radius of any governance action is limited by design: Governance can retune economics within fixed caps and curate canonical markets, but cannot reach existing orders, user balances, LP positions, or the core matching and pricing math.