Для разработчиков / SENDIT
Движок бессрочных контрактов
Один движок, один рынок на каждый фид оракула. Рынки с мгновенным исполнением исполняются в вашей транзакции; остальные исполняются через книгу ордеров раундом цены позже. Маржа берётся из банка, и каждая выплата возвращается в него.
| Величина | Единица |
|---|
| Доллары | базовые единицы pUSD, 1e6маржа, комиссии, выплаты |
|---|
| Цены | единицы оракула, 1e8tp, sl, limitPrice, acceptablePrice |
|---|
| Размер | единицы актива, 1e18usd = units x price / 1e20 |
|---|
| Идентификатор рынка | bytes32, идентификатор фида оракулаиз /api/perp/markets (feedId) |
|---|
| Плечо | uint16, целые числаот 1 до maxLeverage рынка |
|---|
requestOpen(OpenRequest) берёт маржу на эскроу и записывает roundAtRequest. Кипер вызывает execute(id), как только появляется более новый раунд, и исполняет по этому раунду без спреда или отменяет с причиной: цена за пределами acceptablePrice (лонг исполняется по этой цене или ниже, шорт по ней или выше; 0 означает без границы), рынок закрыт, отказ движка. requestClose(positionId, acceptablePrice) работает так же. Трейдер может сделать cancel после TRADER_CANCEL_AFTER (30 секунд) или сразу, пока рынок не открыт; после EXPIRE_AFTER (120 секунд) запрос уже не может исполниться, и отменить его может кто угодно. Каждый возврат идёт на баланс трейдера в банке. Идентификаторы запросов используют общий с движком idBase.
setTriggers(positionId, tp, sl, limitPrice) устанавливает тейк-профит, стоп-лосс и лимитное закрытие на вашей позиции, на любом рынке; ноль очищает поле. Лонг: TP и лимит срабатывают на уровне или выше, SL на уровне или ниже; для шорта зеркально. executeTrigger кипера исполняет только по раунду новее того, при котором были установлены триггеры, и отказывается исполнять позицию, подлежащую ликвидации. На закрытом рынке триггеры ждут открытия.
liquidate(id) доступен без разрешений. Ему нужна свежая цена и капитал ниже поддерживающей маржи, где капитал равен марже + PnL - фандинг - полная комиссия за закрытие, а поддерживающая маржа равна ceil(value / (2 x maxLeverage)) от текущей стоимости позиции. Ликвидация закрывает по цене оракула без спреда; штраф равен LIQ_PENALTY_BPS (1%) от стоимости, ограничен тем, что осталось, половина вызывающему в pUSD и половина протоколу; остаток идёт на баланс трейдера в банке. Ниже нуля начинается безнадёжный долг, который покрывает хранилище. Читайте isLiquidatable(id) или positionState(id); /api/perp/open постранично отдаёт все открытые позиции вместе с состоянием рынка, которое нужно, чтобы проверить их вне сети.
Когда статус фида оракула closed (2), публикатор оставляет в силе последнюю цену сессии. Открытия отклоняются ("market closed"). close или requestClose (который кипер исполняет сразу) проходит по этой последней цене за вычетом closedSpreadBps(feedId), плюс собственный спред рынка на рынке с мгновенным исполнением. Спред закрытого рынка задаёт владелец для каждого рынка: DEFAULT_CLOSED_SPREAD_BPS (10) при листинге, не больше MAX_CLOSED_SPREAD_BPS (100). Последней цене должно быть не больше CLOSED_HEARTBEAT + 30 секунд (или собственного heartbeat фида, если он длиннее), а позиция ниже поддерживающей маржи по этой цене не закрывается ("liquidatable"). Фандинг приостановлен; TP, SL, лимиты и ликвидации ждут первого раунда после открытия. Статусы 0 (unknown) и 3 (halted) замораживают рынок в обе стороны.
idBase() фиксируется при создании: 10,000,000 у текущего движка, поэтому его первая позиция имеет номер 10,000,001. Прежний движок, указанный в perpsPrevious манифеста с version: 1, нумерует с 1, берёт маржу из собственных pUSD кошелька и платит на кошелёк; он появился раньше банка, поэтому ключ не может с ним работать. Его позиции закрываются его собственным close(id), с подписью того кошелька, который их открыл.
The perps engine, VERSION 3: markets (one per oracle feed), positions, fees, funding and liquidation. Margin comes from the bank and every payout goes back to the trader's bank balance.
Trading
| Function | What it does |
|---|
| open((bytes32 feedId, bool isLong, uint256 margin, uint16 leverage, uint256 tp, uint256 sl) a) returns (uint256 id) | Opens on an immediate market in this transaction, at the latest round plus the spread. Margin is pulled from the signer's account. A non-zero tp or sl is handed to the orders book. |
|---|
| close(uint256 id) | Closes an immediate-market position in full, by the trader or a live key of theirs, also while the market is closed (at the last price). |
|---|
| liquidate(uint256 id) | Permissionless. Closes at the oracle price, no spread, when equity is below maintenance; the caller gets half the penalty. |
|---|
| accrue(bytes32 feedId) | Permissionless: brings a market's funding up to now. |
|---|
| flush() returns (uint256 pusdIn, uint256 wethOut) | Permissionless: sells the protocol's fee share for WETH and sends it to the FeeRouter, inside a price band. |
|---|
Called by the orders book
| Function | What it does |
|---|
| openFromOrders(address trader, (bytes32,bool,uint256,uint16,uint256,uint256) a) returns (uint256) | A two-step open, once the orders book has seen a round newer than the request. |
|---|
| closeFromOrders(uint256 id, uint8 reason) | A two-step close or a TP, SL or limit fill. While closed, only a close request fills. |
|---|
Reading
| Function | What it does |
|---|
| getPosition(uint256 id) view returns (Position) | trader, feedId, isLong, open, leverage, openedAt, margin, units, cost, fundingIndex. |
|---|
| positionState(uint256 id) view returns (int256 equity, uint256 maintenance, int256 pnl, int256 funding, uint256 value) | A position's equity against its maintenance, now. |
|---|
| getMarket(bytes32 feedId) view returns (Market) | A market's config, open interest per side and funding indexes. |
|---|
| quote(bytes32 feedId) view returns (uint256 price, uint256 roundId, uint8 status_, bool fresh) | The oracle round the engine would use. |
|---|
| previewFill(bytes32 feedId, bool isLong, bool opening) view returns (uint256) | The fill price with the spread, as a trade would get it now. |
|---|
| isImmediate(bytes32 feedId) view returns (bool) | True when the market fills in your transaction; false means two-step, through the orders book. |
|---|
| isClosable(bytes32 feedId) view returns (bool) | Whether a close can fill now (a fresh price, or a closed market's standing last price). |
|---|
| isLiquidatable(uint256 id) view returns (bool) | Below maintenance at a fresh price. |
|---|
| belowMaintenance(uint256 id) view returns (bool) | Below maintenance at the latest price, fresh or not. |
|---|
| fundingRate(bytes32 feedId) view returns (uint256 rate) | The hourly rate the heavier side pays now, 1e18 = 100%. |
|---|
| closedSpreadBps(bytes32) view returns (uint16) | The extra spread a close pays while the market is closed. |
|---|
| whyNotOpen(address trader, OpenArgs a) view returns (string) | Why open would fail for this account, or "". Call it before sending: revert reasons do not reach a client on this chain. |
|---|
| whyNotFill(OpenArgs a) view returns (string) | openFromOrders' checks, without the balance, the two-step gate or the age limit. |
|---|
| whyNotClose(address caller, uint256 id) view returns (string) | Why close would fail for this signer, or "". |
|---|
| marketCount() view returns (uint256) | How many markets are listed. |
|---|
| marketIds(uint256) view returns (bytes32) | The listed feed ids, by index. |
|---|
| nextPositionId() view returns (uint256) | The id the next position gets. |
|---|
| idBase() view returns (uint256) | Positions are numbered from idBase + 1. Fixed at construction. |
|---|
| params() view returns (uint16 netExposureCapBps, uint16 flushBandBps, uint16 flushMaxInputBps, uint256 fundingK, uint256 fundingCap) | The engine-wide parameters. |
|---|
| totalMargin() view returns (uint256) | The margin of every open position. |
|---|
| protocolOwed() view returns (uint256) | The protocol's fee share waiting for flush. |
|---|
| unrealisedPnl() view returns (int256 total) | Traders' net open PnL, which the vault's NAV subtracts. |
|---|
| grossWinnings() view returns (uint256 total) | What the winning sides are owed now. |
|---|
| netExposure() view returns (uint256 total) | The open imbalance the vault backs. |
|---|
| pusd() view returns (address) | pUSD. |
|---|
| vault() view returns (address) | The vault. |
|---|
| oracle() view returns (address) | The price feeds. |
|---|
| bank() view returns (address) | SenditBank. |
|---|
| orders() view returns (address) | The orders book. |
|---|
| owner() view returns (address) | The owner. |
|---|
| router() view returns (address) | The flush route's router. |
|---|
| flushPool() view returns (address) | The pUSD/WETH pool flush sells through. |
|---|
| weth() view returns (address) | WETH. |
|---|
| feeRecipient() view returns (address) | Where flushed WETH goes (FeeRouter). |
|---|
| pusdIsToken0() view returns (bool) | The flush pool's token order. |
|---|
Owner
| Function | What it does |
|---|
| setMarket(bytes32 feedId, (uint16 maxLeverage, uint16 spreadBps, uint16 maxOiLongBps, uint16 maxOiShortBps, bool enabled, bool inverse) c) | Lists or reconfigures a market: max leverage 1 to 100, spread at most 100 bps. Lowering maxLeverage raises maintenance for open positions at once. |
|---|
| setClosedSpread(bytes32 feedId, uint16 bps) | The closed-market spread, at most MAX_CLOSED_SPREAD_BPS. Binds the next close. |
|---|
| setParams((uint16,uint16,uint16,uint256,uint256) p) | Exposure cap, flush band and funding parameters (fundingK and fundingCap at most 1% an hour). |
|---|
| setOrders(address orders_) | Sets the orders book, once. |
|---|
| setFlushRoute(address router_, address pool_, address weth_, address feeRecipient_) | Where flush sells and where the WETH goes. |
|---|
| transferOwnership(address next) | Hands ownership on. |
|---|
Constants
| Function | What it does |
|---|
| VERSION() view returns (uint256) | 3. |
|---|
| FEE_BPS() view returns (uint256) | 5: 0.05% of the position's size, on open and again on close. |
|---|
| VAULT_FEE_SHARE_BPS() view returns (uint256) | 7000: 70% of every fee goes to the vault, the rest to the protocol. |
|---|
| LIQ_PENALTY_BPS() view returns (uint256) | 100: 1% of the size, half to the liquidator. |
|---|
| MIN_MARGIN() view returns (uint256) | 1e6: one dollar. |
|---|
| MAX_MARKETS() view returns (uint256) | 64. |
|---|
| IMMEDIATE_MAX_AGE() view returns (uint256) | 2 seconds: the oldest round an immediate fill accepts. |
|---|
| STALE_GRACE() view returns (uint256) | 30 seconds added to a feed's heartbeat. |
|---|
| CLOSED_HEARTBEAT() view returns (uint256) | 3600 seconds: how often a closed market's last price is republished. |
|---|
| DEFAULT_CLOSED_SPREAD_BPS() view returns (uint16) | 10: 0.10%, set on every new market. |
|---|
| MAX_CLOSED_SPREAD_BPS() view returns (uint16) | 100: the owner's ceiling, 1%. |
|---|
| MIN_FLUSH() view returns (uint256) | 1e6: the smallest flush. |
|---|
| ETH_USD() view returns (bytes32) | keccak256("ETH/USD"), the feed flush prices against. |
|---|
| CLOSE_TRADER() view returns (uint8) | 0: closed by the trader. |
|---|
| CLOSE_REQUEST() view returns (uint8) | 1: a two-step close request. |
|---|
| CLOSE_TP() view returns (uint8) | 2: take profit. |
|---|
| CLOSE_SL() view returns (uint8) | 3: stop loss. |
|---|
| CLOSE_LIMIT() view returns (uint8) | 4: limit close. |
|---|
| CLOSE_LIQUIDATION() view returns (uint8) | 5: liquidation. |
|---|
Events
| Event | What it does |
|---|
| PositionOpened(uint256 indexed positionId, address indexed trader, bytes32 indexed feedId, (bool isLong, uint16 leverage, uint256 margin, uint256 units, uint256 cost, uint256 price, uint256 fee, int256 fundingIndex) info) | A position opened. trader is the account, never the key. |
|---|
| PositionClosed(uint256 indexed positionId, address indexed trader, bytes32 indexed feedId, uint8 reason, (uint256 price, int256 pnl, int256 funding, uint256 fee, uint256 penalty, uint256 payout, uint256 badDebt, uint256 value) s) | A position closed; reason is one of the CLOSE_ constants. |
|---|
| PositionLiquidated(uint256 indexed positionId, address indexed liquidator, uint256 reward) | Emitted after PositionClosed on a liquidation. |
|---|
| FundingAccrued(bytes32 indexed feedId, uint256 ratePerHour, int256 longIndex, int256 shortIndex) | Funding brought up to date. |
|---|
| MarketListed(bytes32 indexed feedId) | A new market. |
|---|
| MarketConfigured(bytes32 indexed feedId, (uint16,uint16,uint16,uint16,bool,bool) config) | A market's config set. |
|---|
| ClosedSpreadSet(bytes32 indexed feedId, uint16 bps) | A closed-market spread set. |
|---|
| ParamsSet((uint16,uint16,uint16,uint256,uint256) params) | Engine parameters set. |
|---|
| OrdersSet(address indexed orders) | The orders book set. |
|---|
| FlushRouteSet(address router, address pool, address weth, address feeRecipient) | The flush route set. |
|---|
| Flushed(uint256 pusdIn, uint256 wethOut, uint256 ethUsdPrice, address feeRecipient) | The protocol's share sold and sent. |
|---|
| FlushSkipped(uint256 amountIn, uint256 minOut, uint8 reason) | A flush that did not swap: 1 no usable ETH/USD, 2 the swap was refused. |
|---|
The two-step book and the triggers. On a two-step market an open or close is a request, filled by the keeper at the first price round newer than the request. Take profit, stop loss and limit closes live here for every market.
Trading
| Function | What it does |
|---|
| requestOpen((bytes32 feedId, bool isLong, uint256 margin, uint16 leverage, uint256 acceptablePrice, uint256 tp, uint256 sl) r) returns (uint256 id) | Escrows the margin from the signer's account and records the request. acceptablePrice 0 means no bound; long fills at or below it, short at or above. |
|---|
| requestClose(uint256 positionId, uint256 acceptablePrice) returns (uint256 id) | A close request on a two-step market. On a closed market it fills at once at the last price. |
|---|
| cancel(uint256 id) | The trader after TRADER_CANCEL_AFTER, or at once while the market is not open; anyone after EXPIRE_AFTER. The margin goes back to the trader's bank balance. |
|---|
| setTriggers(uint256 positionId, uint256 tp, uint256 sl, uint256 limitPrice) | Sets TP, SL and limit close on your position; zero clears a field. Long: TP and limit fire at or above, SL at or below; short mirrored. |
|---|
Keeper and engine
| Function | What it does |
|---|
| execute(uint256 id) | Keeper only: fills a request at the round in force, which must be newer than the request, or cancels it with a reason. |
|---|
| executeTrigger(uint256 positionId, uint8 kind) | Keeper only: fills a TP, SL or limit at a round newer than the one it was set at. A liquidatable position is refused: liquidations go first. |
|---|
| initTriggers(uint256 positionId, uint256 tp, uint256 sl) | The engine only: the TP and SL an immediate open carried. |
|---|
Reading
| Function | What it does |
|---|
| getRequest(uint256 id) view returns (Request) | trader, feedId, kind, state, isLong, leverage, createdAt, margin, acceptablePrice, roundAtRequest, positionId, tp, sl. |
|---|
| getTriggers(uint256 positionId) view returns (uint256 tp, uint256 sl, uint256 limitPrice, uint256 roundAtSet) | A position's triggers. |
|---|
| pendingCount() view returns (uint256) | Requests waiting. |
|---|
| pendingPage(uint256 offset, uint256 limit) view returns (uint256[] ids, Request[] reqs) | Waiting requests, at most MAX_PAGE per call. |
|---|
| pendingClose(uint256) view returns (uint256) | The pending close request of a position, or 0. |
|---|
| demandedFeeds() view returns (bytes32[] out) | Feeds with pending requests: what the publisher should price next. |
|---|
| demand(bytes32) view returns (uint256) | Pending requests per feed. |
|---|
| escrowed() view returns (uint256) | The margin of pending open requests. |
|---|
| nextRequestId() view returns (uint256) | The next request id, numbered from the engine's idBase + 1. |
|---|
| whyNotRequestOpen(address trader, OpenRequest r) view returns (string) | Why requestOpen would fail for this account, or "". "immediate" means use the engine's open. |
|---|
| whyNotRequestClose(address caller, uint256 positionId) view returns (string) | Why requestClose would fail for this signer, or "". |
|---|
| whyNotCancel(address caller, uint256 id) view returns (string) | Why cancel would fail, or ""; "early" before the wait is over. |
|---|
| keepers(address) view returns (bool) | Whether an address may execute. |
|---|
| perps() view returns (address) | The engine. |
|---|
| pusd() view returns (address) | pUSD. |
|---|
| oracle() view returns (address) | The price feeds. |
|---|
| bank() view returns (address) | SenditBank. |
|---|
| owner() view returns (address) | The owner. |
|---|
Owner
| Function | What it does |
|---|
| setKeeper(address keeper, bool allowed) | Adds or removes a keeper. |
|---|
| transferOwnership(address next) | Hands ownership on. |
|---|
Constants
| Function | What it does |
|---|
| VERSION() view returns (uint256) | 3. |
|---|
| TRADER_CANCEL_AFTER() view returns (uint256) | 30 seconds. |
|---|
| EXPIRE_AFTER() view returns (uint256) | 120 seconds: after this a request cannot fill and anyone may cancel it. |
|---|
| MAX_PAGE() view returns (uint256) | 100. |
|---|
| KIND_OPEN() view returns (uint8) | 1. |
|---|
| KIND_CLOSE() view returns (uint8) | 2. |
|---|
| STATE_PENDING() view returns (uint8) | 1. |
|---|
| STATE_EXECUTED() view returns (uint8) | 2. |
|---|
| STATE_CANCELLED() view returns (uint8) | 3. |
|---|
| CANCEL_TRADER() view returns (uint8) | 1: cancelled by the trader. |
|---|
| CANCEL_EXPIRED() view returns (uint8) | 2: expired. |
|---|
| CANCEL_PRICE() view returns (uint8) | 3: the price moved past acceptablePrice. |
|---|
| CANCEL_CLOSED() view returns (uint8) | 4: the market closed. |
|---|
| CANCEL_POSITION() view returns (uint8) | 5: the position is gone. |
|---|
| CANCEL_REJECTED() view returns (uint8) | 6: the engine refused the fill. |
|---|
| CANCEL_LIQUIDATABLE() view returns (uint8) | 7: the position is liquidatable. |
|---|
| TRIGGER_TP() view returns (uint8) | 1. |
|---|
| TRIGGER_SL() view returns (uint8) | 2. |
|---|
| TRIGGER_LIMIT() view returns (uint8) | 3. |
|---|
Events
| Event | What it does |
|---|
| RequestCreated(uint256 indexed requestId, address indexed trader, bytes32 indexed feedId, Request request) | A request recorded. |
|---|
| RequestExecuted(uint256 indexed requestId, uint256 indexed positionId, uint256 price) | A request filled. |
|---|
| RequestCancelled(uint256 indexed requestId, address indexed trader, uint8 reason) | A request cancelled; reason is a CANCEL_ constant. |
|---|
| TriggersSet(uint256 indexed positionId, uint256 tp, uint256 sl, uint256 limitPrice) | Triggers set or cleared. |
|---|
| TriggerExecuted(uint256 indexed positionId, uint8 kind, uint256 price) | A TP, SL or limit filled. |
|---|
| KeeperSet(address indexed keeper, bool allowed) | A keeper added or removed. |
|---|
The counterparty to every perp trade. LPs deposit pUSD from their bank balance and hold pLP (18 decimals, one dollar each at the start). NAV is pUSD held minus traders' net open PnL.
LP
| Function | What it does |
|---|
| deposit(uint256 amount) returns (uint256 shares) | Pulls pUSD from the signer's account and mints pLP to the account. Locks all the account's pLP for SHARE_LOCK. |
|---|
| withdraw(uint256 shares) returns (uint256 amount) | Burns the account's pLP after the lock and pays its bank balance, at most withdrawable(). |
|---|
| transfer(address to, uint256 value) returns (bool) | Moves msg.sender's own pLP. A key holds none, so giving pLP away is a wallet action. Locked pLP cannot move. |
|---|
| transferFrom(address from, address to, uint256 value) returns (bool) | ERC-20 transferFrom. |
|---|
| approve(address spender, uint256 value) returns (bool) | ERC-20 approve. |
|---|
Reading
| Function | What it does |
|---|
| nav() view returns (uint256) | pUSD held minus unrealised trader PnL, floored at zero. |
|---|
| sharePrice() view returns (uint256) | pUSD per whole pLP, six decimals. |
|---|
| withdrawable() view returns (uint256) | The most a withdrawal can take now: NAV minus what backs open positions, and never the cash winners are owed. |
|---|
| reserved() view returns (uint256) | Net exposure plus gross winnings: what withdrawals cannot touch. |
|---|
| assets() view returns (uint256) | pUSD held. |
|---|
| previewDeposit(uint256 amount) view returns (uint256) | pLP a deposit would mint now. |
|---|
| previewRedeem(uint256 shares) view returns (uint256) | pUSD a withdrawal would pay now. |
|---|
| lockedUntil(address) view returns (uint256) | When an account's pLP unlocks. |
|---|
| balanceOf(address) view returns (uint256) | pLP held. |
|---|
| totalSupply() view returns (uint256) | pLP in existence. |
|---|
| allowance(address, address) view returns (uint256) | ERC-20 allowance. |
|---|
| name() view returns (string) | "Pepper Perp LP". |
|---|
| symbol() view returns (string) | "pLP". |
|---|
| decimals() view returns (uint8) | 18. |
|---|
| engine() view returns (address) | The engine, the only address that settles. |
|---|
| pusd() view returns (address) | pUSD. |
|---|
| bank() view returns (address) | SenditBank. |
|---|
| owner() view returns (address) | The deployer, who set the engine once. |
|---|
| VERSION() view returns (uint256) | 2. |
|---|
| SHARE_LOCK() view returns (uint256) | 1 hour. |
|---|
Engine and owner
| Function | What it does |
|---|
| settle(int256 amount) | The engine only: positive pulls pUSD in, negative pays it out. |
|---|
| setEngine(address engine_) | Once, by the owner. |
|---|
Events
| Event | What it does |
|---|
| Deposited(address indexed account, uint256 amount, uint256 shares) | An LP deposit. |
|---|
| Withdrawn(address indexed account, uint256 shares, uint256 amount) | An LP withdrawal. |
|---|
| Settled(int256 amount) | Money in or out of the engine. |
|---|
| Transfer(address indexed from, address indexed to, uint256 value) | pLP moved, minted or burned. |
|---|
| Approval(address indexed owner, address indexed spender, uint256 value) | ERC-20 approval. |
|---|
| EngineSet(address indexed engine) | The engine set. |
|---|