@solana/keychain-fireblocks 0.4.0 → 0.6.0

package/src/fireblocks-signer.ts

@@ -1,6 +1,12 @@
 import { Address, assertIsAddress } from '@solana/addresses';
-import { getBase58Encoder } from '@solana/codecs-strings';
-import { createSignatureDictionary, SignerErrorCode, SolanaSigner, throwSignerError } from '@solana/keychain-core';
+import { getBase16Decoder, getBase16Encoder, getBase58Encoder } from '@solana/codecs-strings';
+import {
+    assertSignatureValid,
+    createSignatureDictionary,
+    SignerErrorCode,
+    SolanaSigner,
+    throwSignerError,
+} from '@solana/keychain-core';
 import { SignatureBytes } from '@solana/keys';
 import { SignableMessage, SignatureDictionary } from '@solana/signers';
 import {
@@ -18,7 +24,16 @@ import type {
     TransactionResponse,
     VaultAddressesResponse,
 } from './types.js';
-import { FireblocksTransactionStatus, TERMINAL_STATUSES } from './types.js';
+import { FireblocksTransactionStatus, isTerminalStatus } from './types.js';
+
+export async function createFireblocksSigner<TAddress extends string = string>(
+    config: FireblocksSignerConfig,
+): Promise<SolanaSigner<TAddress>> {
+    return await FireblocksSigner.create(config);
+}
+
+let base16Encoder: ReturnType<typeof getBase16Encoder> | undefined;
+let base16Decoder: ReturnType<typeof getBase16Decoder> | undefined;
 
 const DEFAULT_API_BASE_URL = 'https://api.fireblocks.io';
 const DEFAULT_ASSET_ID = 'SOL';
@@ -33,13 +48,14 @@ const DEFAULT_MAX_POLL_ATTEMPTS = 60;
  *
  * @example
  * ```typescript
- * const signer = new FireblocksSigner({
+ * const signer = await FireblocksSigner.create({
  *     apiKey: 'your-api-key',
  *     privateKeyPem: '-----BEGIN PRIVATE KEY-----\n...',
  *     vaultAccountId: '0',
  * });
- * await signer.init();
  * ```
+ *
+ * @deprecated Prefer `createFireblocksSigner()`. Class export will be removed in a future version.
  */
 export class FireblocksSigner<TAddress extends string = string> implements SolanaSigner<TAddress> {
     private _address: Address<TAddress> | null = null;
@@ -54,6 +70,21 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
     private readonly useProgramCall: boolean;
     private initialized = false;
 
+    /**
+     * Fetches the public key from Fireblocks API during initialization.
+     * @deprecated Use `createFireblocksSigner()` instead.
+     */
+    static async create<TAddress extends string = string>(
+        config: FireblocksSignerConfig,
+    ): Promise<FireblocksSigner<TAddress>> {
+        const signer = new FireblocksSigner<TAddress>(config);
+        await signer.init();
+        return signer;
+    }
+
+    /**
+     * @deprecated Use `createFireblocksSigner()` instead. Direct construction will be removed in a future version.
+     */
     constructor(config: FireblocksSignerConfig) {
         if (!config.apiKey) {
             throwSignerError(SignerErrorCode.CONFIG_ERROR, {
@@ -101,6 +132,7 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
 
     /**
      * Initialize the signer by fetching the public key from Fireblocks
+     * @deprecated Use `createFireblocksSigner()` instead, which handles initialization automatically.
      */
     async init(): Promise<void> {
         if (this.initialized) {
@@ -145,13 +177,22 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
         const token = await createJwt(this.apiKey, this.privateKeyPem, uri, '');
 
         const url = `${this.apiBaseUrl}${uri}`;
-        const response = await fetch(url, {
-            headers: {
-                Authorization: `Bearer ${token}`,
-                'X-API-Key': this.apiKey,
-            },
-            method: 'GET',
-        });
+        let response: Response;
+        try {
+            response = await fetch(url, {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'X-API-Key': this.apiKey,
+                },
+                method: 'GET',
+            });
+        } catch (error) {
+            throwSignerError(SignerErrorCode.HTTP_ERROR, {
+                cause: error,
+                message: 'Fireblocks network request failed',
+                url,
+            });
+        }
 
         if (!response.ok) {
             const errorText = await response.text().catch(() => 'Failed to read error response');
@@ -165,8 +206,9 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
         let addressesResponse: VaultAddressesResponse;
         try {
             addressesResponse = (await response.json()) as VaultAddressesResponse;
-        } catch {
+        } catch (error) {
             throwSignerError(SignerErrorCode.PARSING_ERROR, {
+                cause: error,
                 message: 'Failed to parse Fireblocks response',
             });
         }
@@ -181,8 +223,9 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
         try {
             assertIsAddress(firstAddress);
             return firstAddress as Address;
-        } catch {
+        } catch (error) {
             throwSignerError(SignerErrorCode.INVALID_PUBLIC_KEY, {
+                cause: error,
                 message: 'Invalid address from Fireblocks',
             });
         }
@@ -196,15 +239,24 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
         const token = await createJwt(this.apiKey, this.privateKeyPem, uri, bodyStr);
 
         const url = `${this.apiBaseUrl}${uri}`;
-        const response = await fetch(url, {
-            body: body ? bodyStr : undefined,
-            headers: {
-                Authorization: `Bearer ${token}`,
-                'Content-Type': 'application/json',
-                'X-API-Key': this.apiKey,
-            },
-            method,
-        });
+        let response: Response;
+        try {
+            response = await fetch(url, {
+                body: body ? bodyStr : undefined,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                method,
+            });
+        } catch (error) {
+            throwSignerError(SignerErrorCode.HTTP_ERROR, {
+                cause: error,
+                message: 'Fireblocks network request failed',
+                url,
+            });
+        }
 
         if (!response.ok) {
             const errorText = await response.text().catch(() => 'Failed to read error response');
@@ -217,8 +269,9 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
 
         try {
             return (await response.json()) as T;
-        } catch {
+        } catch (error) {
             throwSignerError(SignerErrorCode.PARSING_ERROR, {
+                cause: error,
                 message: 'Failed to parse Fireblocks response',
             });
         }
@@ -228,7 +281,8 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
      * Sign raw bytes using Fireblocks RAW operation
      */
     private async signRawBytes(messageBytes: Uint8Array): Promise<SignatureBytes> {
-        const hexContent = bytesToHex(messageBytes);
+        base16Decoder ||= getBase16Decoder();
+        const hexContent = base16Decoder.decode(messageBytes);
 
         const request: CreateTransactionRequest = {
             assetId: this.assetId,
@@ -289,7 +343,14 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
                 // Try signedMessages first (RAW signing - hex encoded)
                 const fullSig = txResponse.signedMessages?.[0]?.signature?.fullSig;
                 if (fullSig) {
-                    const sigBytes = hexToBytes(fullSig);
+                    const cleanHex = fullSig.startsWith('0x') || fullSig.startsWith('0X') ? fullSig.slice(2) : fullSig;
+                    if (cleanHex.length % 2 !== 0) {
+                        throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+                            message: `Invalid hex signature: odd length (${cleanHex.length} chars)`,
+                        });
+                    }
+                    base16Encoder ||= getBase16Encoder();
+                    const sigBytes = new Uint8Array(base16Encoder.encode(cleanHex.toLowerCase()));
                     if (sigBytes.length !== 64) {
                         throwSignerError(SignerErrorCode.SIGNING_FAILED, {
                             message: `Invalid signature length: expected 64 bytes, got ${sigBytes.length}`,
@@ -315,7 +376,7 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
             }
 
             // Check for terminal failure statuses
-            if (TERMINAL_STATUSES.has(status)) {
+            if (isTerminalStatus(status)) {
                 throwSignerError(SignerErrorCode.SIGNING_FAILED, {
                     message: `Transaction failed with status: ${txResponse.status}`,
                 });
@@ -344,6 +405,11 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
                         ? message.content
                         : new Uint8Array(Array.from(message.content));
                 const signatureBytes = await this.signRawBytes(messageBytes);
+                await assertSignatureValid({
+                    data: messageBytes,
+                    signature: signatureBytes,
+                    signerAddress: this.address,
+                });
                 return createSignatureDictionary({
                     signature: signatureBytes,
                     signerAddress: this.address,
@@ -366,6 +432,15 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
                 const signatureBytes = this.useProgramCall
                     ? await this.signWithProgramCall(transaction)
                     : await this.signRawBytes(new Uint8Array(transaction.messageBytes));
+                // Skip verification for PROGRAM_CALL: it broadcasts to Solana and returns
+                // a txHash (on-chain confirmation), not a signature over the message bytes.
+                if (!this.useProgramCall) {
+                    await assertSignatureValid({
+                        data: transaction.messageBytes,
+                        signature: signatureBytes,
+                        signerAddress: this.address,
+                    });
+                }
                 return createSignatureDictionary({
                     signature: signatureBytes,
                     signerAddress: this.address,
@@ -408,24 +483,3 @@ export class FireblocksSigner<TAddress extends string = string> implements Solan
         }
     }
 }
-
-/**
- * Convert Uint8Array to hex string
- */
-function bytesToHex(bytes: Uint8Array): string {
-    return Array.from(bytes)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-}
-
-/**
- * Convert hex string to Uint8Array
- */
-function hexToBytes(hex: string): Uint8Array {
-    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
-    const bytes = new Uint8Array(cleanHex.length / 2);
-    for (let i = 0; i < bytes.length; i++) {
-        bytes[i] = parseInt(cleanHex.substring(i * 2, i * 2 + 2), 16);
-    }
-    return bytes;
-}

package/src/index.ts

@@ -1,4 +1,4 @@
-export { FireblocksSigner } from './fireblocks-signer.js';
+export { FireblocksSigner, createFireblocksSigner } from './fireblocks-signer.js';
 export type {
     FireblocksSignerConfig,
     CreateTransactionRequest,
@@ -6,4 +6,4 @@ export type {
     TransactionResponse,
     VaultAddressesResponse,
 } from './types.js';
-export { FireblocksTransactionStatus, TERMINAL_STATUSES } from './types.js';
+export { FireblocksTransactionStatus, isTerminalStatus } from './types.js';

package/src/jwt.ts

@@ -1,6 +1,9 @@
+import { getBase16Decoder } from '@solana/codecs-strings';
 import { SignerErrorCode, throwSignerError } from '@solana/keychain-core';
 import { importPKCS8, SignJWT } from 'jose';
 
+let base16Decoder: ReturnType<typeof getBase16Decoder> | undefined;
+
 /**
  * Create a JWT for Fireblocks API authentication
  *
@@ -50,9 +53,8 @@ export async function createJwt(apiKey: string, privateKeyPem: string, uri: stri
  * Compute SHA256 hash and return as hex string
  */
 async function sha256Hex(data: string): Promise<string> {
-    const encoder = new TextEncoder();
-    const dataBuffer = encoder.encode(data);
+    const dataBuffer = new TextEncoder().encode(data);
     const hashBuffer = await crypto.subtle.digest('SHA-256', dataBuffer);
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    base16Decoder ||= getBase16Decoder();
+    return base16Decoder.decode(new Uint8Array(hashBuffer));
 }

package/src/types.ts

@@ -112,29 +112,36 @@ export interface VaultAddress {
 /**
  * Fireblocks transaction status values
  */
-export enum FireblocksTransactionStatus {
-    SUBMITTED = 'SUBMITTED',
-    QUEUED = 'QUEUED',
-    PENDING_SIGNATURE = 'PENDING_SIGNATURE',
-    PENDING_AUTHORIZATION = 'PENDING_AUTHORIZATION',
-    PENDING_3RD_PARTY_MANUAL_APPROVAL = 'PENDING_3RD_PARTY_MANUAL_APPROVAL',
-    PENDING_3RD_PARTY = 'PENDING_3RD_PARTY',
-    BROADCASTING = 'BROADCASTING',
-    CONFIRMING = 'CONFIRMING',
-    COMPLETED = 'COMPLETED',
-    CANCELLED = 'CANCELLED',
-    REJECTED = 'REJECTED',
-    BLOCKED = 'BLOCKED',
-    FAILED = 'FAILED',
-}
+export const FireblocksTransactionStatus = {
+    BLOCKED: 'BLOCKED',
+    BROADCASTING: 'BROADCASTING',
+    CANCELLED: 'CANCELLED',
+    COMPLETED: 'COMPLETED',
+    CONFIRMING: 'CONFIRMING',
+    FAILED: 'FAILED',
+    PENDING_3RD_PARTY: 'PENDING_3RD_PARTY',
+    PENDING_3RD_PARTY_MANUAL_APPROVAL: 'PENDING_3RD_PARTY_MANUAL_APPROVAL',
+    PENDING_AUTHORIZATION: 'PENDING_AUTHORIZATION',
+    PENDING_SIGNATURE: 'PENDING_SIGNATURE',
+    QUEUED: 'QUEUED',
+    REJECTED: 'REJECTED',
+    SUBMITTED: 'SUBMITTED',
+} as const;
+export type FireblocksTransactionStatus =
+    (typeof FireblocksTransactionStatus)[keyof typeof FireblocksTransactionStatus];
 
 /**
- * Terminal transaction statuses (polling should stop)
+ * Check whether a Fireblocks transaction has reached a terminal state (polling should stop).
+ *
+ * Replaces the previously exported `TERMINAL_STATUSES` Set, which was removed
+ * because module-level `Set` allocation is a side effect that prevents tree-shaking.
  */
-export const TERMINAL_STATUSES = new Set([
-    FireblocksTransactionStatus.COMPLETED,
-    FireblocksTransactionStatus.CANCELLED,
-    FireblocksTransactionStatus.REJECTED,
-    FireblocksTransactionStatus.BLOCKED,
-    FireblocksTransactionStatus.FAILED,
-]);
+export function isTerminalStatus(status: string): boolean {
+    return (
+        status === FireblocksTransactionStatus.COMPLETED ||
+        status === FireblocksTransactionStatus.CANCELLED ||
+        status === FireblocksTransactionStatus.REJECTED ||
+        status === FireblocksTransactionStatus.BLOCKED ||
+        status === FireblocksTransactionStatus.FAILED
+    );
+}