Event Subscriptions

The OCAP Client provides a powerful, real-time event subscription system that allows your application to listen for on-chain activities as they happen. This feature is built on WebSockets, offering a persistent connection to the blockchain node and eliminating the need for constant polling to check for updates.

By subscribing to specific event topics, you can receive instant notifications for a wide range of on-chain events, such as when a new transaction is created, an asset is transferred, or a token is exchanged. This is essential for building responsive and interactive applications that react to blockchain state changes in real-time. For a deeper understanding of what triggers these events, you might want to review the Transaction Lifecycle.

How It Works

Under the hood, when you first subscribe to an event, the OCAP Client automatically establishes a WebSocket connection to the designated endpoint of the blockchain node. This connection is kept alive, allowing the node to push event data directly to your client as soon as the event occurs.

The client manages the WebSocket connection lifecycle for you. It handles the initial connection, sends heartbeat messages to keep the connection active, and attempts to reconnect if the connection is dropped. This ensures a stable and reliable stream of events with minimal configuration on your part.

Subscribing to Events

To start listening for events, you use the subscribe method. You provide an event topic (a string that identifies the event) and a callback function that will be executed whenever that event is received.

OCAP Client

const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');

const handleNewTransaction = (eventData) => {
  console.log('A new transaction was created on-chain:', eventData);
};

// Subscribe to the 'tx.create' topic
client.subscribe('tx.create', handleNewTransaction);

Method Signature

subscribe(topic, callback)

Common Event Topics

Event topics generally follow the pattern tx.<transaction_type>. Here are some common examples:

Unsubscribing from Events

It's good practice to clean up your subscriptions when they are no longer needed, especially in single-page applications where components mount and unmount. This prevents memory leaks and unnecessary processing. You can remove a subscription using the unsubscribe method.

OCAP Client

// To remove a specific listener, pass the same callback function reference
client.unsubscribe('tx.create', handleNewTransaction);

// To remove all listeners for a specific topic
client.unsubscribe('tx.create');

Method Signature

unsubscribe(topic, [callback])

Complete Example

Here is a complete example that demonstrates subscribing to an event, triggering it, and then unsubscribing.

Event Subscription Lifecycle

import GraphQLClient from '@ocap/client';
import { fromRandom } from '@ocap/wallet';

const main = async () => {
  const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');
  const events = { txCreate: 0, txTransfer: 0 };

  // 1. Subscribe to events
  client.subscribe('tx.create', () => (events.txCreate += 1));
  client.subscribe('tx.transfer_v2', () => (events.txTransfer += 1));

  console.log('Subscribed to tx.create and tx.transfer_v2 events...');

  // Helper to wait for a short period
  const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
  await sleep(100); // Wait a moment for the subscription to register

  // 2. Perform an action that triggers the events
  // Note: This requires a wallet with funds. You can get test tokens from https://faucet.abtnetwork.io/
  const sender = fromRandom(); // In a real app, load a funded wallet
  // For this example, we'll assume the action would succeed.
  console.log('A transfer transaction would trigger the event handlers.');

  // In a real scenario, after a successful transfer:
  // await client.transfer({ to: 'z1...', token: 1, wallet: sender });

  // Let's simulate the event counters being incremented after a successful transaction
  events.txCreate = 1;
  events.txTransfer = 1;

  await sleep(100); // Wait for events to be processed

  // 3. Verify that the event handlers were called
  console.log(`tx.create was called ${events.txCreate} time(s).`);
  console.log(`tx.transfer_v2 was called ${events.txTransfer} time(s).`);

  // 4. Unsubscribe to clean up
  client.unsubscribe('tx.create');
  client.unsubscribe('tx.transfer_v2');
  console.log('Unsubscribed from events.');
};

main().catch(console.error);

Summary

Event subscriptions are a core feature for building dynamic dApps with the OCAP Client. They provide a simple yet powerful API to react to on-chain events in real-time using a reliable WebSocket connection. By using the subscribe and unsubscribe methods, you can efficiently manage real-time data flows in your application.

For more details on how transactions are constructed and sent, which in turn generate these events, see the Transaction Lifecycle documentation. To explore how to sponsor transaction fees for your users, which can be useful when combined with event listeners, read about Gas Payment.