Crate perpcity_sdk 

PerpCity Rust SDK

A Rust SDK for the PerpCity perpetual futures protocol on Base L2.

Module overview

Module	Purpose
constants	Protocol constants mirrored from on-chain Constants.sol
contracts	ABI bindings via Alloy sol! — structs, events, errors, functions
convert	Conversions between client f64 values and on-chain representations
errors	SDK-wide error types using thiserror
events	Event decoding: raw logs → typed MarketEvent values
feed	Live market event feed over WebSocket
hft	HFT infrastructure: nonce, gas, pipeline, state cache, latency, positions
math	Pure math: tick ↔ price, liquidity estimation, position calculations
transport	Multi-endpoint RPC transport with health-aware routing
types	Client-facing types with human-readable f64 fields

Quick start

use perpcity_sdk::{
    PerpClient, HftTransport, TransportConfig, Urgency,
    Deployments, OpenTakerParams, OpenMakerParams,
    PerpCityError, Result,
};
use alloy::signers::local::PrivateKeySigner;

Modules

IBeacon

Beacon interface — emits IndexUpdated when the oracle index changes. Each perp has its own beacon (from PerpConfig.beacon).

IERC20

Minimal ERC20 interface for USDC interactions.

IFees

Fee module — returns trading fees for a perp.

IMarginRatios

Margin ratio module — returns min/max/liquidation margin ratios.

IMulticall3

Multicall3 interface for batching contract reads.

PerpManager

The PerpManager contract interface. Contains all structs, events, errors, and function signatures from IPerpManager.sol and PerpManager.sol.

client

High-level client for the PerpCity perpetual futures protocol.

constants

Protocol constants from perpcity-contracts/src/libraries/Constants.sol.

contracts

On-chain contract bindings generated via Alloy’s sol! macro.

convert

Conversions between client-facing types (f64, human-readable) and on-chain types (6-decimal integers, U256, sqrtPriceX96).

errors

Error types for the PerpCity SDK.

events

Event decoding for PerpManager and Beacon contracts.

feed

Live market event feed over WebSocket.

hft

High-frequency trading infrastructure.

math

Pure math functions for the PerpCity protocol.

transport

Multi-endpoint RPC transport with health-aware routing.

types

Client-facing types for the PerpCity SDK.

Structs

AdjustMarginParams

Client-facing parameters for adjusting a position’s margin.

AdjustMarginResult

Result of adjusting a position’s margin.

AdjustNotionalParams

Client-facing parameters for adjusting a position’s notional exposure.

AdjustNotionalResult

Result of adjusting a position’s notional size.

Bounds

Leverage and margin constraints for a perpetual market.

CloseParams

Client-facing parameters for closing a position.

CloseResult

Result of closing a position.

Deployments

Deployed contract addresses for a PerpCity instance.

Fees

Fee percentages for a perpetual market, expressed as fractions of 1.

GasLimits

Pre-empirically derived gas limits for PerpCity operations.

HftTransport

Multi-endpoint RPC transport with health-aware routing.

LiveDetails

Real-time position metrics, typically from a quoteClosePosition call.

MarketFeed

A filtered stream of decoded MarketEvents for a single perp.

OpenInterest

Taker open interest for a perp market, in USDC.

OpenMakerParams

Client-facing parameters for opening a maker (LP) position.

OpenMakerQuote

Result of simulating a maker position open via quoteOpenMakerPosition.

OpenResult

Result of opening a position (taker or maker).

OpenTakerParams

Client-facing parameters for opening a taker (long/short) position.

OpenTakerQuote

Result of simulating a taker position open via quoteOpenTakerPosition.

PerpClient

High-level client for the PerpCity protocol.

PerpData

Metadata about a perpetual market.

PerpSnapshot

Live market data from a multicall snapshot.

PoolKey

Identifies a Uniswap V4 pool (and PerpCity perp) by its constituent parameters.

SwapConfig

Swap configuration for quoting through the Uniswap V4 pool.

SwapQuote

Result of a swap simulation via quoteSwap.

TransportConfig

Complete transport configuration.

Enums

MarketEvent

A decoded market event with human-readable f64 values.

PerpCityError

Central error type for the PerpCity SDK.

Urgency

Transaction urgency level, controlling EIP-1559 fee scaling.

Functions

align_tick_down

Round a tick down to the nearest multiple of the protocol tick spacing.

align_tick_up

Round a tick up to the nearest multiple of the protocol tick spacing.

decode_log

Decode a raw Alloy Log into a MarketEvent, if recognized.

get_sqrt_ratio_at_tick

Compute the sqrtPriceX96 for a given tick using the Uniswap V4 bit-shift lookup table.

price_to_tick

Convert a human-readable price to the nearest tick.

tick_to_price

Convert a tick to a human-readable price.

Type Aliases

Result

Convenience alias used throughout the SDK.