BalanceManager
The BalanceManager shared object holds all balances for different assets. To perform trades, pass a combination of BalanceManager and TradeProof into a pool. TradeProofs are generated in one of two ways, either by the BalanceManager owner directly, or by any TradeCap owner. The owner can generate a TradeProof without the risk of equivocation. The TradeCap owner, because it's an owned object, risks equivocation when generating a TradeProof. Generally, a high frequency trading engine trades as the default owner.
With exception to swaps, all interactions with DeepBook require a BalanceManager as one of its inputs. When orders are matched, funds are transferred to or from the BalanceManager. You can use a single BalanceManager between all pools.
API
Following are the different public functions that the BalanceManager exposes.
Create a BalanceManager
The new() function creates a BalanceManager hot potato (a struct with no abilities). Combine it with share, or else the transaction fails. You can combine the transaction with deposit calls, allowing you to create, deposit, then share the balance manager in one transaction.
public fun new(ctx: &mut TxContext): BalanceManager {
let id = object::new(ctx);
event::emit(BalanceManagerEvent {
balance_manager_id: id.to_inner(),
owner: ctx.sender(),
});
BalanceManager {
id,
owner: ctx.sender(),
balances: bag::new(ctx),
allow_listed: vec_set::empty(),
}
}
Create a BalanceManager with custom owner
The new_with_owner() function creates a BalanceManager hot potato (a struct with no abilities) with a custom owner. Combine it with share, or else the transaction fails. You can combine the transaction with deposit calls, allowing you to create, deposit, then share the balance manager in one transaction.
public fun new_with_owner(ctx: &mut TxContext, owner: address): BalanceManager {
let id = object::new(ctx);
event::emit(BalanceManagerEvent {
balance_manager_id: id.to_inner(),
owner,
});
BalanceManager {
id,
owner,
balances: bag::new(ctx),
allow_listed: vec_set::empty(),
}
}
Mint a TradeCap
The owner of a BalanceManager can mint a TradeCap and send it to another address. Upon receipt, that address will have the capability to place orders with this BalanceManager. The address owner cannot deposit or withdraw funds, however. The maximum total number of TradeCap, WithdrawCap, and DepositCap that can be assigned for a BalanceManager is 1000. If this limit is reached, one or more existing caps must be revoked before minting new ones. You can also use revoke_trade_cap to revoke DepositCap and WithdrawCap.
/// Mint a `TradeCap`, only owner can mint a `TradeCap`.
public fun mint_trade_cap(balance_manager: &mut BalanceManager, ctx: &mut TxContext): TradeCap {
balance_manager.validate_owner(ctx);
assert!(balance_manager.allow_listed.size() < MAX_TRADE_CAPS, EMaxCapsReached);
let id = object::new(ctx);
balance_manager.allow_listed.insert(id.to_inner());
TradeCap {
id,
balance_manager_id: object::id(balance_manager),
}
}
/// Revoke a `TradeCap`. Only the owner can revoke a `TradeCap`.
/// Can also be used to revoke `DepositCap` and `WithdrawCap`.
public fun revoke_trade_cap(
balance_manager: &mut BalanceManager,
trade_cap_id: &ID,
ctx: &TxContext,
) {
balance_manager.validate_owner(ctx);
assert!(balance_manager.allow_listed.contains(trade_cap_id), ECapNotInList);
balance_manager.allow_listed.remove(trade_cap_id);
}
Mint a DepositCap or WithdrawCap
The owner of a BalanceManager can mint a DepositCap or WithdrawCap and send it to another address. Upon receipt, that address will have the capability to deposit in or withdraw from BalanceManager. The address owner cannot execute trades, however. The maximum total number of TradeCap, WithdrawCap, and DepositCap that can be assigned for a BalanceManager is 1000. If this limit is reached, one or more existing caps must be revoked before minting new ones.
/// Mint a `DepositCap`, only owner can mint.
public fun mint_deposit_cap(balance_manager: &mut BalanceManager, ctx: &mut TxContext): DepositCap {
balance_manager.validate_owner(ctx);
assert!(balance_manager.allow_listed.size() < MAX_TRADE_CAPS, EMaxCapsReached);
let id = object::new(ctx);
balance_manager.allow_listed.insert(id.to_inner());
DepositCap {
id,
balance_manager_id: object::id(balance_manager),
}
}
/// Mint a `WithdrawCap`, only owner can mint.
public fun mint_withdraw_cap(
balance_manager: &mut BalanceManager,
ctx: &mut TxContext,
): WithdrawCap {
balance_manager.validate_owner(ctx);
assert!(balance_manager.allow_listed.size() < MAX_TRADE_CAPS, EMaxCapsReached);
let id = object::new(ctx);
balance_manager.allow_listed.insert(id.to_inner());
WithdrawCap {
id,
balance_manager_id: object::id(balance_manager),
}
}
Generate a TradeProof
To call any function that requires a balance check or transfer, the user must provide their BalanceManager as well as a TradeProof. There are two ways to generate a trade proof, one used by the owner and another used by a TradeCap owner.
/// Generate a `TradeProof` by the owner. The owner does not require a capability
/// and can generate TradeProofs without the risk of equivocation.
public fun generate_proof_as_owner(
balance_manager: &mut BalanceManager,
ctx: &TxContext,
): TradeProof {
balance_manager.validate_owner(ctx);
TradeProof {
balance_manager_id: object::id(balance_manager),
trader: ctx.sender(),
}
}
/// Generate a `TradeProof` with a `TradeCap`.
/// Risk of equivocation since `TradeCap` is an owned object.
public fun generate_proof_as_trader(
balance_manager: &mut BalanceManager,
trade_cap: &TradeCap,
ctx: &TxContext,
): TradeProof {
balance_manager.validate_trader(trade_cap);
TradeProof {
balance_manager_id: object::id(balance_manager),
trader: ctx.sender(),
}
}
Deposit funds
Only the owner can call this function to deposit funds into the BalanceManager.
/// Deposit funds to a balance manager. Only owner can call this directly.
public fun deposit<T>(balance_manager: &mut BalanceManager, coin: Coin<T>, ctx: &mut TxContext) {
balance_manager.emit_balance_event(
type_name::get<T>(),
coin.value(),
true,
);
let proof = balance_manager.generate_proof_as_owner(ctx);
balance_manager.deposit_with_proof(&proof, coin.into_balance());
}
Withdraw funds
Only the owner can call this function to withdraw funds from the BalanceManager.
/// Withdraw funds from a balance_manager. Only owner can call this directly.
/// If withdraw_all is true, amount is ignored and full balance withdrawn.
/// If withdraw_all is false, withdraw_amount will be withdrawn.
public fun withdraw<T>(
balance_manager: &mut BalanceManager,
withdraw_amount: u64,
ctx: &mut TxContext,
): Coin<T> {
let proof = generate_proof_as_owner(balance_manager, ctx);
let coin = balance_manager.withdraw_with_proof(&proof, withdraw_amount, false).into_coin(ctx);
balance_manager.emit_balance_event(
type_name::get<T>(),
coin.value(),
false,
);
coin
}
public fun withdraw_all<T>(balance_manager: &mut BalanceManager, ctx: &mut TxContext): Coin<T> {
let proof = generate_proof_as_owner(balance_manager, ctx);
let coin = balance_manager.withdraw_with_proof(&proof, 0, true).into_coin(ctx);
balance_manager.emit_balance_event(
type_name::get<T>(),
coin.value(),
false,
);
coin
}
Deposit funds using DepositCap
Only holders of a DepositCap for the BalanceManager can call this function to deposit funds into the BalanceManager.
/// Deposit funds into a balance manager by a `DepositCap` owner.
public fun deposit_with_cap<T>(
balance_manager: &mut BalanceManager,
deposit_cap: &DepositCap,
coin: Coin<T>,
ctx: &TxContext,
) {
balance_manager.emit_balance_event(
type_name::get<T>(),
coin.value(),
true,
);
let proof = balance_manager.generate_proof_as_depositor(deposit_cap, ctx);
balance_manager.deposit_with_proof(&proof, coin.into_balance());
}
Withdraw funds using WithdrawCap
Only holders of a WithdrawCap for the BalanceManager can call this function to withdraw funds from the BalanceManager.
/// Withdraw funds from a balance manager by a `WithdrawCap` owner.
public fun withdraw_with_cap<T>(
balance_manager: &mut BalanceManager,
withdraw_cap: &WithdrawCap,
withdraw_amount: u64,
ctx: &mut TxContext,
): Coin<T> {
let proof = balance_manager.generate_proof_as_withdrawer(
withdraw_cap,
ctx,
);
let coin = balance_manager.withdraw_with_proof(&proof, withdraw_amount, false).into_coin(ctx);
balance_manager.emit_balance_event(
type_name::get<T>(),
coin.value(),
false,
);
coin
}
Read endpoints
public fun validate_proof(balance_manager: &BalanceManager, proof: &TradeProof) {
assert!(object::id(balance_manager) == proof.balance_manager_id, EInvalidProof);
}
/// Returns the balance of a Coin in a balance manager.
public fun balance<T>(balance_manager: &BalanceManager): u64 {
let key = BalanceKey<T> {};
if (!balance_manager.balances.contains(key)) {
0
} else {
let acc_balance: &Balance<T> = &balance_manager.balances[key];
acc_balance.value()
}
}
/// Returns the owner of the balance_manager.
public fun owner(balance_manager: &BalanceManager): address {
balance_manager.owner
}
/// Returns the owner of the balance_manager.
public fun id(balance_manager: &BalanceManager): ID {
balance_manager.id.to_inner()
}