SmartAccount

SmartAccount is a per-user deployed contract — each margin account is a separate on-chain instance. It stores all collateral balances, records which assets have been borrowed, and executes external protocol calls on behalf of its owner. Important: SmartAccount functions cannot be called directly by users. All calls must originate from the registered AccountManager. Every function begins with account_manager.require_auth().

Individual SmartAccount addresses are determined at account creation time. Use Registry.get_accounts(trader_address) or listen for AccountCreationEvent to find a user’s SmartAccount address.

Account State

activate_account

fn activate_account(env: Env) -> ()

Sets IsAccountActive = true. Called by AccountManager immediately after deploying or reusing a SmartAccount.

deactivate_account

fn deactivate_account(env: Env) -> ()

Sets IsAccountActive = false. Called by AccountManager when the account is closed and pushed to the inactive pool.

has_debt

fn has_debt(env: Env) -> bool

Returns true if any borrowed tokens are listed in BorrowedTokensList.

set_has_debt

fn set_has_debt(env: Env, has_debt: bool) -> ()

Sets the HasDebt flag. Called by AccountManager when the debt list transitions from empty to non-empty or vice versa.

Collateral Management

get_all_collateral_tokens

fn get_all_collateral_tokens(env: Env) -> Vec<Symbol>

Returns the list of all token symbols currently held as collateral. Used by RiskEngine to enumerate assets when computing health factor.

add_collateral_token

fn add_collateral_token(env: Env, symbol: Symbol) -> ()

Appends symbol to CollateralTokensList if not already present. Called by AccountManager on first deposit of a new token type.

get_collateral_token_balance

fn get_collateral_token_balance(env: Env, symbol: Symbol) -> U256

Returns the balance of symbol held in this account, in WAD format.

set_collateral_token_balance

fn set_collateral_token_balance(env: Env, symbol: Symbol, amount: U256) -> ()

Overwrites the stored balance for symbol. Called by AccountManager after deposit or withdrawal.

remove_collateral_token_balance

fn remove_collateral_token_balance(
    env: Env,
    trader: Address,
    symbol: Symbol,
    amount: u128,
) -> ()

Transfers amount (in native decimals) of symbol to trader, subtracts from stored CollateralBalanceWAD, and removes the token from CollateralTokensList if balance reaches zero.

sweep_to

fn sweep_to(env: Env, to_address: Address) -> ()

Transfers all collateral tokens to to_address. Called in two scenarios:

close_account() — sweeps to owner
liquidate() — sweeps remaining collateral (after debt repayment) to trader

For XLM, USDC: actual token balances are transferred.
For tracking tokens (BLEND_XLM, AQ_XLM_USDC, etc.): the internal balance record is zeroed but the underlying position in the external protocol (Blend pool, Aquarius pool) is not unwound. The external position remains.

Debt Management

get_all_borrowed_tokens

fn get_all_borrowed_tokens(env: Env) -> Vec<Symbol>

Returns the list of all token symbols with outstanding debt.

add_borrowed_token

fn add_borrowed_token(env: Env, symbol: Symbol) -> ()

Appends symbol to BorrowedTokensList. Called by AccountManager after a successful borrow.

remove_borrowed_token

fn remove_borrowed_token(env: Env, symbol: Symbol) -> ()

Removes symbol from BorrowedTokensList. Called when debt is fully repaid.

get_borrowed_token_debt

fn get_borrowed_token_debt(env: Env, symbol: Symbol) -> U256

Queries the corresponding LendingPool for the current outstanding debt (in WAD) for this account and symbol.

remove_borrowed_token_balance

fn remove_borrowed_token_balance(
    env: Env,
    symbol: Symbol,
    amount: u128,
) -> ()

Repays amount of symbol debt to the LendingPool. Called during repayment or liquidation.

External Protocol Execution

execute

fn execute(
    env: Env,
    target_protocol: Address,
    action: SmartAccExternalAction,
    trader: Address,
    tokens: Vec<Symbol>,
    amounts: Vec<u128>,
) -> (bool, i128)

Routes a call to an external protocol (Blend, Aquarius, or Soroswap). Returns: (success: bool, token_delta: i128) where token_delta is the net token change (positive = received, negative = sent). AccountManager uses this delta to mint or burn TrackingTokens.

Action Types

enum SmartAccExternalAction {
    Deposit,          // Supply tokens to Blend pool
    Withdraw,         // Withdraw tokens from Blend pool
    Swap,             // Swap tokens via Aquarius or Soroswap
    AddLiquidity,     // Add liquidity to Aquarius pool
    RemoveLiquidity,  // Remove liquidity from Aquarius pool
}

Blend Deposit

execute(blend_pool, Deposit, trader, ["XLM"], [1000_0000000])

