Swarms API Documentation – GRIDNET OS Magazine

Introduction

Welcome to the Swarms API documentation!

The Swarms API is a groundbreaking component of GRIDNET OS, a decentralized operating system designed for fostering seamless cross-browser communication. Built atop WebRTC, this robust JavaScript API simplifies the creation of decentralized applications by abstracting the intricacies of WebRTC, thus enabling developers to focus on building powerful, decentralized communication networks with ease.

One of the most prominent features of the Swarms API is its decentralized WebRTC signaling. Unlike traditional systems, there’s no single point of trust or requirement for a centrally deployed server. The Gridnet Core nodes, responsible for maintaining the system, are fully capable of facilitating signaling independently, resulting in a truly decentralized network. This means that even if two peers are connected to different signaling servers, they can still communicate with each other seamlessly, thanks to the underlying decentralized data flow. Gridnet Core nodes discover each other through a variant of the Kademlia peer discovery protocol, ensuring efficient and reliable network connectivity.

Moreover, the Swarms API introduces a unique system of public and private identifiers for Swarms, along with Zero-Knowledge Proof (ZKP) for authorization. This ensures that data exchange occurs only between authorized peers, reinforcing the commitment to security and privacy.

The API also employs virtual audio and video devices to manage access to hardware resources dynamically and negotiate connection quality effectively. This innovative approach allows for the efficient utilization of system resources based on the requirements of each application.

This documentation serves as an in-depth guide to the Swarms API, covering everything from key concepts and detailed usage guides to practical examples. Whether you’re just starting out with GRIDNET OS or you’re an experienced developer looking to harness the power of decentralized communication, this guide will serve as an invaluable resource.

GRIDNET OS, as a decentralized operating system, is specifically designed to provide a comprehensive, unified ecosystem that empowers developers to build a wide variety of decentralized applications and services, without the need to rely on multiple disparate technologies. With its rich set of in-house sensors, actuators, and APIs, GRIDNET OS goes beyond platforms like Ethereum by offering a more extensive and powerful feature set.

The Swarms API is just one example of the advanced tools that GRIDNET OS provides to developers. It enables real-time, peer-to-peer communication, allowing for the creation of next-gen decentralized services that were previously difficult or impossible to achieve using existing decentralized technologies.

Welcome to the future of decentralized communication, powered by GRIDNET OS and the Swarms API!

Rationale

Traditional Internet Communication

The evolution of internet communication began with simple text-based protocols like email and IRC (Internet Relay Chat) moving onto more complex and interactive communication methods such as VoIP (Voice over Internet Protocol), video conferencing, instant messaging, and social networking. These traditional methods rely heavily on centralized servers to facilitate the exchange of information.

In a typical client-server model, communication flows from the sender (client) to the receiver (client) through a centralized server. This server not only routes the communication but also often processes and stores the data being transmitted. While this model has worked well for many years, it comes with significant drawbacks, including dependency on the central server, potential privacy issues, and scalability concerns.

The Advent of WebRTC

WebRTC (Web Real-Time Communication) emerged as a game-changing technology aiming to resolve the shortcomings of the traditional client-server model. WebRTC is a free, open-source project that enables web browsers and mobile applications with Real-Time Communications (RTC) capabilities via simple APIs.

WebRTC allows for peer-to-peer (P2P) communication, removing the need for data to pass through a central server. This design reduces latency, improves speed, and enhances privacy as data isn’t stored on a centralized server. However, setting up a WebRTC connection between peers can be complex, requiring a deep understanding of network protocols and dealing with issues like NAT traversal.

GRIDNET OS and Swarms API: The Next Step

The GRIDNET Operating System and its Swarms API take WebRTC’s concepts a step further, simplifying the process for developers and enhancing the capabilities of decentralized communication.

In essence, the Swarms API within the GRIDNET OS builds upon WebRTC’s foundation, providing a more straightforward and robust mechanism for developing decentralized applications that can communicate globally right from a web browser without installations.With the Swarms API, we abstract away the complexities and inconsistencies associated with native WebRTC implementations. This move empowers developers to focus more on their applications’ functionality rather than dealing with the intricacies of network protocols.

Furthermore, the Swarms API integrates advanced security features like end-to-end encryption and unique Zero-Knowledge proof cryptographic algorithms, ensuring every conversation, group communication, and meeting is fully protected. This level of security and privacy is a step beyond what traditional WebRTC implementations can provide.

Moreover, the Swarms API operates within a Sybil-proof, crypto-incentivized environment, thereby promoting a healthier, more secure network ecosystem.

The GRIDNET OS and its Swarms API represent the next stage in the evolution of internet communication, providing developers with the tools they need to create truly decentralized applications with global reach, privacy, and security in the digital age.

Did you know? Data flows through Swarms are both fully decentralized (even the signaling layer) and can be also onion-routed and crypto-incentivized in a Sybil-proof manner. Research paper: here

Getting Started

Embarking on your journey with the Swarms API is straightforward and accessible. To get a feel for what’s possible, we recommend exploring two of our major decentralized graphical user interface (GUI) equipped applications that utilize Swarms: eMeeting and Whiteboard UI dApps. These applications are available in our GitHub repository.

Decentralized does not imply chaotic..

eMeeting: A decentralized application enabling end-to-end encrypted audio-video conferencing along with screen sharing.
Whiteboard UI dApp: A collaborative tool for group sketching, ideating, and drawing.

These applications can be used simultaneously, taking full advantage of the multitasking capabilities of GRIDNET OS. If one app initializes a Swarm, the other will automatically detect it.

When it comes to code editing, you have options. You can use the editing tool available directly within the GRIDNET OS user interface (the Editor UI dApp), or use your favorite local code editing tool (we’re big fans of Atom).

To get started, you may want to familiarize yourself with deploying a sample graphical “Hello World” UI dApp on GRIDNET OS. Follow our step-by-step tutorial available here.

Once you’re comfortable with deploying a sample graphical application, working with Swarms will be a breeze. It’s as simple as signing up for access to a Swarm by providing its chosen identifier. GRIDNET OS will take care of initializing it properly across the network.

After that, you only need to sign up for the appropriate events and continue interacting with the Swarm. You can enable features like camera, screen sharing, or muting/unmuting of the microphone, all without having to interact directly with the WebRTC API. Swarms takes care of the perfect-negotiation models for you, allowing you to focus on your ideas.

At any point, you can modify the properties of a Swarm, such as changing the required hardware privileges (for instance, indicating that the camera is no longer needed) or setting a pre-shared secret for Zero-Knowledge Proof (ZKP) authorization. The system ensures that data continues to flow even during these configuration changes, with peers not being disconnected but rather ceasing to receive data until mutual peer-to-peer authorization is reestablished.

So, sign up for a Swarm, interact through our high-level APIs, and watch your decentralized applications come to life. Welcome to Swarms!

Concepts

Before diving into the Swarms API, it’s essential to understand the key concepts and components that make up the system. This section provides an overview of these elements to help you build a solid foundation for working with Swarms in GRIDNET OS.

CVMContext

CVMContext is a global object that provides access to the core features of GRIDNET OS. It’s the primary interface for interacting with the operating system and accessing essential services, such as the Swarm Manager.

CSwarmManager

CSwarmManager is a singleton class that manages Swarms within GRIDNET OS. It is responsible for initializing and maintaining connections, handling permissions, and managing the resources of virtual devices. You can access the CSwarmManager through the `CVMContext.getInstance().getSwarmManager()` method.

Swarm

A Swarm represents a group of communicating nodes that manage connections among themselves. Swarms facilitate real-time, peer-to-peer communication in a decentralized network. They have both public and private identifiers, with the private identifier known only among Swarm members.

CSwarmConnection

CSwarmConnection is a class representing individual connections between Swarm members. It is managed by the Swarm Manager and allows for data dispatch, reception, audio-video streaming, and screen sharing. It also handles authorization through Zero-Knowledge Proof (ZKP).

Public and Private Identifiers

Each Swarm has a public and private identifier. The private identifier is known only to Swarm members, while the public identifier is generated using a one-way transformation of the private identifier. This distinction ensures secure communication and authorization within the Swarm.

Zero-Knowledge Proof (ZKP) and Authorization

Zero-Knowledge Proof is a cryptographic technique employed by Swarms API to authorize connections between Swarm members. By using the private identifier of a Swarm, peers can perform mutual authorization without revealing their private information. Swarms also allow users to set a separate pre-shared secret for authorization, further enhancing security.

Virtual Devices and Dummy Tracks

Swarms API utilizes virtual audio and video devices to manage access to hardware resources, such as cameras and microphones. Dummy WebRTC tracks, created using oscillators, enable efficient negotiation of data transmission channels and allow for effective management of hardware permissions. These dummy tracks play a crucial role in ensuring seamless transitions between muted and unmuted data streams without causing full WebRTC renegotiation.

By understanding these fundamental concepts and components, you’ll be well-equipped to work with the Swarms API and build powerful decentralized applications on GRIDNET OS.

Data Encapsulation and Decapsulation

The Swarms API of the GRIDNET OS is designed to simplify the application development process by providing built-in data encapsulation and decapsulation mechanisms. One of the foundational aspects of this simplification lies in the use of CNetMsg and CSwarmMsg containers, which take away the burden of designing and implementing custom data encapsulation datagrams.

As a developer, you often need to ensure that the data transmitted between different components of a system or between different systems is packaged in a manner that ensures its integrity, confidentiality, and consistency. This often requires considerable time and expertise, especially when dealing with complex data types or large volumes of data.

The Swarms API, however, abstracts away much of this complexity. For most basic functionalities, there is no need to create specialized containers. Instead, data can be transmitted as an ArrayBuffer, serving as the payload of CSwarmMsg containers. This approach allows for efficient transmission of data while ensuring its integrity and confidentiality.

The relationship between CNetMsg and CSwarmMsg containers is key to understanding how data encapsulation and decapsulation work within the Swarms API. The CNetMsg container serves as the fundamental network datagram, used throughout the entire GRIDNET OS eco-system. It supports advanced features such as routing, onion routing, various encryption modes, and authentication. The CSwarmMsg, on the other hand, is specifically related to the Swarms technology. It is encapsulated within the CNetMsg and carries information specific to Swarms.

By providing these containers, the Swarms API enables developers to focus on the implementation of their applications, rather than on the low-level details of data transmission. The efficient and effective binary encoding provided by these containers also ensures that data transmission is performant and reliable, regardless of the underlying network conditions.

For a detailed understanding of these data structures and how they facilitate data encapsulation and decapsulation, please refer to the sections detailing CNetMsg and CSwarmMsg at the end of this documentation.

Serialization and Deserialization in CNetMsg and CSwarmMsg

Serialization and deserialization are fundamental concepts in computer science and data management, especially in the context of data transmission over a network.

Serialization is the process of converting data structures or objects into a format that can be stored and reconstructed later in the same or another computer environment. When the resulting series of bits is reread according to the serialization format, it can be used to create a semantically identical clone of the original object.

On the other hand, deserialization is the reverse process, that is, the byte stream is converted back into a replica of the original object.

In the context of GRIDNET’s Swarms API, both CNetMsg and CSwarmMsg utilize serialization and deserialization.

CNetMsg and CSwarmMsg Serialization and Deserialization

The CNetMsg and CSwarmMsg classes both have methods for serialization and deserialization: `getPackedData()` and `static instantiate(packedData)` respectively. These methods handle the process of converting the object’s state to a binary format (serialization) and reconstructing the object from that binary format (deserialization).

Serialization

When you call `getPackedData()` on a CNetMsg or CSwarmMsg object, the object’s state is serialized into a binary format. This involves taking each field of the object and converting it into a format that can be stored as a sequence of bytes. This is accomplished using Basic Encoding Rules (BER), which provides an efficient binary encoding. The result is an ArrayBuffer that represents the serialized state of the object. This ArrayBuffer can be transmitted over the network, stored in a file, or otherwise used where a binary format is required.

Deserialization

