@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2

package/src/utils/solanaKeyParser.test.ts

@@ -0,0 +1,103 @@
+import { expect } from 'chai';
+
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+
+import { parseSolanaPrivateKey } from './solanaKeyParser.js';
+
+describe('parseSolanaPrivateKey', () => {
+  it('parses valid 64-byte JSON array', () => {
+    const bytes = Array.from({ length: 64 }, (_, i) => i);
+    const parsed = parseSolanaPrivateKey(JSON.stringify(bytes));
+
+    expect(parsed).to.be.instanceOf(Uint8Array);
+    expect(Array.from(parsed)).to.deep.equal(bytes);
+    expect(parsed).to.have.length(64);
+  });
+
+  it('parses valid 64-byte comma-separated', () => {
+    const bytes = Array.from({ length: 64 }, (_, i) => i);
+    const parsed = parseSolanaPrivateKey(bytes.join(','));
+
+    expect(Array.from(parsed)).to.deep.equal(bytes);
+    expect(parsed).to.have.length(64);
+  });
+
+  it('parses valid 32-byte seed JSON array and expands to 64 bytes', () => {
+    const seed = Array.from({ length: 32 }, (_, i) => i);
+    const parsed = parseSolanaPrivateKey(JSON.stringify(seed));
+    const expected = Keypair.fromSeed(Uint8Array.from(seed)).secretKey;
+
+    expect(parsed).to.have.length(64);
+    expect(Array.from(parsed)).to.deep.equal(Array.from(expected));
+  });
+
+  it('parses valid 32-byte seed comma-separated and expands to 64 bytes', () => {
+    const seed = Array.from({ length: 32 }, (_, i) => i + 1);
+    const parsed = parseSolanaPrivateKey(seed.join(','));
+    const expected = Keypair.fromSeed(Uint8Array.from(seed)).secretKey;
+
+    expect(parsed).to.have.length(64);
+    expect(Array.from(parsed)).to.deep.equal(Array.from(expected));
+  });
+
+  it('throws on "1,2,abc,4" (non-numeric)', () => {
+    expect(() => parseSolanaPrivateKey('1,2,abc,4')).to.throw(
+      'Comma-separated byte at index 2 is not numeric.',
+    );
+  });
+
+  it('throws on empty string', () => {
+    expect(() => parseSolanaPrivateKey('   ')).to.throw('Input is empty.');
+  });
+
+  it('throws on "256,1,2" (out of range)', () => {
+    expect(() => parseSolanaPrivateKey('256,1,2')).to.throw(
+      'Comma-separated byte at index 0 must be in range 0..255.',
+    );
+  });
+
+  it('throws on "-1,1,2" (negative)', () => {
+    expect(() => parseSolanaPrivateKey('-1,1,2')).to.throw(
+      'Comma-separated byte at index 0 must be in range 0..255.',
+    );
+  });
+
+  it('throws on "1.5,2,3" (non-integer)', () => {
+    expect(() => parseSolanaPrivateKey('1.5,2,3')).to.throw(
+      'Comma-separated byte at index 0 must be an integer.',
+    );
+  });
+
+  it('throws on 10-byte array (wrong length)', () => {
+    const tenBytes = JSON.stringify(Array.from({ length: 10 }, (_, i) => i));
+    expect(() => parseSolanaPrivateKey(tenBytes)).to.throw(
+      'Received 10 bytes; expected exactly 32 or 64.',
+    );
+  });
+
+  it('error message contains HYP_INVENTORY_KEY_SEALEVEL', () => {
+    expect(() => parseSolanaPrivateKey('not-a-key')).to.throw(
+      'HYP_INVENTORY_KEY_SEALEVEL',
+    );
+  });
+
+  it('parses valid base58-encoded 64-byte key', () => {
+    const bytes = Array.from({ length: 64 }, (_, i) => i);
+    const base58Key = bs58.encode(Uint8Array.from(bytes));
+    const parsed = parseSolanaPrivateKey(base58Key);
+
+    expect(Array.from(parsed)).to.deep.equal(bytes);
+    expect(parsed).to.have.length(64);
+  });
+
+  it('parses valid base58-encoded 32-byte seed and expands to 64 bytes', () => {
+    const seed = Array.from({ length: 32 }, (_, i) => i + 1);
+    const base58Seed = bs58.encode(Uint8Array.from(seed));
+    const parsed = parseSolanaPrivateKey(base58Seed);
+    const expected = Keypair.fromSeed(Uint8Array.from(seed)).secretKey;
+
+    expect(parsed).to.have.length(64);
+    expect(Array.from(parsed)).to.deep.equal(Array.from(expected));
+  });
+});

package/src/utils/solanaKeyParser.ts