Reads current b-token positions from Blend
Authorizes native XLM transfer to Blend pool
Calls BlendPool.submit([{request_type: 0, address: xlm_address, amount: 1000_0000000}])
Reads updated positions
token_delta = positions_after - positions_before (b-tokens received)
AccountManager mints TrackingToken(BLEND_XLM) for the SmartAccount

b_rate = blend_reserve.data.b_rate    // from Blend pool reserve
b_tokens_minted = token_delta

Blend Withdraw

execute(blend_pool, Withdraw, trader, ["XLM"], [500_0000000])

Inverse of deposit. Submits a withdrawal request to Blend, receives underlying XLM, burns TrackingTokens.

Aquarius Add Liquidity

execute(aquarius_pool, AddLiquidity, trader, ["XLM", "USDC"], [500_0000000, 300_000000])

Fetches pool reserves
Computes optimal amounts (see Math Reference)
Authorizes token transfers to pool
Calls Pool.deposit(desired_a, desired_b, min_a, min_b)
token_delta = LP tokens received
AccountManager mints TrackingToken(AQ_XLM_USDC)

Aquarius Remove Liquidity

execute(aquarius_pool, RemoveLiquidity, trader, ["XLM", "USDC"], [lp_amount])

Burns LP tokens, receives XLM and USDC back into SmartAccount. AccountManager burns TrackingTokens.

Soroswap Swap

execute(soroswap_pair, Swap, trader, ["XLM"], [100_0000000])

Swaps XLM for USDC (or the pair’s other asset):

Reads pair reserves
Computes output via constant-product formula (0.3% fee)
Authorizes XLM transfer to pair
Calls Pair.swap(amount_out, 0, smart_account)
token_delta = USDC received

Storage Layout

Key	Type	Description
`CollateralTokensList`	`Vec<Symbol>`	All symbols with non-zero collateral
`CollateralBalanceWAD(symbol)`	`U256`	Collateral balance in WAD
`BorrowedTokensList`	`Vec<Symbol>`	All symbols with outstanding debt
`HasDebt`	`bool`	True if any debt exists
`IsAccountActive`	`bool`	Whether account is active
`OwnerAddress`	`Address`	Wallet that owns this account
`AccountManager`	`Address`	Only address authorized to call this contract
`RegistryContract`	`Address`	Registry for resolving peer addresses

Events

SmartAccountActivationEvent {
    margin_account: Address,
    activated_time: u64
}

SmartAccountDeactivationEvent {
    margin_account: Address,
    deactivate_time: u64
}

Error Codes

enum SmartAccountError {
    TokenNotFound,          // Symbol not in token list
    IntegerConversion,      // u128/i128 conversion failed
    ProtocolMismatch,       // Target address not a recognized protocol
}

AccountManager — the only authorized caller of SmartAccount
Tracking Tokens — how external positions are represented
Risk Engine — reads SmartAccount state to compute health factor
Architecture — full call graph showing how SmartAccount fits in the system

Introduction

Contract Reference

TypeScript SDK

Integration Guides

SmartAccount

Account State

activate_account

deactivate_account

has_debt

set_has_debt

Collateral Management

get_all_collateral_tokens

add_collateral_token

get_collateral_token_balance

set_collateral_token_balance

remove_collateral_token_balance

sweep_to

Debt Management

get_all_borrowed_tokens

add_borrowed_token

remove_borrowed_token

get_borrowed_token_debt

remove_borrowed_token_balance

External Protocol Execution

execute

Action Types

Blend Deposit

Blend Withdraw

Aquarius Add Liquidity

Aquarius Remove Liquidity

Soroswap Swap

Storage Layout

Events

Error Codes

​Account State

​activate_account

​deactivate_account

​has_debt

​set_has_debt

​Collateral Management

​get_all_collateral_tokens

​add_collateral_token

​get_collateral_token_balance

​set_collateral_token_balance

​remove_collateral_token_balance

​sweep_to

​Debt Management

​get_all_borrowed_tokens

​add_borrowed_token

​remove_borrowed_token

​get_borrowed_token_debt

​remove_borrowed_token_balance

​External Protocol Execution

​execute

​Action Types

​Blend Deposit

​Blend Withdraw

​Aquarius Add Liquidity

​Aquarius Remove Liquidity

​Soroswap Swap

​Storage Layout

​Events

​Error Codes

​Related

Account State

activate_account

deactivate_account

has_debt

set_has_debt

Collateral Management

get_all_collateral_tokens

add_collateral_token

get_collateral_token_balance

set_collateral_token_balance

remove_collateral_token_balance

sweep_to

Debt Management

get_all_borrowed_tokens

add_borrowed_token

remove_borrowed_token

get_borrowed_token_debt

remove_borrowed_token_balance

External Protocol Execution

execute

Action Types

Blend Deposit

Blend Withdraw

Aquarius Add Liquidity

Aquarius Remove Liquidity

Soroswap Swap

Storage Layout

Events

Error Codes

Related