perps-sdk-ts 1.0.1

package/src/abis.ts

@@ -0,0 +1,56 @@
+/**
+ * Contract ABIs for Avantis Protocol
+ *
+ * These ABIs contain the function signatures needed to interact with
+ * the Avantis smart contracts.
+ */
+
+/**
+ * ERC20 ABI (for USDC)
+ */
+
+import refferal from "./abis/Referral";
+import trading from "./abis/Trading"
+import erc20 from "./abis/erc20"
+import pairStorage from "./abis/pairStorage"
+import tradingStorage from "./abis/tardingStorage"
+import pairinfos from "./abis/pairInfos"
+import priceAggregator from "./abis/priceAggregator"
+import referral from "./abis/Referral"
+import multicall from "./abis/multicall"
+
+export const ERC20_ABI = erc20;
+
+/**
+ * Trading Contract ABI
+ */
+export const TRADING_ABI = trading;
+
+/**
+ * TradingStorage Contract ABI
+ */
+export const TRADING_STORAGE_ABI = tradingStorage;
+
+/**
+ * PairStorage Contract ABI
+ */
+export const PAIR_STORAGE_ABI = pairStorage;
+
+/**
+ * PairInfos Contract ABI
+ */
+export const PAIR_INFOS_ABI = pairinfos;
+
+/**
+ * PriceAggregator Contract ABI
+ */
+export const PRICE_AGGREGATOR_ABI = priceAggregator;
+/**
+ * Referral Contract ABI
+ */
+export const REFERRAL_ABI = referral;
+
+/**
+ * Multicall Contract ABI
+ */
+export const MULTICALL_ABI = multicall;

package/src/client.ts