@@ -0,0 +1,117 @@
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+
+const SOLANA_KEY_ERROR_MESSAGE =
+  'Invalid Solana private key format. Expected JSON byte array, comma-separated bytes, or base58 key (32 or 64 bytes). Set HYP_INVENTORY_KEY_SEALEVEL env var.';
+
+function throwInvalidSolanaKey(reason: string): never {
+  throw new Error(`${SOLANA_KEY_ERROR_MESSAGE} ${reason}`);
+}
+
+function validateKeyLength(bytes: number[]): void {
+  if (bytes.length !== 32 && bytes.length !== 64) {
+    throwInvalidSolanaKey(
+      `Received ${bytes.length} bytes; expected exactly 32 or 64.`,
+    );
+  }
+}
+
+function toSecretKey(bytes: number[]): Uint8Array {
+  validateKeyLength(bytes);
+  if (bytes.length === 32) {
+    return Keypair.fromSeed(Uint8Array.from(bytes)).secretKey;
+  }
+  return Uint8Array.from(bytes);
+}
+
+/**
+ * Parses a Solana private key from various formats.
+ * Supports JSON array format, comma-separated byte values, and base58 values.
+ *
+ * @param rawKey - Raw private key string in JSON array, comma-separated, or base58 format
+ * @returns Uint8Array representation of the private key
+ * @throws Error if the key format is invalid
+ */
+export function parseSolanaPrivateKey(rawKey: string): Uint8Array {
+  const trimmed = rawKey.trim();
+  if (trimmed === '') {
+    throwInvalidSolanaKey('Input is empty.');
+  }
+
+  try {
+    if (trimmed.startsWith('[')) {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (!Array.isArray(parsed)) {
+        throwInvalidSolanaKey('JSON input must be an array of bytes.');
+      }
+
+      const bytes = parsed.map((value, index) => {
+        if (!Number.isInteger(value)) {
+          throwInvalidSolanaKey(
+            `JSON byte at index ${index} must be an integer.`,
+          );
+        }
+        if (value < 0 || value > 255) {
+          throwInvalidSolanaKey(
+            `JSON byte at index ${index} must be in range 0..255.`,
+          );
+        }
+        return value;
+      });
+
+      return toSecretKey(bytes);
+    }
+
+    if (trimmed.includes(',')) {
+      const bytes = trimmed.split(',').map((segment, index) => {
+        const segmentTrimmed = segment.trim();
+        if (segmentTrimmed === '') {
+          throwInvalidSolanaKey(
+            `Comma-separated byte at index ${index} is empty.`,
+          );
+        }
+
+        const value = Number(segmentTrimmed);
+        if (!Number.isFinite(value)) {
+          throwInvalidSolanaKey(
+            `Comma-separated byte at index ${index} is not numeric.`,
+          );
+        }
+        if (!Number.isInteger(value)) {
+          throwInvalidSolanaKey(
+            `Comma-separated byte at index ${index} must be an integer.`,
+          );
+        }
+        if (value < 0 || value > 255) {
+          throwInvalidSolanaKey(
+            `Comma-separated byte at index ${index} must be in range 0..255.`,
+          );
+        }
+
+        return value;
+      });
+
+      return toSecretKey(bytes);
+    }
+
+    try {
+      const decoded = bs58.decode(trimmed);
+      const bytes = Array.from(decoded);
+      return toSecretKey(bytes);
+    } catch {
+      // bs58 decode failed, fall through to outer catch
+    }
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message.includes(SOLANA_KEY_ERROR_MESSAGE)
+    ) {
+      throw error;
+    }
+    throwInvalidSolanaKey('Failed to parse key input.');
+  }
+
+  throwInvalidSolanaKey(
+    'Failed to match supported format (JSON array, comma-separated bytes, or base58 key).',
+  );
+}

package/src/utils/tokenUtils.ts

