Hedera Custodians Library

Introduction

The Hedera Custodians Library is a TypeScript utility that simplifies custodial wallet management and account operations for the Hedera network. It provides a foundation for building secure, scalable custodial integrations in TypeScript applications.

Key Features

• Simplifies integration with the Hedera network

• Abstracts away complexities of custodial wallet management

• Provides a unified interface for different custodial services

• Enhances security and compliance in digital asset management

By leveraging the Hedera Custodians Library, developers can efficiently implement secure and scalable custodial wallet solutions in their Hedera-based applications.

---

Custodial Wallet Management

Custodial wallet management is the practice of a third party being trusted with storage and security concerning the private keys that are associated with the cryptocurrency. Within the Hedera ecosystem, custodial wallet management is essential for the following reasons:

• Security: Custodial services have robust security and safety mechanisms to maintain digital assets.

• Institutional Adoption: Many institutional investors require custodial solutions to comply with regulatory requirements and internal risk management policies.

• Simplified User Experience: Custodial services may abstract the complexities of key management, making the user's interaction with the Hedera network much easier.

• Integration with Traditional Finance: This often bridges cryptocurrency and traditional finance, furthering adoption.

• Multi-signature Support: It can be done in various ways through custodial implementations with multi-signature wallets, which contribute to higher security and make more complex governance structures possible.

• Regulatory Compliance: Custodial services typically have some in-built compliance features to assist users in conforming to KYC/AML.

The Custodians Library makes it easier to integrate custodial services, providing access to these benefits without custom implementations. It currently supports two providers: Fireblocks and DFNS.

---

Fireblocks

If you’re integrating Fireblocks, use the official Fireblocks Hedera SDK Client and Signer, which implements HIP-338. It provides a drop-in Hedera Client and a signer for raw-signing via Fireblocks, plus examples for single and multi-signer flows.

In the context of the Hedera ecosystem:

• Secure Storage: HBAR is stored securely on Fireblocks alongside Hedera tokens, using a combination of MPC (Multi-Party Computation) technology and hardware isolation.

• Securing Transactions: It offers a policy engine that enables the setup of custom approval flows for every transaction conducted on the Hedera network.

• Integration: Fireblocks can be integrated into the Hedera network, allowing seamless transactions with Hedera-based assets and their custodial management.

• API Access: The Hedera Custodian Library has full access to the API, which it uses for wallet automation and signing transactions.

⚠️ This Custodians Library remains compatible with Fireblocks via its FireblocksConfig strategy in the Custodians Integration package (@hashgraph/hedera-custodians-integration). However, the official SDK Client/Signer is the recommended path for new builds.

DFNS

DFNS (Digital Financial Network & Security) is a custodial wallet infrastructure provider that offers MPC-based key management and transaction signing services. In the Hedera ecosystem:

• Key Management: DFNS provides secure key generation and management for Hedera accounts without exposing private keys.

• Programmable Authorization: It offers customizable authorization policies for Hedera transactions, enabling complex approval flows.

• Multi-Tenancy: DFNS supports multi-tenant architectures, allowing businesses to manage multiple Hedera accounts for different users or purposes.

• API-First Approach: The service provides RESTful APIs that the Hedera Custodian Library uses to interact with Hedera accounts and sign transactions.

Both Fireblocks and DFNS provide secure, compliant custodial solutions. By supporting these providers, the Custodians Library gives developers a unified interface for managing custodial wallets on Hedera.

---

API Reference

CustodialWalletService

The CustodialWalletService class is the main entry point for interacting with custodial wallets.

Constructor

constructor(config: FireblocksConfig | DFNSConfig)

Creates a new instance of the CustodialWalletService with the specified configuration.

Methods

async signTransaction(request: SignatureRequest): Promise<Uint8Array>

Signs a transaction using the configured custodial service.

• Parameters:

  • request: A SignatureRequest object containing the transaction to be signed.

• Returns: A Promise that resolves to a Uint8Array containing the signature.

FireblocksConfig

The FireblocksConfig class represents the configuration for the Fireblocks custodial service. This configuration is used to initialize the CustodialWalletService for Fireblocks integration.

Constructor

constructor(
  apiKey: string,
  apiSecretKey: string,
  baseUrl: string,
  vaultAccountId: string,
  assetId: string
)

Creates a new FireblocksConfig instance.

Properties

• apiKey: The API key for Fireblocks.

• apiSecretKey: The API secret key for Fireblocks.

• baseUrl: The base URL for the Fireblocks API.

• vaultAccountId: The Fireblocks vault account ID.

• assetId: The asset ID for the Hedera token in Fireblocks.

DFNSConfig

The DFNSConfig class represents the configuration for the DFNS custodial service.

Constructor

constructor(
  serviceAccountAuthorizationToken: string,
  serviceAccountCredentialId: string,
  serviceAccountPrivateKey: string,
  appOrigin: string,
  appId: string,
  walletId: string
)

Creates a new DFNSConfig instance.

Properties

• serviceAccountAuthorizationToken: The authorization token for the DFNS service account.

• serviceAccountCredentialId: The credential ID for the DFNS service account.

• serviceAccountPrivateKey: The private key for the DFNS service account.

• appOrigin: The origin URL of the DFNS app.

• appId: The ID of the DFNS app.

• walletId: The ID of the DFNS wallet.

SignatureRequest

The SignatureRequest class represents a request to sign a transaction.

Constructor

constructor(transactionBytes: Uint8Array)

Creates a new SignatureRequest instance.

Properties

• transactionBytes: A Uint8Array containing the transaction bytes to be signed.

How to Use the Hedera Custodians Library

See the How-To Guides for integration steps with each provider.