@deriverse/client-state

TypeScript client-state utilities for Deriverse trading workflows on Solana.

This package is designed to work alongside @deriverse/kit and @solana/kit. It maintains in-memory client token and instrument state while processing Deriverse engine/log events.

Requirements

• Node.js 20 or newer.
• CommonJS runtime.
• Runtime dependencies on @deriverse/kit and @solana/kit.

Installation

npm install @deriverse/client-state

What This Package Provides

• createClientState(...) for initializing token and instrument state from a Deriverse Engine, Solana rpc, and selected instrIds.
• State models for token balances, spot/perp order maps, PnL, fees/rebates, pending spot tokens, perp leverage, funding, loss coverage, lookup table data, sequence numbers, and per-instrument update slots.
• Utility functions for in-order exposure, collateral value, withdrawable funds, effective leverage, liquidation price, good-health price, and health calculations.
• ClientState.update(engine, slot, logsNotifications) for applying Deriverse engine/log events and invoking optional callbacks, including slot-aware deposit and withdraw handlers.

Minimal Usage

import { createClientState } from "@deriverse/client-state";

const state = await createClientState({
  engine,
  rpc,
  instrIds: [1, 2],
  onError: async (report, error) => {
    console.error(error, report);
  },
  onDeposit: (report, previousWithdraw, slot) => {
    console.log("deposit", report, slot);
  },
  onWithdraw: (report, previousDeposit, slot) => {
    console.log("withdraw", report, slot);
  }
});

if (!state) {
  throw new Error("Unable to initialize client state");
}

// Later, when a log notification arrives:
state.update(engine, slot, logsNotification);

createClientState(...) returns null when required engine state cannot be initialized, including missing instruments, existing spot state, or existing open perp orders for the requested instruments.

Solana Program IDs And Versions

Build

npm run build

Publish

npm run build
npm pack --dry-run
npm publish

The prepack script runs npm run build automatically, but check the generated dist files before publishing.

License

Apache-2.0. See LICENSE.