Symmio Core v0.8.5 Documentation

6 chapters

Account & Fund Management

01 Account & Fund Management AccountLayer A standalone Diamond proxy (EIP-2535) that replaces the per-frontend MultiAccount contracts. Users create SubAccounts tied to an affiliate and a Symmio core, then trade through VirtualAccounts that provide position isolation at four levels: per-trade, per-market, per-market-direction, or fully custom. The system handles affiliate registration, fee distribution to stakeholders, express deposits that split funds between real and virtual providers, and on-chain hooks for custom logic like NFT minting or loyalty points. 02 Account & Fund Management New Withdraw System Complete replacement of the old single-step withdrawal. Users can now split a withdrawal across multiple chains and providers in a single atomic request. Express providers front the funds immediately for a fee, virtual providers deliver cross-chain, and both can be combined. Includes cooldown management, speed-up approvals for whitelisted users, cancellation flows with blackout windows, and admin force-cancel capabilities. 03 Account & Fund Management Virtual Fund System Enables cross-chain deposits and withdrawals without bridging. A trusted virtual provider credits a user's balance on the target chain via virtualDepositFor, while the actual collateral stays on the source chain. When withdrawing, the provider pays out on the user's preferred chain. Deeply integrated with the new withdraw system — virtual providers implement lifecycle callbacks for acceptance, completion, and cancellation. 04 Account & Fund Management External Transfer Lets users move funds to any trusted target contract through an authorized relayer — not just other Symmio diamonds, but any whitelisted external contract. Symmio trusts the relayer to handle funds at the target, with admin roles to revoke access or confiscate funds if fraud is detected. Also supports virtual external transfers for balance-only movements where no actual token transfer is needed. 05 Account & Fund Management Express Deposit & Withdrawal System Lets affiliates route a configurable percentage of user deposits into an express provider contract, building a liquidity pool that funds faster withdrawals. Users get up to three options: instant (~20 seconds) when liquidity is available, earliest-available (somewhere between now and 12 hours) based on projected liquidity inflows, or the standard 12-hour cooldown as a guaranteed fallback. The system coordinates an Express Contract (per-chain liquidity management with bucket-based scheduling), a Virtual Contract (per-frontend deposit-funded pool), and an off-chain bot for risk assessment and processing. 06 Account & Fund Management SafeDeallocate Prevents a front-running attack where a user deallocates funds while a solver's batched transaction (sendQuote + lockQuote + openPosition) is still in flight. Muon now provides a pendingBalance value representing off-chain committed funds, and the contract ensures available balance covers both pending operations and the deallocation.

6 chapters

Trading Execution

07 Trading Execution Cross Mode for Solvers Solvers can now pool all their collateral into a single cross-margin bucket instead of fragmenting it across individual PartyA counterparties. This means a solver won't get liquidated on one user just because that particular allocation ran thin — solvency is evaluated against the total pool. Has deep implications for nonce handling (zero-nonce signatures for parallel operations), settlement (unified settlement across multiple PartyAs), force close (3-step flow with optional settlement), and liquidation (handled by the ClearingHouse instead of decentralized liquidators). 08 Trading Execution Oracle-Less Trading When a PartyA trades exclusively with a single PartyB, Muon oracle signatures become unnecessary overhead. PartyA can bind to that PartyB, and from that point all signature checks are bypassed. Unbinding requires a cooldown period to prevent abuse. Designed for low-latency trading environments where the solver is the sole trusted counterparty. 09 Trading Execution Batch Position Management Opens or closes multiple positions in a single transaction with one Muon signature instead of one per position. Reduces gas costs and response latency for solvers processing a backlog of requests. 10 Trading Execution Better Instant actions through Instant Layer Replaces the old broad delegateAccess with a safer model: users sign a specific operation (EIP-712) and hand it to PartyB, who submits both signatures together. Supports delegation to session keys (e.g., a browser-generated keypair rotated daily), template operations that chain results across steps (sendQuote → lockQuote → openPosition in one tx), flexible replay protection with salt-only or sequential nonce modes, and **flex fields** -- users can mark specific calldata parameters as modifiable by authorized parties (e.g., letting a TPSL service choose the close amount, or a solver update the Muon signature), with per-field modifier authorization and multi-use support. 11 Trading Execution InstantLayer PartyB Integration Guide Solver-specific integration guide covering how PartyBs set up their operator, register with the Instant Layer, handle user signatures, and execute templated workflows. 12 Trading Execution Instant Layer Service Integration Guide This guide covers how third-party services integrate with Symmio through the Instant Layer to provide StopLoss/TakeProfit (TPSL) , Trigger Market Orders , and Session Key functionality. It is intended for both frontend developers implementing the user-facing flows and backend…

