RUES
The Rusk Universal Event System (RUES) is an integral part of the architecture of Dusk, providing a powerful mechanism for handling real-time communication with an event-driven approach.
RUES is designed to handle binary proofs, binary streams, and on-demand event-driven data, making it ideal for applications that need to process binary proofs or continuous binary data streams. It also enables on-demand data dispatching and real-time notifications, supporting applications like wallet operations that require high-performance binary data handling. This is achieved by avoiding the need to convert data to JSON or base64.
Session Management
Before interacting with RUES, clients must establish a WebSocket session with a Rusk node. This session forms the backbone of real-time event streaming between the client and the node.
Session Initialization
To start a session, initiate a WebSocket connection to the node. Upon connection, the server responds with a Rusk-Session-Id
, a 16 byte random nonce that is essential for event subscriptions and dispatches.
Session Persistence
Ensure that your WebSocket connection remains open for as long as you require real-time event streaming. In a load-balanced environment, consistent routing is required to maintain session persistence.
Session Termination
Sessions can be terminated by either the client or the server. When the WebSocket connection is closed, all event subscriptions are automatically canceled.
Event Identification
Every event in RUES is identified by a unique URL structure, which allows for fine-grained interaction with blockchain components.
Event URL Structure
- target: The blockchain component (e.g.,
contracts
,transactions
,blocks
,node
,graphql
). - topic: The event type (e.g.,
accepted
,statechange
,propagate
).
Example URLs:
- General Event:
/on/contracts/deploy
- Specific Event:
/on/contracts:contract_id/[topic]
In more granular cases, the target
can represent specific elements within components. For example:
Event Subscriptions
RUES enables clients to subscribe to specific events on a node. Subscriptions use the HTTP GET
method and require the Rusk-Session-Id
for authentication.
Subscribe
Request
Example
Headers
Name | Description |
---|---|
Rusk-Version | Specifies the compatible Rusk version |
Rusk-Session-Id | Identifies the current session |
Response Codes
Status code | When |
---|---|
200 OK | Successful subscription |
400 Bad Request | Rusk-Version incompatibility |
424 Failed Dependency | Rusk-Session-Id issues |
404 Not Found | [component] or [target] not found |
Unsubscribe
To unsubscribe from an event, use the HTTP DELETE
method.
Request
Example
Headers
Name | Description |
---|---|
Rusk-Version | Specifies the compatible Rusk version |
Rusk-Session-Id | Identifies the current session |
Response Codes
Status code | When |
---|---|
200 OK | Successful unsubscription |
400 Bad Request | Rusk-Version incompatibility |
424 Failed Dependency | Rusk-Session-Id issues |
404 Not Found | [component] , [target] or [topic] not found |
Event Dispatch
Dispatching events allows clients to send specific data to the node and request data. The POST
method is used for this purpose, often including a request body with the event payload.
Dispatch
Request
Example
Headers
Name | Description |
---|---|
Rusk-Version | Specifies the compatible Rusk version |
Rusk-Session-Id | Identifies the current session |
Content-Type | Usually application/json or application/octet-stream |
Content-Length | The length of the message body in octets (8-bit bytes) |
Accept | Media type(s) that is/are acceptable for a response message |
Response Codes
Status code | When |
---|---|
200 OK | Event received succesfully, response generated |
202 Accepted | Event accepted for processing |
400 Bad Request | Rusk-Version mismatch |
424 Failed Dependency | Rusk-Session-Id mismatch |
404 Not Found | [component] , [target] , or [topic] not found |
422 Unprocessable Content | Payload cannot be processed with the given Content-Type |
General Endpoints
These are endpoints accessible regardless of the node role. They include queries for general blockchain state and node information.
GraphQL Queries
Endpoint: /on/graphql/query
Enables GraphQL-style queries against the Dusk blockchain.
Method: POST
Example Request:
Request Body:
Example query for requesting the latest block.
Example Response:
Node
Node Info
Endpoint: /on/node/info
Retrieves general information about the node, like the chain ID of the network the node operates on, its bootstrapping nodes, the Rusk version it uses and its Kadcast IP address.
Method: POST
Example Request:
Example Response:
Provisioners
Endpoint: /on/node/provisioners
Fetches the list of provisioners (validators).
Method: POST
Example Request:
Example Response:
Common Reference String (CRS)
Endpoint: /on/node/crs
Retrieves the CRS used by the network.
Method: POST
Example Request:
Example Response:
Blocks
Block Events
Endpoint: /on/blocks:[block-hash]/[topic]
, where [topic]
is optional. Block events can have the topic accepted
, or statechange
.
- accepted: Indicates that a block has been accepted into the chain.
- statechange: Represents a change in the state of a block. The state of a block can be either
finalized
orconfirmed
.
Method: GET
Example Request:
This example request listens to the accepted
topic for a given block.
Example Event:
The event is returned as raw binary data. Ensure that your client can properly handle these formats according to the RUES specifications. Example for a newly accepted block.
Gas Price
This endpoint retrieves the gas price for the latest blocks.
Endpoint: /on/blocks/gas-price
Method: POST
Example Request:
Example Response:
Transactions
Transaction Events
Endpoint: /on/transactions/[topic]
, where [topic]
is mandatory. Transaction events can have the topic Removed
, Included
, or Executed
.
- Removed: Indicates that the transaction has been removed from the mempool.
- Included: A transaction has been included in the mempool.
- Executed: A transaction that has been executed in an accepted block.
Method: GET
Example Request:
This example request listens to the Executed
topic for any incoming transaction.
Example Event:
The event is returned as raw binary data. Ensure that your client can properly handle these formats according to the RUES specifications. Example for an executed Moonlight transaction.
Preverify
This endpoint pre-verifies a transaction without executing or propagating it. The transaction is checked to ensure it conforms to network rules before being propagated or executed.
Endpoint: /on/transactions/preverify
Method: POST
Example Request:
Request Body:
The request body should contain the raw binary representation of a transaction.
Example Response:
Upon success, the transaction will be pre-verified, but no specific data is returned unless there is an error.
Propagate
This endpoint propagates a transaction across the network.
Endpoint: /on/transactions/propagate
Method: POST
Example Request:
Request Body:
The request body should contain the raw binary representation of a transaction.
Example Response:
Upon success, the transaction will be propagated across the network. This endpoint returns a response indicating success but no specific data.
Contracts
Contract Events
Endpoint: /on/contracts:[contract-id]/[event-name]
, where [event-name]
is optional. If the event name is not provided, the connection will listen to all events on the given contract.
Method: GET
Example Request:
This example request listens to stake
events from the stake contract.
Example Event:
The event is returned as raw binary data. Ensure that your client can properly handle these formats according to the RUES specifications. Example for a stake event.
Network
Peers
This endpoint retrieves a list of peers connected to the node, where the given value is the amount of peers to return, if available.
Endpoint: /on/network/peers
Method: GET
Example Request:
Request Body:
Example Response:
Archive node Endpoints
These endpoints provide access to historical data and events stored by archive nodes.
Moonlight Transaction History
This endpoint provides access to the Moonlight transaction history stored by archive nodes in an efficient way.
Details to be filled in based on implementation.
Historical Events
This endpoint provides access to other historical events in the blockchain.
Details to be filled in based on implementation.
Prover Endpoints
The Provers in the network are responsible for generating Zero-Knowledge proofs. These endpoints offer proof-related functionality.
Prove
This endpoint triggers the prover to generate a Zero-Knowledge proof for the provided data.
Endpoint: /on/prover/prove
Method: POST
Example Request:
Request Body:
The request body should contain raw binary data
Example Response:
Upon success, the prover will return the generated proof, likely as raw binary data.