Ledger state

The Sugar Rush ledger’s state is partitioned into two compartments. The main compartment holds this state:

• accounts: HashMap<PublicKeyHash, Account>
• markets: HashMap<TradingPair, Market>
• orders: HashMap<OrderId, Ownership>
• next_order_id: OrderId
• fee_account: Owner
• administrator: PublicKeyHash

The deposit compartments are represented by this state:

• pending_deposits: HashMap<RequestId, Account>

An account consists of:

• actor: PublicKeyHash A public key hash that can sign for user requests that spend funds managed by this account

• destination: (Address, Option<PlutusData>) The address and optional datum to which funds will be evacuated, if consensus breaks down. In particular, this enables treasury-owned sugar rush accounts, with trading authority temporarily delegated.

• uncommitted_value: Value An uncommitted value, not tied up in any orders

• nonce: u64 Each action performed by the user must have a nonce greater than this one, and successful application of the user request will replace this nonce.

• orders: HashMap<TradingPair, List<OrderId>> All open or partially filled orders across all orderbooks in the sugar rush ledger

A Market consists of:

• trading_pair: TradingPair A tuple of tokens for which this market is trading between; Somewhat arbitrarily but to match industry convention, the first asset is known as the “Base” asset, and the second is known as the “Quote” asset; Prices are denominated in “Units of quote per unit of base”. Orders which offer up the quote asset to receive the base asset are known as “Bids”, while orders that do the reverse are called “Asks”.

• taker_fee: Ratio The fee that takers are charged when their orders get matched against an order in the orderbook. It is deducted from the asset that the user would receive. (This user is known as the “taker”, since they are taking liquidity from the market)

• maker_fee: Ratio The fee that makers are charged when their order in the orderbook is (partially) executed. It is deducted from the amount that would be received by the maker as a result of the trade. (This user is known as the “maker”, since by providing liquidity to sit in the orderbook, they are “making” a market)

• bids: BTreeMap<Reverse<Price>, VecDeque<Order>> The open bids in this trading pair, sorted from highest bid price to lowest bid price;

• asks: BTreeMap<Price, VecDeque<Order>> The open asks in this trading pair, sorted from lowest ask price to highest ask price;

• orders: HashMap<OrderId, (Side, Price)> A reverse index for finding orders in the bid/ask maps

An order consists of:

• id: OrderId

• owner: PublicKeyHash

• pair: TradingPair

• side: Side

• price: Price

• original_amount: Quantity

• remaining: Quantity

• created: Timestamp

• destination: Option<(Address, Option<Datum>)> If set, the evacuation map will contain these funds separately. This can, for example, ensure an order settles against Sundae v4 after evacuation, rather than returning to the users wallet.

• last_executed: Timestamp

An Ownership is a reverse index object used for identifying the owner and market for an order. It consists of:

• id: OrderId
• owner: PublicKeyHash
• pair: TradingPair

With respect to Gummiworm, at any given time the evacuation map can be computed for each user as the sum of their uncommitted funds, and the remaining balance on all open orders without a destination, associated with the destination of the account, plus any orders with a destination.

Initialization

The initial state of the Sugar Rush ledger is specified (via hash) in the Head’s initialization effect.

Evacuation map

Evacuation map: HashMap<PublicKeyHash, Value>.

Evacuation map changes:

• Update: this PublicKeyHash should now have this Value.
• Remove: remove this PublicKeyHash