Somnia

We express our gratitude to the Somnia team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

The Somnia Spot DEX is a central limit order book (CLOB) spot trading protocol deployed on the Somnia blockchain. It enables users to place, match, and settle limit and market orders for ERC-20 token pairs, with conditional stop-loss and take-profit orders triggered automatically via Somnia's native on-chain reactivity precompile.

The system users should acknowledge all the risks summed up in the risks section of the report

{Finding_Table?columns=title,severity,status&setting.filter.type=Vulnerability}

Documentation quality

• Functional requirements are detailed.

• • Project overview is detailed

  • All roles in the system are described.

  • Use cases are described and detailed.

  • For each contract, all futures are described.

  • All interactions are described.

• Technical description is detailed.

• • Run instructions are provided.

  • Technical specification is provided.

  • The NatSpec documentation is sufficient.

Code quality

• The development environment is configured.

Test coverage

Code coverage of the project is 81.94 (branch coverage).

• Deployment and core user interactions are thoroughly covered with high line and statement coverage.

• Mixed-decimal and upgrade scenarios are well tested.

• Negative-path and edge-case branch coverage has gaps in several contracts.

• Reentrancy and concurrent multi-user interaction scenarios lack dedicated tests.

The protocol is composed of two deployable contracts, SpotPool and SpotStopOrderRegistry, both designed for deployment behind upgradeable proxies using ERC-7201 namespaced storage. The out-of-scope deployer libraries support both UpgradeableBeacon + BeaconProxy and TransparentUpgradeableProxy patterns. SpotPool inherits from the abstract OrderBook matching engine and the abstract ERC20Vault, forming a self-contained spot market for a single base/quote token pair. ERC-20 tokens (or the chain's native token via a sentinel address) are deposited into the vault, which tracks internal balances. When an order is placed, the required tokens (plus maker fees for the on-book portion, rounded up via ceiling division) are locked from the user's internal balance. The matching engine performs a dry-run/real-run two-pass fill against the opposite side of the book, transfers tokens between maker and taker internal balances on each fill, and charges fees (floor-rounded) to a configurable fee recipient. Fees use a sub-basis-point precision unit (BPS_TIMES_1K, where 1 BPS = 1,000 units). Supported order types include NormalOrder, FillOrKill, ImmediateOrCancel, and PostOnly, with self-matching prevention via CancelTaker or CancelMaker options.

Price-time priority within the order book is maintained by a composite data structure: a Red-Black Tree of unique price-priority levels combined with an intrusive doubly-linked list for FIFO ordering within each level and efficient full-book traversal. Order indices are allocated via a LIFO free-list (OrderIndexAllocator) to minimize new storage slot creation, and each OrderId encodes both a reusable slot index and a monotonically increasing unique counter to prevent stale-reference confusion. Per-user open order tracking is handled through a separate linked-list index (PerUserOrderIndex), and expired orders are lazily cleaned up during order placement and book traversal.

SpotStopOrderRegistry is a standalone upgradeable contract that holds pending stop orders with GTE (greater-than-or-equal) or LTE (less-than-or-equal) trigger conditions on the midpoint price. It subscribes to the SpotPool's MarkPriceUpdated event via the Somnia reactivity precompile at 0x0100. When the precompile invokes the registry's onEvent callback, all orders whose trigger conditions are satisfied are processed: each is submitted as an IOC order to the SpotPool via placeOrderFor, with failures captured by try-catch to avoid blocking sibling orders. Users pay SOMI (the chain's native token) per order creation to fund handler invocation gas; SOMI is refunded on cancellation and consumed on trigger. An admin (via OwnableUpgradeable) manages subscription lifecycle, fee parameters, slippage tolerance, and excess SOMI withdrawals.

Files in Scope

• Common.sol: Defines the OrderIndex and OrderId user-defined value types, their packing/unpacking helpers, the NATIVE_TOKEN sentinel address used by the vault for native token accounting, timestamp conversion to nanoseconds, ceiling/floor division utilities, absolute-value helpers, BPS-based fee calculation functions, and the OrderIndexAllocator library that manages a LIFO free-list for reusable order slot indices.

• IERC20Vault.sol: Declares the interface for the internal-balance vault, specifying deposit, depositNative, withdraw, and getWithdrawableBalance, along with associated error types for insufficient balance, zero amounts, and native token transfer failures.

• IOrderBook.sol: Declares the interface for the central limit order book, defining the Order, OrderBookParameters, and OrderBookLevel structs, the OrderType and SelfMatchingOption enums, and the external functions for placeOrder, placeOrderFor, cancelOrder, reduceOrder, getBookLevels, and paginated off-chain order iteration.

• ISpotPool.sol: Extends IOrderBook and IERC20Vault to define the spot pool interface, adding updateFeeRecipient, placeTakerOrderWithoutVault (a combined deposit-trade-withdraw convenience function), convertToQuoteAtPriceCeil, and getPoolParams for reading all pool configuration in a single call.

• ISpotStopOrderRegistry.sol: Declares the interface for the stop order registry, defining the PendingOrderType, Operator enums, the PendingOrderWithTrigger and StoredPendingOrder structs, and external functions for createPendingOrder, cancelPendingOrder, claimSomi, subscription management, and admin configuration setters.

• ISomniaReactivity.sol: Declares the minimal interface for the Somnia reactivity precompile at 0x0100, specifying the SubscriptionData struct and the subscribe/unsubscribe functions used by the stop order registry to create and remove event subscriptions.

• LinkedList.sol: Implements an intrusive doubly-linked list library keyed by uint64 values, providing insertNodeBefore, insertNodeAfter, eraseNode, getNextKey, and getPreviousKey operations. Multiple independent logical lists are supported within a single storage mapping, using zero as the empty sentinel.

• OrderBook.sol: Abstract contract implementing the core CLOB matching engine. It manages order storage, the dry-run/real-run two-pass matching loop against the opposite book side, expired-order cleanup, per-user order tracking, and order lifecycle hooks (_onOrderPlaced, _onOrderAddedToBook, _onOrderFilled, _onOrderRemoved, _onOrderReduced) that concrete subclasses override to implement token locking and settlement.

• OrderIndexManager.sol: Abstract contract that wraps OrderIndexAllocator with a monotonically increasing unique counter to produce globally unique OrderId values, providing _getNextOrderId and _freeOrderIndex for subclasses.

• PerUserOrderIndex.sol: Library that maintains a per-address linked list of open order indices, supporting O(1) addOrder (prepend), removeOrder, getLatestOrderForUser, and getNextUserOrder traversal.

• PriorityIndex.sol: Library that combines a Red-Black Tree of unique price-priority levels with a doubly-linked list of order indices to maintain price-time priority ordering. It provides insertOrder, eraseOrder, getBestOrder, and getNextBestOrder, with price-to-priority conversion that inverts bid prices so higher bids map to lower (better) priority keys.

• SpotStopOrderRegistry.sol: Concrete upgradeable contract that stores pending stop orders with GTE/LTE trigger conditions, manages a Somnia reactivity subscription to MarkPriceUpdated events, processes triggered orders as IOC submissions to the associated SpotPool via placeOrderFor, handles SOMI payment collection and refund (with an unclaimed fallback for contracts that cannot receive native tokens), and exposes admin functions for subscription lifecycle and configuration.

• SpotPool.sol: Concrete upgradeable contract that combines the OrderBook matching engine with the ERC20Vault to form a complete spot trading market. It implements all order lifecycle hooks to lock/unlock base and quote tokens, charges maker and taker fees on fills, computes and emits the midpoint mark price, validates order book parameters against zero-quote-fill dust attacks, and provides placeTakerOrderWithoutVault for atomic deposit-trade-withdraw execution.

• ERC20Vault.sol: Abstract contract providing internal-balance accounting for ERC-20 tokens and the chain's native token (via a sentinel address). It exposes deposit, depositNative, and withdraw with nonReentrant guards, and internal helpers _depositFor, _withdrawFor, _transfer, and _useBalance used by SpotPool for token locking and settlement.

• RedBlackTree.sol: Vendored implementation of BokkyPooBah's Red-Black Tree library, providing O(log n) insert, remove, first, last, next, and prev operations on a self-balancing binary search tree of uint256 keys. It is used by PriorityIndex to maintain sorted unique price-priority levels.

Privileged roles

SpotStopOrderRegistry.sol

• owner (inherited from OwnableUpgradeable): Administrative control over the registry's configuration, subscriptions, and excess SOMI funds.

• • Can call createSubscription to create a Somnia reactivity subscription for automated order triggering.

  • Can call removeSubscription to remove the active reactivity subscription, rendering all existing pending orders inert.

  • Can call setSomiPaymentPerOrder to update the SOMI payment required per pending order creation.

  • Can call setSlippageToleranceBps to update the slippage tolerance applied to triggered market orders.

  • Can call withdrawSomi to withdraw excess SOMI (not reserved for pending-order refunds or unclaimed balances) to an arbitrary recipient.

  • Can call transferOwnership to transfer the owner role to a new address.

  • Can call renounceOwnership to irrevocably renounce the owner role.

• Somnia Reactivity Precompile (address(0x0100)): Sole caller authorized to deliver on-chain event callbacks.

• • Can call onEvent to trigger pending stop orders when the SpotPool emits a MarkPriceUpdated event, causing matched orders to be placed into the spot order book.

SpotPool.sol

• owner (inherited from OrderBook, which inherits OwnableUpgradeable): Administrative control over order book parameters and the approved-contracts allow-list.

• • Can call updateOrderBookParameters to update tick size, minimum quantity, and lot size.

  • Can call updateIsApprovedContractToPlaceOrders to approve or revoke contracts authorized to place orders on behalf of users.

  • Can call transferOwnership to transfer the owner role to a new address.

  • Can call renounceOwnership to irrevocably renounce the owner role.

• Approved contracts (managed by owner via updateIsApprovedContractToPlaceOrders): Contracts on the allow-list that may act on behalf of arbitrary users.

• • Can call placeOrderFor to place orders in the order book on behalf of any specified owner address.

• feeRecipient (set at initialization, self-managed): The address that accumulates trading fees and controls its own succession.

• • Can call updateFeeRecipient to nominate a new fee recipient address (cannot be the zero address or the current recipient).

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope