Struct AccountState 

pub struct AccountState { /* private fields */ }

Implementations

impl AccountState

pub fn new( balances: FnvHashMap<AssetNameExchange, AssetBalance<AssetNameExchange>>, orders_open: OpenOrders, orders_cancelled: FnvHashMap<ClientOrderId, Order<ExchangeId, InstrumentNameExchange, Cancelled>>, trades: Vec<Trade<AssetNameExchange, InstrumentNameExchange>>, ) -> Self

pub fn enable_margin(&mut self)

Makes this a margin account: every balance reports its loan, and an order whose MarginEffect says so borrows what an arrival lacks or repays loans from what it receives — see SpotMarginConfig.

A balance that already reports a loan, as one seeded from a live margin account does, keeps it; every other balance starts owing nothing.

pub fn free(&self, asset: &AssetNameExchange) -> Decimal

The free balance of asset, zero for an asset the account has never held.

pub fn loans(&self) -> impl Iterator<Item = (&AssetNameExchange, Decimal)> + '_

Each asset this account owes principal in, with the principal owed.

pub fn loans_changed(&self) -> u64

A count that changes whenever the set of assets in loans may have: each time an asset’s principal opens from zero or is repaid to zero.

For a caller that caches something derived from that set, such as when interest next falls due, and would otherwise recompute it after every operation.

pub fn charge_interest( &mut self, asset: &AssetNameExchange, interest: Decimal, time_exchange: DateTime<Utc>, ) -> AssetBalance<AssetNameExchange>

Adds interest to the interest asset’s loan owes, leaving total and free as they are: interest is owed to the lender, and repaid before principal.

Panics

Panics if asset has no balance — see reserve. A loan opens its balance, so an asset with a loan to charge always has one.

pub fn orders(&self) -> &OpenOrders

This account’s open orders, indexed for lookup and ordered for matching.

pub fn remove_order(&mut self, cid: &ClientOrderId) -> Option<RestingOrder>

Takes the order resting under cid off the book, with whatever is held against it.

The caller records how it ended, with ack_cancelled, ack_filled or ack_expired. Booking is only through book, which keeps an id in at most one place.

pub fn book( &mut self, order: OpenOrder, reservation: Option<Reservation>, ) -> Result<(), AlreadyResting>

Puts order on the book holding reservation, unless an order is already resting under its ClientOrderId.

A client order id names one order at a time, not one for good: once an order has ended its id may name a new one. So booking forgets how an earlier order under the same id ended, which keeps an id in at most one place, the book or one ledger, and a snapshot from listing it twice.

Errors

AlreadyResting, with order and reservation handed back and nothing changed, if an order is already resting under its id. See OpenOrders::insert.

pub fn hold( &mut self, order: OpenOrder, reservation: Option<Reservation>, ) -> Result<(), AlreadyResting>

Holds order until its venue releases it, with reservation held against it, unless an order is already resting under its ClientOrderId. Forgets how an earlier order under the id ended, as book does.

Errors

AlreadyResting, as for book. See OpenOrders::hold.

pub fn take_held( &mut self, instrument: &InstrumentNameExchange, ) -> Vec<ClientOrderId>

The orders held on instrument, earliest arrival first, no longer held. See OpenOrders::take_held.

pub fn ack_cancelled( &mut self, order: Order<ExchangeId, InstrumentNameExchange, Cancelled>, )

Records that order was cancelled, so it is reported by a later account snapshot and a second cancel for it can be told apart from a cancel for an order that never existed.

Replaces whatever the ledgers held for an earlier order under the same id.

pub fn is_cancelled(&self, cid: &ClientOrderId) -> bool

Whether cid names an order this account cancelled.

pub fn ack_filled( &mut self, order: Order<ExchangeId, InstrumentNameExchange, Filled>, )

Records that order filled, so a cancel that loses the race to it can say so and an order-state lookup can report it.

Replaces whatever the ledgers held for an earlier order under the same id.

pub fn is_filled(&self, cid: &ClientOrderId) -> bool

Whether cid names an order this account filled.

pub fn order_ended(&self, cid: &ClientOrderId) -> Option<UnindexedInactiveOrder>

How the order cid ended, or None if it is still open or this account never held it.

An order a configured initial_state reported as cancelled is found too; one it reported in any other inactive state is not, because a snapshot seeds only open and cancelled orders.

An id names at most one order at a time, and an id is in at most one place: the book, or one of the ledgers an order can end in, holding the latest order under it (see book). So the answer is how the latest order under cid ended.

pub fn ack_expired( &mut self, order: Order<ExchangeId, InstrumentNameExchange, Expired>, )

Records that order reached its own deadline, so it is reported by a later account snapshot and a cancel arriving after it can be told apart from a cancel for an unknown order.

Replaces whatever the ledgers held for an earlier order under the same id.