When you want to reconstruct a CNetMsg or CSwarmMsg object from a binary format, you use the `static instantiate(packedData)` method. This method takes an ArrayBuffer as an argument, which should represent the serialized state of a CNetMsg or CSwarmMsg object. The method then decodes the ArrayBuffer using the BER encoding rules and populates a new object with the decoded data.

The serialization and deserialization methods in CNetMsg and CSwarmMsg allow developers to focus on the logic of their applications, without needing to handle the low-level details of data transmission. These methods provide an efficient and reliable way to transmit complex objects over the network, ensuring that the transmitted data maintains its integrity and consistency.

Typical Workflow

chaotic ourselves once we might had been..

Thank you for that information. Here’s the revised version of the workflow:

Initialization of the Swarms Manager:Initialize the `CSwarmsManager` instance using the `getInstance` static method. This method ensures the singleton nature of the class. The initialization comes with default settings for local stream, authentication keys, and token pool, among others.
Joining a Swarm:
The user can join a specific Swarm using the `joinSwarm` method. This method signals the full node about the client’s intent to join a specific Swarm, identified by its `trueSwarmID`. The `joinSwarm` method also automatically adds a `CSwarm` instance to the `CSwarmsManager`, representing the Swarm that the client has joined.
Data Handling:After joining a Swarm, the user can send and receive data. In case of facilitaing ougress data deliveries, the `sendData` method of `CSwarm` can be used to send data to all members of the Swarm or to a specific recipient within the Swarm by using either sendMessage() – which accepts the CNetMessage data-wrapper or send()- which accepts a plain ArrayBuffer – methods of CSwarmConnection. When it comes to receiving data, should developer need to listen to multiple Swarms all at once though a singel event handler the `onNewSwarmData` event listener in `CSwarmsManager` is used to handle incoming data . Otherwise, developer may choose to employ callbacks such as onNewPeerData() or onMessage() of CSwarm – depending on requirements. Developer may also choose to be notified about incoming datagrams from specific peers/connections. In such a case it is perfectly fine to use event handlers of CSwarmConnection such as its onMessage() event handler. Every incoming data event is event-driven
.Swarm Management:The `CSwarmsManager` and `CSwarm` instances manage the Swarm’s state autonomously. They maintain the connection to the Swarm, track connection quality, and can switch signaling nodes when necessary. This process happens transparently, without the need for explicit user intervention.
Managing Capabilities:The `CSwarmsManager` manages the capabilities of the Swarm with default values. By default, both audio and video capabilities are enabled. However, if needed, these capabilities can be customized using the `setAllowedCapabilities` method.
Leaving a Swarm:When the user is done interacting within a Swarm, they can leave using the `leaveSwarm` method. This informs the full node that the client wishes to leave the Swarm.

This workflow should provide a comprehensive understanding of how to interact with the Swarms API, taking into account the automatic Swarm addition by the `joinSwarm` method, the autonomous management of Swarms, and the management of capabilities with default values.

CSwarm Class Documentation

The `CSwarm` class is a fundamental part of the Swarms API of GRIDNET OS. It abstracts the complexities of managing WebRTC connections, allowing developers to focus more on application logic and less on lower-level networking concerns.

were we not..

Purpose of CSwarm

In traditional WebRTC API usage, managing connections between peers can be a complex task. Each connection needs to be established, maintained, and monitored individually, with developers having to handle various edge-case scenarios such as connection failures and network interruptions. This requires a deep understanding of the WebRTC API and the underlying networking concepts, making the development process more complex and time-consuming.

CSwarm, on the other hand, abstracts these complexities and provides a higher-level interface for managing WebRTC connections. With CSwarm, developers do not need to worry about individual connection management or handle edge-case scenarios. The CSwarm class takes care of all these, providing a simplified and more intuitive API for developers to use.

Advantages of CSwarm

Simplified Connection Management: CSwarm automatically manages the state of each connection, keeping track of active and pending connections. It also automatically handles the transition of a connection from pending to active, reducing the amount of code needed to be written by developers.
Resilient Connection Handling: CSwarm has built-in mechanisms to handle connection interruptions and failures. It can automatically resume connections when possible, ensuring a more reliable and robust communication network.
Security and Authentication: CSwarm incorporates security measures, such as Zero-Knowledge Proof authentication, to ensure that only authenticated peers can join the swarm and start exchanging data. This means developers do not have to implement these security measures themselves, saving development time and reducing the potential for security vulnerabilities.
Automatic Media Flow Management: Once peers have authenticated and a connection is established, CSwarm takes care of ensuring that audio and video start flowing between the peers. Again, this reduces the complexity for developers, allowing them to focus on building their application logic rather than handling media streams.
Event-Driven Architecture: CSwarm provides a set of event listeners that developers can subscribe to, allowing them to respond to various events such as state changes, message arrivals, or connection quality changes. This event-driven architecture makes it easier to build reactive applications that can respond to changes in the network dynamically.

By abstracting the complexities of managing WebRTC connections, CSwarm allows developers to focus more on their application’s core functionality, accelerating the development process and reducing potential sources of errors. It provides a powerful, easy-to-use API that can significantly simplify the process of building decentralized, peer-to-peer applications using WebRTC.

Event-driven Development and Ease of Use

CSwarm leverages an event-driven approach, offering developers a set of event listeners to monitor and react to various swarm activities, such as state changes, message arrivals, track events, and connection quality changes. This allows for the creation of more responsive applications, as developers can program behaviors based on specific events, and create a more dynamic user experience.

The class provides methods for adding event listeners to either individual connections or all connections within the swarm, creating an abstraction layer that significantly simplifies the development process. This means developers can focus on higher-level application logic, rather than dealing with the intricacies of individual connection event handling.

Automatic Resource Optimization

CSwarm also includes built-in resource optimization mechanisms. The class includes a method for setting effective outgress capabilities, allowing developers to control the flow of media streams without triggering renegotiation of the underlying connections. Furthermore, after setting these capabilities, CSwarm automatically allows the Swarm Manager to optimize hardware resources, eliminating handles to resources that are no longer needed. Thus, from the end-user’s perspective – the red diode indicating camera usage would be shining only when the camera is being used by a certain decentralized application within the GRIDNET OS’ multi-tasking environment. Applications get to choose what resources they actually need, and the system takes care of optimizing away what’s not needed anymore.

Decoupling of Connection Management

Another key advantage of CSwarm is the decoupling of connection management from the rest of your application logic. Rather than having to manage each connection individually, CSwarm maintains a list of active and pending connections, automatically handling the transition between these states.

Moreover, if a connection fails or is interrupted, CSwarm can automatically attempt to resume the connection. This resilience and automated management free up developers to focus on the key aspects of their applications, without needing to constantly monitor and manage the state of each connection.

Enhanced Security Measures

In today’s digital age, security is a top priority, especially in the realm of real-time communication. CSwarm is designed with this in mind, and it incorporates a number of built-in security measures.
CSwarm incorporates enhanced security measures to ensure the integrity and confidentiality of data shared across the network. It uses Zero-Knowledge Proof authentication, ensuring that only authenticated peers can join the swarm and exchange data. This means developers don’t have to implement these security measures themselves, which not only saves development time but also reduces the potential for security vulnerabilities.

In addition to this, CSwarm also ensures that audio and video streams only begin flowing once the corresponding peers have authenticated each other. This prevents unauthorized access to the media streams and protects the privacy and security of the users.

Connection Quality Monitoring and Management

CSwarm goes beyond just managing connections; it actively monitors and manages the quality of these connections. By using a variety of heuristic methods, CSwarm can keep a constant check on connection states and latency. The importance of such a feature cannot be overstated in real-time applications, where connection quality can significantly impact user experience.

This advanced monitoring capability allows CSwarm to detect any anomalies or drop in performance and can trigger appropriate actions to restore the quality of the connection. Furthermore, it is equipped with an autonomous keep-alive mechanism that ensures connections remain active and healthy, reducing the chances of unexpected disconnections or performance issues.

Decentralized Signaling over GRIDNET Nodes

One of the standout features of CSwarm is its ability to operate over decentralized GRIDNET nodes. In contrast to traditional WebRTC applications, which often rely on centralized signaling servers, CSwarm leverages the decentralized nature of GRIDNET to manage signaling.

This decentralized approach provides a number of advantages. Firstly, it eliminates the single point of failure that comes with relying on a central server. This makes the system more robust and resilient to failures. Secondly, it enables the system to scale more effectively, as new nodes can be added to the network without overloading a central server.

In addition to these advantages, decentralized signaling over GRIDNET nodes also provides enhanced security. By operating in a decentralized manner, communication is more resistant to attacks and interception, and the system can ensure that audio and video streams only start flowing once peers have authenticated through zero knowledge proof.

In summary, CSwarm offers a comprehensive solution for managing, monitoring, and enhancing the quality of connections in a decentralized network. By abstracting away the complexities of connection management, providing advanced monitoring capabilities, and leveraging the power of decentralized signaling, CSwarm enables developers to build robust, scalable, and secure real-time communication applications.

Properties

These are sample internal properties. These should not be accessed directly.

```
mAllowedCapabilities
```
The capabilities allowed by the local user for all connections.
```
 `mEffectiveIngressCapabilities
