ExternalTransfer

The ExternalTransfer Facet allows users to move funds from their Symmio balance to other contracts — either another Symmio diamond (e.g., a perps diamond and a future options diamond on the same chain) or any external contract that has been whitelisted by an admin. Unlike internal transfers (which move funds between accounts within the same diamond), external transfers move funds out to a different contract entirely, bypassing the withdrawal cooldown.

Two transfer modes are supported:

1. Standard External Transfer: Real ERC-20 tokens are sent to a registered relayer, which is responsible for depositing them at the target contract. The relayer receives a callback and can revert the transaction if risk checks fail.

2. Virtual External Transfer: For balances that exist only as storage entries (virtual funds with no corresponding tokens in the contract), a virtual provider acts as intermediary. The source diamond deducts the user's balance and notifies the provider, which is expected to credit the receiver on the target contract via virtualDepositFor.

Trust Model: Symmio trusts both the target contract and its registered relayer (or virtual provider). Admins with INTEGRATION_ADMIN_ROLE manage relayer authorizations via addRelayerForExternalTransferTarget / removeRelayerForExternalTransferTarget in the ControlFacet. The protocol should have processes in place to revoke access if fraud or anomalies are detected.

---

Overview

The ExternalTransfer Facet provides the following key functionalities:

• Standard External Transfer: Sends real collateral tokens to a whitelisted target contract through a registered relayer, with no cooldown.

• Virtual External Transfer: Initiates a two-step virtual transfer through a virtual provider for balances without corresponding on-chain tokens.

• Accept Virtual Transfer: Allows the virtual provider to confirm and complete a pending virtual external transfer.

• Cancel Virtual Transfer: Allows the sender to reclaim their balance if the virtual provider has not yet accepted.

---

externalTransfer()

Transfers collateral from the sender's available balance to a whitelisted target contract via its registered relayer. No cooldown is applied. The relayer receives the tokens and an onTransfer callback, and is responsible for depositing the funds at the target.

The relayer can revert the transaction for any reason (e.g., the target doesn't support that receiver, or a risk check fails).

Function Signature:

function externalTransfer(
    address receiver,
    uint256 amount,
    address target
) external whenNotExternalTransferPaused notSuspended(signer) notLiquidatedPartyA(signer);

Parameters:

• receiver: The address of the recipient in the target contract.

• amount: The amount to transfer (in collateral decimals).

• target: The address of the whitelisted target contract.

Relayer Callback:

function onTransfer(address collateral, address sender, address receiver, uint256 amount, address target);

Events Emitted:

• ExternalTransfer(address sender, address receiver, uint256 amount, address target)

---

virtualExternalTransfer()

Initiates a virtual external transfer for balances that have no corresponding on-chain tokens. The sender's balance is deducted on the source diamond and the virtual provider is notified via onExternalTransfer. The transfer remains in PENDING status until the provider accepts it.

The expected flow after initiation:

1. Virtual provider receives onExternalTransfer callback

2. Provider calls acceptVirtualExternalTransfer on the source diamond (status → COMPLETED)

3. Provider calls virtualDepositFor on the target diamond to credit the receiver

If the provider does not accept, the sender can cancel and reclaim their balance.

Function Signature:

function virtualExternalTransfer(
    address receiver,
    uint256 amount,
    address target,
    address virtualProvider
) external whenNotExternalTransferPaused notSuspended(signer) notLiquidatedPartyA(signer);

Parameters:

• receiver: The address of the recipient in the target contract.

• amount: The amount to transfer (in collateral decimals).

• target: The target contract address.

• virtualProvider: The registered virtual provider who will handle the transfer.

Events Emitted:

• InitiateVirtualExternalTransfer(uint256 id, address sender, address receiver, uint256 amount, address target, address virtualProvider)

---

acceptVirtualExternalTransfer()

Allows the virtual provider to accept a pending virtual external transfer, marking it as COMPLETED. After accepting on the source diamond, the provider is expected to call virtualDepositFor on the target diamond to credit the receiver.

Function Signature:

function acceptVirtualExternalTransfer(uint256 id) external whenNotExternalTransferPaused;

Parameters:

• id: The ID of the virtual external transfer to accept.

Access: Only callable by the virtual provider specified in the transfer request.

Events Emitted:

• AcceptVirtualExternalTransfer(uint256 id)

---

cancelVirtualExternalTransfer()

Cancels a previously initiated virtual external transfer and refunds the sender's balance. Only available while the transfer is still in PENDING status (i.e., the provider has not yet accepted). The virtual provider is notified via onCancelExternalTransfer.

Function Signature:

function cancelVirtualExternalTransfer(uint256 id) external notSuspended(signer) whenNotExternalTransferPaused;

Parameters:

• id: The ID of the virtual external transfer to cancel.

Events Emitted:

• CancelVirtualExternalTransfer(uint256 id)

---

Data Structure:

struct VirtualExternalTransferRequest {
    uint256 id;
    address sender;    // User on source diamond
    address receiver;  // Recipient on target contract
    address source;    // Source Symmio contract
    address target;    // Target contract
    uint256 amount;
    uint256 timestamp;
    address provider;  // Virtual provider handling the transfer
    VirtualExternalTransferStatus status;  // PENDING, COMPLETED, CANCELED
}

View Function:

function getVirtualExternalTransfer(uint256 id) external view returns (VirtualExternalTransferRequest memory);