@@ -0,0 +1,373 @@
+import { ethers, JsonRpcProvider, Contract, TransactionReceipt, TransactionRequest } from 'ethers';
+import { BaseSigner } from './signers/base';
+import { LocalSigner } from './signers/local';
+import { KMSSigner } from './signers/kms';
+import { FeedClient } from './feed/feed_client';
+import { CONTRACTS, getContractAddress } from './config';
+import { PairsCache } from './rpc/pairs_cache';
+import { AssetParametersRPC } from './rpc/asset_parameters';
+import { CategoryParametersRPC } from './rpc/category_parameters';
+import { FeeParametersRPC } from './rpc/fee_parameters';
+import { TradingParametersRPC } from './rpc/trading_parameters';
+import { BlendedRPC } from './rpc/blended';
+import { TradeRPC } from './rpc/trade';
+import { SnapshotRPC } from './rpc/snapshot';
+import { TradingOperationsRPC } from './rpc/trading_operations';
+import { DelegationRPC } from './rpc/delegation';
+import { PairInfoQueriesRPC } from './rpc/pair_info_queries';
+import { ReferralOperationsRPC } from './rpc/referral_operations';
+import { MulticallRPC } from './rpc/multicall';
+import { fromBlockchain6 } from './types';
+import {
+  ERC20_ABI,
+  TRADING_ABI,
+  TRADING_STORAGE_ABI,
+  PAIR_STORAGE_ABI,
+  PAIR_INFOS_ABI,
+  PRICE_AGGREGATOR_ABI,
+  REFERRAL_ABI,
+  MULTICALL_ABI,
+} from './abis';
+
+/**
+ * Main client for interacting with Avantis trading platform
+ */
+export class TraderClient {
+  public provider: JsonRpcProvider;
+ signer?: BaseSigner;
+  public feedClient?: FeedClient;
+
+
+  // Contracts
+  private contracts: Map<string, Contract> = new Map();
+
+  // RPC modules
+  public pairsCache: PairsCache;
+  public assetParams: AssetParametersRPC;
+  public categoryParams: CategoryParametersRPC;
+  public feeParams: FeeParametersRPC;
+  public tradingParams: TradingParametersRPC;
+  public blendedParams: BlendedRPC;
+  public tradeRPC: TradeRPC;
+  public snapshotRPC: SnapshotRPC;
+
+  // New trading modules
+  public tradingOps: TradingOperationsRPC;
+  public delegation: DelegationRPC;
+  public pairInfoQueries: PairInfoQueriesRPC;
+  public referral: ReferralOperationsRPC;
+  public multicall: MulticallRPC;
+
+  /**
+   * Create a new TraderClient
+   * @param providerUrl - Ethereum RPC endpoint
+   * @param signer - Transaction signer (optional)
+   * @param feedClient - Feed client for price updates (optional)
+   */
+  constructor(
+    providerUrl: string,
+    signer?: BaseSigner,
+    feedClient?: FeedClient
+  ) {
+    this.provider = new JsonRpcProvider(providerUrl);
+    this.signer = signer;
+    this.feedClient = feedClient;
+
+
+    // Initialize RPC modules
+    this.initializeContracts();
+    this.pairsCache = new PairsCache(
+      this.provider,
+      this.getContract('PairStorage')
+    );
+
+    const pairStorage = this.getContract('PairStorage');
+    const pairInfos = this.getContract('PairInfos');
+    const trading = this.getContract('Trading');
+    const tradingStorage = this.getContract('TradingStorage');
+    const referral = this.getContract('Referral');
+
+    this.assetParams = new AssetParametersRPC(
+      this.provider,
+      pairStorage,
+      pairInfos,
+      this.pairsCache,
+      tradingStorage
+    );
+
+    this.categoryParams = new CategoryParametersRPC(
+      this.provider,
+      pairStorage,
+      this.pairsCache
+    );
+
+    this.feeParams = new FeeParametersRPC(
+      this.provider,
+      pairInfos,
+      this.pairsCache,
+      referral
+    );
+
+    this.tradingParams = new TradingParametersRPC(
+      this.provider,
+      pairInfos,
+      this.pairsCache
+    );
+
+    this.blendedParams = new BlendedRPC(
+      this.assetParams,
+      this.categoryParams,
+      this.pairsCache
+    );
+
+    this.tradeRPC = new TradeRPC(
+      this.provider,
+      trading,
+      tradingStorage,
+      this.pairsCache
+    );
+
+    this.snapshotRPC = new SnapshotRPC(
+      this.pairsCache,
+      this.assetParams,
+      this.categoryParams,
+      this.feeParams,
+      this.blendedParams
+    );
+
+    // Initialize new trading modules
+    this.tradingOps = new TradingOperationsRPC(
+      trading,
+      tradingStorage,
+      this.signer
+    );
+
+    this.delegation = new DelegationRPC(
+      trading,
+      this.signer
+    );
+
+    this.pairInfoQueries = new PairInfoQueriesRPC(
+      pairInfos,
+      this.getContract('PriceAggregator')
+    );
+
+    this.referral = new ReferralOperationsRPC(
+      referral,
+      this.signer
+    );
+
+    this.multicall = new MulticallRPC(
+      this.getContract('Multicall')
+    );
+  }
+
+  /**
+   * Initialize contract instances
+   */
+  private initializeContracts(): void {
+    this.contracts.set(
+      'TradingStorage',
+      new Contract(CONTRACTS.TradingStorage, TRADING_STORAGE_ABI, this.provider)
+    );
+    this.contracts.set(
+      'PairStorage',
+      new Contract(CONTRACTS.PairStorage, PAIR_STORAGE_ABI, this.provider)
+    );
+    this.contracts.set(
+      'PairInfos',
+      new Contract(CONTRACTS.PairInfos, PAIR_INFOS_ABI, this.provider)
+    );
+    this.contracts.set(
+      'PriceAggregator',
+      new Contract(CONTRACTS.PriceAggregator, PRICE_AGGREGATOR_ABI, this.provider)
+    );
+    this.contracts.set(
+      'USDC',
+      new Contract(CONTRACTS.USDC, ERC20_ABI, this.provider)
+    );
+    this.contracts.set(
+      'Trading',
+      new Contract(CONTRACTS.Trading, TRADING_ABI, this.provider)
+    );
+    this.contracts.set(
+      'Referral',
+      new Contract(CONTRACTS.Referral, REFERRAL_ABI, this.provider)
+    );
+    this.contracts.set(
+      'Multicall',
+      new Contract(CONTRACTS.Multicall, MULTICALL_ABI, this.provider)
+    );
+  }
+
+  /**
+   * Get a contract instance
+   * @param name - Contract name
+   * @returns Contract instance
+   */
+  private getContract(name: string): Contract {
+    const contract = this.contracts.get(name);
+    if (!contract) {
+      throw new Error(`Contract ${name} not initialized`);
+    }
+    return contract;
+  }
+
+  /**
+   * Set signer for transaction signing
+   * @param signer - Signer instance
+   */
+  setSigner(signer: BaseSigner): void {
+    this.signer = signer;
+    this.tradingOps.setSigner(signer);
+    this.delegation.setSigner(signer);
+    this.referral.setSigner(signer);
+  }
+
+  /**
+   * Set local signer using private key
+   * @param privateKey - Private key
+   */
+  setLocalSigner(privateKey: string): void {
+    this.signer = new LocalSigner(privateKey, this.provider);
+    this.setSigner(this.signer);
+  }
+
+  /**
+   * Set AWS KMS signer
+   * @param kmsKeyId - KMS key ID
+   * @param region - AWS region
+   */
+  setAwsKmsSigner(kmsKeyId: string, region: string = 'us-east-1'): void {
+    this.signer = new KMSSigner(kmsKeyId, this.provider, region);
+    this.setSigner(this.signer);
+  }
+
+  /**
+   * Get native token balance
+   * @param address - Address to check
+   * @returns Balance in native token
+   */
+  async getBalance(address: string): Promise<bigint> {
+    return await this.provider.getBalance(address);
+  }
+
+  /**
+   * Get USDC balance
+   * @param address - Address to check
+   * @returns USDC balance
+   */
+  async getUsdcBalance(address: string): Promise<number> {
+    const balance = await this.getContract('USDC').balanceOf(address);
+    return fromBlockchain6(balance);
+  }
+
+  /**
+   * Get USDC allowance for trading
+   * @param address - Address to check
+   * @returns Allowance amount
+   */
+  async getUsdcAllowanceForTrading(address: string): Promise<number> {
+    const tradingStorageAddress = await this.getContract('TradingStorage').getAddress();
+    const allowance = await this.getContract('USDC').allowance(address, tradingStorageAddress);
+    return fromBlockchain6(allowance);
+  }
+
+  /**
+   * Approve USDC for trading
+   * @param amount - Amount to approve
+   * @returns Transaction receipt
+   */
+  async approveUsdcForTrading(amount: number): Promise<TransactionReceipt | null> {
+    if (!this.signer) {
+      throw new Error('Signer not set');
+    }
+
+    const tradingStorageAddress = await this.getContract('TradingStorage').getAddress();
+    const amountWei = BigInt(Math.floor(amount * 1e6));
+
+    const tx: TransactionRequest = {
+      to: CONTRACTS.USDC,
+      data: this.getContract('USDC').interface.encodeFunctionData('approve', [
+        tradingStorageAddress,
+        amountWei,
+      ]),
+    };
+
+    return await this.signAndGetReceipt(tx);
+  }
+
+  /**
+   * Sign transaction and wait for receipt
+   * @param tx - Transaction to sign
+   * @returns Transaction receipt
+   */
+  async signAndGetReceipt(tx: TransactionRequest): Promise<TransactionReceipt | null> {
+    if (!this.signer) {
+      throw new Error('Signer not set');
+    }
+
+    // Fill in missing transaction fields
+    const address = await this.signer.getAddress();
+    tx.from = address;
+
+    if (!tx.chainId) {
+      const network = await this.provider.getNetwork();
+      tx.chainId = network.chainId;
+    }
+
+    if (tx.nonce === undefined) {
+      tx.nonce = await this.provider.getTransactionCount(address);
+    }
+
+    if (!tx.gasLimit) {
+      tx.gasLimit = await this.provider.estimateGas(tx);
+    }
+
+    if (!tx.maxFeePerGas && !tx.gasPrice) {
+      const feeData = await this.provider.getFeeData();
+      if (feeData.maxFeePerGas) {
+        tx.maxFeePerGas = feeData.maxFeePerGas;
+        tx.maxPriorityFeePerGas = feeData.maxPriorityFeePerGas || feeData.maxFeePerGas;
+      } else {
+        tx.gasPrice = feeData.gasPrice || undefined;
+      }
+    }
+
+    // Sign the transaction
+    const signedTx = await this.signer.signTransaction(tx);
+
+    // Send the transaction
+    const txResponse = await this.provider.broadcastTransaction(signedTx);
+
+    // Wait for confirmation
+    return await txResponse.wait();
+  }
+
+  /**
+   * Estimate gas for a transaction
+   * @param tx - Transaction to estimate
+   * @returns Estimated gas
+   */
+  async estimateGas(tx: TransactionRequest): Promise<bigint> {
+    return await this.provider.estimateGas(tx);
+  }
+
+  /**
+   * Get transaction count (nonce)
+   * @param address - Address to check
+   * @returns Transaction count
+   */
+  async getTransactionCount(address: string): Promise<number> {
+    return await this.provider.getTransactionCount(address);
+  }
+
+  /**
+   * Get chain ID
+   * @returns Chain ID
+   */
+  async getChainId(): Promise<bigint> {
+    const network = await this.provider.getNetwork();
+    return network.chainId;
+  }
+}

package/src/config.ts

@@ -0,0 +1,62 @@
+/**
+ * Configuration file containing contract addresses and API endpoints
+ * for Avantis trading platform
+ */
+
+export interface ContractAddresses {
+  TradingStorage: string;
+  PairStorage: string;
+  PairInfos: string;
+  PriceAggregator: string;
+  USDC: string;
+  Trading: string;
+  Multicall: string;
+  Referral: string;
+}
+
+/**
+ * Mainnet contract addresses for Avantis (Base Network)
+ */
+export const CONTRACTS: ContractAddresses = {
+  TradingStorage: '0x8a311D7048c35985aa31C131B9A13e03a5f7422d',
+  PairStorage: '0x5db3772136e5557EFE028Db05EE95C84D76faEC4',
+  PairInfos: '0x81F22d0Cc22977c91bEfE648C9fddf1f2bd977e5',
+  PriceAggregator: '0x64e2625621970F8cfA17B294670d61CB883dA511',
+  USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  Trading: '0x44914408af82bC9983bbb330e3578E1105e11d4e',
+  Multicall: '0xb7125506Ff25211c4C51DFD8DdED00BE6Fa8Cbf7',
+  Referral: '0x1A110bBA13A1f16cCa4b79758BD39290f29De82D',
+};
+
+/**
+ * API endpoints for Avantis services
+ */
+export const API_ENDPOINTS = {
+  SOCKET_API: 'https://socket-api-pub.avantisfi.com/socket-api/v1/data',
+  PYTH_WS: 'wss://hermes.pyth.network/ws',
+  PYTH_HTTP: 'https://hermes.pyth.network/v2/updates/price/latest',
+};
+
+/**
+ * Network configuration
+ */
+export interface NetworkConfig {
+  chainId: number;
+  name: string;
+  rpcUrl: string;
+  contracts: ContractAddresses;
+}
+
+/**
+ * Get contract address by name
+ */
+export function getContractAddress(contractName: keyof ContractAddresses): string {
+  return CONTRACTS[contractName];
+}
+
+/**
+ * Update contract addresses (useful for testing or different networks)
+ */
+export function setContractAddresses(addresses: Partial<ContractAddresses>): void {
+  Object.assign(CONTRACTS, addresses);
+}

package/src/crypto/spki.ts

@@ -0,0 +1,197 @@
+import { keccak256, getBytes, concat, SigningKey } from 'ethers';
+
+/**
+ * Cryptographic utilities for KMS signature handling
+ * Handles ECDSA signature conversion and Ethereum address derivation
+ */
+
+/**
+ * Convert a public key (as big integer coordinates) to an Ethereum address
+ * @param publicKeyX - X coordinate of public key
+ * @param publicKeyY - Y coordinate of public key
+ * @returns Ethereum address
+ */
+export function publicKeyIntToEthAddress(publicKeyX: bigint, publicKeyY: bigint): string {
+  // Concatenate 0x04 (uncompressed key prefix) + x + y
+  const xBytes = publicKeyX.toString(16).padStart(64, '0');
+  const yBytes = publicKeyY.toString(16).padStart(64, '0');
+  const publicKeyHex = '0x04' + xBytes + yBytes;
+
+  // Keccak256 hash
+  const hash = keccak256(publicKeyHex);
+
+  // Take last 20 bytes as address
+  return '0x' + hash.slice(-40);
+}
+
+/**
+ * Parse DER-encoded public key and convert to Ethereum address
+ * @param derPublicKey - DER-encoded public key bytes
+ * @returns Ethereum address
+ */
+export function derEncodedPublicKeyToEthAddress(derPublicKey: Uint8Array): string {
+  // Parse the DER structure to extract the public key
+  // DER structure for ECDSA public key (simplified parsing)
+
+  // Find the public key bytes (starts with 0x04 for uncompressed key)
+  let publicKeyStart = -1;
+  for (let i = 0; i < derPublicKey.length - 64; i++) {
+    if (derPublicKey[i] === 0x04) {
+      publicKeyStart = i;
+      break;
+    }
+  }
+
+  if (publicKeyStart === -1) {
+    throw new Error('Could not find uncompressed public key in DER structure');
+  }
+
+  // Extract 65 bytes: 0x04 + 32 bytes X + 32 bytes Y
+  const publicKeyBytes = derPublicKey.slice(publicKeyStart, publicKeyStart + 65);
+
+  // Convert to hex
+  const publicKeyHex = '0x' + Buffer.from(publicKeyBytes).toString('hex');
+
+  // Keccak256 hash (skip the 0x04 prefix)
+  const hash = keccak256(publicKeyHex);
+
+  // Take last 20 bytes as address
+  return '0x' + hash.slice(-40);
+}
+
+/**
+ * Parse DER-encoded signature to extract r and s values
+ * @param derSignature - DER-encoded signature
+ * @returns Object with r and s as hex strings
+ */
+export function getSigRS(derSignature: Uint8Array): { r: string; s: string } {
+  // DER signature structure:
+  // 0x30 [total-length] 0x02 [r-length] [r-bytes] 0x02 [s-length] [s-bytes]
+
+  let offset = 0;
+
+  // Check sequence tag
+  if (derSignature[offset++] !== 0x30) {
+    throw new Error('Invalid DER signature: missing sequence tag');
+  }
+
+  // Skip total length
+  offset++;
+
+  // Read r
+  if (derSignature[offset++] !== 0x02) {
+    throw new Error('Invalid DER signature: missing r integer tag');
+  }
+
+  const rLength = derSignature[offset++];
+  let rBytes = derSignature.slice(offset, offset + rLength);
+  offset += rLength;
+
+  // Remove leading zero if present (DER encoding adds it for positive numbers)
+  if (rBytes[0] === 0x00) {
+    rBytes = rBytes.slice(1);
+  }
+
+  const r = '0x' + Buffer.from(rBytes).toString('hex');
+
+  // Read s
+  if (derSignature[offset++] !== 0x02) {
+    throw new Error('Invalid DER signature: missing s integer tag');
+  }
+
+  const sLength = derSignature[offset++];
+  let sBytes = derSignature.slice(offset, offset + sLength);
+
+  // Remove leading zero if present
+  if (sBytes[0] === 0x00) {
+    sBytes = sBytes.slice(1);
+  }
+
+  const s = '0x' + Buffer.from(sBytes).toString('hex');
+
+  return { r, s };
+}
+
+/**
+ * Recover the v value for an ECDSA signature
+ * @param msgHash - Message hash that was signed
+ * @param r - r component of signature
+ * @param s - s component of signature
+ * @param expectedAddress - Expected Ethereum address
+ * @returns v value (27 or 28)
+ */
+export function getSigV(
+  msgHash: string,
+  r: string,
+  s: string,
+  expectedAddress: string
+): number {
+  // Try both possible v values (27 and 28)
+  for (const v of [27, 28]) {
+    try {
+      const signature = {
+        r,
+        s,
+        v,
+      };
+
+      // Construct the signature string
+      const sigString = concat([
+        signature.r,
+        signature.s,
+        new Uint8Array([signature.v]),
+      ]);
+
+      // Try to recover the address
+      const recoveredAddress = SigningKey.recoverPublicKey(
+        getBytes(msgHash),
+        sigString
+      );
+
+      const recoveredAddr = keccak256('0x' + recoveredAddress.slice(4));
+      const addr = '0x' + recoveredAddr.slice(-40);
+
+      if (addr.toLowerCase() === expectedAddress.toLowerCase()) {
+        return v;
+      }
+    } catch (e) {
+      // Continue to next v value
+      continue;
+    }
+  }
+
+  throw new Error('Could not recover v value from signature');
+}
+
+/**
+ * Get complete signature (r, s, v) from DER-encoded KMS signature
+ * @param kmsSignature - DER-encoded signature from KMS
+ * @param msgHash - Message hash that was signed
+ * @param ethAddress - Expected Ethereum address
+ * @returns Complete signature object
+ */
+export function getSigRSV(
+  kmsSignature: Uint8Array,
+  msgHash: string,
+  ethAddress: string
+): { r: string; s: string; v: number } {
+  const { r, s } = getSigRS(kmsSignature);
+  const v = getSigV(msgHash, r, s, ethAddress);
+
+  return { r, s, v };
+}
+
+/**
+ * Convert signature components to a single hex string
+ * @param r - r component
+ * @param s - s component
+ * @param v - v component
+ * @returns Signature as hex string
+ */
+export function signatureToHex(r: string, s: string, v: number): string {
+  const rHex = r.startsWith('0x') ? r.slice(2) : r;
+  const sHex = s.startsWith('0x') ? s.slice(2) : s;
+  const vHex = v.toString(16).padStart(2, '0');
+
+  return '0x' + rHex.padStart(64, '0') + sHex.padStart(64, '0') + vHex;
+}