```
The effective ingress capabilities for all connections within the swarm.
```
mEffectiveOutgressCapabilities
```
The effective outgress capabilities for all connections within the swarm.
```
mJoinConfirmed
```
Confirmation of node registration within the Swarm.
```
mID
```
Unique identifier for the Swarm instance.

Methods

```
transferConnToActive(connID)
```
Transfers a connection from the pending connections pool to the active connections pool.
```
getAllowedCapabilities
```
Gets the allowed capabilities of the Swarm instance.
```
getEffectiveIngressCapabilities
```
Gets the effective ingress capabilities of the Swarm instance.
```
getEffectiveOutgressCapabilities
```
Gets the effective outgress capabilities of the Swarm instance.
```
getActiveConnectionsCount
```
Gets the count of active connections.
```
getPendingConnectionsCount
```
Gets the count of pending connections.
```
setAllowedCapabilities(allowed)
```
Sets the allowed capabilities for the Swarm instance.
```
setEffectiveIngressCapabilities(allowed)
```
Sets the effective ingress capabilities for the Swarm instance.
```
setEffectiveOutgressCapabilities(allowed)
```
Sets the effective outgress capabilities for the Swarm instance.
```
handleGetUserMediaError(e)
```
Handles errors when getting user media.
```
createPendingConnWithPeer(peerID)
```
Creates a pending connection with a peer.
```
processSignalEntity(sdpE)
```
Processes incoming signaling datagrams.
```
removeConnection(peerID)
```
Removes a connection.
```
getActiveConnection(peerID)
```
Retrieves an active connection.
```
getConnection(peerID)
```
Retrieves a connection.
```
getPendingConnection(peerID)
```
Retrieves a pending connection.
```
controllerThreadF()
```
Controls all the mechanics.

unregisterEventListenersByAppID(appID = 0, eventListener = null)

Unregisters an event listener.

```
getSwarmSize()
```
Retrieves the number of participants.
```
getMyID
```
Retrieves the Swarm instance’s ID.
```
reconnect()
```
Reconnects to the swarm.
```
peers
```
Returns active peers.
```
getID
```
Returns the ID of the Swarm instance.
```
initialize()
```
Initializes a Swarm instance.
```
close(killConnections = true)
```
Closes a swarm, possibly also killing all connections.

Interface Description:

Here’s a detailed description of each public method in the `CSwarm` class along with use case examples:

```
addSwarmStateChangeEventListener(eventListener, appID = 0)
```
This method registers an event listener function that will be triggered when the state of the swarm changes. This can be useful in scenarios where specific actions need to be taken when the state of the swarm changes. For instance, if an application wants to log these changes or update the user interface based on the swarm state.
```
addSwarmRegistrationConfirmedEventListener(eventListener, appID = 0)
```
This method registers an event listener function that will be triggered when the swarm registration is confirmed. This can be useful when an application needs to wait for the confirmation of the registration before proceeding with other operations, such as sending data to peers.
```
addSwarmAuthRequirementsChangedEventListener(eventListener, appID = 0)
```
This method registers an event listener function that will be triggered when the authentication requirements of the swarm change. This can be useful in scenarios where the application needs to react to changes in the authentication requirements, such as prompting the user to reauthenticate.
```
addTrackEventListener(eventListener = null, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when a new track is added or an existing track is removed. This can be useful in scenarios where the application needs to keep track of the tracks in a real-time media stream.
```
addSwarmMessageListener(eventListener, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when a new message is received in the swarm. This is useful when the application needs to process messages received from peers.
```
addMessageListener(eventListener, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when a new message is received. This is useful when the application needs to process individual messages received from peers.
```
addDataChannelMessageEventListener(eventListener, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when a new message is received on the data channel. This is useful in applications that use the data channel to send non-media data.
```
addPeerStatusChangeEventListener(eventListener, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when the status of a peer changes. This can be useful in scenarios where the application needs to react to changes in the status of peers, such as updating the user interface.
```
addConnectionQualityChangeEventListener(eventListener, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when the quality of a connection changes. This can be useful in scenarios where the application needs to adapt to changes in connection quality, such as adjusting the quality of a video stream.
```
addSwarmConnectionStateChangeEventListener(eventListener = null, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when the state of a swarm connection changes. This is useful when the application needs to react to changes in the state of swarm connections, such as updating the user interface or logging the state changes.
```
addConnectionStateChangeEventListener(eventListener = null, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when the state of a connection changes. This can be useful in scenarios where the application needs to react to changes in the state of connections, such as updating the user interface or logging
```
addICEConnectionStateChangeEventListener(eventListener = null, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when the Interactive Connectivity Establishment (ICE) connection state changes. This can be useful in scenarios where the application needs to react to changes in the ICE connection state, such as updating the user interface, logging the state changes, or handling connection failures.
```
addDataChannelStateChangeEventListener(eventListener = null, appID = 0, peerID = null)
```
This method registers an event listener function that will be triggered when the state of a data channel changes. This is useful in applications that use the data channel to send non-media data and need to react to changes in the state of the data channel, such as opening, closing, or error states.
```
getTrackEventListeners()
```
This method returns the list of event listeners registered for track events. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getPeerAuthEventListeners()
```
This method returns the list of event listeners registered for peer authentication events. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getSwarmConnectionNewMessageListeners()
```
This method returns the list of event listeners registered for new message events in a swarm connection. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getSwarmConnectionNewSwarmMessageListeners()
```
This method returns the list of event listeners registered for new swarm message events. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getSwarmConnectionStateChangeEventListeners()
```
This method returns the list of event listeners registered for swarm connection state change events. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getConnectionStateChangeEventListeners()
```
This method returns the list of event listeners registered for connection state change events. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getICEConnectionStateChangeEventListeners()
```
This method returns the list of event listeners registered for ICE connection state change events. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getDataChannelStateChangeEventListeners()
```
This method returns the list of event listeners registered for data channel state change events. This can be used when the application needs to manage these listeners, for example, to remove some of them or to check if a specific listener is already registered.
```
getMyID()
```
This method returns the unique ID of the node within the swarm. This is particularly useful when the application needs to identify itself in the context of a swarm. For instance, when communicating with other nodes, it may need to disclose its ID for verification purposes or to facilitate directed communication.
```
reconnect()
```
This method triggers a reconnection attempt to the swarm. It can be used in scenarios where the connection to the swarm has been lost due to network issues or any other reason and a reconnection is necessary.
```
peers()
```
This getter method returns a list of active peers within the swarm. This can be used when the application needs to know the peers in the swarm for any reason, such as sending a message to all peers, checking the status of peers, or managing interactions among peers.
```
getID()
```
This getter method returns the unique ID of the swarm. This is useful when the application needs to identify the swarm for any reason, like logging, monitoring, or to manage multiple swarms.
```
initialize()
```
This method initializes the swarm. This is typically used when a new swarm is created or when the application needs to reset an existing swarm to its initial state.
```
close(killConnections = true)
```
This method closes the swarm and optionally terminates all connections. This is typically used when the application is done with the swarm and wants to release the resources associated with it.

Introduction to CSwarmConnection

CSwarmConnection is a powerful construct developed to abstract and enhance the traditional RTCPeerConnection component of the WebRTC API. It provides a more comprehensive, flexible, and security-conscious interface for managing peer-to-peer connections, while still leveraging the robust capabilities of RTCPeerConnection under the hood.

WebRTC is a versatile technology that enables real-time communication between peers on the internet. Its core construct, RTCPeerConnection, handles the complexity of establishing these connections. However, the use of RTCPeerConnection can be cumbersome, and it lacks certain advanced features that are critical for a more nuanced handling of peer connections. This is where CSwarmConnection comes into play.

Benefits of Using CSwarmConnection over RTCPeerConnection

Enhanced Security: CSwarmConnection introduces the concept of capabilities, which allow for more granular control over the permissions for incoming and outgoing data streams. This ensures that connections do not negotiate beyond the necessary permissions, providing a strong layer of security.
Muting/Unmuting without Renegotiation: CSwarmConnection allows for the muting and unmuting of audio and video live streams without the need for a full WebRTC renegotiation. This is made possible through the use of dynamically generated dummy tracks, which offer the flexibility of managing live streams efficiently.
Separate Ingress and Outgress Capabilities: With CSwarmConnection, you can specify different permissions for incoming and outgoing data streams. This offers the flexibility to control what you send and what you receive independently, potentially saving bandwidth and enhancing the user experience.
Zero-Knowledge Proof Authentication: CSwarmConnection supports ZKP authentication, which provides an additional layer of security during connection establishment. In these scenarios, all outgress data streams can be temporarily muted, ensuring no unnecessary data is transmitted during the authentication process.
Streamlined Interface: CSwarmConnection provides a more streamlined and intuitive interface compared to RTCPeerConnection, making it easier to establish, manage, and control peer-to-peer connections.

By integrating these advanced features, CSwarmConnection offers a more efficient and secure means of managing peer-to-peer connections over the internet, making it a suitable choice for developers seeking to leverage the power of WebRTC while also maintaining a high degree of control and security over their connections.

Introduction to Capabilities in CSwarmConnection

In the context of CSwarmConnection, capabilities refer to the permissions set for both incoming (ingress) and outgoing (outgress) data streams. They play a crucial role in ensuring that the WebRTC connections do not negotiate beyond the necessary permissions, thus providing a layer of security and control over the data being transmitted.

Ceiling Capabilities

Ceiling capabilities are the highest level of permissions that a user has set for a connection. These capabilities can be seen as the maximum allowed level of data transmission that a connection can utilize. They’re particularly useful when a user wishes to restrict the types of media (audio, video, or both) they’re willing to send or receive.

For instance, a user might be willing to send video streams but not want to receive them, either to save bandwidth or simply because they don’t need them. By setting a ceiling capability that only allows outgoing video streams, the user can ensure that incoming WebRTC connections won’t end up negotiating for receiving video streams.

Effective Capabilities

Effective capabilities refer to the actual capabilities that are currently in use for a connection. These capabilities can be less than or equal to the ceiling capabilities, but never exceed them. The effective capabilities of a connection can be dynamically adjusted based on the requirements of a session. For example, a user can mute their audio or video stream, effectively lowering the capabilities of that connection until they choose to unmute it.

Ingress and Outgress Capabilities

Ingress and outgress capabilities provide fine-grained control over the incoming and outgoing data streams, respectively. This allows users to set different permissions for the data they are sending compared to the data they are receiving. For instance, a user may want to send both audio and video data but only receive audio data. This can be achieved by setting different ingress and outgress capabilities.

Muting and Unmuting vs Capabilities

It’s important to note that the concept of muting and unmuting is separate from capabilities. While capabilities are about permissions (i.e., what a connection is allowed to send or receive), muting and unmuting relate to the state of the media streams (i.e., whether they are currently transmitting data or not).

Muting and unmuting extend the security and flexibility of the connection by allowing for audio and video live streams to be turned off and on at any moment, without the need for a full WebRTC renegotiation. This is achieved through the use of dummy tracks.

When a connection is muted, the media track (audio or video) is instantly replaced with a dummy track, which is generated dynamically. This results in the remote peer seeing a black screen (for video) or hearing silence (for audio). When the stream is unmuted, the dummy track is replaced with the real track coming from the local camera or microphone.

The use of dummy tracks and the ability to mute and unmute streams without renegotiating the connection are particularly useful in scenarios where a peer sets a new pre-shared secret. In these scenarios, all the connections within the swarm would have outgress data streams muted and then unmuted on a per-connection basis as these peers authenticate themselves through Zero-Knowledge Proof (ZKP). This ensures that no unnecessary data is transmitted during the authentication process, providing an additional layer of security.

Understanding these concepts and using them effectively can greatly enhance the security, efficiency, and flexibility of your WebRTC connections.

API documentation

Connection Management

```
CSwarmConnection()
```
Initializes a new instance of the `CSwarmConnection` class. This is typically used when establishing a new connection within a swarm network.
```
renewRTConnObject()
```
Renews the Real Time Communication (RTC) connection object. This method might be used if the existing RTC connection object becomes invalid or outdated.
```
setLocalDummyStream(stream)
```
Sets the local dummy stream. This can be useful for testing or for setting up a fallback stream.
```
isDummyStreamReady()
```
Checks if the dummy stream is ready. This is important to ensure that the stream is prepared and available for use, for example, before initiating a media session.
```
setLocalStream(stream)
```
Sets the local stream. This is typically used to set the media stream from the local device that will be transmitted to the remote peer.
```
setDataChannel(c)
```
Sets the data channel. This method is used to establish a channel for data communication between peers.
```
setStatus(status)
```
Sets the status of the connection. This could be used to manage the connection state internally.
```
ping()
```
This method sends a ping message to the other peer. This is used to notify the other peer about an active connection by constructing and dispatching a `CSwarmMsg`. It’s often used to maintain the connectivity and check the availability of the other peer.
```
sendMessage(message, onlyIfAuthenticated = true)
```
This method sends a `CNetMessage` container to the other peer. This could be used for transmitting application-specific messages or control signals. The `onlyIfAuthenticated` parameter allows the method to ensure that the message is only sent if the connection is authenticated.
```
sendSwarmMessage(message, protocolID, onlyIfAuthenticated = true)
```
This method sends a `CSwarmMsg` container to the other peer. It’s similar to `sendMessage`, but it is used specifically for sending swarm-related messages. The `protocolID` is used to specify the protocol to be used for sending the message. Like `sendMessage`, it can also ensure that the message is only sent if the connection is authenticated.
```
send(data, protocolID = 0, onlyIfAuthenticated)
```
This method sends raw bytes to the other peer. This can be useful when you need to transmit raw data, such as binary files or unformatted text. The `protocolID` is used to specify the protocol to be used for sending the data, and the `onlyIfAuthenticated` parameter can ensure that the data is only sent if the connection is authenticated.
```
initEvents()
```
This method initializes events related to the connection. This is generally called during the setup of the connection to register event handlers for various connection-related events. This can include events such as connection state changes, data channel messages, signaling state changes, and more.
```
close()
```
Closes the connection. This method is typically used when the interaction between the peers is complete, or if an error condition requires the connection to be terminated.

Event Handling

```
onMessage(message)
```
Processes incoming messages. This method could be used to handle any data or control messages received from the remote peer.
```
onDataChannelMessageEvent(event)
```
Handles data channel message events. This is usually used to process non-media data received from the other peer.
```
onPeerStatusChange(status)
```
Handles peer status change. This can be useful to update the user interface or to take certain actions when the remote peer’s status changes.
```
onConnQualityChange(quality)
```
Handles connection quality change. This might be used to adjust the media bitrate or to alert the user when the connection quality degrades.
```
onSwarmConnectionStateChange(eventData)
```
Handles swarm connection state change. This method could be used to coordinate actions across multiple connections within a swarm.
```
onDataChannelErrorEvent(event)
```
Handles data channel error events. This is important for error reporting and recovery.
```
onDataChannelEvent(event)
```
Handles data channel events. This might be used to handle control messages or to process data received over the data channel.
```
onHandleSignalingStateChangeEvent(event)
```
Handles signaling state change events. This is important for coordinating the signaling process during connection setup.
```
onLocalICECandidateEvent(event)
```
Handles local ICE candidate events. This is usually used to send ICE candidates to the remote peer during the ICE negotiation process.
```
onRemoteICECandidateEvent(candidate)
```
Handles remote ICE candidate events. This is typically used to add received ICE candidates to the local RTC connection.
```
onConnectionStateChangeEvent(e)
```
Handles connection state change events. This is essential for monitoring the state of the RTC connection and taking appropriate actions.
```
onNegotiatioNeeded(event)
```
Handles negotiation needed events. This is usually triggered when a change occurs that requires session negotiation.
```
onICEConnectionStateChangeEvent(event)
```
Handles ICE connection state change events. This is necessary to monitor the state of the ICE connection, for example, to detect disconnections or failures.
```
onPeerAuth(result = eSwarmAuthResult.failure, mode = eSwarmAuthMode.none)
```
Handles peer authentication. This is crucial for verifying the identity of the remote peer.
```
onTrackEvent(event)
```
Handles track events. This is usually used to process events related to media tracks, such as the addition or removal of tracks.
```
onSwarmMessage(message)
```
This method handles incoming swarm messages. These messages are typically used to communicate various types of information or commands within the swarm network. For instance, they could be used to coordinate actions, broadcast updates, or manage security features.

State Checking

```
get getRTCConnectionState()
```
Returns the current RTC connection state. This could be used to check whether the connection is new, connecting, connected, disconnected, failed, or closed.
```
get getRTCSignalingState()
```
Returns the current RTC signaling state. This is useful for checking the stage of the negotiation process (e.g., whether an offer/answer has been created or if the connection is stable).
```
get getStatus()
```
Returns the current status of the connection. This could be used for various purposes, such as updating the user interface, triggering certain actions based on the status, or logging.
```
get getLocalSDPOffer()
```
Returns the most recent Local Session Description Protocol (SDP) offer. This could be used to inspect the current offer, for example, to debug or log the offer details.

Media Handling

```
mute(audio = true, video = true, outgress = true, autoStopDummyTrack = false, autoStopDummyTrackAfterMS = 1000)
```
This asynchronous method mutes audio/video tracks. It doesn’t mute the data channel. This function could be used in a scenario where the user wants to stop sending audio/video media data to the other peer, for example, during a live video conference call when the user wants to go silent or off-camera.
```
unmute(audio = true, video = true, outgress = true)
```
This asynchronous method unmutes audio/video tracks. It doesn’t re-enable the data channel. This function could be used when the user wants to start sending audio/video data again after it was previously muted.
```
notifyAboutStateOfMedia(protocolID = 0)
```
This method notifies the remote peer about the state of the local media. This could be used to signal changes in media state, such as pausing or resuming a video stream.

Other Methods

```
get ingressStream()
```
Gets the ingress stream. This method could be used to fetch the inbound media stream for further processing or rendering.
```
set ingressStream(stream)
```
Sets the ingress stream. This method could be used to set the inbound media stream, typically received from the remote peer.
```
get getLocalDummyStream()
```
Gets the local dummy stream. This method could be useful for testing or for situations where a dummy media stream is required.
```
get getLocalStream()
```
Gets the local stream. This method could be used to fetch the outbound media stream for further processing or rendering.
```
get getDataChannel()
```
Gets the data channel. This method could be used to fetch the data channel for sending or receiving non

Internal Properties

These are sample internal properties. These should not be accessed directly. Some of the internal properties are enumerated below.

```
mLastKeepAliveReceivedMS
```
Time of the last received ‘keepAlive’ message.
```
mSwarm
```
The Swarm to which this connection belongs.
```
mPeerID
```
The ID of the peer with which this connection is established.
```
mDataChannel
```
WebRTC data channel for this connection.
```
mRTCConnection
```
WebRTC connection object.
```
mRecentLocalICE
```
Most recent local ICE candidate.
```
mStatus
```
Current status of the connection.

Enumerations

```
eSwarmMsgType
```
Enumerates types of swarm messages.
```
eSwarmConnectionState
```
Enumerates states of a swarm connection.
```
eRTCConnectionState
```
Enumer

Connection Capabilities

These are defined by the `eConnCapabilities` enumeration:

```
data
```
The connection is capable of data transmission.
```
audio
```
The connection is capable of audio transmission.
```
video
```
The connection is capable of video transmission.
```
audioVideo
```
The connection is capable of both audio and video transmission.

Swarm Message Types

These are defined by the `eSwarmMsgType` enumeration, and they specify the type of message contained in a `CSwarmMsg` container:

```
keepAlive
```
A message that maintains the connection.
```
binary`, `text`, `file
```
Various types of data that can be sent.
```
typing`, `avatar`, `command
```
Notifications about user actions.

mutedAudio`, `unmutedAudio`, `mutedCam`, `unmutedCam

Notifications about audio and video status changes.

```
startedScreenSharing`, `stoppedScreenSharing
```
Notifications about screen sharing status changes.

authenticationRequestVal`, `authenticationRequestCand`, `authenticationSuccess`, `authenticationFailure`, `zeroKnowledgeProof

Messages related to authentication.

Connection and Signaling States

These states are defined by the `eSwarmConnectionState`, `eRTCConnectionState`, and `eRTCSignalingState` enumerations. These states are used to describe the current state of the connection and the signaling process.

Swarm State

This is defined by the `eSwarmState` enumeration:

```
active
```
The swarm is currently active.
```
idle
```
The swarm is currently idle.

RTC Extra Data Type

This is defined by the `eRTCExtraDataType` enumeration:

```
sdp
```
Session Description Protocol data.
```
data
```
Other types of data.

Swarm Authentication Requirement

This is defined by the `eSwarmAuthRequirement` enumeration:

```
open
```
No authentication is required.
```
PSK_ZK
```
Pre-shared key zero-knowledge proof authentication is required.

Swarm Peer Status

This is defined by the `eSwarmPeerStatus` enumeration:

```
active
```
The peer is currently active.
```
notReachable
```
The peer is currently unreachable.

Connection Quality

This is defined by the `eConnQuality` enumeration:

```
none
```
No connection.
```
low, medium, high, max
```
Different levels of connection quality.

Sure, I’ll continue from where I left off.

Swarm Message Type

The `eSwarmMsgType` enumeration is used to specify the type of message contained within a `CSwarmMsg` container:

```
keepAlive
```
This message type is primarily used to maintain an active connection between peers.

Virtual Hardware Devices

Virtual hardware devices are an innovative feature provided by CSwarmConnection that enables the generation of dynamic audio and video data streams. These virtual devices serve three main purposes:

1. Efficiency: Virtual devices help eliminate the need for additional renegotiations when audio/video streams are enabled or disabled. They make the process smoother and more efficient by dynamically generating necessary streams.

2. Compatibility: Due to certain inconsistencies and bugs present in major implementations of the Chromium browser, virtual devices provide a consistent workaround that ensures that the WebRTC communication remains seamless.

3. Security: Virtual devices increase security by providing a “dummy” stream from a virtual device when the other end of the connection loses authorization. This ensures that no real data is exposed in such scenarios.

Often, streams from virtual devices are used only for brief periods during the process of muting and unmuting. This is done to improve compatibility across different WebRTC implementations and save bandwidth by entirely shutting down the video stream after switching to the dummy track from a virtual device.

The two main virtual device types are represented by the classes `CVirtualCamDev` and `CVirtualAudioDev`, which represent a virtual camera and a virtual microphone device respectively.

CVirtualCamDev

The `CVirtualCamDev` class represents a virtual camera. When instantiated, it can dynamically generate a video stream that mimics a real camera. This can be used as a “dummy” stream during periods when the real video stream is being enabled or disabled, or when the other end of the connection loses authorization.

CVirtualAudioDev

The `CVirtualAudioDev` class represents a virtual microphone. Similar to the virtual camera, it can dynamically generate an audio stream that mimics a real microphone. This stream can be used as a “dummy” stream during periods when the real audio stream is being enabled or disabled, or when the other end of the connection loses authorization.

These virtual devices provide a powerful tool for managing WebRTC connections in a secure, efficient, and compatible way. Their autonomous nature helps simplify many complex tasks associated with WebRTC communication, making CSwarmConnection a beneficial choice over traditional `RTCPeerConnection` constructs.

CVirtualCamDev

`CVirtualCamDev` is a class that represents a virtual camera device. This device generates a dummy video stream that can be used when the actual video stream is being enabled or disabled, or when the other end of the connection loses authorization.

Constructor

constructor(widthP = 640, heightP = 480)

The constructor creates a new instance of a virtual camera device. The width and height of the video can be specified, with default values of 640 and 480 respectively. The constructor also initializes a video track for the virtual device.

Properties

```
mEnabled
```
This boolean property indicates whether the virtual camera is currently enabled or not.
```
mTrack
```
This property holds the video track for the virtual device. The track is an object that includes a method to generate a video track with the specified width and height.

Methods

```
enabled(isIt)
```
This setter method sets the value of `mEnabled`.
```
enabled()
```
This getter method returns the current value of `mEnabled`.
```
getTrack()
```
This getter method returns the current video track (`mTrack`) of the virtual device.

CVirtualAudioDev

`CVirtualAudioDev` is a class that represents a virtual microphone device. This device generates a dummy audio stream that can be used when the actual audio stream is being enabled or disabled, or when the other end of the connection loses authorization.

Constructor

The constructor creates a new instance of a virtual microphone device. It initializes the audio context, creates an oscillator, defines the type of wave, and sets the volume.

Properties

```
mMuted
```
This boolean property indicates whether the virtual microphone is currently muted or not.
```
mWasOscillatorEverStarted
```
This boolean property indicates whether the oscillator has ever been started.
```
mAudioCtx
```
This property holds the audio context for the virtual device.
```
mOscillator
```
This property holds the oscillator for the virtual device.
```
mVolumeDev
```
This property holds the gain node that controls the volume of the audio stream.

Methods

```
startOscillator()
```
This method starts the oscillator if it hasn’t been started before. It also connects the oscillator to the volume control.
```
stopOscillator(onlyDetach = true)
```
This method stops the oscillator and disconnects it from the volume control.
```
renew()
```
This method stops the current audio track and creates a new one.
```
muted(isIt)
```
This setter method sets the value of `mMuted`.
```
muted()
```
This getter method returns the current value of `mMuted`.
```
getTrack()
```
This getter method returns the current audio track of the virtual device.
```
setVolume(val)
```
This setter method sets the volume of the audio stream.
```
getVolume()
```
This getter method returns the current volume of the audio stream.
```
enabled(isIt)
```
This setter method sets the value of `mEnabled`.
```
enabled()
```
This getter method returns the current value of `mEnabled`.

CSwarmsManager Class

The `CSwarmsManager` class acts as the main orchestrator within the Swarms API, providing a comprehensive framework for managing various instances of `CSwarm` objects. This sophisticated class is the central hub for all Swarm-related activities, effectively serving as the control center for the distributed p2p network.

The `CSwarmsManager` operates by managing and coordinating a collection of `CSwarm` objects. Each `CSwarm` object represents a Swarm, which is essentially a sub-network within the larger network. Swarms are responsible for managing the peer-to-peer connections between users, providing the fundamental building blocks for data exchange and interaction within the network.

A `CSwarm` in turn manages multiple `CSwarmConnection` objects, each of which represents a direct connection between two peers in a Swarm. This structured hierarchy allows for the efficient management of resources, connection handling, data transfer, and network optimization.

The `CSwarmsManager`’s role is pivotal in managing the lifecycle of Swarms, including their creation, maintenance, and deletion. It continuously monitors the underlying Swarms to ensure optimal network performance and resource allocation. Every Swarm needs to be registered with the `CSwarmsManager`, which then provides necessary control and monitoring services.

As a Singleton class, only one instance of `CSwarmsManager` exists within a given context. This design ensures that there is a single point of control and coordination for all Swarms within the network, promoting consistency and efficient management.

The `CSwarmsManager` is responsible for a range of functionalities, including media handling (audio, video, and screen capture), stream optimization, capabilities management, and authentication. It also provides a range of callbacks to handle various Swarm events, including new data arrival and connection status changes.

By providing a centralized management system for `CSwarm` and `CSwarmConnection` objects, `CSwarmsManager` plays an essential role in the operation and optimization of the Swarms API. This intricate interplay between `CSwarmsManager`, `CSwarm`, and `CSwarmConnection` forms the backbone of the Swarms API, providing a robust and flexible platform for peer-to-peer network management.
The `CSwarmsManager` class is a singleton that manages and monitors Swarms within a web-browser context. It provides methods for controlling and managing resources like video/audio feeds, streams, etc., and handles interaction with the underlying Swarms.

Benefits

The `CSwarmsManager` class, part of the Swarms API, brings several significant benefits compared to using the raw WebRTC API. Here are a few of them:

Abstraction and Ease of Use:
One of the primary advantages of `CSwarmsManager` is that it abstracts the complexities of managing Swarms, which in turn manage WebRTC connections. Instead of manually managing peer connections, signaling, and data channels, developers can use high-level functions provided by `CSwarmsManager` also in aggregated scope of group connections comprising Swarms (in our terminology). This significantly reduces the amount of code needed and the potential for errors.

Autonomous Management:
The `CSwarmsManager` class autonomously manages Swarms and their connections. It maintains the connection to the Swarm, tracks connection quality, and can switch signaling nodes when necessary. This process happens transparently, without the need for explicit user intervention, making the system more robust and easier to use.
Resource Management:
The Swarms API, with `CSwarmsManager` at its core, provides an intelligent mechanism to manage resources. It ensures optimal resource utilization across all running decentralized applications within a web browser’s tab. This resource management extends to audio and video feeds, ensuring optimal use of hardware resources.
Agregated Multi-party Communication:
Managing multi-party communication can be challenging with the raw WebRTC API. `CSwarmsManager` simplifies this process by handling the complexities of data routing among multiple peers but also of multiple groups. It also provides developers with the ability to send data to all members of multiple Swarms, to Swarms or specfic recipients.
Security:
`CSwarmsManager` by orchestrating all of conceives together with `CSwarm` and `CSwarmConnection` provides built-in mechanisms for secure communication. It supports token-based authentication and has mechanisms to authenticate SDP (Session Description Protocol) entities, ensuring secure communication within the Swarm.
Scalability:
With the raw WebRTC API, scaling to support multiple connections can be a challenge. `CSwarmsManager`, with its ability to manage multiple Swarms and connections, provides a scalable solution for real-time communication.

Multi-tasking Support

The Swarms API, including the `CSwarmsManager` class, is a part of GRIDNET OS, and as such, it provides a robust platform for both cross-browser and local cross-process communication.

The key feature of GRIDNET OS is its ability to provide a unified interface for communication, synchronization, and resource optimization, irrespective of whether the communication is happening within a single tab, across different tabs in a browser, or even across different browsers. This is a powerful feature as it abstracts the complexities of communication and synchronization, allowing developers to focus on their application logic.

Within a single browser’s tab, multiple decentralized applications (dApps) can run concurrently, each potentially participating in different swarms. The Swarms API allows these dApps to query for active swarms and attach themselves to these swarms if required. This cross-process communication is managed efficiently by the Swarms API, ensuring optimal use of resources and seamless communication between the dApps.

Another critical aspect of the Swarms API is its support for privacy. A dApp can mark a swarm as private, restricting other applications from attaching themselves to the private swarm. This feature is essential for scenarios where a dApp needs to ensure data privacy and secure communication.

The Swarms API is a versatile communication and synchronization interface that caters to various scenarios, from cross-browser communication to local cross-process communication within a single browser’s tab. It efficiently manages resources, ensures secure communication, and provides powerful constructs for synchronization, making it an essential part of the GRIDNET OS.

Key Properties:

These should not be accessed directly.

mSwarms An array storing the Swarms.
mTools An instance of CTools.
mSwarmDataListeners An array of listeners for Swarm data events.
mTokenPool Token pool used for authentication.
mPrivKey Private key used for authentication.
mLocalStream The local media stream.
mDefaultOutgressCapabilities The default capabilities for outgoing connections.

Noteworthy Methods:

- optimizeRequestedResources() Optimizes resources such as video/audio feeds.

– `setEffectiveIngressCapabilities(allowed, swarmID)`, `setAllowedCapabilities(allowed, swarmID)`: Methods to set capabilities for ingress and general communication.

- addSwarm(swarm, doInit) Adds a Swarm to the manager.
- sendData(data, recipientID, swarmID) Sends data to members of a Swarm.
- findSwarmByID(id) Finds a Swarm by its ID.
- initialize() Initializes the `CSwarmsManager` instance with default settings and devices.

– `connectionStatusChangedCallback(status)`, `newSwarmSDPMsgCallback(sdp)`, `onNewSwarmData(swarmID, peerID, data)`: Various callback methods for handling changes in connection status, SDP messages, and new Swarm data.

- routeExtraData(data, swarmID, source, destination, onlyImmediatePeers) Routes extra data to destination.
- authenticateSDP(sdp) Authenticates a control datagram.
- syncSwarm(swarmID, userID, privKey) Synchronizes the state of the Swarm with the rest of the network.

– `bootstrapMedia(capabilities)`, `prepareForCapabilities()`: Methods to prepare hardware resources as per the provided capabilities.

- unregisterProcessFromSwarms(processID) Unregisters a process from the Swarm.

– `joinSwarm(trueSwarmID, userID, privKey, capabilities, appInstance)`, `pingFullNode(swarmID, userID, privKey)`, `leaveSwarm(trueSwarmID)`: Methods to join, ping, or leave a Swarm.

API Documentation

```
getInstance(vmContext)
```
– Parameters:
– `vmContext`: The context of the virtual machine.
– Returns: The single instance of `CSwarmsManager`.
– Description: This static method creates a new instance of `CSwarmsManager` if none exists, or returns the existing instance.
– Use case: This method is typically used to get a reference to the `CSwarmsManager` singleton.
```
stopBothVideoAndAudio(stream)
```
– Parameters:
– `stream`: The media stream to stop.
– Returns: None.
– Description: This method stops both the video and audio components of the specified media stream.
– Use case: This method can be used when the user wants to stop both the video and audio streams at the same time, such as when ending a video call.
```
stopVideoOnly(stream)
```
– Parameters:
– `stream`: The media stream from which to stop the video.
– Returns: None.
– Description: This method stops only the video component of the specified media stream.
– Use case: This method can be used when the user wants to stop only the video stream, such as when the user wants to continue a call with audio only.
```
stopAudioOnly(stream)
```
– Parameters:
– `stream`: The media stream from which to stop the audio.
– Returns: None.
– Description: This method stops only the audio component of the specified media stream.
– Use case: This method can be used when the user wants to stop only the audio stream, such as when the user wants to continue a call with video only.
```
stopCapture()
```
– Parameters: None.
– Returns: None.
– Description: This method stops the screen capture.
– Use case: This method can be used when the user wants to stop sharing their screen during a video call or a live stream.
```
startBothMicAndCam()
```
– Parameters: None.
– Returns: A promise that resolves when both the microphone and camera have been started.
– Description: This asynchronous method starts both the microphone and camera.
– Use case: This method can be used when initiating a video call, where both audio and video are required.
```
startCapture()
```
– Parameters: None.
– Returns: A promise that resolves when the screen capture has started.
– Description: This asynchronous method starts screen capture.
– Use case: This method is useful when the user wants to share their screen, for example during a presentation or a video conference.
```
startCamOnly()
```
– Parameters: None.
– Returns: A promise that resolves with the stream when the camera has started.
– Description: This asynchronous method first stops any existing video stream (to prevent zombie handles) and then starts the camera only.
– Use case: This method can be used when the user wants to start only the video stream, such as when initiating a video-only call or streaming a video.
```
startMicOnly()
```
– Parameters: None.
– Returns: A promise that resolves when the microphone has started.
– Description: This asynchronous method starts only the microphone.
– Use case: This method can be used when the user wants to start only the audio stream, such as when initiating an audio-only call or recording a podcast.
```
optimizeRequestedResources()
```
– Parameters: None.
– Returns: None.
– Description: This method optimizes the resources requested from the underlying web browser, such as video and audio feeds. This may include releasing the camera when it is not in use, to ensure the user’s privacy.
– Use case: This method can be used in situations where resource optimization is required, for example, when running on devices with limited resources, or to ensure that the webcam is not in use when not needed.
```
setEffectiveIngressCapabilities(allowed, swarmID = null)
```
– Parameters:
`allowed`: Defines the allowed capabilities.
`swarmID` (optional): The ID of the swarm to set the capabilities for. If not provided, sets the capabilities for all swarms.
Returns: None.
Description: This method is used to set the effective ingress capabilities. It can be used to mute the microphone or disable video output to all immediate peers. It does not affect the presence of tracks themselves.
Use case: Use this function when you want to disable or enable certain capabilities (like video or microphone) for a specific swarm or for all swarms.
```
setAllowedCapabilities(allowed, swarmID = null)
```
– Parameters:
`allowed`: Defines the allowed capabilities.
`swarmID` (optional): The ID of the swarm to set the capabilities for. If not provided, sets the capabilities for all swarms.
Returns: None.
Description: This method sets the allowed capabilities which can affect connections with all immediate swarms’ peers.
Use case: Similar to `setEffectiveIngressCapabilities`, this method can be used to set the capabilities for a specific swarm or all swarms.
```
getAllowedMedia(allowed)
```
– Parameters:
`allowed`: Defines the allowed capabilities.
Returns: A promise that resolves with the allowed media.
Description: This asynchronous method retrieves the allowed media based on the provided capabilities.
Use case: This method can be used to get the media streams (audio, video, etc.) that are allowed based on the user’s settings or preferences.
```
onLocalStream(stream, swarmID)
```
– Parameters:
`stream`: The local media stream.
`swarmID`: The ID of the swarm.
Returns: None.
Description: This method is a handler for the event when a local media stream becomes available.
Use case: This method can be used as a callback for when the local media stream is ready, for instance, to then display the stream in a video player.
```
onLocalTrackHandler(event)
```
– Parameters:
`event`: The event object associated with the local track.
Returns: None.
Description: This method is a handler for the event when a local track becomes available.
Use case: This method can be used as a callback for when a track of the local media stream is ready, for instance, to handle specific track events such as track added or track removed.
```
getEffectiveOutgressCapabilities()
```
Parameters: None.
Returns: The effective outgress capabilities.
Description: This method retrieves the effective outgress capabilities.
Use case: Use this method when you want to get the current outgress capabilities which are being used, such as for displaying the current settings in a user interface.
```
getActiveHardwareCapabilities()
```
Parameters: None.
Returns: The active hardware capabilities.
Description: This method retrieves the capabilities of the active hardware.
Use case: This can be used to get the capabilities of the hardware currently in use, for instance, to ensure that the hardware is capable of performing certain tasks before attempting them.
```
setLocalStreamEffectiveCapabilities(capabilities = -1)
```
Parameters:
`capabilities` (optional): The capabilities to set. If not provided, defaults to `-1`.
Returns: None.
Description: This method sets the effective capabilities of the local stream.
Use case: This method can be used to change the capabilities of the local stream, for example, to mute the audio or disable the video.
```
addSwarm(swarm, doInit = true)
```
Parameters:
`swarm`: The swarm to add.
`doInit` (optional): A boolean indicating whether to initialize the swarm. If not provided, defaults to `true`.
Returns: None.
Description: This method adds a swarm to the Swarms Manager and optionally initializes it.
Use case: Use this method when you want to add a new swarm to the Swarms Manager, such as when a new user joins a group chat or video call.
```
sendData(data, recipientID, swarmID)
```
Parameters:
`data`: The data to send.
`recipientID`: The ID of the recipient.
`swarmID`: The ID of the swarm.
Returns: None.
Description: This method sends data to a specific recipient in a specific swarm. If `recipientID` or `swarmID` are `null`, it sends the data to all members or all active swarms, respectively.
Use case: This method can be used to send data, such as chat messages or file transfers, to a specific user or to all users in a swarm.
```
findSwarmByID(id)
```
– Parameters:
`id`: The ID of the swarm to find.
Returns: The swarm with the given ID, or `null` if no such swarm exists.
Description: This method finds a swarm by its ID.
Use case: This method can be used to find a specific swarm, such as when you need to interact with a specific group chat or video call.
```
set setTPBankIDToUse(id)
```
– Parameters:
`id`: The ID of the token pool bank to use.
Returns: None.
Description: This setter method sets the ID of the token pool bank to use.
Use case: Use this method when you want to set the token pool bank to use for incentivization of outgoing data.
```
get getTPBankIDToUse()
```
– Parameters: None.
Returns: The ID of the token pool bank being used.
Description: This getter method retrieves the ID of the token pool bank being used.
Use case: Use this method when you want to get the ID of the token pool bank currently in use.
```
addSwarmDataListener(listener)
```
– Parameters:
`listener`: The data listener to add.
Returns: None.
Description: This method adds a data listener to the Swarms Manager.
Use case: Use this method when you want to listen for data events from all active swarms.
```
set setTokenPool(pool)
```
– Parameters:
`pool`: The token pool to set.
Returns: None.
Description: This setter method sets the token pool used for incentivization of outgoing data.
Use case: Use this method when you want to set the token pool for incentivization purposes.
```
get getTokenPool()
```
– Parameters: None.
Returns: The current token pool.
Description: This getter method retrieves the token pool used for incentivization of outgoing data.
Use case: Use this method when you want to get the current token pool for incentivization purposes.
```
set setPrivKey(privKey)
```
– Parameters:
`privKey`: The private key to set.
Returns: None.
Description: This setter method sets the private key used for authentication.
Use case: Use this method when you want to set the private key for authentication purposes.
```
get getPrivKey()
```
– Parameters: None.
Returns: The current private key.
Description: This getter method retrieves the private key used for authentication.
Use case: Use this method when you want to get the current private key for authentication purposes.
```
get getDummyVideoStream()
```
– Parameters: None.
Returns: The current dummy video stream.
Description: This getter method retrieves the dummy video stream.
Use case: Use this method when you want to get the current dummy video stream, for example for testing purposes.
```
initialize()
```
– Parameters: None.
Returns: None.
Description: This method initializes the Swarm Manager. It sets up the virtual audio and video devices and initializes the dummy stream.
Use case: Use this method to initialize the Swarm Manager, typically when starting the application.
```
connectionStatusChangedCallback(status)
```
– Parameters:
`status`: The new connection status.
Returns: None.
Description: This async callback is invoked when there is a change in connection status. The implementation details of this method should reflect what actions need to be taken during such changes.
Use case: This method is typically used internally within the `CSwarmManager` class to handle changes in connection status.
```
newSwarmSDPMsgCallback(sdp)
```
– Parameters:
`sdp`: The SDP message.
Returns: None.
Description: This method is a callback that is invoked when a new Swarm SDP message arrives. The implementation details should reflect what actions need to be taken upon the arrival of a new SDP message.
Use case: This method is typically used internally within the `CSwarmManager` class to handle new Swarm SDP messages.
```
onNewSwarmData(swarmID, peerID, data)
```
– Parameters:
`swarmID`: ID of the Swarm.
`peerID`: ID of the Peer.
`data`: The data received.
Returns: None.
Description: This method is invoked when new data arrives from a Swarm. The implementation details should reflect what actions need to be taken upon the arrival of new data.
Use case: Use this method to handle the reception of new data from a Swarm. For example, you might use it to update the UI or process the received data.
```
get getSwarmIDs()
```
– Parameters: None.
Returns: The current Swarm IDs.
Description: This getter method retrieves the IDs of the current Swarms.
Use case: Use this method when you want to get the IDs of the current Swarms.
```
get getCurrentSwarmID()
```
– Parameters: None.
Returns: The current Swarm ID.
Description: This getter method retrieves the ID of the current Swarm.
Use case: Use this method when you want to get the ID of the current Swarm.
```
set setCurrentSwarmID(swarmID)
```
– Parameters:
`swarmID`: The ID of the Swarm.
Returns: None.
Description: This setter method sets the ID of the current Swarm.
Use case: Use this method when you want to set or change the current Swarm ID. For instance, when you are switching between different Swarms, this method can be used to update the current Swarm ID.
```
get getIsPrivKeyAvailable()
```
– Parameters: None.
Returns: A boolean indicating whether the private key is available.
Description: This getter method checks if the private key for authentication is available.
Use case: Use this method when you want to check the availability of the private key. For example, before attempting any operation that requires the private key, you can use this method to ensure the key is available.
```
get getIsTokenPoolAvailable()
```
– Parameters: None.
Returns: A boolean indicating whether the token pool is available.
Description: This getter method checks if the token pool for incentivization of outgoing data is available.
Use case: Use this method when you want to check the availability of the token pool. For instance, before attempting any operation that requires the token pool, you can use this method to ensure it is available.
```
routeExtraData(data = null, swarmID = null, source = null, destination = null, onlyImmediatePeers = true)
```
– Parameters:
`data`: The extra data to route. Default is null.
`swarmID`: The ID of the Swarm. Default is null.
`source`: The source of the data. Default is null.
`destination`: The destination of the data. Default is null.
`onlyImmediatePeers`: A boolean indicating whether to send the data only to immediate peers. Default is true.
Returns: A boolean indicating whether the data was successfully routed.
Description: This method routes extra data to a specific Swarm or to all Swarms if no Swarm ID is provided.
Use case: Use this method when you want to send extra data to a specific Swarm or to all Swarms. For example, in a chat application, you might use this method to send a message to a specific Swarm or to all Swarms.
```
routeSDPEntity(sdp)
```
– Parameters:
`sdp`: The SDP (Session Description Protocol) entity to route.
Returns: None.
Description: This method takes an SDP entity, authenticates it when possible, and delivers it to the full node for further routing to the destination.
Use case: Use this method when you want to send an SDP message to a peer via a full node. For example, during a WebRTC call setup, you might use this method to send an SDP offer or answer.
```
get getCapabilitiesRequestedBySwarms()
```
– Parameters: None.
Returns: The capabilities requested by the Swarms.
Description: This getter method retrieves the capabilities that have been requested by the Swarms.
Use case: Use this method when you want to check the capabilities that have been requested by the Swarms. For instance, you might use this method to adjust your resource allocation based on the capabilities requested by the Swarms.
```
authenticateSDP(sdp)
```
– Parameters:
`sdp`: The SDP (Session Description Protocol) entity to authenticate.
Returns: None.
Description: This method authenticates a control datagram (an SDP entity).
Use case: Use this method when you need to authenticate an SDP message. For example, during a WebRTC call setup, you might use this method to authenticate an SDP offer or answer.
```
syncSwarm(swarmID = null, userID = new ArrayBuffer(), privKey = new ArrayBuffer())
```
– Parameters:
`swarmID`: The ID of the Swarm. Default is null.
`userID`: The ID of the user. Default is an empty ArrayBuffer.
`privKey`: The private key for authentication. Default is an empty ArrayBuffer.
Returns: None.
Description: This method synchronizes the state of the Swarm with the rest of the network. It might attempt to reconnect to the selected Swarm if needed.
Use case: Use this method when you want to synchronize the state of a Swarm with the rest of the network. For example, after a network disruption, you might use this method to reestablish synchronization with the network.
```
bootstrapMedia(capabilities = this.mDefaultOutgressCapabilities)
```
– Parameters:
`capabilities`: The capabilities to be supported during the media bootstrap process. By default, it takes the default outgress capabilities.
Returns: None.
Description: This method bootstraps media devices as per the provided capabilities.
Use case: Use this method when you want to initialize the media devices according to certain capabilities. For example, you might use this method to bootstrap the media devices to support audio and video.
```
prepareForCapabilities()
```
– Parameters: None.
Returns: Promise.
Description: This async method prepares all the hardware resources so that the Allowed Capabilities are satisfied.
Use case: Use this method when you want to prepare the system’s hardware resources for certain capabilities. For example, you might use this method to prepare the system for video streaming.
```
unregisterProcessFromSwarms(processID)
```
– Parameters:
`processID`: The ID of the process to unregister.
Returns: None.
Description: This method unregisters a process, given its process ID, from the Swarm. If no processes are using a Swarm, the connection with the Swarm would be terminated to save resources.
Use case: Use this method when you want to remove a process from the Swarm. For example, you might use this method to unregister a process that has completed its task.
```
joinSwarm(trueSwarmID = new ArrayBuffer(), userID = new ArrayBuffer(), privKey = new ArrayBuffer(), capabilities = eConnCapabilities.audioVideo, appInstance)
```
– Parameters:
`trueSwarmID`: The true ID of the Swarm to join. Default is an empty ArrayBuffer.
`userID`: The ID of the user. Default is an empty ArrayBuffer.
`privKey`: The private key for authentication. Default is an empty ArrayBuffer.
`capabilities`: The ceiling capabilities supported during participation within Swarm. Default is audio and video.
`appInstance`: The application instance to associate with the Swarm.
Returns: None.
Description: This method provides an indication to a full-node (signaling server) of our will to join a particular or a most ‘suitable’ swarm – decided at full-node’s discretion.
Use case: Use this method when you want to join a Swarm. For example, you might use this method to join a Swarm for a group video call.
```
pingFullNode(swarmID = new ArrayBuffer(), userID = new ArrayBuffer(), privKey = new ArrayBuffer())
```
– Parameters:
`swarmID`: The ID of the Swarm. Default is an empty ArrayBuffer.
`userID`: The ID of the user. Default is an empty ArrayBuffer.
`privKey`: The private key for authentication. Default is an empty ArrayBuffer.
Returns: None.
Description: This method provides an indication to full-node (signaling server) that the client still requires its signaling/data routing support. Note that the server might require a reward (through Transmission Token) for doing so.
Use case: Use this method when you want to notify the full-node that the client is still active and requires its services. For example, during a long file transfer, you might use this method to keep the connection active.
```
leaveSwarm(trueSwarmID = new ArrayBuffer())
```
– Parameters:
`trueSwarmID`: The true ID of the Swarm to leave. Default is an empty ArrayBuffer.
Returns: None.
Description: This method provides an indication to signaling server that we’re to leave a given swarm.
Use case: Use this method when you want to leave a Swarm. For example, after a group video call, you might use this method to leave the call Swarm.

Typical Workflow

1. Initialization of the Swarms Manager:

Initialize the `CSwarmsManager` instance using the `getInstance` static method. This method ensures the singleton nature of the class. The initialization comes with default settings for local stream, authentication keys, and token pool, among others.

2. Joining a Swarm:

The user can join a specific Swarm using the `joinSwarm` method. This method signals the full node about the client’s intent to join a specific Swarm, identified by its `trueSwarmID`. The `joinSwarm` method also automatically adds a `CSwarm` instance to the `CSwarmsManager`, representing the Swarm that the client has joined.

3. Data Handling:

After joining a Swarm, the user can send and receive data. The `sendData` method of `CSwarm` can be used to send data to all members of the Swarm or to a specific recipient within the Swarm. The `onNewSwarmData` event listener in `CSwarmsManager` is used to handle incoming data.

4. Swarm Management:

The `CSwarmsManager` and `CSwarm` instances manage the Swarm’s state autonomously. They maintain the connection to the Swarm, track connection quality, and can switch signaling nodes when necessary. This process happens transparently, without the need for explicit user intervention.

5. Managing Capabilities:

The `CSwarmsManager` manages the capabilities of the Swarm with default values. By default, both audio and video capabilities are enabled. However, if needed, these capabilities can be customized using the `setAllowedCapabilities` method.

6. Leaving a Swarm:

When the user is done interacting within a Swarm, they can leave using the `leaveSwarm` method. This informs the full node that the client wishes to leave the Swarm.

This workflow should provide a comprehensive understanding of how to interact with the Swarms API, taking into account the automatic Swarm addition by the `joinSwarm()` method, the autonomous management of Swarms, and the management of capabilities with default values.

Decentralized Signaling

WebRTC (Web Real-Time Communication) is a free, open-source project that enables peer-to-peer communication between browsers and mobile applications via simple APIs. However, to establish a direct communication channel (also known as a peer connection), certain steps need to be taken, and this is where signaling comes in.

Signaling

in the context of WebRTC is the process of coordinating communication between peers to set up, control, and terminate a session. It’s important to note that WebRTC itself does not implement signaling; it must be implemented by the application using WebRTC.

During signaling, session control messages are exchanged between peers, including:

Session control messages: These can be used to open or close communication sessions.
Error messages: These are sent if an error occurs during the setup or communication process.
Media metadata: This includes information about media capabilities, codecs, codec settings, bandwidth, and media types.
Network data: This can include information about IP addresses and ports, network status, and other data used to route media.

The two peers use this data to agree on a set of compatible communication characteristics, which they then use to establish a connection. This process is called Session Description Protocol (SDP) negotiation.

Although WebRTC is designed for peer-to-peer communication, it’s not always possible for two peers to communicate directly due to network restrictions, such as firewalls and NAT (Network Address Translation) devices. This is where TURN and STUN servers come into play.

Let us now briefly tackle both of these concepts.

STUN (Session Traversal Utilities for NAT) servers are used to discover the public IP and port that corresponds to a local IP and port. This is necessary because a device on a local network is usually not aware of its own public IP address or the port that the NAT device has opened for it.
TURN (Traversal Using Relays around NAT) servers, on the other hand, are used when direct (peer-to-peer) connection is not possible. In such cases, the TURN server acts as a relay, forwarding data between peers. However, using TURN servers requires more resources because all data transmitted during the session must pass through the server.

In a traditional WebRTC setup, signaling and STUN/TURN servers are often centralized, which can lead to issues with scalability, reliability, and privacy.

The Swarms API introduces a novel approach with fully decentralized signaling facilitated by the nodes comprising the network. Instead of relying on centralized servers to facilitate communication, every node in the swarm network can act as a signaling facilitator. This results in a more resilient, scalable, and potentially more private communication network.

In this setup, each node in the network has an equal role and can help in establishing a communication session between peers, thereby creating a more robust and efficient network. Additionally, this approach can potentially reduce the reliance on resource-intensive TURN servers, as more paths for peer-to-peer communication become available in the decentralized network. This makes the Swarms API a compelling solution for developers looking to build applications with real-time, peer-to-peer communication capabilities.

Benefits of decentralized signaling

To delve deeper, let’s discuss some of the key benefits and novel functionalities offered by the Swarms API’s decentralized signaling:

Scalability:
In a traditional centralized system, increasing the number of users can lead to a strain on the signaling and STUN/TURN servers, requiring more server resources to maintain performance. In contrast, a decentralized system like the one facilitated by the Swarms API can scale more naturally. As new nodes join the network, they also contribute to the network’s signaling capacity, helping to balance the load.
Reliability and Redundancy:
In a centralized system, if the signaling server goes down, it can disrupt the entire communication network. However, in a decentralized network, the failure of a single node has a much lesser impact, as other nodes can take over its signaling duties. This leads to a much more robust and reliable network.
Privacy and Security:
In a typical WebRTC setup, the signaling server has access to all the session initiation data. This could potentially be a privacy concern. But in a decentralized system, where signaling is handled peer-to-peer, this risk is mitigated. Furthermore, in terms of security, the Swarms API can leverage end-to-end encryption, ensuring that only the intended recipients can read the communicated data.
Efficient Resource Utilization:
In traditional WebRTC, the need for TURN servers can become a significant cost and performance factor, as all data needs to be relayed through these servers when direct peer-to-peer communication is not possible. By enabling more flexible, decentralized paths for communication, the Swarms API can potentially reduce reliance on these resource-intensive servers.
Cross-Browser and Cross-Platform Communication:
The Swarms API, being part of the GRIDNET OS, not only supports cross-browser communication but also facilitates cross-platform communication. This implies that applications running on different devices or platforms can communicate seamlessly, enhancing the overall user experience.
Ease of Development:
The Swarms API abstracts away many of the complexities involved in establishing and managing peer-to-peer connections, such as SDP negotiation, ICE candidate exchange, and dealing with network restrictions. This allows developers to focus on their application logic, rather than the intricacies of WebRTC and signaling protocols.
Interoperability:
The Swarms API, built on the foundation of WebRTC, ensures interoperability with all platforms that support WebRTC. This enables developers to build applications that can seamlessly communicate across a wide range of devices and platforms including desktop, mobile, and embedded systems.
Network Topology Flexibility:
In contrast to the client-server model, where all clients connect to a central server, the Swarms API supports more flexible network topologies. This includes mesh networks (where each peer connects to every other peer), star networks (where a central node relays messages between peers), and hybrid models.
Automatic Network Management: The Swarms API takes care of network management tasks like connection establishment, maintenance, and termination, as well as error handling. This significantly simplifies the development process, allowing developers to focus on application-level logic rather than networking details.
Multi-Swarm Support:
With Swarms API, applications can join multiple swarms, each possibly with different communication requirements and capabilities. This is akin to a person being part of multiple different conversation groups, each with their own participants and topics. This feature enables complex communication scenarios and fosters a richer, more interactive user experience.
Real-Time Communication:
The Swarms API is designed to support real-time communication. Whether it’s video conferencing, live streaming, online gaming, or real-time collaboration, Swarms API provides the necessary tools to build responsive, real-time applications.
Reduced Latency:
In traditional client-server architectures, data often needs to travel a long way from the sender to the server, and then back to the receiver, which can introduce significant latency. In contrast, Swarms API’s peer-to-peer communication can dramatically reduce this latency, as data can often travel directly from the sender to the receiver.

The Swarms API offers a compelling alternative to traditional client-server communication models, providing a wealth of benefits such as scalability, reliability, privacy, and reduced latency. Its decentralized nature, combined with the power of WebRTC, allows for the creation of a new generation of real-time, peer-to-peer applications.
With these benefits and innovative functionalities, the Swarms API offers a powerful toolset for developers aiming to leverage peer-to-peer communication in their applications, making it easier than ever to build scalable, reliable, and secure real-time communication applications.

Compared to Ethereum

The Swarm API, as part of GRIDNET OS, offers unique features and capabilities that distinguish it from other communication constructs like those available on Ethereum. The comparison below highlights the advantages of the Swarm API:

Real-Time Communication: Ethereum, as a blockchain platform, isn’t designed for real-time communication. Focusing thus on – Transactions (as means of cummunication) these Ethereum can take several minutes to be processed, and each transaction incurs a cost. On the other hand, the Swarm API is designed for real-time, peer-to-peer communication, making it ideal for applications like video chat, real-time gaming, and collaborative tools.
Efficient Resource Management: The Swarm API offers sophisticated resource management capabilities, such as the ability to optimize hardware resources across multiple decentralized applications. In contrast, Ethereum doesn’t offer any native support for managing resources like video and audio feeds.
Built-In Privacy Features: The Swarm API offers built-in privacy features, such as the ability to create private swarms, and to control who can join a swarm. Ethereum, on the other hand, is a public blockchain where all transactions (if considered as means of communication) are visible to all participants.
Scalability: While Ethereum struggles with scalability issues, the Swarm API is designed to scale effectively. By leveraging WebRTC for peer-to-peer communication, the Swarm API can handle a large number of connections without the need for a central server.
Reduced Costs: Ethereum transactions require gas fees, which can be high during periods of network congestion. In contrast, the Swarm API, being only a part of GRIDNET OS, doesn’t incur transaction fees for communication, making it a more cost-effective solution for real-time communication. Notie that on-chain transactions involve a fee in ERG, similarly to Ethereum.
Interoperability and Compatibility: The Swarm API is built on WebRTC, a standard protocol supported by all modern web browsers. This ensures broad compatibility and interoperability across platforms and devices. Ethereum, however, with transactions considered as means of communication – requires a specific environment to run its smart contracts and DApps.
Decentralized Signaling: The Swarm API uses decentralized signaling facilitated by nodes in the network, removing the need for a central signaling server. This enhances privacy and eliminates a potential point of failure. Ethereum doesn’t have a concept similar to signaling in its communication constructs.
Flexibility: The Swarm API offers greater flexibility in network topologies and capabilities, supporting different forms of communication like data, audio, and video. Ethereum is primarily focused on data transactions and doesn’t natively support audio or video communication.

The Swarm API, as part of GRIDNET OS, takes the potential of decentralized technologies to a new level by offering real-time, peer-to-peer communication with advanced features for privacy, resource management, and scalability. While Ethereum has its strengths in areas like smart contracts and DApps, the Swarm API excels in areas where Ethereum falls short, particularly in real-time communication and resource optimization.

`CNetMsg` Container Documentation

The `CNetMsg` is a primary container used across the entire GRIDNET OS ecosystem for encapsulating data during network communication. The container supports advanced mechanisms such as routing, onion routing, end-to-end encryption, session-based encryption, and authentication.

Class Definition

Constructor

constructor(entityType = eNetEntType.unknown, reqType = eNetReqType.unknown, data = new ArrayBuffer(), secData = new ArrayBuffer())

Gets the allowed capabilities of the Swarm instance.
The constructor initializes a new `CNetMsg` object. By default, it sets the `entityType` to `unknown`, `reqType` to `unknown`, `data` to an empty `ArrayBuffer`, and `secData` to an empty `ArrayBuffer`.

Properties

```
mEntityType
```
Represents the type of the entity. It is set in the constructor.
```
mRequestType
```
Represents the type of the request. It is set in the constructor.
```
mData
```
Represents the primary data of the message. It is set in the constructor.
```
mSig
```
Represents the security data of the message. It is set in the constructor.

Member Methods

The class contains various getters and setters, most of which correspond to the properties of the class. Here are some key methods:

```
get getIsEncrypted()
```
Returns whether the message is encrypted.
```
set setIsEncrypted(isIt)
```
Sets whether the message should be encrypted.
```
get getIsFromMobile()
```
Returns whether the message is sent from a mobile device.
```
set setIsFromMobile(isIt)
```
Sets whether the message is sent from a mobile device.
```
get getIsBoxedEncryption()
```
Returns whether the message uses boxed encryption.
```
set setIsBoxedEncryption(isIt)
```
Sets whether the message should use boxed encryption.
```
get getIsSession()
```
Returns whether the message is a session.
```
set setIsSession(isIt)
```
Sets whether the message should be a session.
```
get getIsAuthenticated()
```
Returns whether the message is authenticated.
```
set setIsAuthenticated(isIt)
```
Sets whether the message should be authenticated.

Routing Additions

The `CNetMsg` class also includes methods for handling routing:

```
get getDestination()
```
Returns the destination of the message.
```
set setDestination(id)
```
Sets the destination of the message.
```
get getSource()
```
Returns the source of the message.
```
set setSource(id)
```
Sets the source of the message.
```
get getHops()
```
Returns the number of hops the message has traversed.
```
incHops()
```
Increments the number of hops the message has traversed.

Encryption and Decryption

The `CNetMsg` class supports encryption and decryption:

```
encrypt(key, doECIES = true)
```
Encrypts the message body using either ECIES or a stream cipher, depending on the `doECIES` parameter.
```
decrypt(decryptionKey, pubKey)
```
Decrypts the message body using the provided decryption key and public key.

Serialization and Deserialization

The `CNetMsg` class supports serialization and deserialization:

```
getPackedData()
```
Serializes the `CNetMsg` object into an `ArrayBuffer`.
```
static instantiate(packedData)
```
Takes an `ArrayBuffer` as input and returns an instance of `CNetMsg`.

CNetMsg Detailed Documentation

```
constructor(entityType = eNetEntType.unknown, reqType = eNetReqType.unknown, data = new ArrayBuffer(), secData = new ArrayBuffer())
```
Creates a new instance of `CNetMsg` class.
Parameters:
– `entityType`: An enumeration value of type `eNetEntType` which represents the type of entity this message is related to. By default, it’s set to `unknown`.
– `reqType`: An enumeration value of type `eNetReqType` which represents the type of request this message is related to. By default, it’s set to `unknown`.
– `data`: The main data content of the message, represented as an `ArrayBuffer`. By default, it’s an empty `ArrayBuffer`.
– `secData`: The security related data of the message, also represented as an `ArrayBuffer`. By default, it’s an empty `ArrayBuffer`.
Returns: N/A.
Use Case: Used to create a new `CNetMsg` instance with optional initial values for `entityType`, `reqType`, `data`, and `secData`.
```
set setIsFromMobile(isIt)`
```
Sets whether the message originates from a mobile device.
Parameters:
– `isIt`: A Boolean value indicating whether the message originates from a mobile device.
Returns: N/A.
Use Case: This function is used when a message needs to be marked as originating from a mobile device. This information could be useful in various scenarios, such as formatting data for mobile-friendly interfaces, or tracking usage metrics across devices.
```
get getIsFromMobile()`
```
Gets whether the message originates from a mobile device.
Parameters: N/A.
Returns: A Boolean value indicating whether the message originates from a mobile device.
Use Case: This function is used when it’s necessary to know whether a message originated from a mobile device. For example, this could be used to tailor responses that are optimized for mobile interfaces.
```
set setIsEncrypted(isIt)`
```
Sets whether the message should be encrypted.
Parameters:
– `isIt`: A Boolean value indicating whether the message should be encrypted.
Returns: N/A.
Use Case: Used when a message needs to be marked for encryption. This is typically used in scenarios where sensitive data needs to be protected during transmission.
```
get getIsEncrypted()`
```
Gets whether the message is encrypted.
Parameters: N/A.
Returns: A Boolean value indicating whether the message is encrypted.
Use Case: This function is used when it’s necessary to know whether a message is encrypted. For instance, this could be used to ensure that sensitive data is only processed if the message is securely encrypted.
```
encrypt(key, doECIES = true)`
```
Encrypts the body of the `CNetMsg` instance.
Parameters:
– `key`: The key to be used for encryption.
– `doECIES`: A Boolean value indicating whether to use ECIES (Elliptic Curve Integrated Encryption Scheme) for encryption. By default, it’s set to `true`.
Returns: N/A.
Use Case: Used when the data within the`CNetMsg` instance needs to be encrypted. This is particularly useful when sending sensitive data over the network. The ability to switch between ECIES and a symmetric cipher provides flexibility depending on the security and performance needs of the application.
```
decrypt(decryptionKey, pubKey)`
```
Decrypts the body of the `CNetMsg` instance.
Parameters:
– `decryptionKey`: The key to be used for decryption. This can be either a private asymmetric key or a symmetric key, based on the Flags.
– `pubKey`: The public key to be used for verifying the signature, if present.
Returns: A Boolean value indicating whether the decryption was successful. If anything goes wrong, the function returns `false`.
Use Case: Used when the data within the `CNetMsg` instance needs to be decrypted. This is necessary when a message that was encrypted (perhaps due to sensitive data) needs to be read.
```
signCrypt(privKey, pubKey)`
```
Encrypts and signs the `CNetMsg` instance using the provided private and public keys.
Parameters:
– `privKey`: The private key to be used for signing and encryption.
– `pubKey`: The public key to be used for encryption.
Returns: N/A.
Use Case: This method is used when you want to both encrypt the message content and sign it using a specific key pair. The signature can help ensure the authenticity and integrity of the message, while encryption ensures its confidentiality.

Serialization and Deserialization
```
getPackedData()`
```
Serializes the `CNetMsg` instance into an `ArrayBuffer`.
Parameters: N/A.
Returns: An `ArrayBuffer` that represents the serialized state of the `CNetMsg` instance.
Use Case: This method is used when a `CNetMsg` instance needs to be serialized for transmission over the network. The serialized form is a binary representation of the message that can be efficiently transmitted and then deserialized back into a `CNetMsg` instance on the receiving end.
```
static instantiate(packedData)`
```
Deserializes an `ArrayBuffer` into a `CNetMsg` instance.
Parameters:- `packedData`: An `ArrayBuffer` that represents the serialized state of a `CNetMsg` instance.
Returns: A `CNetMsg` instance that has been populated with the data from the provided `ArrayBuffer`.
Use Case: This method is used when an `ArrayBuffer` that represents a serialized `CNetMsg` instance has been received and needs to be deserialized back into a `CNetMsg` instance. This allows the data in the message to be accessed and processed.

CSwarmMsg Class

The `CSwarmMsg` class represents a specific message in a swarm. It contains data related to the message such as the sender and receiver, the type of the message, and the data of the message.

Constructor

constructor(type = eSwarmMsgType.text, from = new ArrayBuffer(), to = new ArrayBuffer(), data = new ArrayBuffer(), timestamp = 0, external = false)

The constructor initializes a `CSwarmMsg` instance with the specified parameters.
Parameters:
– `type`: The type of the message. It can be any value from the `eSwarmMsgType` enumeration.- `from`: The sender of the message. It’s an ArrayBuffer representing the sender’s ID.- `to`: The receiver of the message. It’s an ArrayBuffer representing the receiver’s ID.- `data`: The actual data of the message. It’s an ArrayBuffer that contains the data.- `timestamp`: The timestamp of the message. It’s a numerical value representing the time the message was created.- `external`: A Boolean value indicating whether the message is external. This value is not serialized and is used for optimization purposes.

```
 protocolID(id)
```
This method sets the protocol ID of the message.
Parameters:
– `id`: The protocol ID to be set.
Return value: N/A
Use Case: The protocol ID can be used to differentiate between different application-specific protocols. This can be useful in a system where multiple protocols are being used, and each message needs to be processed differently depending on the protocol it belongs to.
```
 layer0Datagram()
```
This method returns the `CNetMsg` datagram which encapsulates `CSwarmMsg`.
Parameters: N/A
Return value: An instance of `CNetMsg`.
Use Case: This method is useful when you need to retrieve the underlying `CNetMsg` datagram that encapsulates the `CSwarmMsg`. This can be useful for debugging or for processing the message at a lower level.
```
 protocolID()
```
This method returns the protocol ID of the message.
Parameters: N/A
Return value: The protocol ID of the message.
Use Case: This method is useful when you need to check the protocol ID of a message. This can be useful for processing the message correctly based on its protocol.
```
 dataTxt()
```
This method returns the data of the message as a string.
Parameters: N/A
Return value: The data of the message as a string.
Use Case: This method is useful when you need to retrieve the data of the message in a human-readable format. This can be useful for debugging or displaying the data to a user.
```
set data(val)
```
This method sets the data of the message.
Parameters:
– `val`: The data to be set. It’s converted to an ArrayBuffer if it’s not already one.
Return value: N/A
Use Case: This method is useful when you need to change the data of a message. This can be useful when the message data needs to be updated due to changes in the state of the system.
```
get dataBytes()
```
This method returns the data of the message as an ArrayBuffer.
Parameters: N/A
Return value: The data of the message as an ArrayBuffer.
Use Case: This method is useful when you need to retrieve the data of the message in its raw binary format. This can be useful for processing the data at a lower level or for transmitting the data over a network.
```
get type()
```
This method returns the type of the message.
Parameters: N/A
Return value: The type of the message. It’s a value from the `eSwarmMsgType` enumeration.
Use Case: This method is useful when you need to check the type of a message. This can be useful for processing the message correctly based on its type.
```
get sourceID()
```
This method returns the sender’s ID of the message.
Parameters: N/A
Return value: The sender’s ID of the message as an ArrayBuffer.
Use Case: This method is useful when you need to check who sent a message. This can be useful for processing the message correctly based on the sender.
```
get destinationID()
```
This method returns the receiver’s ID of the message.
Parameters: N/A
Return value: The receiver’s ID of the message as an ArrayBuffer.
Use Case: This method is useful when you need to check who is the intended recipient of a message. This can be useful for routing the message to the correct recipient.
```
get timestamp()
```
This method retrieves the timestamp of the message.
Parameters: N/A
Return value: The timestamp of the message.
Use Case: Timestamps can be useful for a variety of reasons such as ordering messages, determining message latency, or verifying the freshness of a message.
```
sign(privKey)
```
This method signs the message with a given private key.
Parameters:
– `privKey`: The private key used to sign the message.
Return value: Returns `true` on successful operation.
Use Case: This method is used when you want to sign a message to ensure its integrity and authenticity. By signing a message, you can prove that the message was not tampered with and that it was indeed sent by the claimed sender.
```
verifySignature(pubKey)
```
This method verifies the signature of the message with a given public key.
Parameters:
– `pubKey`: The public key used to verify the message’s signature.
Return value: Returns `true` if the signature is verified.
Use Case: This method is used when you want to verify the authenticity of a received message. By verifying the signature of a message, you can ensure that the message was indeed sent by the claimed sender and that it was not tampered with during transmission.
```
getPackedData(includeSig = true)
```
This method retrieves the packed data of the message.
Parameters:
– `includeSig`: A boolean indicating whether to include the message’s signature in the packed data. Defaults to `true`.
Return value: Returns an ArrayBuffer containing the packed data of the message.
Use Case: This method is used when you want to serialize the message for transmission or storage. By retrieving the packed data of the message, you can transmit or store the message in a compact, binary format.
```
static instantiate(packedData)
```
This method creates a new CSwarmMsg instance from packed data.
Parameters:
– `packedData`: An ArrayBuffer containing the packed data of the message.
Return value: Returns a new CSwarmMsg instance.
Use Case: This method is used when you want to deserialize a message from its packed data. By creating a new CSwarmMsg instance from packed data, you can reconstruct the message for processing or display.

Conclusions

This initial version of the Swarms API documentation represents a significant step in providing developers with the necessary resources to understand and interact with the GRIDNET ecosystem. Although it is not exhaustive, it presents the foundational concepts and data structures, such as CNetMsg and CSwarmMsg, which are pivotal in developing decentralized applications on the GRIDNET OS.

We’ve included details on data encapsulation, serialization, and deserialization, and have explained how these processes are efficiently handled by the Swarms API, freeing developers from the burden of low-level network programming. We’ve also highlighted the importance of the provided containers and how they can be used as a payload for transmitting data.

As we continue to expand and enhance the GRIDNET OS platform, you can expect this documentation to grow in tandem. Future versions will delve deeper into the specifics, explore advanced use cases, and provide additional guidance on how to leverage the full potential of the Swarms API.

In the meantime, we believe the materials provided here, along with the sample implementations of successful UI dApps like eMeeting and Whiteboard, offer a solid foundation for developers to bootstrap their projects. These examples demonstrate practical use of the concepts covered in this documentation and serve as a valuable reference.

We encourage developers to engage with the vibrant GRIDNET OS community, where you can share experiences, ask questions, and learn from others. Please remember that our support team is available on the GRIDNET Talk forums (https://talk.gridnet.org) in sections related to GRIDNET OS’ decentralized applications’ development. We are always eager to hear about your experiences and challenges, and we look forward to seeing the innovative applications you will create on the GRIDNET OS platform.

Thank you for your interest in GRIDNET OS. Happy coding!