Skip to main content

Hathor headless wallet troubleshooting

1. Error Message: Reached maximum number of subscribed addresses without output​

This error indicates that the maximum number of addresses without transactions has been reached. Under the hood, the full node counts every empty address that was requested, even if they were not generated consecutively. Empty addresses are derived up to the limit defined by the WS_MAX_SUBS_ADDRS_EMPTY param. When such a threshold is reached, the referred error is thrown. Two main actions can be taken:

    1. Use the default value of the gapLimit parameter in the wallet headless.
    1. Set the gapLimit parameter with the number of addresses to be generated in sequence without usage in the config.js file of the wallet headless. In this case, if you are not running your own full node, it must also be done. A detailed roadmap of how to run a full node locally is available in the sections Running in Docker and Running from Source Code of the Full Node guide. For running the full node, set the WS_MAX_SUBS_ADDRS_EMPTY param with the same value of the GAP limit pointed out to the wallet headless. More details about how to run a full node with a custom configuration are available in the section Custom Configuration of the Full Node guide.

A more complete explanation of the gap limit may also be found in the Gap Limit entry of the Fundamentals section.

2. Timeout solving transaction's proof-of-work. All transactions need to solve a proof-of-work as an anti-spam mechanism. Currently, Hathor Labs provides this service for free, but their servers may be fully loaded right now.​

This error can be generated if you are trying to send a transaction and the transaction mining service is fully loaded at that time. In that case, you should wait a little longer before trying to resend the transaction. On the other hand, if you are trying to send multiple transactions, allow more time between each transaction.

3. Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at /$someEndpoint. (Reason: CORS header ‘Access-Control-Allow-Origin’ missing). Status code: 404.​

Cross-Origin Resource Sharing (CORS) is an HTTP-header-based mechanism that allows a server explicitly accept some cross-origin requests while rejecting others according to a same-origin policy. In other words, through this standard, a server can indicate which origins, in addition to its own, a browser should allow the loading of resources.

info

The same-origin policy is a critical security mechanism that restricts how a document or script loaded by one origin can interact with a resource from another origin. It helps isolate potentially malicious documents. An origin is the tuple (protocol, host, port) of each URL. So, http://hathor.gitbook.io and http://hathor.network correspond to two different origins as the corresponding tuples are not the same.

The root of that error lies in the headers exchanged in HTTP requests/responses. A typical HTTP communication involves client A sending requests (/data, for example) to server B

GET /data HTTP/1.1
Host: B.com
Origin: http://A.com
...

which, in turn, sends responses to client A.

HTTP/1.1 200 OK
...
Access-Control-Allow-Origin: http://A.com

Note that in the request, client A sends, among other data, two headers: Host and Origin. Server B's response also contains a specific header: Access-Control-Allow-Origin. This header tells which origins are allowed to have requests processed on the server. In that example, the browser will allow code running on A client to access the response because the headers Origin (from the request) and Access-Control-Allow-Origin (from the response) match.

info

The Access-Control-Allow-Origin header is included in the response from one server to a request originating from another server and identifies the permitted origin of the request. A web browser compares the Access-Control-Allow-Origin with the requesting website's origin and permits access to the response if they match.

When Origin and Access-Control-Allow-Origin headers of an HTTP communication do not match, a CORS error is reported on the browser and the response is not processed. A message like the one shown in this 4th troubleshooting item is displayed in the browser console.

This is what happens when a browser sends a request directly to the wallet headless: Origin and Access-Control-Allow-Origin headers do not match and a CORS error is reported. The reason is that the headless wallet does not add the Access-Control-Allow-Origin header to the response it sends to a client.

A common way to overcome this issue is by introducing a reverse proxy between the browser and the wallet headless communication. Even though any proxy solution can be used, the NGINX is one of the most used solutions for this. After installing it, the following configuration must be added to the default file located in the /nginx/sites-enabled/default/ folder. Note that this configuration assumes that the wallet headless is running on localhost and port 8000.

 location / {
        proxy_pass http://localhost:8000;

        set $allow_origin '*';
        set $http_methods 'GET, POST, OPTIONS';
        set $allow_headers 'X-Wallet-Id,DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';

        if ($request_method = 'OPTIONS') {
                add_header 'Access-Control-Allow-Origin' $allow_origin;
                add_header 'Access-Control-Allow-Methods' $http_methods;
                add_header 'Access-Control-Allow-Headers' $allow_headers;
                add_header 'Access-Control-Max-Age' 1728000;
                add_header 'Content-Type' 'text/plain; charset=utf-8';
                add_header 'Content-Length' 0;
                return 204;
        }

        if ($request_method = 'POST') {
                add_header 'Access-Control-Allow-Origin' $allow_origin;
                add_header 'Access-Control-Allow-Methods' $http_methods;
                add_header 'Access-Control-Allow-Headers' $allow_headers;
                add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
        }

        if ($request_method = 'GET') {
                 add_header 'Access-Control-Allow-Origin' $allow_origin;
                 add_header 'Access-Control-Allow-Methods' $http_methods;
                 add_header 'Access-Control-Allow-Headers' $allow_headers;
                 add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
        }
}

Some important considerations about these settings:

  • Access-Control-Allow-Origin: The header specification header allows for multiple origins, the null value, or the wildcard *. The wildcard indicates any client can get cross-origin resources.
  • Access-Control-Allow-Headers: The most common headers have been defined. However, the X-Wallet-Id is the only header specific to the wallet headless.

By adding this configuration to NGINX, every request to the port it is listening to will be forwarded to the wallet headless. Besides, for each response it receives from the wallet, it will add a set of headers depending on the HTTP method invoked. For example, suppose a client running on server A requests the balance of its wallet whose id is "wallet-A" to the wallet headless running on server B along with an NGINX proxy between them. The NGINX proxy will receive an HTTP request such as:

GET /wallet/balance HTTP/1.1
Host: B.com
Origin: http://A.com
X-Wallet-Id: wallet-A
...

NGINX proxy will forward this request to the wallet headless listening on port 8000. After processing the request, the wallet sends a response to the proxy. As this communication involves a GET HTTP method, the proxy adds 4 complimentary headers including the Access-Control-Allow-Origin.

HTTP/1.1 200 OK
...
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: 'X-Wallet-Id,...'

After receiving the response, the client browser checks all response headers and allows the wallet balance information to be rendered. No CORS errors are reported in this HTTP communication.