7 chapters

Risk & Liquidation

13 Risk & Liquidation ClearingHouse Handles the two liquidation scenarios that decentralized liquidators can't: cross-mode PartyB insolvency (where thousands of positions across many users need coordinated unwinding) and stuck PartyA liquidations (where the on-chain state is too corrupted for the normal dispute resolver to fix). Operates as a multi-step lifecycle — deallocate funds from involved parties, close positions at ClearingHouse-specified prices, distribute proceeds, and settle. Also handles the edge case where both a PartyA and its cross-mode PartyB are liquidated simultaneously via auto-takeover. 14 Risk & Liquidation Soft Liquidation A tiered warning system before hard liquidation. As a PartyB's balance approaches the danger zone, the ClearingHouse can issue on-chain penalties at configurable thresholds — giving the solver time to top up funds instead of immediately closing all positions and disrupting every user on every frontend. 15 Risk & Liquidation ADL Close (Auto-Deleveraging) Allows solvers to unilaterally close positions to reduce risk exposure without needing emergency mode or delisted symbols. No solvency checks are enforced on PartyB during ADL, which means it works even when the solver is underwater. To prevent abuse, PartyBs must deposit [pledge collateral](pledge.md) that can be slashed if ADL is misused. Emits mock events that mirror the normal close flow so indexers and UIs don't need special handling. 16 Risk & Liquidation Pledge Collateral A separate collateral pool that PartyBs deposit as a guarantee of good behavior. Independent of trading collateral, pledge serves as "skin in the game" — if a PartyB acts maliciously (e.g., abuses ADL), their pledge can be slashed by an admin. Supports any ERC20 token with a two-step request-approval withdrawal flow to prevent rug-pulls. 17 Risk & Liquidation Cross-Mode Settlement During Liquidation In cross mode, a PartyB's solvency includes unrealized profit from all counterparties, so its raw allocated balance can be much lower than what it actually controls. During PartyA liquidation, the settlement draws from that raw balance. settlePartyBUpnlForLiquidation lets liquidators realize the PartyB's uPNL from other solvent counterparties before settlement, converting unrealized profit into allocated balance. Cross-mode PartyBs with insufficient balance revert until this step is performed, while isolated PartyBs retain the existing capped-payment behavior. 18 Risk & Liquidation Liquidation Insurance Vault Caps how much liquidators can earn per position and redirects the excess into a protocol vault. That vault is reserved to reimburse PartyBs who suffer losses from late liquidations — situations where a position should have been liquidated earlier but wasn't. 19 Risk & Liquidation Liquidation Escrow Prevents PartyA from recovering pending trading fees through the reimbursement path when their liquidation is LATE or OVERDUE. Particularly important in [oracle-less trading](oracle-less-trading.md) mode, where a bound PartyA can submit fabricated UPNL to drain allocatedBalances into fees, worsen their liquidation severity, then recover the fees at settlement. The escrow holds these fees for the ClearingHouse to distribute — typically to compensate PartyBs who suffered CVA haircuts. Also separates deferred excess balance (always returned to PartyA) from pending fee reimbursement (escrowed in LATE/OVERDUE).

2 chapters

Funding & Positions

