Add publishing docs: README update, CONTRIBUTING, CHANGELOG (#2)

koko1123 · web-flow · commit cfcea5ab6de1 · 2026-02-26T10:47:22.000-05:00
Update README with accurate feature list, installation instructions,
environment setup, and links to sibling SDKs. Add CONTRIBUTING.md
with dev commands and code style guide. Add CHANGELOG.md with
initial 0.1.0 release entry.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-25
+
+### Added
+
+- **Contract interaction** -- Read/write calls with comptime-computed ABI selectors via eth.zig (zabi)
+- **Position management** -- `openTakerPosition`, `openMakerPosition`, `closePosition`, `adjustNotional`, `adjustMargin`
+- **HFT nonce manager** -- Lock-free atomic nonce acquisition with `std.atomic.Value(u64)`, zero RPC round-trips per transaction
+- **Gas cache** -- Pre-computed gas limits for all contract operations, configurable TTL with urgency-based multipliers (low/normal/high/critical)
+- **Transaction pipeline** -- Combines nonce manager + gas cache for fire-and-forget transaction submission with gas bump support
+- **Multi-RPC failover** -- Automatic endpoint selection based on health status and latency, 30s cooldown on unhealthy endpoints
+- **Connection management** -- Dual HTTP/WebSocket connection support with multi-RPC failover
+- **State cache** -- Multi-layer caching with configurable TTLs (slow: 60s for fees/bounds, fast: 2s for prices/funding)
+- **Pure math** -- Tick/price conversions, sqrt price math, liquidity calculations, position PnL -- all in pure Zig with no external deps
+- **Event streaming** -- Comptime keccak256 topic hashes, event identification from logs, subscription registry
+- **Position manager** -- Position tracking with stop-loss, take-profit, and trailing stop triggers
+- **Latency observability** -- Rolling window latency tracker with min/max/avg/p50/p95/p99 percentiles
+- **Pre-approved USDC** -- `setupForTrading()` approves max allowance once at startup, eliminating per-trade approval transactions
+- **View functions** -- `getFundingRate`, `getUtilFee`, `getInsurance`, `getOpenInterest` for market data reads
+- **Quote functions** -- ABI definitions for `quoteOpenTakerPosition`, `quoteOpenMakerPosition` simulation
+- Unit tests for all HFT infrastructure modules (150+ tests)
+- Integration test framework with Anvil support
+- CI pipeline with build, test, and format checks
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,95 @@
+# Contributing to PerpCity Zig SDK
+
+## Prerequisites
+
+- [Zig 0.15.2](https://ziglang.org/download/)
+- [Anvil](https://book.getfoundry.sh/anvil/) (for integration tests)
+
+## Getting Started
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/StrobeLabs/perpcity-zig-sdk.git
+   cd perpcity-zig-sdk
+   ```
+
+2. Build the project:
+   ```bash
+   zig build
+   ```
+
+3. Run unit tests:
+   ```bash
+   zig build test
+   ```
+
+## Development Commands
+
+| Command | Description |
+|---------|-------------|
+| `zig build` | Build the SDK |
+| `zig build test` | Run unit tests (pure math, no network) |
+| `zig build integration-test` | Run integration tests (requires Anvil) |
+| `zig fmt --check src/ tests/` | Check formatting |
+| `zig fmt src/ tests/` | Auto-format code |
+
+## Project Structure
+
+```
+src/
+  root.zig              # Full SDK module (with eth.zig dependency)
+  math_root.zig         # Pure math module (no external deps)
+  context.zig           # SDK context with RPC provider and wallet
+  approve.zig           # USDC approval helpers
+  perp_manager.zig      # Core contract interactions
+  open_position.zig     # Position operations
+  types.zig             # Shared type definitions
+  constants.zig         # Protocol constants
+  conversions.zig       # Tick/price conversions
+  liquidity.zig         # Liquidity calculations
+  position.zig          # Position math
+  perp.zig              # Perp math
+  nonce.zig             # Lock-free nonce management
+  gas.zig               # Gas price cache and pre-computed limits
+  tx_pipeline.zig       # Transaction pipeline
+  state_cache.zig       # Multi-layer state cache
+  multi_rpc.zig         # Multi-endpoint failover
+  connection.zig        # Connection management
+  latency.zig           # Latency tracking
+  events.zig            # Event streaming
+  position_manager.zig  # Position tracking with triggers
+  abi/                  # ABI definitions
+tests/
+  unit_tests.zig        # Unit test runner
+  unit/                 # Unit test files
+  integration_tests.zig # Integration test runner
+  integration/          # Integration test files
+```
+
+## Code Style
+
+- Run `zig fmt` before committing. CI enforces formatting.
+- All time-dependent methods accept explicit `now_ms: i64` parameters for deterministic testing. Do not use OS-level clock calls in library code.
+- Use comptime where possible for ABI encoding and type-level computation.
+- Avoid heap allocations on the hot path. Prefer stack-allocated buffers with bounded sizes.
+- Keep the pure math layer (`math_root.zig`) free of external dependencies.
+
+## Pull Request Workflow
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Run CI checks locally:
+   ```bash
+   zig build && zig build test && zig fmt --check src/ tests/
+   ```
+4. Open a pull request against `main`
+5. All CI checks must pass before merge
+
+## Reporting Issues
+
+Open an issue on [GitHub](https://github.com/StrobeLabs/perpcity-zig-sdk/issues) with:
+
+- A description of the issue
+- Steps to reproduce
+- Expected vs actual behavior
+- Zig version (`zig version`)
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-# perpcity-zig-sdk
+# PerpCity Zig SDK
 
-High-performance, low-level Zig SDK for the PerpCity perpetual futures protocol. Built for HFT bots and latency-sensitive trading systems.
+High-performance, low-level Zig SDK for the PerpCity perpetual futures protocol on Base. Built for HFT bots and latency-sensitive trading systems.
 
 ## Why Zig?
 
@@ -11,7 +11,7 @@ This SDK is designed for use cases where nanoseconds matter. Zig gives us:
 - **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, this is not the SDK for you. This is for systems that need sub-millisecond transaction construction and direct EVM interaction with no abstraction tax.
+If you're building a trading bot in Python or TypeScript, use [perpcity-sdk](https://github.com/StrobeLabs/perpcity-sdk) or [perpcity-python-sdk](https://github.com/StrobeLabs/perpcity-python-sdk) instead. This SDK is for systems that need sub-millisecond transaction construction and direct EVM interaction with no abstraction tax.
 
 ## Features
 
@@ -20,15 +20,37 @@ If you're building a trading bot in Python or TypeScript, this is not the SDK fo
 - **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
+- **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
+
+## Installation
+
+Add to your `build.zig.zon`:
+
+```zig
+.dependencies = .{
+    .perpcity_sdk = .{
+        .url = "git+https://github.com/StrobeLabs/perpcity-zig-sdk.git#<commit>",
+    },
+},
+```
+
+Then in `build.zig`:
+
+```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.15.2**.
 
 ## Quick Start
 
 ```zig
-const eth = @import("eth");
 const sdk = @import("perpcity_sdk");
 
 // Initialize context
@@ -41,7 +63,7 @@ var ctx = sdk.context.PerpCityContext.init(
 ctx.fixPointers();
 defer ctx.deinit();
 
-// Ensure USDC approval
+// Approve USDC once at startup (max allowance)
 try ctx.setupForTrading();
 
 // Open a 10x long taker position
@@ -53,35 +75,15 @@ const position = try sdk.perp_manager.openTakerPosition(&ctx, perp_id, .{
 });
 ```
 
-## Installation
-
-Add to your `build.zig.zon`:
-
-```zig
-.dependencies = .{
-    .perpcity_sdk = .{
-        .url = "git+https://github.com/StrobeLabs/perpcity-zig-sdk.git#<commit>",
-    },
-},
-```
-
-Then in `build.zig`:
-
-```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.15.2**.
-
 ## Architecture
 
 ```
 Pure math layer (no dependencies):
   types, constants, conversions, liquidity, position, perp
 
-HFT infrastructure:
-  nonce manager, gas cache, tx pipeline, state cache, multi-rpc
+HFT infrastructure (no dependencies):
+  nonce, gas, tx_pipeline, state_cache, multi_rpc, connection,
+  latency, events, position_manager
 
 Contract interaction (requires eth.zig):
   context, approve, perp_manager, open_position
@@ -90,19 +92,53 @@ ABI definitions:
   perp_manager_abi, erc20_abi, fees_abi, margin_ratios_abi, beacon_abi
 ```
 
-The pure math layer has zero external dependencies and can be used standalone for off-chain calculations (mark price conversions, PnL estimation, liquidation checks).
+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
 
-## Testing
+### Build
 
 ```bash
-# Unit tests (pure math, no network)
+zig build
+```
+
+### Test
+
+```bash
+# Unit tests (pure math + HFT infrastructure, no network)
 zig build test
 
-# Integration tests (requires Anvil)
+# Integration tests (requires Anvil running locally)
 anvil &
 zig build integration-test
 ```
 
+### Lint
+
+```bash
+zig fmt --check src/ tests/
+```
+
+## Environment Setup
+
+Create a `.env.local` file:
+
+```env
+# Required for integration tests
+PRIVATE_KEY=your_private_key_here
+RPC_URL=https://your-rpc-url.com
+
+# Contract addresses (Base Sepolia)
+PERP_MANAGER_ADDRESS=0x...
+USDC_ADDRESS=0x...
+```
+
 ## License
 
 MIT
+
+## Links
+
+- [Perp City Documentation](https://docs.perpcity.io)
+- [Strobe Labs](https://strobelabs.io)
+- [TypeScript SDK](https://github.com/StrobeLabs/perpcity-sdk)
