docs/content/standards/deepbookv3-sdk/balance-manager.mdx
The BalanceManager is a core component of DeepBookV3 that holds all asset balances. The SDK provides comprehensive functions to create, manage, and interact with balance managers.
The DeepBookV3 SDK provides the following functions for managing balance managers.
<details> <summary>createAndShareBalanceManager</summary>Use createAndShareBalanceManager to create a new balance manager and automatically share it. The call returns a function that takes a Transaction object.
Use createBalanceManagerWithOwner to create a new balance manager with a custom owner. Returns the manager object. The call returns a function that takes a Transaction object.
Parameters
ownerAddress: String representing the address of the owner.Use shareBalanceManager to share a balance manager that was created but not yet shared. The call returns a function that takes a Transaction object.
Parameters
manager: TransactionArgument representing the balance manager to share.Use depositIntoManager to deposit funds into a balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.coinKey: String that identifies the coin to deposit.amountToDeposit: Number representing the amount to deposit.Use withdrawFromManager to withdraw funds from a balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.coinKey: String that identifies the coin to withdraw.amountToWithdraw: Number representing the amount to withdraw.recipient: String representing the recipient address.Use withdrawAllFromManager to withdraw all funds of a specific coin type from a balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.coinKey: String that identifies the coin to withdraw.recipient: String representing the recipient address.Use checkManagerBalance to check the balance of a specific coin in a balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.coinKey: String that identifies the coin to check.Use generateProof to generate a trade proof for the balance manager. Automatically calls the appropriate function based on whether a tradeCap is set. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.Use generateProofAsOwner to generate a trade proof as the owner of the balance manager. The call returns a function that takes a Transaction object.
Parameters
managerId: String representing the ID of the balance manager.Use generateProofAsTrader to generate a trade proof using a tradeCap. The call returns a function that takes a Transaction object.
Parameters
managerId: String representing the ID of the balance manager.tradeCapId: String representing the ID of the trade cap.Use mintTradeCap to mint a tradeCap for the balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.Use mintDepositCap to mint a depositCap for the balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.Use mintWithdrawalCap to mint a withdrawCap for the balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.Use depositWithCap to deposit funds into a balance manager using a depositCap. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.coinKey: String that identifies the coin to deposit.amountToDeposit: Number representing the amount to deposit.Use withdrawWithCap to withdraw funds from a balance manager using a withdrawCap. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.coinKey: String that identifies the coin to withdraw.amountToWithdraw: Number representing the amount to withdraw.Use revokeTradeCap to revoke a TradeCap. This also revokes the associated DepositCap and WithdrawCap. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.tradeCapId: String representing the ID of the TradeCap to revoke.Use setBalanceManagerReferral to set a pool-specific referral for the balance manager. Requires a tradeCap for permission checking. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.referral: String representing the referral ID (DeepBookPoolReferral).tradeCap: TransactionArgument representing the trade cap for permission.Use unsetBalanceManagerReferral to remove a referral from the balance manager for a specific pool. Requires a tradeCap for permission checking. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.poolKey: String that identifies the pool to unset the referral for.tradeCap: TransactionArgument representing the trade cap for permission.Use getBalanceManagerReferralId to get the referral ID associated with a balance manager for a specific pool. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.poolKey: String that identifies the pool.Use registerBalanceManager to register a balance manager with the registry. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.Use owner to get the owner address of a balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.Use id to get the ID of a balance manager. The call returns a function that takes a Transaction object.
Parameters
managerKey: String that identifies the balance manager.Use balanceManagerReferralOwner to get the owner address of a pool referral (DeepBookPoolReferral). The call returns a function that takes a Transaction object.
Parameters
referralId: String representing the ID of the referral.Use balanceManagerReferralPoolId to get the pool ID associated with a pool referral (DeepBookPoolReferral). The call returns a function that takes a Transaction object.
Parameters
referralId: String representing the ID of the referral.The following examples demonstrate common balance manager operations.
// Example: Create and share a new balance manager
createBalanceManager = (tx: Transaction) => {
tx.add(this.balanceManager.createAndShareBalanceManager());
};
// Example: Create a balance manager with custom owner and share it
createManagerWithOwner = (tx: Transaction) => {
const ownerAddress = '0x123...';
// Create the manager with custom owner
const manager = tx.add(this.balanceManager.createBalanceManagerWithOwner(ownerAddress));
// Share the manager
tx.add(this.balanceManager.shareBalanceManager(manager));
};
// Example: Deposit USDC into a balance manager
depositFunds = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const coinKey = 'DBUSDC';
const amount = 1000; // 1000 USDC
tx.add(this.balanceManager.depositIntoManager(managerKey, coinKey, amount));
};
// Example: Withdraw SUI from a balance manager
withdrawFunds = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const coinKey = 'SUI';
const amount = 100; // 100 SUI
const recipient = '0x456...';
tx.add(this.balanceManager.withdrawFromManager(managerKey, coinKey, amount, recipient));
};
// Example: Withdraw all DEEP from a balance manager
withdrawAllDeep = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const coinKey = 'DEEP';
const recipient = '0x456...';
tx.add(this.balanceManager.withdrawAllFromManager(managerKey, coinKey, recipient));
};
// Example: Mint a TradeCap and use it
mintAndUseTradeCap = async (tx: Transaction) => {
const managerKey = 'MANAGER_1';
// Mint the TradeCap
const tradeCap = tx.add(this.balanceManager.mintTradeCap(managerKey));
// Transfer to a trader
const traderAddress = '0x789...';
tx.transferObjects([tradeCap], traderAddress);
};
// Example: Use DepositCap to deposit funds
depositWithCapability = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const coinKey = 'DBUSDC';
const amount = 5000; // 5000 USDC
tx.add(this.balanceManager.depositWithCap(managerKey, coinKey, amount));
};
// Example: Use WithdrawCap to withdraw funds
withdrawWithCapability = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const coinKey = 'SUI';
const amount = 50; // 50 SUI
const withdrawnCoin = tx.add(this.balanceManager.withdrawWithCap(managerKey, coinKey, amount));
// Transfer the withdrawn coin
tx.transferObjects([withdrawnCoin], '0xabc...');
};
// Example: Generate a trade proof and use it to place an order
placeOrderWithProof = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const poolKey = 'SUI_DBUSDC';
// Generate proof automatically (uses owner or tradeCap method)
const proof = tx.add(this.balanceManager.generateProof(managerKey));
// Use the proof to place an order
tx.add(
this.deepBook.placeLimitOrder({
poolKey: poolKey,
balanceManagerKey: managerKey,
clientOrderId: '12345',
price: 2.5,
quantity: 100,
isBid: true,
payWithDeep: true,
}),
);
};
// Example: Set a pool-specific referral for a balance manager
setManagerReferral = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const referralId = '0xdef...'; // DeepBookPoolReferral ID
// Get or create the TradeCap
const tradeCap = tx.object('0x...'); // Assuming tradeCap is already minted
tx.add(this.balanceManager.setBalanceManagerReferral(managerKey, referralId, tradeCap));
};
// Example: Unset a referral for a specific pool
unsetManagerReferral = (tx: Transaction) => {
const managerKey = 'MANAGER_1';
const poolKey = 'SUI_DBUSDC';
const tradeCap = tx.object('0x...');
tx.add(this.balanceManager.unsetBalanceManagerReferral(managerKey, poolKey, tradeCap));
};
// Example: Complete balance manager setup workflow
completeSetup = async (tx: Transaction) => {
const ownerAddress = '0x123...';
// Step 1: Create manager with custom owner
const manager = tx.add(this.balanceManager.createBalanceManagerWithOwner(ownerAddress));
// Step 2: Share the manager
tx.add(this.balanceManager.shareBalanceManager(manager));
// Step 3: Mint capabilities
const tradeCap = tx.add(this.balanceManager.mintTradeCap('MANAGER_1'));
const depositCap = tx.add(this.balanceManager.mintDepositCap('MANAGER_1'));
const withdrawCap = tx.add(this.balanceManager.mintWithdrawalCap('MANAGER_1'));
// Step 4: Transfer capabilities to owner
tx.transferObjects([depositCap, withdrawCap, tradeCap], ownerAddress);
};