Flow Stream API Example

A simple JavaScript project demonstrating how to use WebSocket as a client to interact with the Flow blockchain. This repository contains examples to subscribe to various Flow topics (such as block digests, block headers, blocks, events, account statuses, and transaction statuses) using WebSocket connections.

Table of Contents

• Flow Stream API Example
  • Table of Contents
  • Introduction
  • Features
  • Requirements
  • Installation
  • Configuration
  • How to Run
    • Using NPM Scripts
    • Running the WebSocket Client Directly
  • Contributing

Introduction

This example project is designed to test and demonstrate the functionality of WebSocket connections with the Flow blockchain. It shows how to subscribe to and handle real-time updates using different topics available on the Flow network. You can try out different scripts to see how subscriptions behave when provided with various arguments (including intentionally wrong ones).

Features

• WebSocket Client Implementation: Connects to a configurable WebSocket endpoint.
• Multiple Examples: Scripts for subscribing to:
  • Block digests
  • Block headers
  • Blocks
  • Events
  • Account statuses
  • Transaction statuses
• Environment Configuration: Easily set the WebSocket endpoint via an environment file.
• Event Handling: Demonstrates handling of incoming messages, subscription acknowledgements, errors, and connection closures.

Requirements

• Node.js (v14 or higher is recommended)
• npm (comes with Node.js)

Installation

1. Clone the repository:

   git clone https://github.com/The-K-R-O-K/flow-stream-api-example.git
   cd flow-stream-api-example

2. Install dependencies:

   npm install

Configuration

The project uses an environment variable to configure the WebSocket endpoint. An example file is provided:

1. Copy the example environment file to create your own configuration:

   cp example.env .env

2. Open the newly created .env file and update the WEBSOCKET_URL with the correct endpoint. For example:

   WEBSOCKET_URL=wss://rest-mainnet.onflow.org/ws
   FLOW_ACCESS_NODE_API=https://rest-mainnet.onflow.org

How to Run

Using NPM Scripts

The package.json defines several npm scripts for different functionalities. You can run any of them directly. For example:

• Block Digests from Start Height:

  npm run block_digests:from_start_height

• Block Headers from Start ID:

  npm run block_headers:from_start_id

• Blocks from Latest Block:

  npm run blocks:from_latest_block

• Events (and other topics):
  There are similar scripts for events, account statuses, and transaction statuses. Use the command:

  npm run <script_name>

  Replace <script_name> with one of the following:

  • block_digests:from_start_id
  • block_digests:from_latest_block
  • block_digests:wrong_args
  • block_headers:from_start_height
  • block_headers:from_latest_block
  • block_headers:wrong_args
  • blocks:from_start_height
  • blocks:from_start_id
  • blocks:wrong_args
  • events:from_start_height
  • events:from_start_id
  • events:from_latest_block
  • events:wrong_args
  • account_statuses:from_start_height
  • account_statuses:from_start_id
  • account_statuses:from_latest_block
  • account_statuses:wrong_args
  • transaction_statuses:listen_tx_statuses

Running the WebSocket Client Directly

The main entry point for the generic WebSocket client is located at src/websocket_client.js. This file demonstrates how to:

• Load configuration from the .env file.
• Establish a WebSocket connection.
• Handle events such as open, message, error, and close.

To run the client directly, use:

node src/websocket_client.js

Upon connection, the client logs the WebSocket URL and confirms the connection. You can modify this file to send custom messages using the provided sendMessage() method.

Contributing

Contributions to this project are welcome. If you have ideas for improvements or additional examples, please fork the repository and submit a pull request.