Balance Operations (Deposit, Withdraw, Transfers)

The Symmio deposit and withdraw system lets users deposit collateral, initiate withdrawals, and optionally take express withdrawals from their isolated balances.

Standard withdrawals can be subject to a cooldown period, during which the requested funds are locked. To skip that delay, a user can request an express withdrawal through a registered liquidity provider, usually for a fee, and get faster access to the funds.

Deposit

Users deposit collateral into their isolated balance with deposit. The call handles internal accounting, enforces system constraints, and optionally transfers ERC-20 tokens from the user's wallet.

deposit(address collateral, uint256 amount) // user = msg.sender

depositFor(address collateral, address user, uint256 amount)

On invocation, the function:

• Validates that the collateral token is whitelisted.

• Ensures amount is greater than zero and user is a valid address.

• Verifies the deposit won't exceed balanceLimitPerUser.

• Normalizes amount to 18 decimals for internal consistency.

• Increases the user's isolated balance.

• Transfers tokens from the user's wallet to the protocol if doTransfer is true.

Note: virtualDepositFor updates a balance without transferring the actual collateral. Only addresses granted VIRTUAL_DEPOSITOR_ROLE can call it.

Withdraw

Withdrawing from an isolated balance is a two-phase process, initiation then completion, with a cooldown period between the two phases to harden the protocol against abuse and malicious withdrawal attempts.

Symmio also supports express withdrawals through approved third-party express providers. A provider pre-funds the user's withdrawal amount immediately for a fee, then collects the actual withdrawal from the protocol after the cooldown ends. The user skips the wait, and the provider takes on the risk of delayed settlement or a security-based withdrawal failure.

1. Initiate withdraw

Request a withdrawal with one of:

function initiateWithdraw(address collateral, uint256 amount, address to)

function initiateExpressWithdraw(
address collateral,
uint256 amount,
address to,
address provider,
bytes memory userData
)

Parameters:

• collateral: the ERC-20 token to withdraw.

• amount: amount to withdraw, in collateral decimals.

• to: destination address for the funds.

• provider: registered express withdrawal provider.

• userData: arbitrary data passed to the provider for validation (express withdrawals).

Behavior:

• Validates that the sender has enough available (unlocked) balance.

• Verifies solvency and per-user balance limits.

• Immediately deducts the withdrawal amount from the user's isolated balance.

• Creates a Withdraw object with status INITIATED.

If a provider is specified, it also ensures the provider is registered and active, calls validateWithdraw(...) on the provider contract, and records the provider metadata in the Withdraw object.

2. Complete withdraw

Once the cooldown has elapsed, finalize the withdrawal:

function completeWithdraw(uint256 id)

To read the current cooldown durations, call:

• getPartyADeallocateCooldown for PartyA:

• getPartyBDeallocateCooldown for PartyB:

function getPartyADeallocateCooldown() external view returns (uint256)

function getPartyBDeallocateCooldown() external view returns (uint256)

The final destination depends on whether a provider was used. With an express provider, funds go to the provider's configured receiver; otherwise they go to the original to address. The function then sets the Withdraw status to COMPLETED.

Cancel withdraw (non-express only)

function cancelWithdraw(uint256 id)

Allowed only when no express provider was specified. Restores the withdrawn amount to the user's isolated balance and marks the request CANCELED.

Suspend and restore

These admin functions handle invalid or disputed withdrawals.

function suspendWithdraw(uint256 id)

function restoreWithdraw(uint256 id, uint256 validAmount)

suspendWithdraw marks the withdrawal SUSPENDED. restoreWithdraw returns validAmount to the user and sends any excess to the system-owned invalidWithdrawalsAmountsPool.

Express withdraw system

The express withdrawal system lets external providers pre-fund user withdrawals in exchange for liquidity fees or execution spreads, giving instant withdrawals that bypass the standard cooldown.

Provider requirements

To be eligible, an express withdrawal provider must:

• Implement the IExpressWithdrawProvider interface.

• Be registered with isActive == true and a valid, non-zero receiver address.

• Implement validateWithdraw(...) to enforce any custom logic or verification.

If validation fails, the protocol reverts with:

ExpressWithdrawRejectedByProvider(provider, reason)

Final fund flow (with provider)

When a provider is used, the actual protocol withdrawal funds are sent to the provider's receiver address, and the provider funds the user immediately (typically off-chain or through liquidity routing).

Internal transfer

internalTransfer moves collateral directly from a user's available Symmio balance to another user's isolated balance within the same protocol (for example, Symmio Options).

internalTransfer(address collateral, address user, uint256 amount)

This function transfers collateral from the sender (msg.sender) to the recipient user inside the Symmio system. It moves no tokens externally, only updating internal accounting, and enforces security and solvency checks for both sender and receiver.

Validation and behavior

• Verifies that amount is greater than zero.

• Ensures the recipient user address is not zero.

• Checks that neither party is suspended or paused.

• Validates that the sender has enough available balance (excluding locked funds).

• Enforces the receiver's balance cap (balanceLimitPerUser) if the receiver is not PartyB.

• Emits an InternalTransfer event with pre- and post-transfer balances.

Restrictions: can't be used by PartyB accounts, or when the protocol is in instant mode, or when internal transfers are paused.

External transfer

externalTransfer moves collateral from a user's Symmio balance to a whitelisted external target contract, such as another Symmio service (for example, Symmio Perpetuals or Lending). It gives instant, cooldown-free transfers across Symmio subsystems.

externalTransfer(address collateral, address user, uint256 amount, address target)

This function:

• Transfers collateral from msg.sender to a designated external system (for example, from Options to Perpetuals).

• Skips any withdrawal delay or cooldown.

• Performs both the internal balance deduction and the ERC-20 token transfer.

• Notifies the receiving contract through a standardized callback.

Validation and behavior

• Requires a non-zero amount, user, and target address.

• Ensures the target contract is whitelisted for the collateral.

• Subtracts the amount from the sender's isolated balance.

• Converts internal units (18 decimals) to the token's native decimals.

• Performs an ERC-20 transfer to the target contract.

• Invokes onTransfer on the target contract for integration handling.

• Emits an ExternalTransfer event.

Use cases: instant liquidity movement between Symmio Options and Symmio Perps, and transfers between isolated product-specific accounts without a user withdrawal.

Restrictions: the sender must not be suspended or paused, transfers are allowed only to whitelisted target contracts, and this can't be used when external transfers are paused.