20 Funding & Positions Accumulated Funding Rate Replaces the old system where solvers had to process funding for every individual position at each epoch. Instead, funding rates are tracked as weighted averages at the symbol level. When a solver sets a new rate, it blends into the running average — no need to touch individual positions. Rates are pre-multiplied by market price at storage time to eliminate price lookups during calculation. Supports dynamic epoch duration changes with automatic rate scaling. 21 Funding & Positions Aggregated Positions And Fundings For Better UPNL Calculation Maintains running totals of position size and notional value per (party, symbol, positionType) combination, so UPNL calculations only need to iterate over active symbols instead of individual quotes. For a solver with 5,000 positions across 50 symbols, this turns solvency checks from O(5000) to O(50). Also tracks aggregate funding debt for the same efficiency gain.

3 chapters

Fees & Symbols

22 Fees & Symbols Custom open/close fee for affiliates Affiliates can now set custom open and close fees at four priority levels: per user+symbol, per user default, per symbol, or affiliate-wide default. The close fee is factored into solvency checks after position closure. Also adds fillCloseRequestToLiquidation — when a normal close would push PartyA into insolvency, this calculates the maximum partial close that brings them exactly to the liquidation threshold. 23 Fees & Symbols Symbol Types Groups symbols into categories (e.g., Binance pairs vs. lowcap vibe markets) and lets PartyBs whitelist entire categories rather than individual symbols. When new symbols are added to a category, all whitelisted PartyBs can immediately trade them without additional configuration. 24 Fees & Symbols Storing custom data in quotes Allows attaching arbitrary bytes to a quote at creation time via sendQuoteWithAffiliateAndData. The data persists through the entire quote lifecycle and is included in events, enabling off-chain systems to track things like temp quote IDs from instant mode flows.

6 chapters

Infrastructure

25 Infrastructure Muon Signature Verification and Key Management Moves from a single hardcoded Muon public key and gateway signer to an external MuonSignatureVerifier contract that manages multiple keys. Enables key rotation without redeploying the diamond, supports multiple independent Muon nodes for fault tolerance, and decouples key management access control from the core protocol. 26 Infrastructure Hook System Every position open, close, cancel, and funding charge now fires an on-chain hook notification. Affiliates register hook contracts implementing ISymmioHook to execute custom logic — reward tracking, volume analytics, cashback programs — all with fresh on-chain data. The signer context is cleared before hook invocation to prevent privilege escalation. 27 Infrastructure Virtual Account Lifecycle Hooks Virtual Accounts (VAs) are deterministic addresses managed by the AccountLayer that act as partyA on Symmio Core. When the AccountLayer is registered as a system hook ( affiliateHooks[address(0)] ) on Symmio Core, it receives callbacks on position lifecycle events to… 28 Infrastructure Role Admin System Adds delegated role management on top of the existing RBAC. Previously, only a single admin could grant and revoke roles. Now the owner appoints default admins, who can delegate management of specific roles to dedicated addresses via addRoleAdmin / removeRoleAdmin. Per-role admins can grant and revoke their assigned role without needing owner or default admin transactions. Delegation is one level deep — per-role admins cannot sub-delegate. 29 Infrastructure Two-Step Ownership Transfer The new owner must explicitly call acceptOwnership after the current owner calls transferOwnership. Prevents accidental ownership loss from address typos. 30 Infrastructure Event Changelog: v0.8.4 to v0.8.5 Complete changelog of every event change from v0.8.4 to v0.8.5 — removed backward-compatible overloads, changed signatures, new events on existing facets, events from new facets (ClearingHouse, Binding, Pledge, ExternalTransfer, Withdraw), and all AccountLayer diamond events. Includes migration checklists for subgraph developers, hedger integrators, and frontend teams.

2 chapters

Upgrade & Migration

31 Upgrade & Migration Migration Process Backfills the new aggregated position structures and cross bucket locked values from existing v0.8.4 data. Run during a global pause after the diamond cut — migrates quote-level data into symbol-level aggregates and sums per-PartyA locked/pending locked balances into the cross bucket. Allocated balances are not aggregated — solvers fund the cross bucket independently after enabling cross mode. 32 Upgrade & Migration System Deployment Guide Post-migration configuration tasks for initializing v0.8.5 parameters and verifying the upgrade.