Pour les développeurs / SENDIT
Moteur de perps
Un seul moteur, un marché par feed de l'oracle. Les marchés immédiats s'exécutent dans votre transaction ; les autres s'exécutent via le carnet d'ordres, un round de prix plus tard. La marge vient de la banque, et chaque paiement y retourne.
| Grandeur | Unité |
|---|
| Dollars | unités de base pUSD, 1e6marge, frais, paiements |
|---|
| Prix | unités de l'oracle, 1e8tp, sl, limitPrice, acceptablePrice |
|---|
| Taille | unités de l'actif, 1e18usd = units x price / 1e20 |
|---|
| Identifiant de marché | identifiant de feed de l'oracle, bytes32depuis /api/perp/markets (feedId) |
|---|
| Effet de levier | uint16, nombres entiersde 1 au maxLeverage du marché |
|---|
requestOpen(OpenRequest) met la marge sous séquestre et enregistre roundAtRequest. Un keeper appelle execute(id) dès qu'un round plus récent existe et exécute à ce round sans spread, ou annule avec une raison : au-delà de acceptablePrice (une position longue s'exécute à ce prix ou en dessous, une courte à ce prix ou au-dessus ; 0 signifie aucune borne), marché fermé, refus du moteur. requestClose(positionId, acceptablePrice) fonctionne de la même façon. Le trader peut faire cancel après TRADER_CANCEL_AFTER (30 secondes), ou tout de suite tant que le marché n'est pas ouvert ; après EXPIRE_AFTER (120 secondes), la demande ne peut plus être exécutée et n'importe qui peut l'annuler. Chaque remboursement va au solde du trader dans la banque. Les identifiants de demande partagent l'idBase du moteur.
setTriggers(positionId, tp, sl, limitPrice) pose un take profit, un stop loss et une clôture à cours limité sur votre position, sur n'importe quel marché ; zéro efface un champ. Position longue : le TP et la limite se déclenchent à ce prix ou au-dessus, le SL à ce prix ou en dessous ; l'inverse pour une courte. L'executeTrigger du keeper n'exécute qu'à un round plus récent que celui où les déclencheurs ont été posés, et refuse une position liquidable. Sur un marché fermé, les déclencheurs attendent la réouverture.
liquidate(id) est ouvert à tous, sans permission. Il faut un prix frais et des fonds propres sous le seuil de maintenance, où les fonds propres valent marge + PnL - financement - la totalité des frais de clôture, et la maintenance vaut ceil(value / (2 x maxLeverage)) de la valeur actuelle de la position. La clôture se fait au prix de l'oracle sans spread ; la pénalité est LIQ_PENALTY_BPS (1 %) de la valeur, plafonnée à ce qui reste, moitié à l'appelant en pUSD et moitié au protocole ; le reste va au solde du trader dans la banque. En dessous de zéro, c'est une créance irrécouvrable, que le coffre absorbe. Lisez isLiquidatable(id) ou positionState(id) ; /api/perp/open parcourt page par page chaque position ouverte, avec l'état de marché dont vous avez besoin pour la vérifier hors chaîne.
Quand le statut du feed de l'oracle est fermé (2), l'éditeur maintient le dernier prix de la séance. Les ouvertures sont refusées ("market closed"). Un close, ou un requestClose (que le keeper exécute aussitôt), passe à ce dernier prix moins closedSpreadBps(feedId), plus le spread propre au marché sur un marché immédiat. Le spread de fermeture est fixé par marché par le propriétaire : DEFAULT_CLOSED_SPREAD_BPS (10) à la cotation, au plus MAX_CLOSED_SPREAD_BPS (100). Le dernier prix doit avoir au plus CLOSED_HEARTBEAT + 30 secondes (ou le heartbeat propre du feed s'il est plus long), et une position sous la maintenance à ce prix ne se ferme pas ("liquidatable"). Le financement est suspendu ; TP, SL, limites et liquidations attendent le premier round après la réouverture. Les statuts 0 (inconnu) et 3 (arrêté) gèlent le marché dans les deux sens.
idBase() est fixé à la construction : 10 000 000 sur le moteur actuel, donc sa première position est la 10 000 001. Le moteur précédent, listé dans le perpsPrevious du manifeste avec version: 1, numérote à partir de 1, prend la marge dans le pUSD du portefeuille lui-même et paie le portefeuille ; il est antérieur à la banque, donc une clé ne peut pas agir dessus. Ses positions se ferment avec son propre close(id), signé par le portefeuille qui les a ouvertes.
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. |
|---|