Smart Contract Overview¶

Sera's settlement layer is an open-source Ethereum contract system composed of a custody vault, the core orderbook, a smart order router, and a batching wrapper.

Contract Addresses¶

Ethereum Mainnet¶

Addresses can drift between deployments. Fetch live values from GET /config instead of hardcoding.

Source Code¶

All contracts are open source on GitHub and have been independently audited. Links below point to the audited revision.

Architecture¶

flowchart TD
    User["User / API"] --> Sera["Sera.sol<br/><i>Core settlement, signatures, withdrawals</i>"]
    User --> SOR["SeraSOR.sol<br/><i>Multi-leg routed swaps</i>"]
    SOR --> Sera
    Batcher["SeraBatcher.sol<br/><i>Batch execution wrapper</i>"] --> Sera
    Batcher --> SOR
    Sera --> Vault["Vault.sol<br/><i>Custody and ledger balances</i>"]

Contract Roles¶

• Vault.TRADER_ROLE is granted to Sera so only the matching engine can move tracked balances.
• Sera.EXECUTOR_ROLE is granted to the off-chain executor, SeraSOR, and SeraBatcher.
• Sera.PAUSER_ROLE and DEFAULT_ADMIN_ROLE stay with protocol administration.
• All admin roles are held by a Timelock contract, which is in turn owned by a multisig.
• Sera.trustedRouter is set to the active SeraSOR deployment.

EIP-712 Domain¶

Orders, routed intents, and withdrawals are signed under the Sera domain:

const domain = {
  name: 'Sera',
  version: '1',
  chainId: 1,
  verifyingContract: '0xB5C50C5D5f038404F85970b7f5B7259C4AC0E198'
};

Contracts¶

Sera.sol¶

Core settlement contract for matching, deposits, replay protection, and withdrawals.

• matchOrders() settles a signed maker/taker pair.
• depositFund() and depositFundWithPermit() fund vault balances through Sera.
• executeInstantWithdrawDualSig() executes user-plus-executor withdrawals.
• emergencyWithdraw() preserves on-chain recovery if the API stack is unavailable.

View Sera.sol Reference →

SeraSOR.sol¶

Smart Order Router for one-shot multi-leg swaps.

• executeIntent() consumes a signed routed intent.
• Intermediate route balances stay transient inside the transaction instead of touching the vault.

View SeraSOR.sol Reference →

SeraBatcher.sol¶

Executor wrapper for best-effort and atomic batching.

• batchMatchOrders() continues on failure.
• batchMatchOrdersAtomic() reverts the whole batch on any failure.
• batchMatchMixed() combines atomic batches, individual matches, and routed intents.

View SeraBatcher.sol Reference →

Vault.sol¶

Custody and ledger contract.

• deposit() and withdraw() move ERC-20 balances in and out.
• transferLedger() settles matched trades without moving physical tokens.
• balanceOf() exposes per-user tracked balances.

View Vault.sol Reference →

Settlement Flow¶

sequenceDiagram
    participant User
    participant Sera as Sera.sol
    participant Vault as Vault.sol

    User->>Sera: depositFund(token, owner, amount)
    Sera->>Vault: deposit(owner, token, amount)

    Sera->>Vault: transferLedger(fromUser, toUser, token, amount)
    Note over Vault: Matching updates ledger balances only

    User->>Sera: executeInstantWithdrawDualSig(intent, userSig, executorSig)
    Sera->>Vault: withdraw(user, token, amount, recipient)
    Vault-->>User: ERC-20 transfer

Security Features¶

• Non-custodial — every action requires the user's signature; the protocol cannot move funds without authorization.
• Emergency withdrawal — users can withdraw directly on-chain even if the API is down (subject to a ~24h delay).
• Reentrancy protection — sensitive functions use transient reentrancy guards.
• Pausable — admin emergency-pause mechanism.
• Role-based access control — separate executor, admin, and pauser roles.

Next Steps¶