Margin engine

The margin engine is a Stylus (Rust) program that margins a portfolio of Stock Tokens as one position. You give it signed quantities and USD prices, and it returns the margin the portfolio needs. It is a view: nothing is signed off chain, and anyone can rebuild its scenario set from its parameters.

Address#

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

A Solidity reference implementation of the same engine is deployed at 0x68B73e2c70cd61B9d94cCF7c0F3502F9DE93749c (references.Margin), so the two can be compared call by call. Nothing in Tapehouse depends on it. Testnet, not audited.

Ask for a requirement#

import { readFileSync } from 'node:fs'
import { createPublicClient, http } from 'viem'
import { engine, 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 portfolio = {
  quantities: [10n * 10n ** 18n, 0n],
  prices: [250_00000000n, 180_00000000n],
}
const { margin, missing, regime } = await engine.currentRequirement(client, deployments, portfolio)

The lists follow the order of assets(). Quantities are signed token amounts with 18 decimals, negative for a short. Prices are USD with 8 decimals. The numbers above are placeholders: read assets() for the order and the band for real prices.

Inputs and outputs#

Functions#

Requirement#

currentRequirement is open or closed by the band's session:

A call that leaves the band's session() too little gas reverts with InsufficientGas instead of reading as an unknown session.

Parameters#

volatility, correlation, weekendGap, depth and pool revert with UnknownAsset(symbol) for a symbol the engine does not hold.

Scenarios#

They revert with ScenarioOutOfRange(index) and UnsupportedScenarioSize(size). Neither is in the SDK's exported ABI.

Updates#

Events#

The history of every parameter rebuilds from these events alone.

Roles and admin powers#

The owner is the only privileged account. It can replace the parameters, and nothing else, with these limits:

• Each value stays at or above its floor, and a depth stays above zero and at or below its ceiling. The floors and ceilings are set in the constructor and never change.
• Each value moves by at most ×1.5 or ÷1.5 per update, except that a depth may fall by any amount, since a smaller depth only raises requirements.
• An update comes at least a day after the one before. The first may come at any time.
• The correlation matrix must stay positive definite.

The engine's assets, pools and band are fixed at deployment. A new asset means a new engine.

Invariants#

• The engine draws a deterministic scenario set on every call: 256 joint draws, 256 with every correlation 1, 256 with every correlation 0, a market move down and up, and the weekend-gap scenarios. The requirement is the largest of the expected shortfall at 99% with diversification capped at 80%, the stress scenarios and a single-position floor, plus the liquidity add-on.
• Arithmetic is integer. A Solidity reference answers every view of the program to the bit.
• A position margined alone is the portfolio that holds only it: call currentRequirement with every other quantity zero. Hold each asset in one position only, because the engine prices what it is given and does not check it.
• Across a closure, and whenever the session is unknown, leverage is capped: the requirement is at least a fifth of the gross exposure, so gross exposure over margin stays at or below 5×.

SDK#

TypeScript, module engine in @tapehouse/sdk.

The margin accounts call the engine for every position: accounts.health returns a position's equity next to the engine's requirement, and accounts.liquidationPrice searches the engine for the price at which a position stops meeting it.

Next#

• Portfolio margin
• Margin accounts
• Calibration
• Stylus versus Solidity