XSWD – XELIS Documentation

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": {},
    "signature": null
}

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 object that contains the permissions list set by the user.
- It is empty at the first connection.
- It persists the permissions which the user has allowed the application to use.
The signature field is a signature generated by the wallet to validate that the permissions given above are valid and allowed by users.
- It is a hexadecimal string provided by XSWD.
- It is a signature made on the hash of Application Data fields except the signature field itself.

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.

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.

Integrated Address Encrypted Storage