Getting addresses
Getting addresses from the wallet.
Parameters
- x-wallet-id: Wallet identifier.
Request
curl -X GET -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/address/
Response
{"address":"H8bt9nYhUNJHg7szF32CWWi1eB8PyYZnbt"}
Addresses Differentiation
The wallet holds in memory a newly generated address until a transaction is associated with it. Hence, before the first transaction, every HTTP request will return the same address. For forcing the generation of a new address for each request, the query parameter mark_as_used must be informed in the URL.
curl -H "X-Wallet-Id: {wallet-id}" "http://localhost:8000/wallet/address?mark_as_used=true"
After reaching the threshold of addresses with no transactions in a row defined by the gapLimit parameter, the wallet keeps returning the same last generated address.
It is also possible to retrieve all addresses until the limit defined by the gapLimit parameter. In this case, the endpoint is addresses.
curl -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/addresses
Increasing the gap limit value may directly impact the headless wallet performance. Check the notes about its configuration.
Use Case Considerations
Addresses Assignment
The addresses generation may be impacted by the gap limit parameter depending on the moment addresses are assigned to users.
- If every new user receives a new address by the moment of its registering, there is the potential of a considerable number of no transaction addresses being generated. In this case, new addresses will be derived up to the gap limit threshold. After that, the HD wallet will return the same last address with no transaction unless one of the generated addresses has at least one transaction associated with it.
- If a new address is generated for a user only after his first transaction, the addresses generation step will not be impacted by the gap limit parameter.
More information about the gap limit is available in the foundations section.
Addresses Validation
Checking if a newly generated address is already assigned to a user may be necessary depending on the dynamic of HD wallet use.
- If new addresses are not generated with the parameter
mark_as_used, two users may receive the same address. In this case, validating if an address already belongs to a user is required to avoid output transactions errors. - Since the wallet holds newly generated addresses in memory, its restart may lead to the generation of empty addresses already previously generated even those ones generated with the parameter
mark_as_used. To avoid different users sharing the same address, a validation of addresses in use may be required.
Addresses that already received transactions are stored directly in the blockchain and not in the wallet's memory. Hence, a wallet restart does not cause those addresses to be repeatedly returned by the wallet.
Addresses Management
To better understand how a wallet manages addresses in memory, let's assume a wallet with the following current addresses configuration:
| Index | Address | Transactions Received |
|---|---|---|
| 0 | H893wtKJRG22rQdrvtXiwKnhRecLEMkXyv | 3 |
| 1 | HPvkeYZMVrAJKWFj4oNhaSz8skVv5WveGt | 0 |
| 2 | HPSuKkLKCzV92UteAGkG2WVcRczyt3AtVP | 1 |
| 3 | HFRu5zxjF7sGu8MjLkhKcM1eQXvYc7LivD | 0 |
| 4 | HPveFSSye1Yd26SpykWdgongzB9Zjqkssf | 0 |
| 5 | H8hJPNAJ3wydFevPVL9uGriEVpChXZwkZB | 0 |
Considering that configuration, a sequence of 6 operations is performed and each respective response returned by the wallet is presented below.
(1) Getting an address: When requesting a new address through the /wallet/address endpoint, the wallet will return the first empty address (with no associated transactions) after the last non-empty one (the address of index 2).
Request
curl -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/address
Response
HFRu5zxjF7sGu8MjLkhKcM1eQXvYc7LivD
(2) Getting an address: A new address request (/wallet/address) causes the wallet to re-search the first empty address immediately after the last one with associated transactions. As the address returned by the last request remains without associated transactions, it is returned again.
Request
curl -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/address
Response
HFRu5zxjF7sGu8MjLkhKcM1eQXvYc7LivD
(3) Getting an address with **mark_as_used**: As previously described, an address request that passes the mark_as_used parameter (/wallet/address?mark_as_used=true) forces the wallet to return a new empty address on a subsequent new address request. In other words, in this address request, the wallet will search by the first empty address after the last non-empty one and return it as a response to the request. But, as the mark_as_used parameter was informed, that address will be set as used in memory so that a new address request causes the wallet look for the next empty address to be returned. Thus, to fulfill this current request, the following address is returned.
Request
curl -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/address?mark_as_used=true
Response HFRu5zxjF7sGu8MjLkhKcM1eQXvYc7LivD
(4) Getting an address: The first empty address after the last one with any associated transactions was returned in the previous address request (the address of index 3). Also, that last returned has been set as used. So, in this new address request, that address will be seen as non-empty and the wallet will look for the next empty address after it. Thus, the address of index 4 is returned.
Request
curl -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/address
Response
HPveFSSye1Yd26SpykWdgongzB9Zjqkssf
(5) Restarting the wallet and getting an address: When restarting the wallet, all information held by it in memory is lost. It includes the information that the index 3 address has been marked as used. But, note that any information previously saved in the blockchain is not affected. For example, all addresses with transactions associated remain as non-empty addresses - this is the case of addresses of indexes 2 and 3). Thus, the addresses configuration will return to its initial state. When requesting a new address after this restart, the wallet will look for the first empty address after the last non-empty one and find the address of index 3 again.
Request
curl -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/address
Response
HFRu5zxjF7sGu8MjLkhKcM1eQXvYc7LivD
(6) Receiving a transaction and getting an address: Let's assume that the address at index 4 has received a transaction. In this case, it becomes the last non-empty address of the wallet. Thus, when a new address is requested, the wallet will look for the first empty address after that one and find the address of index 5.
Request
curl -H "X-Wallet-Id: {wallet-id}" http://localhost:8000/wallet/address
Response
H8hJPNAJ3wydFevPVL9uGriEVpChXZwkZB
The final addresses configuration after performing these 6 operations is as follows.
| Index | Address | Transactions Received |
|---|---|---|
| 0 | H893wtKJRG22rQdrvtXiwKnhRecLEMkXyv | 3 |
| 1 | HPvkeYZMVrAJKWFj4oNhaSz8skVv5WveGt | 0 |
| 2 | HPSuKkLKCzV92UteAGkG2WVcRczyt3AtVP | 1 |
| 3 | HFRu5zxjF7sGu8MjLkhKcM1eQXvYc7LivD | 0 |
| 4 | HPveFSSye1Yd26SpykWdgongzB9Zjqkssf | 1 |
| 5 | H8hJPNAJ3wydFevPVL9uGriEVpChXZwkZB | 0 |