@solana/keychain-fireblocks

Fireblocks-based signer for Solana transactions using Fireblocks' institutional custody API.

Installation

pnpm add @solana/keychain-fireblocks

Prerequisites

1. A Fireblocks account with API access
2. A vault account with Solana (SOL) asset configured
3. An API user with signing permissions and RSA 4096 private key

Follow the Fireblocks documentation to get started.

Usage

Basic Setup

import { createFireblocksSigner } from '@solana/keychain-fireblocks';

const signer = await createFireblocksSigner({
    apiKey: 'your-fireblocks-api-key',
    privateKeyPem: `-----BEGIN PRIVATE KEY-----
...your RSA 4096 private key...
-----END PRIVATE KEY-----`,
    vaultAccountId: '0',
});

console.log('Signer address:', signer.address);

Signing Transactions

import { pipe, signTransaction, createTransaction } from '@solana/kit';

// Create your transaction
const transaction = pipe(
    createTransaction({ version: 0 }),
    // ... add instructions
);

// Sign the transaction
const signedTransaction = await signTransaction([signer], transaction);

Signing Messages

import { signMessage } from '@solana/signers';

const message = new TextEncoder().encode('Hello, Solana!');
const signature = await signMessage([signer], message);

Signing Mode

The signer always uses Fireblocks RAW signing: it signs the message bytes and returns the signature to you, and you broadcast the transaction yourself. This is the only mode compatible with the SolanaSigner contract.

Fireblocks PROGRAM_CALL signing is not supported. It broadcasts the transaction on-chain and only returns a broadcast transaction id, not a reusable signer-bound signature, which would risk duplicate spends. Passing useProgramCall: true is rejected at construction with a CONFIG_ERROR.

With Devnet

const signer = await createFireblocksSigner({
    apiKey: 'your-fireblocks-api-key',
    privateKeyPem: '...',
    vaultAccountId: '0',
    assetId: 'SOL_TEST', // Use devnet asset
});

Configuration

FireblocksSignerConfig

| Field | Type | Required | Default | Description | | ----------------- | --------- | -------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | string | Yes | - | Fireblocks API key (X-API-Key header) | | privateKeyPem | string | Yes | - | RSA 4096 private key in PEM format for JWT signing | | vaultAccountId | string | Yes | - | Fireblocks vault account ID | | apiBaseUrl | string | No | https://api.fireblocks.io | Custom API base URL | | assetId | string | No | SOL | Asset ID (SOL for mainnet, SOL_TEST for devnet) | | pollIntervalMs | number | No | 1000 | Polling interval in ms when waiting for transaction completion | | maxPollAttempts | number | No | 60 | Maximum polling attempts before timeout | | requestDelayMs | number | No | 0 | Delay in ms between concurrent signing requests | | useProgramCall | boolean | No | false | Deprecated, unsupported. Setting true is rejected at construction with a CONFIG_ERROR (PROGRAM_CALL broadcasts on-chain without a reusable signature). Omit it; removal planned in a future major. |

How It Works

1. Initialization: Fetches the vault account's Solana address from Fireblocks API
2. JWT Authentication: Signs API requests with RS256 JWT using your RSA private key
3. Transaction Creation: Creates a RAW signing transaction in Fireblocks
4. Signature Extraction: Extracts the Ed25519 signature from the completed transaction/message

Signing Mode

• RAW (only supported mode): Signs the message bytes only. You receive the signature and broadcast the transaction yourself. Fireblocks PROGRAM_CALL (broadcast) signing is not supported — see Signing Mode above.

Security Considerations

1. Private Key Security: The RSA private key should never be committed to source control. Use environment variables or secure secret management.
2. API Key Rotation: Rotate API keys periodically according to your security policy.
3. Policy Engine: Configure Fireblocks Transaction Authorization Policy (TAP) to enforce signing rules.

License

MIT