Skip to main content

Read-only wallets

Read-only wallets allow applications to interact with a wallet without storing or using its private key.

In read-only mode, a wallet application can inspect balances, list transactions, prepare unsigned transactions, and submit signed transactions. However, it cannot sign transactions by itself because it does not have access to the wallet’s private key.

This makes read-only wallets useful for integrated systems that need blockchain visibility and transaction preparation, while keeping private keys isolated in a separate secure environment.

TL;DR: see Key takeaways.

What is a read-only wallet?​

A wallet application can load a wallet in two main modes:

  • Default mode: the wallet is loaded from private key material, such as a seed phrase.
  • Read-only mode: the wallet is loaded from public key material, such as an extended public key.

In default mode, the wallet application can access the private key material required to sign transactions. Because signed transactions can be submitted to the network, a wallet in default mode can write to the blockchain.

In read-only mode, the wallet application does not have access to the private key material. It can derive addresses, read balances, inspect transactions, and prepare transaction data, but it cannot produce valid signatures. Without signatures, it cannot authorize spending funds or performing actions that require ownership proof.

In short:

ModeLoaded fromCan read wallet data?Can sign transactions?Can write to the blockchain?
Default modeSeed phrase or private key materialYesYesYes
Read-only modeExtended public keyYesNoNot by itself

How does read-only mode work?​

The following diagram shows how read-only wallet mode works in a wallet application:

Read-only wallet mode

Credits: icons created by James Kopina, Jaime Serra, and Made x Made from the Noun Project.

Read-only mode is configured per wallet. This means a wallet application can support multiple wallets at the same time, with each wallet running in a different mode, as long as the application implements that behavior.

A read-only wallet is usually not useful as a standalone wallet system. Since it cannot sign transactions, it needs another component to approve and sign the transactions it creates. For this reason, read-only wallets are commonly used in composite wallet systems.

note

A wallet system is the full set of software and hardware components used to manage wallets on a blockchain.

In the simplest case, a wallet system is a single wallet application operated by the user. A composite wallet system is composed of more than one autonomous component, such as a wallet application and a separate signing module.

In a composite wallet system, one component loads the wallet in read-only mode and handles everyday wallet operations, while another component protects the private key material and signs transactions.

For example:

  1. The wallet application loads the wallet using the extended public key.
  2. The wallet application reads balances, lists transactions, and prepares an unsigned transaction.
  3. The unsigned transaction is sent to a secure signing component.
  4. The secure component signs the transaction using the private key material.
  5. The signed transaction is returned to the wallet application.
  6. The wallet application submits the signed transaction to the network.

To learn more about this architecture, see Functioning of read-only wallets for integrated systems.

What problems do read-only wallets solve?​

Read-only wallets help improve the security, usability, and flexibility of wallet systems.

The main benefit is private key protection. Since the wallet application does not need the private key material to operate in read-only mode, private keys can be isolated in a more secure environment.

This separation is useful when a system needs to:

  • reduce the exposure of private keys;
  • separate transaction creation from transaction signing;
  • integrate with a hardware wallet, custody service, or key management system;
  • allow an application to monitor balances without being able to spend funds;
  • support operational workflows where one system prepares transactions and another approves them.

A common use case is an integrated system where users interact with a wallet application that runs in read-only mode. The application can display balances and prepare transactions, but it must request signatures from a secure module before submitting transactions to the blockchain.

This design limits the risk of exposing private key material in the main application environment.

How to use read-only wallets on Hathor​

On Hathor, a wallet is usually started in default mode using the seed phrase that defines it.

To start a wallet in read-only mode, the wallet application uses the wallet's extended public key instead.

At the moment, among Hathor's official wallet applications — desktop, mobile, and headless wallet — read-only wallet support is available in Hathor headless wallet v0.19.2 or later.

Third-party wallet applications integrated with Hathor Network can add support for read-only wallets using Hathor wallet library v0.40.0 or later.

info

Use read-only mode when the application should inspect or prepare wallet activity without directly holding the private key material required to sign transactions.

Hathor's Read-only Wallets​

A wallet application running in read-only mode can perform every operation that does not require transaction signing, as long as the application implements support for that operation.

In general, a read-only wallet can:

  • Derive wallet addresses from the extended public key;
  • Read wallet balances;
  • Inspect wallet transaction history;
  • Create unsigned transactions;
  • Submit transactions that were already signed by another component.

However, it cannot:

  • Sign transactions;
  • Spend funds by itself;
  • Authorize operations that require private key ownership proof.

At the moment, Hathor headless wallet in read-only mode does not support creating the following transaction types for single-signature wallets:

  • create custom token;
  • mint token;
  • melt token.

Composite Wallet Systems​

To implement read-only wallets in a composite wallet system, you usually need two environments:

  1. Application environment: runs the wallet application with the wallet loaded in read-only mode.
  2. Secure signing environment: protects private key material and signs transactions.

The application environment handles regular wallet interactions. It can read blockchain data, display balances, create unsigned transactions, and submit signed transactions.

The secure signing environment handles private key operations. It receives unsigned transaction data, validates the signing request according to the system's rules, signs the transaction, and returns the signed transaction to the application environment.

The secure signing component may be implemented with:

  • Hardware wallets;
  • Key management systems;
  • Custody providers;
  • Internal signing service;
  • or a combination of these options.

This design is similar to using a desktop wallet together with a hardware wallet. The desktop wallet prepares the transaction, while the hardware wallet protects the private key and signs only after approval.

For more details, see Functioning of read-only wallets for integrated systems.

Key takeaways​

In this article, we covered that:

  • A read-only wallet is a wallet loaded into a wallet application without private key material.
  • On Hathor, read-only wallets are started from the extended public key instead of the seed phrase.
  • A read-only wallet can inspect wallet data and prepare unsigned transactions.
  • A read-only wallet cannot sign transactions or authorize spending by itself.
  • Read-only wallets are useful when private keys must be isolated from the main application environment.
  • In a composite wallet system, a separate secure component stores private key material and signs transactions.

What's next?​