Read-only Wallets for Integrated Systems

This article explains how to use read-only wallets in an integrated system.

It is intended for developers and teams building systems that need to interact with Hathor Network while keeping private keys isolated from the main application environment.

You will learn:

• how a read-only wallet fits into an integrated system;
• which components are required;
• what each component is responsible for;
• how a transaction is created, signed, and submitted;
• what data needs to move between the wallet application and the signing module; and
• what to consider before implementing this architecture.

TL;DR: see Key takeaways.

Context

To interact with Hathor Network, an integrated system needs a wallet system.

A wallet system is the set of software and hardware components used to manage wallets, create transactions, sign transactions, and submit them to the network.

In the simplest setup, the wallet system can be a single wallet application, such as Hathor headless wallet, running in the organization's own infrastructure.

However, this simple setup means the same environment that creates and submits transactions may also have access to private key material. For some integrations, this is not desirable.

Read-only wallets solve this by separating the wallet system into at least two parts:

1. A read-only module, which can inspect wallet data and prepare transactions.
2. A secure module, which stores private key material and signs transactions.

This separation allows the main application environment to operate without direct access to private keys.

Composite Wallet System Architecture

A composite wallet system is a wallet system composed of more than one autonomous component.

For example, a user may create a transaction in a desktop wallet but sign it with a hardware wallet. In this case, the desktop wallet prepares the transaction, while the hardware wallet protects the private key and produces the signature.

The same idea applies to integrated systems.

Architecture overview

The following diagram shows an example architecture for an organization using read-only wallets:

Credits: icons created by Med Marki, Rendicon, and Jaime Serra from the Noun Project.

A composite wallet system using read-only wallets has at least two modules:

Module	Main responsibility	Has private keys?	Typical implementation
Read-only module	Read wallet data, create unsigned transactions, append signatures, and submit signed transactions	No	Hathor headless wallet running in read-only mode
Secure module	Store private key material and sign transaction inputs	Yes	Hardware wallet, KMS, custody provider, or internal signing service

The read-only module is usually exposed to the integration backend. The secure module should run in a more restricted environment, because it handles private key material.

Read-only Module

The read-only module is the component responsible for wallet operations that do not require private keys.

In a Hathor integration, this module is commonly implemented with Hathor headless wallet running in read-only mode.

The read-only module stores or receives the wallet's extended public key. With this information, it can derive addresses and inspect wallet activity, but it cannot sign transactions.

The read-only module can usually be responsible for:

• loading wallets in read-only mode;
• deriving wallet addresses;
• checking balances;
• listing transaction history;
• preparing unsigned transactions;
• collecting input metadata required for signing;
• appending signed input data to a transaction;
• submitting signed transactions to Hathor Network.

Because this module does not store private keys, it does not need the same level of private-key protection as the secure module. However, it should still be protected as part of the production infrastructure, because it can prepare and submit transactions.

Secure Module

The secure module is responsible for protecting private key material and generating signatures.

This module may be implemented as:

• a hardware wallet;
• a key management system;
• a custody provider;
• an internal signing service;
• or a combination of these options.

A KMS may be self-managed or provided by a third-party cloud provider or custody platform.

Regardless of the implementation, the secure module has two primary responsibilities:

1. Store private key material securely.
2. Sign transaction inputs when a valid signing request is received.

The secure module should run in an environment designed for private-key protection. It should validate every signing request before producing a signature.

For example, before signing, the secure module may check:

• whether the request came from an authorized service;
• whether the transaction matches an approved business rule;
• whether the amount is within allowed limits;
• whether the destination address is allowed;
• whether the address path belongs to the expected wallet;
• whether the request has already been processed.

warning

The secure module should not blindly sign every request it receives.

A read-only wallet can prepare transaction data, but the secure module is responsible for deciding whether that transaction should be signed.

Transaction Process

The following sequence diagram shows how an integrated system creates a transaction using a read-only wallet and a separate signing module:

Process Overview

In this example, the wallet system has two components:

1. Hathor headless wallet, acting as the read-only module.
2. A KMS, acting as the secure module.

The integrated system uses the read-only module to create the transaction, prepare the input data, append signatures, and submit the transaction to Hathor Network.

The only operation the read-only module cannot perform is signing. For that, the integrated system sends signing requests to the secure module.

At a high level, the process is:

1. Load the wallet in read-only mode.
2. Create an unsigned transaction.
3. Retrieve the input data required for signing.
4. Ask the secure module to sign each required input.
5. Generate signed input data.
6. Append all signed input data to the transaction.
7. Submit the signed transaction to Hathor Network.

Step-by-step Transfer Flow

The following steps describe the full transaction flow.

1. Load the wallet in read-only mode

The integrated system starts the wallet using the wallet's extended public key.

At this point, the wallet application can inspect wallet data, but it cannot sign transactions.

