@fireblocks/psbt-sdk/README.md

SDK for signing Partially Signed Bitcoin Transactions (PSBTs) using Fireblocks

<p align="center">
  <img src="./logo.svg" width="350" alt="Fireblocks">
</p>
<div align="center">

  [![npm version](https://badge.fury.io/js/@fireblocks%2Fpsbt-sdk.svg)](https://badge.fury.io/js/@fireblocks%2Fpsbt-sdk)
</div>

# 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](https://github.com/fireblocks/ts-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](https://github.com/bitcoinjs/bitcoinjs-lib)

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

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

## PsbtSigner

```typescript
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

```typescript
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](test/index.test.ts)
- [example.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](LICENSE).