@fireblocks/psbt-sdk

Fireblocks PSBT SDK

Warning
This package is in an alpha stage and should be used at your own risk.
The provided interfaces might go through backwards-incompatibale changes.
For a more stable library (without explicit PSBT support) you can use the Fireblocks Typescript SDK

The Fireblocks PSBT SDK makes it easy to sign PSBTs (Partially Signed Bitcoin Transactions) using Fireblocks.

Features

• Sign all inputs of a PSBT
• Sign specific inputs of a PSBT
• ECDSA signatures

Taproot (Schnorr) signatures are on the roadmap and will be supported in a future release.

Installation

To install the Fireblocks PSBT SDK, run the following command:

npm install @fireblocks/psbt-sdk

Usage

You can choose between:

1. Signing a PSBT with PsbtSigner
2. Using FireblocksSigner with bitcoinjs-lib

Additionally you have two options for passing the Fireblocks SDK configuration parameters:

1. As environment variables (see .env.example)
2. As a configuration object with apiKey and secretKey properties passed to the create method under the fireblocks property

PsbtSigner

import { PsbtSigner } from "@fireblocks/psbt-sdk";

const psbtSigner: PsbtSigner = PsbtSigner.create({
  assetId: "BTC",
  vaultId: "0",
});

// Sign a PSBT in base64 format
const signedPsbtBase64 = await psbtSigner.signBase64("cHNid...AAA==");

// Sign a PSBT in hex format
const signedPsbtHex = await psbtSigner.signHex("70736...70000");

// Sign a bitcoin.Psbt object
const signedPsbt = await psbtSigner.signPsbt(bitcoin.Psbt.fromBase64("cHNid...AAA=="));

FireblocksSigner

import { FireblocksSigner } from "@fireblocks/psbt-sdk";
import * as bitcoin from "bitcoinjs-lib";

const psbt = bitcoin.Psbt.fromBase64("cHNid...AAA==");

const fireblocksSigner: FireblocksSigner = await FireblocksSigner.create({
  assetId: "BTC",
  vaultId: "0",
  addressIndex: 0,
  note: `Signing PSBT: ${psbt.toBase64()}`, // Optional note to add to the transaction
});

// Sign the first input
await psbt.signInputAsync(0, fireblocksSigner);

// Or sign all inputs
await psbt.signAllInputsAsync(fireblocksSigner);

console.log("Signed PSBT:", psbt.toBase64());

psbt.finalizeAllInputs();
console.log("Signed transaction:", psbt.extractTransaction().toHex());

Optional Parameters

Both PsbtSigner.create and FireblocksSigner.create accept the following optional parameters:

• note: A note to add to the Fireblocks transaction.

PsbtSigner.create accepts the following optional parameters:

• batch: Whether to batch the signatures into a single transaction. Defaults to true. When set to false, each signature is sent to Fireblocks as a separate transaction.
  When set to true, if a PSBT requires multiple signatures (for example, a PSBT with multiple inputs that need to be signed), all the signatures are sent to Fireblocks as a single batched raw signing transaction.
• limit: The maximum number of addresses to retrieve from the Fireblocks vault, ordered in descending order by their balance. Defaults to 10.
• addressIndexes: The vault's BIP44 address indexes to use for signing. If not provided, the top limit addresses in terms of balance will be used.

Co-Signer Verification

For programmatic verification of PSBT signature requests in your co-signer callback, if you either:

• Use PsbtSigner
• Or include the base64-encoded PSBT in the FireblocksSigner's note parameter

The PSBT will be available for your co-signer callback under: extraParameters.rawMessageData.psbt

Examples

• test/index.test.ts
• example.ts

Testing

To run the tests, execute the following command:

npm test

Make sure to copy .env.example to .env and fill in the Fireblocks API key and secret before running the tests. Your workspace is expected to have a BTC or BTC_TEST vault with a non-zero balance.

In addition, if you'd like to have the debug logs printed out to the console, make sure to set the DEBUG environment variable:
DEBUG=fireblocks_psbt_sdk:*

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

License

The Fireblocks PSBT SDK is licensed under the MIT License.