WebSocket Connections

To use WebSocket, you have to create a WebSocket client and connect it to the API instance:

// socket.js
import {WebSocketClient} from 'adamant-api';

const ws = new WebSocketClient({
  /* ... */
});

export {ws};

// api.js
import {AdamantApi} from 'adamant-api';
import {ws} from './socket.js';

const api = new AdamantApi({
  /* ... */
});

api.initSocket(ws); // <-- WebSocket initialization

export {api};

Options

type WsType = 'ws' | 'wss';

interface WsOptions {
  /**
   * ADM address to subscribe to transactions
   */
  admAddress?: AdamantAddress;

  /**
   * Multiple ADM addresses to subscribe to transactions
   */
  admAddresses?: AdamantAddress[];

  /**
   * Transaction types to subscribe
   */
  types?: number[];

  /**
   * Message types to subscribe
   */
  assetChatTypes?: number[];

  /**
   * Websocket type: `'wss'` or `'ws'`. `'wss'` is recommended
   */
  wsType?: WsType;

  /**
   * Must connect to node with minimum ping. Not recommended. Default is `false`
   */
  useFastest?: boolean;

  /**
   * Max tries to reconnect to the websocket. Until the connection is established,
   * transactions will be pulled from the node's REST API
   *
   * Default is `3`
   */
  maxTries?: number;

  /**
   * Delay before reconnection in ms
   *
   * Default is `5000`
   */
  reconnectionDelay?: number;

  /**
   * Logger for websocket events. Default logger is `console`.
   */
  logger?: Logger | null;
}

Example:

const ws = new WebSocketClient({admAddress: 'U1234567890', useFastest: true});

.catch()

Sets an error handler for all event handlers and disconnection errors.

• Typing

  function catch(callback: ErrorHandler): this;

• Example

  Handling middleware error:

  socket.onMessage(() => throw new Error('catch me'));
  
  socket.catch(error => {
    console.log(error); // Error: catch me
  });

  Handling disconnection error:

  socket.catch(error => {
    if (error.name === 'AdamantWsConnectionError') {
      const errorMessages = {
        connection_error: 'Connection error',
        disconnection: 'Disconnected',
      };
  
      console.log(errorMessages[error.reason]);
    } else {
      // Other errors
    }
  });

.onConnection()

Adds an event listener handler for connection.

• Typing

  type ConnectionHandler = (connectedNode: string) => void;
  function onConnection(callback: ConnectionHandler): this;

• Parameters

  • callback — Function to be called on connection.

• Example

  Log connected node to console:

  // wss://clown.adamant.im:36665
  socket.onConnection(connectedNode => console.log(connectedNode));

.onReconnection()

Adds an event listener handler for reconnection. Note that node will never change when reconnecting if options.useFastest set to true.

• Typing

  type ConnectionHandler = (connectedNode: string) => void;
  function onReconnection(callback: ConnectionHandler): this;

• Parameters

  • callback — Function to be called on reconnection.

• Example

  Log new connected node to console:

  // wss://endless.adamant.im:36665
  socket.onConnection(connectedNode => console.log(connectedNode));

.off()

Removes the handler from all types.

• Typing

  function off(handler: SingleTransactionHandler): this;

• Parameters

  • handler — Function reference to remove from handlers.

• Example

  The myFunction function will be called only once:

  function myFunction() {
    console.log('Hello!');
    socket.off(this);
  }
  
  socket.on(myFunction);

.on()

Adds an event listener handler for all transaction types or specific transaction types.

• Typing

  function on(handler: AnyTransactionHandler): this;
  function on<T extends EventType>(
    types: T | T[],
    handler: TransactionHandler<TransactionMap[T]>
  ): this;

• Parameters

  • handler — Function to handle transactions.
  • types — Specific transaction type(s).

• Returns

  The current instance (this).

• Example

  Generic Handler:

  api.on(genericTransactionHandler);

  Specific Transaction Type:

  api.on(TransactionType.SEND, sendTransactionHandler);

.onMessage()

Registers an event handler for Chat Message transactions.

• Typing

  function onMessage(handler: TransactionHandler<ChatMessageTransaction>): this;

• Parameters

  • handler — Function to handle Chat Message transactions.

• Returns

  The current instance (this).

• Example

  api.onMessage(chatMessageHandler);

.onTransfer()

Registers an event handler for Token Transfer transactions.

• Typing

  function onTransfer(
    handler: TransactionHandler<TokenTransferTransaction>
  ): this;

• Parameters

  • handler — Function to handle Token Transfer transactions.

• Returns

  The current instance (this).

• Example

  api.onTransfer(tokenTransferHandler);

.onNewDelegate()

Registers an event handler for Register Delegate transactions.

• Typing

  function onNewDelegate(
    handler: TransactionHandler<RegisterDelegateTransaction>
  ): this;

• Parameters

  • handler — Function to handle Register Delegate transactions.

• Returns

  The current instance (this).

• Example

  api.onNewDelegate(registerDelegateHandler);

.onVoteForDelegate()

Registers an event handler for Vote for Delegate transactions.

• Typing

  function onVoteForDelegate(
    handler: TransactionHandler<VoteForDelegateTransaction>
  ): this;

• Parameters

  • handler — Function to handle Vote for Delegate transactions.

• Returns

  The current instance (this).

• Example

  api.onVoteForDelegate(voteForDelegateHandler);

.onKVS()

Registers an event handler for Key-Value Store (KVS) transactions.

• Typing

  function onKVS(handler: TransactionHandler<KVSTransaction>): this;

• Parameters

  • handler — Function to handle KVS transactions.

• Returns

  The current instance (this).

• Example

  api.onKVS(kvsHandler);