pub fn is_expired(&self, cid: &ClientOrderId) -> bool

Whether cid names an order that reached its deadline while this account held it.

pub fn update_time_exchange(&mut self, time_exchange: DateTime<Utc>)

Restates every balance as of time_exchange.

Open orders keep their own stamps

Open::time_exchange is the instant the venue accepted the order, and an order does not become a different order because time passed. This used to rewrite it on every advance, which was invisible only because nothing rested: the venue filled every order on arrival, so orders_open held at most what an initial_state seeded.

It is not invisible once orders rest. Arrival order is half of price-time priority, so rewriting it would make a matching engine’s tie-break depend on when the clock last moved rather than on when each order arrived — and since every order would be rewritten to the same instant, there would be no tie-break left at all. It would also make every open order look newer than the engine’s copy on each advance, which is exactly what the rustrade engine’s OrderManager recency guard reads to decide whether an update is stale.

pub fn balances( &self, ) -> impl Iterator<Item = &AssetBalance<AssetNameExchange>> + '_

pub fn orders_open( &self, ) -> impl Iterator<Item = &Order<ExchangeId, InstrumentNameExchange, Open>> + '_

Every open order, in no particular order — see OpenOrders::resting for the order a venue matches in.

pub fn orders_cancelled( &self, ) -> impl Iterator<Item = &Order<ExchangeId, InstrumentNameExchange, Cancelled>> + '_

pub fn orders_expired( &self, ) -> impl Iterator<Item = &Order<ExchangeId, InstrumentNameExchange, Expired>> + '_

pub fn trades( &self, time_since: DateTime<Utc>, ) -> impl Iterator<Item = &Trade<AssetNameExchange, InstrumentNameExchange>> + '_

pub fn balance_mut( &mut self, asset: &AssetNameExchange, ) -> Option<&mut AssetBalance<AssetNameExchange>>

pub fn ack_trade( &mut self, trade: Trade<AssetNameExchange, InstrumentNameExchange>, )

pub fn reserve( &mut self, asset: &AssetNameExchange, amount: Decimal, time_exchange: DateTime<Utc>, ) -> Result<AssetBalance<AssetNameExchange>, BalanceInsufficient>

Holds amount of asset against an order, moving it out of free.

total is untouched: the asset is still held, it is merely no longer spendable. The held portion is total - free, which is what Balance::used reports and what a venue restates to its client.

Errors

BalanceInsufficient if free does not cover amount. The ledger is left untouched, so a caller may reject the order and carry on.

Panics

Panics if asset has no balance. The balances are the venue’s own fixture, so an absent one is a mis-specified account rather than a runtime condition — see SimulatedVenue’s caller obligations.

pub fn settle( &mut self, asset: &AssetNameExchange, amount: Decimal, time_exchange: DateTime<Utc>, ) -> AssetBalance<AssetNameExchange>

Settles amount of asset already held by reserve out of the account.

Only total moves: free was reduced when the amount was reserved. Reserving and then settling the same amount therefore lowers both by it, which is what an order that fills on arrival does.

Panics

Panics if asset has no balance — see reserve. Settling more than is held would take total below free and break the ledger’s invariant, so it panics in debug builds; callers settle an amount they reserved.

pub fn release( &mut self, asset: &AssetNameExchange, amount: Decimal, time_exchange: DateTime<Utc>, ) -> AssetBalance<AssetNameExchange>

Gives amount of asset back to free, undoing a reserve that will never be settled.

Only free moves: nothing left the account, so total is unchanged. This is what a cancelled, expired or rejected order does to the balance held against it.

Panics

Panics if asset has no balance — see reserve. Releasing more than is held would take free above total and break the ledger’s invariant, so it panics in debug builds; callers release an amount they reserved.

pub fn charge( &mut self, asset: &AssetNameExchange, amount: Decimal, time_exchange: DateTime<Utc>, ) -> AssetBalance<AssetNameExchange>

Moves amount of asset into the account, or out of it when negative, whatever free holds.

For a charge the account cannot refuse, such as a holding cost: a venue posts carry whether or not the account can cover it. total and free move together, so what is held stays held, and a debit larger than free takes free below zero rather than being refused. The caller reports that, since only it knows what the charge was for.

Panics

Panics if asset has no balance — see reserve.

pub fn deliver( &mut self, delivery: &Delivery, effect: MarginEffect, time_exchange: DateTime<Utc>, ) -> AssetBalance<AssetNameExchange>

Moves a Delivery into the account, or out of it when negative, creating the balance at zero if the account has never held its asset.

What a fill delivers: the base a spot buy receives, or the proceeds of a spot sell. A venue credits the asset an order receives whether or not the account held it before, so unlike every debit, an absent balance here is not a mis-specified fixture. total and free move together, as for charge.

Unchecked, like charge: a negative delivery larger than free takes free below zero rather than being refused. commit is the checked path, and a fill that can be refused goes through it.