Integrated system → Read-only module:
Start wallet with extended public key

Read-only module → Integrated system:
Wallet loaded and ready

2. Create an unsigned transaction

The integrated system asks the read-only module to create a transaction.

The read-only module selects the required inputs and prepares the transaction, but the transaction is still unsigned.

Integrated system → Read-only module:
Create transaction

Read-only module → Integrated system:
Unsigned transaction
Data required to generate input signatures

The response should include the unsigned transaction and the data that will later be used by the secure module to generate signatures.

3. Retrieve input information

Before signing, the integrated system needs the input data for each UTXO that will be spent.

Integrated system → Read-only module:
Get input data for the transaction

Read-only module → Integrated system:
Array of input information

Each input usually needs enough information for the secure module to verify and sign the spending authorization.

4. Sign each input with the secure module

For each input, the integrated system sends a signing request to the secure module.

Integrated system → Secure module:
Sign input authorization

Secure module → Integrated system:
Signature for input

The request should include the required signing payload and the address path associated with the input.

The secure module validates the request and returns the signature.

5. Generate signed input data

After receiving the signature, the integrated system sends it back to the read-only module.

The read-only module uses the signature to generate the signed input data expected by the transaction.

Integrated system → Read-only module:
Generate signed input data using signature

Read-only module → Integrated system:
Signed input data

This step is repeated for each input in the transaction.

6. Append signatures to the transaction

After all inputs are signed, the integrated system sends the signed input data to the read-only module.

Integrated system → Read-only module:
Append signed input data to unsigned transaction

Read-only module → Integrated system:
Signed transaction

The transaction is now ready to be submitted to Hathor Network.

7. Submit the signed transaction

Finally, the integrated system asks the read-only module to submit the signed transaction.

Integrated system → Read-only module:
Submit signed transaction

Read-only module → Hathor Network:
Broadcast transaction

Read-only module → Integrated system:
Transaction submission result

The read-only module forwards the signed transaction to a Hathor full node and returns the network response to the integrated system.

To see the code for this process, see Use a wallet in read-only mode.

Implementation Checklist

Before implementing read-only wallets in an integrated system, make sure you have defined the following pieces.

Wallet Configuration

You need to know:

• how the extended public key will be provided to the read-only module;
• how wallets will be identified by the integrated system;
• whether the read-only module will manage one wallet or multiple wallets;
• how wallet state will be initialized and monitored.

Signing Flow

You need to define:

• what payload the secure module receives for each input;
• how the secure module validates the signing request;
• how address paths are mapped to private key material;
• how signatures are returned to the integration backend;
• how failed signing attempts are handled.

Security Controls

You should define:

• which services can request signatures;
• whether signing requests require authentication;
• whether signing requests require approval;
• which transaction limits apply;
• which destination addresses are allowed;
• how signing activity is logged and audited;
• how replayed or duplicated signing requests are detected.

Operational Behavior

You should also decide:

• how errors are retried;
• how partially signed transactions are handled;
• how transaction submission failures are reported;
• how the system monitors wallet balances;
• how the system alerts operators about signing or submission failures.

Practical Implementation Notes

When implementing this architecture, keep the following points in mind.

Keep transaction creation and signing separate

The read-only module should create and prepare transactions, but it should not have access to private keys.

The secure module should sign only after validating the signing request.

Treat signing as a critical operation

Signing is the only step that authorizes spending. For this reason, the secure module should apply stricter security controls than the read-only module.

Validate the transaction before signing

The secure module should verify that the signing request matches the expected transaction policy.

For example, it may validate the destination address, amount, token, address path, and request origin before returning a signature.

Log every signing request

Every signing request should be traceable.

Useful audit fields include:

• request ID;
• wallet identifier;
• input index;
• address path;
• destination address;
• amount;
• token;
• requesting service;
• approval status;
• timestamp.

Handle each input explicitly

A transaction may have multiple inputs. The integration should expect to repeat the signing flow for each input that needs a signature.

Key takeaways

In this article, we covered that:

• A composite wallet system separates wallet operations across multiple components.
• The read-only module loads wallets from extended public keys and performs operations that do not require private keys.
• The secure module stores private key material and signs transaction inputs.
• Hathor headless wallet can be used as the read-only module in an integrated system.
• The secure module may be implemented with a hardware wallet, KMS, custody provider, or internal signing service.
• To perform a transfer, the integrated system creates an unsigned transaction, signs each input through the secure module, appends the signed input data, and submits the final transaction to Hathor Network.
• The secure module should validate every signing request before producing a signature.

What's next?

• About read-only wallets: understand what read-only wallets are, what problems they solve, and how they work on Hathor.

• Use a wallet in read-only mode: follow a hands-on tutorial to implement the read-only wallet flow with Hathor headless wallet.

• Hathor headless wallet HTTP API reference: consult the API reference while building integrations with Hathor headless wallet.