| 量 | 単位 |
|---|
| ドル額 | pUSD の基本単位、1e6証拠金、手数料、払い出し |
|---|
| 価格 | オラクル単位、1e8tp、sl、limitPrice、acceptablePrice |
|---|
| サイズ | 資産単位、1e18usd = units x price / 1e20 |
|---|
| マーケット ID | bytes32 のオラクルフィード ID/api/perp/markets から（feedId） |
|---|
| レバレッジ | uint16、整数1 からそのマーケットの maxLeverage まで |
|---|
requestOpen(OpenRequest) は証拠金を預かり、roundAtRequest を記録します。キーパーは、より新しいラウンドが存在するようになると execute(id) を呼び、そのラウンドでスプレッドなしに約定させるか、理由を付けてキャンセルします。理由は、acceptablePrice を越えた場合（ロングはそれ以下で、ショートはそれ以上で約定し、0 は制限なし）、マーケットが閉じている場合、エンジンが拒否した場合です。requestClose(positionId, acceptablePrice) も同じように動きます。トレーダーは TRADER_CANCEL_AFTER（30 秒）の後に、またはマーケットが開いていない間はすぐに cancel できます。EXPIRE_AFTER（120 秒）を過ぎるとリクエストはもう約定せず、誰でもキャンセルできます。すべての返金はトレーダーのバンク残高に入ります。リクエスト ID はエンジンの idBase を共有します。
setTriggers(positionId, tp, sl, limitPrice) は、どのマーケットでも、あなたのポジションにテイクプロフィット、ストップロス、指値決済を設定します。ゼロはそのフィールドをクリアします。ロングでは TP と指値はその価格以上で、SL はその価格以下で発動し、ショートはその逆です。キーパーの executeTrigger は、トリガーが設定されたラウンドより新しいラウンドでのみ約定させ、清算可能なポジションは拒否します。閉場中のマーケットでは、トリガーは再開を待ちます。
liquidate(id) は誰でも呼べます。新しい価格と、維持証拠金を下回るエクイティが必要です。エクイティは証拠金 + 損益 - ファンディング - 決済手数料の全額であり、維持証拠金はポジションの現在価値の 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 秒（フィード自身のハートビートのほうが長ければそちら）以内のものでなければならず、その価格で維持証拠金を下回るポジションは決済されません（"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. |
|---|