On a margin account, for an order whose effect is Repay, what is delivered into an asset the account owes repays that loan first, interest then principal, and only the rest is added to free. Under any other effect, or on a cash account, all of it is added to free.

pub fn release_reservation( &mut self, reservation: &Reservation, auto_repay_at_cancel: bool, time_exchange: DateTime<Utc>, ) -> AssetBalance<AssetNameExchange>

Gives reservation back to free, as release does, then, with auto_repay_at_cancel, repays the loan its order took when it was placed (Reservation::loan) out of the free balance, interest first.

What a cancelled, expired or rejected order does to the balance held against it on a margin account, which repays an unused loan when the order it was taken for ends. Without auto_repay_at_cancel the loan stays owed. A reservation that borrowed nothing is simply released.

Panics

As release.

pub fn repay_loan( &mut self, asset: &AssetNameExchange, amount: Decimal, time_exchange: DateTime<Utc>, ) -> AssetBalance<AssetNameExchange>

Repays up to amount of asset’s loan out of its free balance, interest first, and never more than free holds.

Panics

Panics if asset has no balance — see reserve.

pub fn commit( &mut self, debit: &Debit, credit: Option<&Credit>, effect: MarginEffect, borrowable: Decimal, min_borrow: Decimal, time_exchange: DateTime<Utc>, ) -> Result<Committed, BalanceInsufficient>

Commits one arriving order’s whole ledger effect, or none of it.

One order’s arrival can both settle a fill and take a hold: a taker that the book could only partly fill settles what traded and reserves against the remainder it leaves resting. Those are one event at the venue, so they are one operation here — and because every requirement is tested before anything moves, an arrival this account cannot afford leaves the ledger exactly as it found it.

Why this is not two calls

Settling first and reserving second is the same two moves in the order that can fail halfway: the settle commits, the reserve is refused, and nothing puts back what total has already lost — release moves only free, and its own assertion fires if it is used as a rollback. The venue would then hold a balance its client never hears about, silently and for the rest of the run. Asking for the whole requirement up front is what makes that state unreachable rather than merely avoided.

One restatement per asset moved

A balance is an absolute restatement rather than a delta, and a fill is atomic at the venue, so emitting the state between the settle and the hold would report a balance the account never held — for the same reason a conservative reservation that had to be released and re-debited would. Committed therefore carries one balance per asset the arrival moved: the one it paid with, and the one it received when that is another asset.

What the fill pays back

credit is what the fill gives the account, and which Credit it is decides what it does:

• PaidBack, into the paying asset — the margin and realised PnL of the part of a CFD fill that closes a position. It counts towards what free must cover, because one fill can carry both: a CFD flip, closing a long and opening a short in one order, is paid back for the long and posts margin for the short, so the flip is funded by the long it closes.
• Delivery, into another asset — what a spot fill receives: base for a buy, the proceeds for a sell, each net of any fee charged in it. It funds nothing, since it is not the asset paid with, and it is delivered whether or not the account held that asset before. It is negative only for a fill whose fee exceeds what it receives, and then that asset’s free must cover the excess too.

Nothing is credited until every requirement is known to be covered, so a refusal still leaves the ledger exactly as it was. None is an arrival with nothing to pay back: an order that rests having traded nothing.

What a margin account lends and repays

On a margin account, for an order whose effect is Borrow, a requirement free and the credit do not cover borrows the shortfall of the paying asset, raised to min_borrow if it is less, if that loan is at most borrowable, the most the venue will lend of it now. The loan is taken with the rest of the arrival, or not at all. Committed::borrowed says how much was lent, and Committed::excess_borrowed how much of it the minimum added, which stays free. A paying asset the account has never held has nothing free, and is opened when the loan is taken. A cash account, and an order with another effect, ignore borrowable and min_borrow, and a negative borrowable lends nothing.

For an order whose effect is Repay, what the credit delivers repays the loan of the asset it is delivered into, as deliver does.

Errors

BalanceInsufficient, naming the asset short, if free plus a credit into the paying asset, plus what may be borrowed, does not cover settled + reserved, or if a negative credit into another asset exceeds that asset’s free. The ledger is left untouched.

Panics

Panics if the paying asset has no balance and the arrival borrows none of it — see reserve. Debug-asserts that a PaidBack credit is not negative.

Trait Implementations

impl Debug for AccountState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<AccountSnapshot<ExchangeId, AssetNameExchange, InstrumentNameExchange>> for AccountState

Seeds an account from a snapshot, as a SimulatedVenue does from its initial_state.

Errors

DuplicateSeededOrder if the snapshot lists one ClientOrderId more than once among its open and cancelled orders.

type Error = DuplicateSeededOrder

The type returned in the event of a conversion error.

fn try_from(value: UnindexedAccountSnapshot) -> Result<Self, Self::Error>

Performs the conversion.