@@ -0,0 +1,89 @@
+import { ProtocolType, assert } from '@humanode-hyperlane/utils';
+
+import type { ExternalBridgeType } from '../config/types.js';
+
+import {
+  PROTOCOL_TO_HYP_NATIVE_STANDARD,
+  type Token,
+  TokenStandard,
+} from '@humanode-hyperlane/sdk';
+
+const REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS = new Set<TokenStandard>([
+  TokenStandard.EvmHypCollateral,
+  TokenStandard.EvmHypNative,
+  TokenStandard.SealevelHypCollateral,
+  TokenStandard.SealevelHypNative,
+]);
+
+// SDK-backed native token standard check scoped to EVM and Sealevel only (2-protocol scope).
+// NOTE: We intentionally do NOT use the full PROTOCOL_TO_HYP_NATIVE_STANDARD map (all 7 protocols)
+// because the rebalancer only supports EVM and Sealevel native token bridging.
+// Expanding this would change gas reservation behavior for other protocols.
+const REBALANCER_NATIVE_STANDARDS = new Set([
+  PROTOCOL_TO_HYP_NATIVE_STANDARD[ProtocolType.Ethereum],
+  PROTOCOL_TO_HYP_NATIVE_STANDARD[ProtocolType.Sealevel],
+]);
+
+/**
+ * Check if a token's balance is the same as native gas balance.
+ * For these tokens, we must reserve funds for IGP when calculating max transferable.
+ *
+ * @param standard - The token standard to check.
+ * @returns `true` if the token is a native token standard, `false` otherwise.
+ */
+export function isNativeTokenStandard(standard: TokenStandard): boolean {
+  return REBALANCER_NATIVE_STANDARDS.has(standard);
+}
+
+/**
+ * @dev This function exists because the rebalancer currently only supports a subset of collateralized token standards
+ *   (see `REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS` vs. all possible `TOKEN_COLLATERALIZED_STANDARDS`).
+ *
+ * @deprecated This function is conditionally deprecated. It is intended for removal once the rebalancer
+ *   achieves full support for all collateralized token standards.
+ *   After this condition is met and this function is removed, please use `token.isCollateralized()` as the alternative.
+ *
+ * @param token - The token to be checked for rebalancing eligibility.
+ * @returns `true` if the token is of a collateralized standard currently supported by the rebalancer, `false` otherwise.
+ */
+export function isCollateralizedTokenEligibleForRebalancing(
+  token: Token,
+): boolean {
+  return (
+    token.isCollateralized() &&
+    REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS.has(token.standard)
+  );
+}
+
+/**
+ * Resolves the correct token address for external bridges (e.g. LiFi).
+ *
+ * For warp route tokens, `addressOrDenom` is the warp router contract address,
+ * NOT the underlying token. External bridges need the actual token address:
+ * - Native tokens (EvmHypNative, SealevelHypNative): Use the bridge's native token representation
+ * - Collateral tokens (EvmHypCollateral, SealevelHypCollateral): Use `collateralAddressOrDenom` (the underlying token)
+ * - Synthetic tokens: `collateralAddressOrDenom` is undefined, `addressOrDenom` IS the token
+ *
+ * @param token - The warp route token to resolve
+ * @param externalBridgeType - The type of external bridge (e.g. 'lifi')
+ * @param getNativeTokenAddress - Function to get the bridge's native token representation
+ * @returns The correct token address for the external bridge
+ */
+export function getExternalBridgeTokenAddress(
+  token: Token,
+  externalBridgeType: ExternalBridgeType,
+  getNativeTokenAddress: (type: ExternalBridgeType) => string,
+): string {
+  if (isNativeTokenStandard(token.standard)) {
+    return getNativeTokenAddress(externalBridgeType);
+  }
+
+  if (token.collateralAddressOrDenom) return token.collateralAddressOrDenom;
+
+  assert(
+    !REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS.has(token.standard),
+    `Missing collateralAddressOrDenom for collateralized token on ${token.chainName} (${token.standard})`,
+  );
+
+  return token.addressOrDenom;
+}

package/src/utils/transactionUtils.ts

@@ -0,0 +1,41 @@
+import {
+  assert,
+  type KnownProtocolType,
+  type ProtocolType,
+} from '@humanode-hyperlane/utils';
+import {
+  PROTOCOL_TO_DEFAULT_PROVIDER_TYPE,
+  type ProtocolTypedTransaction,
+  type WarpTypedTransaction,
+} from '@humanode-hyperlane/sdk';
+
+/**
+ * Runtime-validated cast from WarpTypedTransaction to ProtocolTypedTransaction.
+ * WarpTypedTransaction extends TypedTransaction but ProtocolTypedTransaction
+ * only covers known protocol types.
+ * Safe at runtime because WarpCore only produces default-provider transactions.
+ *
+ * The double-cast (as unknown as) is unavoidable due to TypeScript's type narrowing
+ * limitations: WarpTypedTransaction is a union of all protocol transaction types,
+ * and ProtocolTypedTransaction<P> is a conditional/mapped type. Even after the
+ * runtime assert() proves type safety, TypeScript cannot narrow the union across
+ * this structural boundary. The cast is safe because the assert validates the
+ * transaction type matches the expected protocol at runtime.
+ *
+ * @param tx - The transaction to cast
+ * @param expectedProtocol - The expected protocol type
+ * @returns The transaction cast to ProtocolTypedTransaction
+ * @throws Error if the transaction type doesn't match the expected protocol
+ */
+export function toProtocolTransaction(
+  tx: WarpTypedTransaction,
+  expectedProtocol: ProtocolType,
+): ProtocolTypedTransaction<ProtocolType> {
+  const expectedType =
+    PROTOCOL_TO_DEFAULT_PROVIDER_TYPE[expectedProtocol as KnownProtocolType];
+  assert(
+    expectedType && tx.type === expectedType,
+    `Transaction type ${tx.type} doesn't match expected protocol ${expectedProtocol} (expected ${expectedType})`,
+  );
+  return tx as unknown as ProtocolTypedTransaction<ProtocolType>;
+}