Citadel SDK, the JS edition

A JS library for interacting with Citadel Wallet hardware devices through WebUSB and Bluetooth connections. This SDK provides a simple interface to connect, communicate, and perform cryptographic operations with Citadel hardware wallets.

Features

• Support for multiple transport layers (WebUSB and Bluetooth)
• Ability to retrieve the wallet's Public key
• Ability to sign transactions with the wallet
• Plays (hopefully) well with both Node and Web runtimes

Demo Application

Need more convincing or want to see the SDK in action? The repository includes a demo sub-project that lets you test the Citadel SDK with a subset of decentralized applications (dapps) on the Hedera network. The demo provides a simple user interface to:

• Connect to a Citadel hardware device
• Perform various Hedera transactions
• Test transaction signing with the hardware wallet

Running the Demo

First create a .env file from the provided demo/.env.example one and fill in the required values. At a minimum, you'll need to fill in VITE_HEDERA_ACCOUNT_ID, VITE_HEDERA_PUBLIC_KEY and, possibly, VITE_NETWORK (which you'll most likely set it to testnet) with the Hedera account ID and public key of the account you want to use for testing.

Note: the account must be registered on the Hedera network. You can use a soft-wallet such as HashPack to do so.

After that, you can run the demo application by running the following commands (make sure you are within the demo directory):

pnpm install
pnpm dev

The demo application showcases real-world usage of the SDK and provides a reference implementation for integrating the Citadel SDK into your own applications.

Installation

# Using npm
npm install @buidlerlabs/citadel-sdk-js

# Using yarn
yarn add @buidlerlabs/citadel-sdk-js

# Using pnpm
pnpm add @buidlerlabs/citadel-sdk-js

Usage

Checking Supported Transports

Before creating a connection, you can check which transport methods are supported by the current browser environment:

import { CitadelLink } from '@buidlerlabs/citadel-sdk-js';

const supportedTransports = await CitadelLink.getSupportedTransports();
console.log(supportedTransports);

// Possible, self explanatory, output:
// [
//   { transport: TransportType.WebUsb, supported: true },
//   { transport: TransportType.Bluetooth, supported: false }
// ]

Connecting to a Device

import { CitadelLink } from '@buidlerlabs/citadel-sdk-js';

// Create a new CitadelLink instance using WebUSB
const citadelLink = new CitadelLink(TransportType.WebUsb);
// Or using Bluetooth
// const citadelLink = new CitadelLink(TransportType.Bluetooth);

Note: Bluetooth support hasn't been fully tested yet.

Getting the Wallet Public Key

try {
  const publicKey = await citadelLink.getWalletPublicKey();
  
  console.log('Wallet Public Key:', publicKey.toString('hex'));
} catch (error) {
  console.error('Error getting wallet public key:', error);
}

Signing a Message with the Wallet Key

try {
  const message = new Uint8Array([/* your message data here */]);
  const signature = await citadelLink.signWithWalletKey(message);
  
  console.log('Signature:', Buffer.from(signature).toString('hex'));
} catch (error) {
  console.error('Error signing message:', error);
}

Closing the Connection

If you want to close the connection to the device, you can call the appropriately-called close() method:

await citadelLink.close();

API Reference

CitadelLink Class

The main class for interacting with Citadel hardware devices.

Static Methods

getSupportedTransports(): Promise<SupportedTransportResolution[]>

Returns an array of objects containing information about which transport methods are supported in the current environment.

Constructor

constructor(transportType: TransportType)

Creates a new CitadelLink instance with the specified transport type.

• transportType: The type of transport to use (WebUsb or Bluetooth)

Instance Methods

close(): Promise<void>

Closes the connection to the device.

getWalletPublicKey(): Promise<Buffer>

Retrieves the wallet's public key from the device.

signWithWalletKey(msg: Uint8Array): Promise<Uint8Array>

Signs a message using the wallet's private key.

• msg: The message to sign as a Uint8Array

TransportType Enum

Defines the available transport types:

• WebUsb: For USB connections
• Bluetooth: For Bluetooth connections

SupportedTransportResolution Interface

Describes the support status of a transport type:

interface SupportedTransportResolution {
  transport: TransportType;
  supported: boolean;
}

Error Handling

The SDK throws errors in various scenarios:

• When an unsupported transport type is specified
• When connection to the device fails
• When device operations fail

Always wrap your CitadelLink operations in try/catch blocks to handle these errors gracefully.