Architecture
Eight upgradeable contracts on BNB Chain settle every trade; off-chain services sign prices, batch intents and serve read data.
On-chain contracts#
shadowpaper runs on BNB Chain (BSC). All trading state, including positions, balances, the payout queue, SPAPER minting and staking, is held in eight upgradeable contracts plus one deposit proxy per user.
| Contract | Role |
|---|---|
| Exchange | Positions, balances, settlement, payout queue and fees |
| PriceOracle | Verifies signed index prices for the current batch |
| BatchExecutor | Executes one block's signed trades in a single transaction |
| SessionKeyManager | Session key registration, revocation and nonces |
| PaperTokenomics | Computes the SPAPER minted on each loss |
| PaperToken | The SPAPER token (non-transferable) |
| PaperStaking | SPAPER staking and USDT dividends |
| DepositProxyFactory | Deploys per-user CREATE2 deposit addresses |
Close and liquidation settlement logic is linked as an external library (SettleLib). Contract addresses are listed under Contract addresses.
Governance#
Every contract is owned through a TimelockController with a 24-hour delay. The timelock is controlled by a 2-of-3 Safe multisig. Each proxy has its own ProxyAdmin, owned by the timelock.
A guardian role, held by the same Safe, can pause the protocol immediately. The guardian cannot unpause, upgrade contracts or change parameters; those actions require the timelock.
Off-chain services#
| Service | Role |
|---|---|
| Relayer | Accepts signed intents, applies admission rules and batches them every block |
| Price signer | Signs Binance USDⓈ-M index prices on a separate machine that holds no funds |
| Indexer | Serves the public read API |
| Keepers | Run liquidations, queue payouts, open-interest caps, dividend distribution and deposit sweeps |
Off-chain services cannot move user funds. Every action they submit is re-checked by the contracts, and liquidation, queue payout and deposit sweep are public functions that anyone can call.
Transaction flow#
The following steps trace one trade, for example a 100× BTC long with 100 USDT margin, from signature to settlement.
The signed price and every trade it settles are included in the same transaction, so no trade can settle at a price that was not verified on-chain.