Skip to main content

Read-only wallets for integrated systems

Introduction​

This article explains the functioning of the read-only wallets features for an integrated system. Understanding this functioning is essential to implement read-only wallets into a use case.

Glossary​

These terms are used throughout this article:

  • User is any individual or organization that interacts with a blockchain system or benefits from its utilization.

  • Integrated system is any system already integrated with Hathor system.

  • Wallet is an abstract entity in blockchain technology that enables users to transact — i.e., to read, write, and manage their blockchain transactions. In practical terms, a wallet acts as a decentralized account on the ledger.

  • Wallet application is an application that implements wallets for one or multiple blockchains.

  • Headless wallet is a wallet application whose interface is an API.

  • Hathor headless wallet is the official headless wallet of Hathor, intended to integrate external systems with Hathor Network.

Context​

To interact with a blockchain, an integrated system needs to implement a wallet system. A wallet system comprises all software and hardware components one uses to manage its wallets on Hathor blockchain. In the simplest case, such wallet system may be just a single instance of a wallet application — either Hathor headless wallet, or any other proprietary or third-party wallet application that supports the read-only wallets feature — operated by the organization itself in its integration environment.

However, an organization may decide to use read-only wallets in its wallet system to strengthen the protection of its private keys. In this scenario, the wallet system will be composed of more than just a single instance of a wallet application. In the following sections, we will explain the architecture of such wallet system and the process of a new transfer using it.

Architecture of a wallet composite system​

A composite wallet system is a wallet system composed of more than one component — for example, a person using a desktop wallet application to create the transactions along with a hardware wallet device to sign the transactions.

Architecture overview​

The following diagram presents the wallet system's architecture for an organization using the read-only wallets feature:

Wallet system architecture with read-only mode component

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

Once an organization decides to use the read-only wallet feature, its wallet system can no longer be composed of a single component. Its wallet system needs at least two components: (1) a read-only wallet module; and (2) a secure module.

Read-only module​

The read-only module is an instance of a wallet application that starts all integrated system's wallets in read-only mode — and stores their respective extended public keys. This component of the wallet system will be used to perform all wallet interactions except for signing transactions.

Since this instance of wallet application does not store any private key, it is not necessary to fulfill private-key protection requirements in the environment where it runs.

Secure module​

The secure module may be a hardware wallet, a KMS (key management system), or a mix of these alternatives. The KMS may be self-custodial or a third-party service that provides custody of keys, such as provided by AWS and Azure.

Regardless of the composition of the secure module, its primary functions are the same:

  1. Store the private keys
  2. Sign all transactions

More importantly, the secure wallet module runs in a different environment that fulfills all security requirements to protect the private keys.

Transaction process of a wallet composite system​

The following sequence diagram presents an overview of the process of an integrated system (Alice) creating a transaction with her wallet composite system, where read-only wallets plays a key role:

Transaction process of a wallet composed system

Overview of the process​

In the previous diagram, we see a wallet system composed of two components: (1) Hathor headless wallet as the wallet application; and (2) a KMS. Hathor headless wallet is in the role of the read-only module whereas the KMS is in the secure module role. Alice is the integrated system who owns such wallet composite system.

Alice uses the read-only wallet to create the transaction, append the signatures to it, and submit it to Hathor Network. The only step that Alice cannot do with the read-only wallet is to sign the transaction. To do it, she uses her secure module, i.e., her KMS.

Process details​

In this section, we describe step-by-step the previous diagram. All communication we see between Alice and her software components — namely, Hathor headless wallet and KMS — happens through HTTP APIs:

  1. Alice uses her extended public key in an API request to start a wallet in read-only mode.
  2. Her wallet application (Hathor headless wallet) replies that the started wallet is ready to be used.
  3. Alice requests to create a transaction.
  4. Her wallet application replies with two relevant data: (i) the unsigned transaction and (ii) the data that will be used to generate the input signature. Generate the input signature is precisely what her wallet application in read-only mode cannot do. She will then need to request it to her KMS.
  5. But first, she will request again her wallet application for the input data of each UTXO that needs to be spent.
  6. The wallet application will then provide her with the data of all inputs at once.
  7. She will request her KMS to sign the authorization to spend the UTXO of the first, providing the UTXO's address path and unsigned authorization to be spent.
  8. The KMS replies with the signature to spend the first UTXO. This was the only step that Alice could not do with her wallet application using the read-only wallet.
  9. With this signature in her hands, she now uses her wallet application again (always in read-only mode) to generate signed data of the first input.
  10. Her wallet replies with the signed input data. She then repeats steps 7 to 10 for each input in the transaction.
  11. With all signed inputs, she uses her wallet to append all signed input data into the unsigned transaction.
  12. And then, her wallet application replies with the transaction now signed.
  13. Finally, she uses the wallet application to submit the transaction to Hathor Network.
  14. The wallet application submits the transaction to one of the Hathor full nodes it connects, and as soon it receives a response, it forwards it to Alice.

To see the code to implement this process, see Read-only wallets on headless wallet.

Key takeaways​

In this article, we explained that:

  • A wallet composite system comprises at least two components: one works in read-only mode and does almost all wallet functionalities, whereas the other stores the private keys and signs transactions.
  • To perform a transfer using the described wallet composite system, one can create a transaction with a read-only wallet module, use a segregated module to sign the transaction, and use again the read-only module to append signatures into the transaction, and finally submit it to Hathor Network.

What's next?​