Margin accounts

MarginAccounts is where a borrower holds collateral and borrows USDG from the supply vault, which has these accounts as its one borrower. Each address has a cross position and, for any asset it chooses, an isolated position. A position holds Stock Tokens, USDG and WETH, owns a share of the vault's debt, and is margined by the margin engine.

Address#

Robinhood Chain testnet, chain 46630, from deployments/46630.json, under tapehouse.MarginAccounts.

Testnet, not audited.

Read a position#

import { readFileSync } from 'node:fs'
import { createPublicClient, http } from 'viem'
import { accounts, CROSS, parseDeployments } from '@tapehouse/sdk'

const deployments = parseDeployments(JSON.parse(readFileSync('deployments/46630.json', 'utf8')))
const client = createPublicClient({ transport: http('https://rpc.testnet.chain.robinhood.com') })
const account = '0xB986a345655097302cac8b4af6C948FfaF7f55FC'

const { equity, requirement, missing, regime } = await accounts.health(client, deployments, account, CROSS)
const price = await accounts.liquidationPrice(client, deployments, account, CROSS, 'TSLA', 50_000_000n)

CROSS is bytes32(0). An isolated position is named by its asset's symbol as bytes32, which toBytes32('TSLA') produces. Equity and requirement are USD with 18 decimals. The liquidation price is USD with 8 decimals.

Positions and checks#

• An asset sits in one position of an account at a time, because a split holding would pay a smaller liquidity add-on than the whole. An isolated position is margined alone, so it gets no diversification and its loss never reaches the cross position.
• Stock Tokens are held in raw units and valued at the low edge of their band, which already carries the token's multiplier. A halted band counts for nothing. WETH counts for 80% of its Chainlink price, and for nothing when that price is over a day old. USDG counts at par.
• Borrowing, and withdrawing from a position in debt, need the position's equity to meet the engine's currentRequirement over its Stock Tokens at those prices. A position without Stock Tokens needs only non-negative equity. A position holding USDG does not borrow: it repays with repayWithCollateral.
• Deposits and repayments stay open whatever the band, the session and the guardian. Borrowing and withdrawing from a position in debt close for a position holding an asset whose band is halted, whose Stock Token has a multiplier change pending or whose liquidity the engine cannot read; for any position while the L2 sequencer is not settled; and for a position holding Stock Tokens while the band cannot tell the session.
• After a band was last seen halted or with a multiplier change pending, borrowing and withdrawing against it stay closed for RECOVERY, 30 minutes, and revert with AssetRecovering(symbol, until). observe(symbol) records the sighting.
• From the regular open on the last trading day before a weekend or holiday close until the reopening, a loan or withdrawal must leave gross exposure to Stock Tokens at most weekendLeverage over equity.
• While the 24/5 session is closed, each position's debt carries a premium of premiumRate basis points a year on top of the vault's interest. A repayment pays the debt first and the premium after.

Functions#

position is CROSS or an asset's symbol. account is the account's owner. Where the table says "Account or authorized", the caller is the account, an address it passed to setAuthorization, or an agent with an unexpired mandate.

Deposit and withdraw#

Borrow and repay#

Lending the position's Stock Tokens#

Authorization and mandates#

An address authorized in full is not bound by a mandate. A call outside a mandate reverts with MandateDebtLimit, MandateLeverageLimit or MandateReceiver, and after expiresAt with MandateExpired.

Permissionless upkeep#

Liquidator only#

Everything here reverts with NotLiquidator(caller) for any other caller.

Owner, guardian and backstop#

Views#

Events#

Roles and admin powers#

• The owner sets the liquidator, backstop and each lending vault once, adds baskets, sets the premium rate (at most 100% a year), withdraws the fee reserve and names the guardian. It cannot move a position's collateral, and the band, engine, vault, caps and reserve share are fixed at deployment.
• The guardian can pause new borrowing and withdrawals from positions in debt. Deposits, repayments, seizures and write-offs stay open.
• The liquidator is the only address that seizes collateral and writes off debt.
• The backstop claims the premium set aside for it. Of each premium paid, reserveShare goes to the fee reserve and the rest is set aside for the backstop.
• USDG's and Stock Tokens' issuer can pause tokens, blocklist addresses and burn balances. A paused Stock Token, or one whose issuer has blocklisted the accounts, backs no new risk (AssetFrozen). If the issuer burns from the accounts, every holding of the asset falls in proportion once sync runs.

Invariants#

• Each position's debt is a share of the vault's debt, kept as borrow shares with Morpho Blue's virtual offsets. Only the accounts repay the vault.
• The accounts hold each asset up to a cap fixed at deployment, and the positions' total debt is capped by debtCap, with weekendDebtCap bounding a new loan before and across a closure.
• Collateral USDG is never lent.
• A write-off retires the position's borrow shares and the vault writes the same amount off, so lenders bear it and no other position's debt moves.

SDK#

TypeScript, module accounts in @tapehouse/sdk. Transactions return viem contract calls for simulateContract and writeContract.

repayWithCollateral, accruePremium, sync, clear and the owner, guardian and liquidator functions have no wrapper: use marginAccountsAbi, which the package exports.

Next#

• Open an account
• Borrow
• Liquidator
• Margin engine