Custos docs

Getting started

Custos documentation

Custos is a margin engine the Hedera network keeps: an HBAR-USD perpetual market whose liquidations and funding are run by Hedera's Schedule Service, with no keeper bot and no server. It ships as a scaffold-hbar template you can scaffold with one command.

On most chains, anything that must happen on a timer (liquidations, funding, interest, expiries) is run by an automation network or a team's own bot. Hedera has its own answer: since HIP-1215, a contract can book a call to itself in the future, and the network runs it. Custos uses that for the highest-stakes job there is, liquidating positions with real money on the line, and solves its sharp edges in the open: capacity, the gas hold, broken chains, gas limits and testing.

What you get#

Three reusable parts, and a market built from them:

ContractJobReuse it for
ScheduledKeeperRuns a job every interval with no bot: each tick books the next one on the Schedule Service and pays for it.Liquidations, interest, expiries, rebalancing, payouts
PriceGuardChainlink is the price, Supra is the cross-check. Refuses stale or disagreeing prices, never reverts on a broken feed.Anything that must not act on a bad price
MarginAccountPosition book and risk math: PnL, funding, equity, maintenance margin, liquidation price.Perps, margin, leveraged positions
PerpMarketThe HBAR-USD market. The network liquidates and charges funding on every tick.The demo; copy it for a new market
LiquidityPoolUSDC in, cUSDC-LP out: a native Hedera token the pool creates and mints. Every trader's counterparty.Any vault whose shares should be a real Hedera token
HbarDepositZapLPs deposit with HBAR: SaucerSwap swaps it to USDC and the zap deposits it, in one transaction.Any vault that should accept HBAR directly

Hedera services in play#

  • Schedule Service: the keeper. Every tick books the next one (HIP-1215).
  • Token Service: USDC collateral, and the cUSDC-LP share token, created and minted by the pool contract.
  • Consensus Service: an audit log of every keeper event on topic 0.0.10839050(opens in a new tab).
  • Mirror node: the app's history, and the source the audit log is built from.
  • Ecosystem: Chainlink and Supra prices; SaucerSwap for opening with HBAR, closing to HBAR, depositing HBAR, and the keeper's refuel; HashPack and Kabila wallets.

Where to go next#