Introduction

XSWD (XELIS Secure WebSocket DApp) is a secure protocol that utilizes WebSocket to exchange permissioned data between the wallet and a decentralized application.

The protocol acts as a proxy for the wallet JSON-RPC API, and each request made by an application must receive permission from the user. This enables a more secure and granular approach of controlling which functions get executed and what data can be accessed.

WebSockets enable real-time, bidirectional communication between web clients and servers, for direct communication, allowing to be notified of any event happening on the wallet.

In any case, the user can easily prevent any unauthorized access. Without this protocol, you would have to authorize full access to your wallet for interacting with any third-party application.

Moreover, XSWD openly proxies all daemon requests when the wallet is connected to a node. It provides developers with the ability to manage only one connection and swiftly access all the necessary blockchain information.

Read on below to delve deeper into the specifics.

Features and Benefits

• Elimination of RPC Bridge Dependency: XSWD eliminates the need for the RPC bridge browser extension.

• Secure dApp Interaction: XSWD ensures safe connections and authentication with dApps via WebSocket removing the risk of being stolen from a compromised/malicious application.

• Flexible Permissions: Users can opt to deny, allow (one-time or always), or permanently reject requests from dApps, providing control over data access.

• Ease of Integration: Manage integration effortlessly through CLI wallet commands. Toggle the XSWD Server and manage dApp permissions.

• Proxy for Daemon Requests: XSWD acts as a proxy, offering a comprehensive API for developers to integrate XELIS into their services or dApps. Maintain a single connection to access all blockchain information.

• Real-time Notifications: Receive real-time notifications of wallet events, such as incoming transactions, new blocks, and more.

• Standardized Protocol: XSWD uses the WebSocket protocol and JSON-RPC 2.0 for communication, ensuring compatibility with most programming languages and frameworks.

• Compatibility: XSWD is compatible with all platforms and devices, including web browsers, mobile devices, and desktop applications.

Protocol

The protocol is based on WebSocket protocol and the communication is made using JSON-RPC 2.0. XSWD only listens on port 44325 and on the path /xswd. This is done so the user does not need to configure anything on the application side, it knows automatically where to connect to.

When a connection is established, the first message sent by the application must be the ApplicationData format, which is the following:

{
    "id": "0000006b2aec4651b82111816ed599d1b72176c425128c66b2ab945552437dc9",
    "name": "XELIS Example",
    "description": "Description example of up to 255 characters",
    "url": "https://xelis.io",
    "permissions": [
        "get_balance",
        "subscribe",
        "get_address"
    ],
}

• The id field is a unique identifier of the application and must be a 64 character long hexadecimal string.
  
• The name field is the name of the application and must be a string of up to 32 characters.
• The description field is the description of the application and must be a string of up to 255 characters.
• The url field is the URL of the application and must be a valid URL of up to 255 characters. It’s origin must match the url in case of website application.
• The permissions field is an array that contains the permissions list set by the user.
  • It must contains ALL permissions that may be used by the application. For example, if you want to send transactions, you must include build_transaction RPC method in it.

In case of a successful and accepted request by the wallet user, the XSWD will respond with the following message:

{
    "id": null,
    "jsonrpc": "2.0",
    "result": true
}

In case of failure, the XSWD will respond with an error in JSON-RPC format:

{
    "id": null,
    "jsonrpc": "2.0",
    "error": {
        "code": -32603,
        "message": "Invalid JSON format for application data"
    }
}

Permissions

The permissions are set based on the RPC method requested and are the following:

• ask: The application must ask the user for permission each time a request is made.
• accept_always: The application is allowed to make the request without asking the user each time.
• deny_always: The application is not allowed to perform the request and the user will not be asked again. The request will be always denied until this permission is changed.

The permissions are not persisted in the wallet and are only valid for the current session. For persistence, the application must store the permissions set by the user and send it back in the ApplicationData message if allowed.

RPC Methods

The RPC methods are the same as the JSON-RPC API of the wallet except that you must set the prefix wallet. for each RPC method that are destined to the wallet. You can find the list of methods in the JSON-RPC API documentation.

Same for the daemon, you must set the prefix node. for each RPC method that are destined to the daemon.
NOTE: RPC methods that are prefixed with node. are only available if the wallet is connected to a node and don’t require any permission set by the user.

You can also listen to any wallet event available in the traditional RPC-API through XSWD.

Relayer

XSWD Relayer is a lightweight, high-performance WebSocket tunnel designed to connect exactly two peers via a temporary secure channel. It forwards messages in both directions, with zero inspection or transformation. This makes it ideal for building trustless communication layers, encrypted tunnels, or peer-to-peer protocols over WebSocket.

It is useful for applications that cannot directly connect to the XSWD server, such as web applications running in a browser or mobile applications. The relayer acts as a trustless bridge between the application and the XSWD server, forwarding messages in both directions.

You can find the source code of the relayer on our GitHub repository .

We currently provide a public relayer at wss://relayer.xelis.io that can be used by any application. However, you can also deploy your own relayer if you want to have more control over it or if you want to use it in a private network.

For connecting to applications using the relayer on a xelis wallet, the expected format is the following:

{
    "app_data": {
        "id": "0000006b2aec4651b82111816ed599d1b72176c425128c66b2ab945552437dc9",
        "name": "XELIS Example",
        "description": "Description example of up to 255 characters",
        "url": "https://xelis.io",
        "permissions": [
            "get_balance",
            "subscribe",
            "get_address"
        ],
    },
    "relayer": "wss://relayer.xelis.io/ws/123648b9-3585-4fee-b63f-b09c73655132",
    "encryption_mode": {
        "mode": "aes",
        "key": "0000000000000000000000000000000000000000000000000000000000000000"
    }
}

NOTE: The relayer field must be a valid WebSocket URL of the relayer and must contain the exact path to which the application is connect to and the wallet will have to connect. In the case of the official relayer, the path is generated by the relayer when the application connects to it and is unique for each connection. This is done to ensure that the messages are forwarded to the correct application.

Encryption Mode can be either:

• null: No encryption, the relayer will forward messages in plain text.
• aes: Your messages are encrypted and require a key. The key must be a 64 character long hexadecimal string.
• chacha20poly1305: Your messages are encrypted using ChaCha20-Poly1305 encryption with the provided key. The key must be a 64 character long hexadecimal string.

The encryption takes place on the application side before sending the message to the relayer and on the wallet side after receiving the message from the relayer. The relayer only forwards the messages without any inspection or transformation. This make it ideal for building trustless communication layers, encrypted tunnels, or peer-to-peer protocols over WebSocket.

The encryption mode must be selected based on the availability of the encryption libraries on the application side. For example, if you are building a web application, you may want to use aes encryption mode as it is widely supported in web browsers.

Future Features

Because you can only use one XSWD per device, we are planning to make a proxy system that would distribute the requests to multiple wallets and allow managing multiple wallets at the same time. This may be useful for advanced users who want to manage multiple wallets at the same time or for developers who want to test their application with multiple wallets at once.

Another idea would be to provide a random generated certificate for TLS support above the WebSocket protocol to ensure the security of the communication between the application and the wallet. Unfortunately that would break the compatibility with browsers as they don’t support self-signed certificates for WebSocket protocol. But this could be reserved for specific applications that would use the XSWD protocol.