Skip to content

About

High-performance Zig SDK for PerpCity perpetual futures protocol. Built for HFT bots and latency-sensitive trading systems on Base.

Topics

Resources

Contributing

Stars

4 stars

Watchers

1 watching

Forks

Repository files navigation

PerpCity Zig SDK

High-performance, low-level Zig SDK for the PerpCity perpetual futures protocol on Arbitrum. Built for HFT bots and latency-sensitive trading systems.

Why Zig?

This SDK is designed for use cases where nanoseconds matter. Zig gives us:

  • Zero runtime overhead -- no GC, no hidden allocations, no async coloring
  • Deterministic memory layout -- cache-friendly structs with predictable performance
  • Comptime ABI encoding -- function selectors computed at compile time, zero runtime cost
  • Direct hardware control -- atomic nonce management, lock-free data structures

If you're building a trading bot in Python or TypeScript, use perpcity-sdk or perpcity-python-sdk instead. This SDK is for systems that need sub-millisecond transaction construction and direct EVM interaction with no abstraction tax.

Features

  • Contract interaction -- Read/write calls with comptime-computed selectors via eth.zig
  • Position management -- Open/close taker and maker positions, adjust margin and notional
  • HFT nonce manager -- Lock-free atomic nonce acquisition, no RPC round-trip per transaction
  • Gas cache -- Pre-computed gas limits and fee caching to skip estimateGas calls
  • Transaction pipeline -- Combines nonce manager + gas cache for fire-and-forget submission
  • Multi-RPC failover -- Automatic failover across multiple RPC endpoints with latency tracking
  • State cache -- Multi-layer caching (mark prices, perp configs) with configurable TTLs
  • Pure math -- Tick/price conversions, sqrt price math, liquidity calculations -- all in pure Zig with no external deps
  • Event streaming -- Subscription registry for on-chain event processing
  • Position manager -- Stop-loss, take-profit, and trailing stop triggers
  • Latency observability -- Rolling window latency tracking with p50/p95/p99 percentiles
  • Runnable examples -- Self-contained programs in examples/, compiled in CI so they can't rot

Installation

Add to your build.zig.zon:

.dependencies = .{
    .perpcity_sdk = .{
        .url = "git+https://github.com/StrobeLabs/perpcity-zig-sdk.git#<commit>",
    },
},

Then in build.zig:

const sdk_dep = b.dependency("perpcity_sdk", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("perpcity_sdk", sdk_dep.module("perpcity_sdk"));

Requires Zig 0.17.0.

Quick Start

const sdk = @import("perpcity_sdk");

// Build a context -- it owns the RPC transport and wallet on the heap, so the
// value is safe to move around (no pointer fixups needed).
var ctx = try sdk.context.PerpCityContext.init(
    allocator,
    "https://arb1.arbitrum.io/rpc",
    private_key, // [32]u8
    deployments, // sdk.types.PerpCityDeployments
);
defer ctx.deinit();

// Approve USDC once for this market (max allowance).
try ctx.setupForTrading(perp);

// Size a 10x long from margin + price, then open the taker position.
const perp_delta = try sdk.sizing.derivePerpDelta(1000.0, 10.0, mark_price, true);
const position = try sdk.perp_contract.openTaker(&ctx, perp, .{
    .margin = 1000.0,
    .perp_delta = perp_delta, // signed: positive = long, negative = short
    .amt1_limit = 0, // USD-side slippage limit
});

Architecture

Pure math layer (no dependencies):
  types, constants, conversions, sizing, funding, liquidity, position, perp

HFT infrastructure (no dependencies):
  nonce, gas, tx_pipeline, state_cache, multi_rpc, connection,
  latency, events, position_manager

Contract interaction (requires eth.zig):
  chain_client (ChainClient seam + EthChainClient), context,
  perp_contract, perp_factory, approve

ABI definitions:
  perp_abi, perp_factory_abi, module_registry_abi, protocol_fee_manager_abi,
  fees_abi, margin_ratios_abi, funding_abi, pricing_abi, price_impact_abi,
  beacon_abi, erc20_abi

The pure math and HFT infrastructure layers have zero external dependencies and can be used standalone for off-chain calculations (mark price conversions, PnL estimation, liquidation checks) and trading infrastructure (nonce management, gas caching, latency tracking).

Development

Build

zig build

Test

# Unit tests (pure math + HFT infrastructure, no network)
zig build test

# Integration tests (requires Anvil running locally)
anvil &
zig build integration-test

Lint

zig fmt --check src/ tests/ examples/

Examples

Runnable examples live in examples/. CI compiles them with zig build examples, so breaking changes are caught.

view_market.zig -- A read-only market snapshot. It prints the mark price, index, funding rate, tick spacing, and fees for a single market.

It reads two environment variables:

  • RPC_URL -- an Arbitrum RPC endpoint
  • PERP_ADDRESS -- the market contract address

Run it with the following example commands for a sepolia market:

export RPC_URL=https://sepolia-rollup.arbitrum.io/rpc
export PERP_ADDRESS=0xf5b11be0f707741196fcdc3ad5ecc43eee619e15
zig build run-example-view

Finding a market address. Go to the perp factory: https://sepolia.arbiscan.io/address/0xa54F81e7BD5C0d52d6fdE2ba40d0B1123d53E7a7#events. Find a PerpCreated event, and click "ABI". Then copy the perp address.

To compile every example without running one:

zig build examples

Environment Setup

Create a .env.local file:

# Required for integration tests
PRIVATE_KEY=your_private_key_here
RPC_URL=https://your-rpc-url.com

# Contract addresses (Arbitrum Sepolia)
PERP_ADDRESS=0x...
USDC_ADDRESS=0x...

License

MIT

Links

About

High-performance Zig SDK for PerpCity perpetual futures protocol. Built for HFT bots and latency-sensitive trading systems on Base.

Topics

Resources

Contributing

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages