perps-sdk-ts 1.0.1

package/dist/client.d.ts

@@ -0,0 +1,118 @@
+import { JsonRpcProvider, TransactionReceipt, TransactionRequest } from 'ethers';
+import { BaseSigner } from './signers/base';
+import { FeedClient } from './feed/feed_client';
+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';
+/**
+ * Main client for interacting with Avantis trading platform
+ */
+export declare class TraderClient {
+    provider: JsonRpcProvider;
+    signer?: BaseSigner;
+    feedClient?: FeedClient;
+    private contracts;
+    pairsCache: PairsCache;
+    assetParams: AssetParametersRPC;
+    categoryParams: CategoryParametersRPC;
+    feeParams: FeeParametersRPC;
+    tradingParams: TradingParametersRPC;
+    blendedParams: BlendedRPC;
+    tradeRPC: TradeRPC;
+    snapshotRPC: SnapshotRPC;
+    tradingOps: TradingOperationsRPC;
+    delegation: DelegationRPC;
+    pairInfoQueries: PairInfoQueriesRPC;
+    referral: ReferralOperationsRPC;
+    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);
+    /**
+     * Initialize contract instances
+     */
+    private initializeContracts;
+    /**
+     * Get a contract instance
+     * @param name - Contract name
+     * @returns Contract instance
+     */
+    private getContract;
+    /**
+     * Set signer for transaction signing
+     * @param signer - Signer instance
+     */
+    setSigner(signer: BaseSigner): void;
+    /**
+     * Set local signer using private key
+     * @param privateKey - Private key
+     */
+    setLocalSigner(privateKey: string): void;
+    /**
+     * Set AWS KMS signer
+     * @param kmsKeyId - KMS key ID
+     * @param region - AWS region
+     */
+    setAwsKmsSigner(kmsKeyId: string, region?: string): void;
+    /**
+     * Get native token balance
+     * @param address - Address to check
+     * @returns Balance in native token
+     */
+    getBalance(address: string): Promise<bigint>;
+    /**
+     * Get USDC balance
+     * @param address - Address to check
+     * @returns USDC balance
+     */
+    getUsdcBalance(address: string): Promise<number>;
+    /**
+     * Get USDC allowance for trading
+     * @param address - Address to check
+     * @returns Allowance amount
+     */
+    getUsdcAllowanceForTrading(address: string): Promise<number>;
+    /**
+     * Approve USDC for trading
+     * @param amount - Amount to approve
+     * @returns Transaction receipt
+     */
+    approveUsdcForTrading(amount: number): Promise<TransactionReceipt | null>;
+    /**
+     * Sign transaction and wait for receipt
+     * @param tx - Transaction to sign
+     * @returns Transaction receipt
+     */
+    signAndGetReceipt(tx: TransactionRequest): Promise<TransactionReceipt | null>;
+    /**
+     * Estimate gas for a transaction
+     * @param tx - Transaction to estimate
+     * @returns Estimated gas
+     */
+    estimateGas(tx: TransactionRequest): Promise<bigint>;
+    /**
+     * Get transaction count (nonce)
+     * @param address - Address to check
+     * @returns Transaction count
+     */
+    getTransactionCount(address: string): Promise<number>;
+    /**
+     * Get chain ID
+     * @returns Chain ID
+     */
+    getChainId(): Promise<bigint>;
+}

package/dist/client.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraderClient = void 0;
+const ethers_1 = require("ethers");
+const local_1 = require("./signers/local");
+const kms_1 = require("./signers/kms");
+const config_1 = require("./config");
+const pairs_cache_1 = require("./rpc/pairs_cache");
+const asset_parameters_1 = require("./rpc/asset_parameters");
+const category_parameters_1 = require("./rpc/category_parameters");
+const fee_parameters_1 = require("./rpc/fee_parameters");
+const trading_parameters_1 = require("./rpc/trading_parameters");
+const blended_1 = require("./rpc/blended");
+const trade_1 = require("./rpc/trade");
+const snapshot_1 = require("./rpc/snapshot");
+const trading_operations_1 = require("./rpc/trading_operations");
+const delegation_1 = require("./rpc/delegation");
+const pair_info_queries_1 = require("./rpc/pair_info_queries");
+const referral_operations_1 = require("./rpc/referral_operations");
+const multicall_1 = require("./rpc/multicall");
+const types_1 = require("./types");
+const abis_1 = require("./abis");
+/**
+ * Main client for interacting with Avantis trading platform
+ */
+class TraderClient {
+    /**
+     * Create a new TraderClient
+     * @param providerUrl - Ethereum RPC endpoint
+     * @param signer - Transaction signer (optional)
+     * @param feedClient - Feed client for price updates (optional)
+     */
+    constructor(providerUrl, signer, feedClient) {
+        // Contracts
+        this.contracts = new Map();
+        this.provider = new ethers_1.JsonRpcProvider(providerUrl);
+        this.signer = signer;
+        this.feedClient = feedClient;
+        // Initialize RPC modules
+        this.initializeContracts();
+        this.pairsCache = new pairs_cache_1.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 asset_parameters_1.AssetParametersRPC(this.provider, pairStorage, pairInfos, this.pairsCache, tradingStorage);
+        this.categoryParams = new category_parameters_1.CategoryParametersRPC(this.provider, pairStorage, this.pairsCache);
+        this.feeParams = new fee_parameters_1.FeeParametersRPC(this.provider, pairInfos, this.pairsCache, referral);
+        this.tradingParams = new trading_parameters_1.TradingParametersRPC(this.provider, pairInfos, this.pairsCache);
+        this.blendedParams = new blended_1.BlendedRPC(this.assetParams, this.categoryParams, this.pairsCache);
+        this.tradeRPC = new trade_1.TradeRPC(this.provider, trading, tradingStorage, this.pairsCache);
+        this.snapshotRPC = new snapshot_1.SnapshotRPC(this.pairsCache, this.assetParams, this.categoryParams, this.feeParams, this.blendedParams);
+        // Initialize new trading modules
+        this.tradingOps = new trading_operations_1.TradingOperationsRPC(trading, tradingStorage, this.signer);
+        this.delegation = new delegation_1.DelegationRPC(trading, this.signer);
+        this.pairInfoQueries = new pair_info_queries_1.PairInfoQueriesRPC(pairInfos, this.getContract('PriceAggregator'));
+        this.referral = new referral_operations_1.ReferralOperationsRPC(referral, this.signer);
+        this.multicall = new multicall_1.MulticallRPC(this.getContract('Multicall'));
+    }
+    /**
+     * Initialize contract instances
+     */
+    initializeContracts() {
+        this.contracts.set('TradingStorage', new ethers_1.Contract(config_1.CONTRACTS.TradingStorage, abis_1.TRADING_STORAGE_ABI, this.provider));
+        this.contracts.set('PairStorage', new ethers_1.Contract(config_1.CONTRACTS.PairStorage, abis_1.PAIR_STORAGE_ABI, this.provider));
+        this.contracts.set('PairInfos', new ethers_1.Contract(config_1.CONTRACTS.PairInfos, abis_1.PAIR_INFOS_ABI, this.provider));
+        this.contracts.set('PriceAggregator', new ethers_1.Contract(config_1.CONTRACTS.PriceAggregator, abis_1.PRICE_AGGREGATOR_ABI, this.provider));
+        this.contracts.set('USDC', new ethers_1.Contract(config_1.CONTRACTS.USDC, abis_1.ERC20_ABI, this.provider));
+        this.contracts.set('Trading', new ethers_1.Contract(config_1.CONTRACTS.Trading, abis_1.TRADING_ABI, this.provider));
+        this.contracts.set('Referral', new ethers_1.Contract(config_1.CONTRACTS.Referral, abis_1.REFERRAL_ABI, this.provider));
+        this.contracts.set('Multicall', new ethers_1.Contract(config_1.CONTRACTS.Multicall, abis_1.MULTICALL_ABI, this.provider));
+    }
+    /**
+     * Get a contract instance
+     * @param name - Contract name
+     * @returns Contract instance
+     */
+    getContract(name) {
+        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) {
+        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) {
+        this.signer = new local_1.LocalSigner(privateKey, this.provider);
+        this.setSigner(this.signer);
+    }
+    /**
+     * Set AWS KMS signer
+     * @param kmsKeyId - KMS key ID
+     * @param region - AWS region
+     */
+    setAwsKmsSigner(kmsKeyId, region = 'us-east-1') {
+        this.signer = new kms_1.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) {
+        return await this.provider.getBalance(address);
+    }
+    /**
+     * Get USDC balance
+     * @param address - Address to check
+     * @returns USDC balance
+     */
+    async getUsdcBalance(address) {
+        const balance = await this.getContract('USDC').balanceOf(address);
+        return (0, types_1.fromBlockchain6)(balance);
+    }
+    /**
+     * Get USDC allowance for trading
+     * @param address - Address to check
+     * @returns Allowance amount
+     */
+    async getUsdcAllowanceForTrading(address) {
+        const tradingStorageAddress = await this.getContract('TradingStorage').getAddress();
+        const allowance = await this.getContract('USDC').allowance(address, tradingStorageAddress);
+        return (0, types_1.fromBlockchain6)(allowance);
+    }
+    /**
+     * Approve USDC for trading
+     * @param amount - Amount to approve
+     * @returns Transaction receipt
+     */
+    async approveUsdcForTrading(amount) {
+        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 = {
+            to: config_1.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) {
+        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) {
+        return await this.provider.estimateGas(tx);
+    }
+    /**
+     * Get transaction count (nonce)
+     * @param address - Address to check
+     * @returns Transaction count
+     */
+    async getTransactionCount(address) {
+        return await this.provider.getTransactionCount(address);
+    }
+    /**
+     * Get chain ID
+     * @returns Chain ID
+     */
+    async getChainId() {
+        const network = await this.provider.getNetwork();
+        return network.chainId;
+    }
+}
+exports.TraderClient = TraderClient;

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 declare const CONTRACTS: ContractAddresses;
+/**
+ * API endpoints for Avantis services
+ */
+export declare const API_ENDPOINTS: {
+    SOCKET_API: string;
+    PYTH_WS: string;
+    PYTH_HTTP: string;
+};
+/**
+ * Network configuration
+ */
+export interface NetworkConfig {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    contracts: ContractAddresses;
+}
+/**
+ * Get contract address by name
+ */
+export declare function getContractAddress(contractName: keyof ContractAddresses): string;
+/**
+ * Update contract addresses (useful for testing or different networks)
+ */
+export declare function setContractAddresses(addresses: Partial<ContractAddresses>): void;

package/dist/config.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Configuration file containing contract addresses and API endpoints
+ * for Avantis trading platform
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_ENDPOINTS = exports.CONTRACTS = void 0;
+exports.getContractAddress = getContractAddress;
+exports.setContractAddresses = setContractAddresses;
+/**
+ * Mainnet contract addresses for Avantis (Base Network)
+ */
+exports.CONTRACTS = {
+    TradingStorage: '0x8a311D7048c35985aa31C131B9A13e03a5f7422d',
+    PairStorage: '0x5db3772136e5557EFE028Db05EE95C84D76faEC4',
+    PairInfos: '0x81F22d0Cc22977c91bEfE648C9fddf1f2bd977e5',
+    PriceAggregator: '0x64e2625621970F8cfA17B294670d61CB883dA511',
+    USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    Trading: '0x44914408af82bC9983bbb330e3578E1105e11d4e',
+    Multicall: '0xb7125506Ff25211c4C51DFD8DdED00BE6Fa8Cbf7',
+    Referral: '0x1A110bBA13A1f16cCa4b79758BD39290f29De82D',
+};
+/**
+ * API endpoints for Avantis services
+ */
+exports.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',
+};
+/**
+ * Get contract address by name
+ */
+function getContractAddress(contractName) {
+    return exports.CONTRACTS[contractName];
+}
+/**
+ * Update contract addresses (useful for testing or different networks)
+ */
+function setContractAddresses(addresses) {
+    Object.assign(exports.CONTRACTS, addresses);
+}

package/dist/crypto/spki.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare function publicKeyIntToEthAddress(publicKeyX: bigint, publicKeyY: bigint): string;
+/**
+ * Parse DER-encoded public key and convert to Ethereum address
+ * @param derPublicKey - DER-encoded public key bytes
+ * @returns Ethereum address
+ */
+export declare function derEncodedPublicKeyToEthAddress(derPublicKey: Uint8Array): string;
+/**
+ * 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 declare function getSigRS(derSignature: Uint8Array): {
+    r: string;
+    s: string;
+};
+/**
+ * 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 declare function getSigV(msgHash: string, r: string, s: string, expectedAddress: string): number;
+/**
+ * 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 declare function getSigRSV(kmsSignature: Uint8Array, msgHash: string, ethAddress: string): {
+    r: string;
+    s: string;
+    v: number;
+};
+/**
+ * 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 declare function signatureToHex(r: string, s: string, v: number): string;

package/dist/crypto/spki.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publicKeyIntToEthAddress = publicKeyIntToEthAddress;
+exports.derEncodedPublicKeyToEthAddress = derEncodedPublicKeyToEthAddress;
+exports.getSigRS = getSigRS;
+exports.getSigV = getSigV;
+exports.getSigRSV = getSigRSV;
+exports.signatureToHex = signatureToHex;
+const ethers_1 = require("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
+ */
+function publicKeyIntToEthAddress(publicKeyX, publicKeyY) {
+    // 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 = (0, ethers_1.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
+ */
+function derEncodedPublicKeyToEthAddress(derPublicKey) {
+    // 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 = (0, ethers_1.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
+ */
+function getSigRS(derSignature) {
+    // 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)
+ */
+function getSigV(msgHash, r, s, expectedAddress) {
+    // 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 = (0, ethers_1.concat)([
+                signature.r,
+                signature.s,
+                new Uint8Array([signature.v]),
+            ]);
+            // Try to recover the address
+            const recoveredAddress = ethers_1.SigningKey.recoverPublicKey((0, ethers_1.getBytes)(msgHash), sigString);
+            const recoveredAddr = (0, ethers_1.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
+ */
+function getSigRSV(kmsSignature, msgHash, ethAddress) {
+    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
+ */
+function signatureToHex(r, s, v) {
+    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;
+}