Understanding the wallet identifier
The wallet ID concept correlates headless wallet service and wallets. The headless wallet is the underlying Hathor service upon which wallets are instantiated. A wallet is an application that serves as the primary user interface controlling access to tokens, managing keys and addresses, tracking the balance, and creating and signing transactions.
Recall that to start a headless wallet service and create a wallet, a 24-word seed is required - the user's private key. Thus, the headless wallet service is able to generate a distinct wallet from each seed. Although there is no restriction on starting multiple wallets from just a single seed, it is imperative to keep in mind that all wallets instantiated from the same seed actually correspond to the same wallet. On the other hand, it is of keen importance to note that if different passphrases are used to create wallets from the same seed, what will be generated are, in fact, utterly different wallets.
Wallets started from the same 24-word seed mean they share the same set of blockchain addresses. Thereby, they control the same tokens, track the same balance, and can interchange the creation and signing of transactions.
As a user can create as many as wallets he wants (from multiple seeds or from the same one) by starting a headless wallet service, there is a one-to-many relation between a headless wallet service and wallet instances. Consequently, the headless wallet must have a way to identify each created wallet. In fact, since it is responsible for managing transactions between wallets, it must know which wallet is starting each transaction. This is met by the X-Wallet-Id parameter supplied during a wallet creation. The next figure describes this architecture.
Headless Wallet Service Managing Multiple Wallets.
Note that two distinct wallets, each one associated with its unique X-Wallet-Id, were created from the headless wallet service: the wallet-A and the wallet-B. Assume that two distinct seeds were used to generate the wallets.
The Figure depicts the headless service managing three transactions:
wallet-A sending tokens to the wallet-B: Every transaction must contain, among other information, the destination addresses to which it is transferring tokens - in this case, Addr-B2. However, since the headless wallet can manage multiple wallets, it must know which wallet the tokens will be transferred from. To do so, it inspects the request header and looks for the X-Wallet-Id of the wallet that started the transaction - in this case, the wallet-A.
Note the source address is not required in a transaction. As the headless wallet service knows the wallet initiating a transaction, it will use an internal strategy to select the UTXOs to use in the transaction. Nevertheless, there may be scenarios where the tokens of a transaction must be transferred from a specific address. In such cases, a UTXO filter can be used to select that addresses.
wallet-B sending tokens to the wallet-A: Analogously, wallet-B must inform its own X-Wallet-Id and addresses (in this case, just Addr-A5) that will receive the tokens.
wallet-B sending tokens to a third-party wallet: Wallets started from the headless wallet service can exchange tokens (send/receive) with any other wallet - whether created from another headless wallet instance or even a third party. The transaction runs in the same way: the source wallet informs its X-Wallet-Id - in this case, wallet-B - and the destination address (Addr-C1).
Wallet ID in Practice
To better analyze the wallet ID in practice, let's map the fake addresses from the figure above to valid Hathor addresses:
- (wallet-A) Addr-A5 : HKrn2NVRqzo7oNhQdu5T4b3PxFS1h8uE1m
- (wallet-B) Addr-B2 : HQj8WrQdq9T7iRifsfZx4qRYe1v8nUbJ5f
- (third-party wallet) Addr-C1 : H9wG5Mvc7x8DHFRhsV1BZ4mLKHgYK7QMNJ
In all transactions below, the X-Wallet-Id of the respective wallet that starts the transaction is informed as a header of the HTTP request. The destination address and tokens to be transferred are defined in the request body.
wallet-A sending tokens to the wallet-B:
curl -X POST -H "X-Wallet-Id: wallet-A" \
--data "address=HQj8WrQdq9T7iRifsfZx4qRYe1v8nUbJ5f" --data "value=100" \
http://localhost:8000/wallet/simple-send-tx
wallet-B sending tokens to the wallet-A:
curl -X POST -H "X-Wallet-Id: wallet-B" \
--data "address=HKrn2NVRqzo7oNhQdu5T4b3PxFS1h8uE1m" --data "value=300" \
http://localhost:8000/wallet/simple-send-tx
wallet-B sending tokens to a third-party wallet:
curl -X POST -H "X-Wallet-Id: wallet-B" \
--data "address=H9wG5Mvc7x8DHFRhsV1BZ4mLKHgYK7QMNJ" --data "value=200" \
http://localhost:8000/wallet/simple-send-tx