# About Chronologue Relay P2P Protocols

This article explains the basics of peer-to-peer (P2P) sharing protocols and will help you decide whether to opt into them on your Chronologue Relay console. It will enable you to get the most out of P2P functionality by clarifying which type works best for particular needs.

By opting into P2P sharing, you can expand your access to astronomical events from across time to experience immersive virtual reality (VR), optimize your data stream for speed, and work around OCTAVIA's [Chronologue API](https://chronologue.dev/octavia/api/api-reference_chronologue) rate limit constraints. P2P does this by allowing you to access data from remote nodes in a network. By gathering and sharing Chronologue telescope observations in a decentralized system, you overcome the limitations of single-source delivery.

A P2P network is like a library cooperative. In a neighborhood library swap, neighbors share books directly with each other instead of everyone traveling to the same library across town. With a P2P network, Chronologue Relay users gather and share astronomical data rather than depending on OCTAVIA's Chronologue API as an exclusive source.

Two P2P protocol types support most Chronologue Relay network sharing:

- **Streaming protocols** allow **real-time viewing** of low-payload media files, such as standard- or high-definition preview videos for Chronologue events or 2D interactive statistical visualizations.
- **Torrenting protocols** support the **download** of high-payload files to your local Relay console's internal database for rendering in VR. The data stream has no rate limit to obstruct its flow, and the distribution of server resources across network peers supports efficient data transmission, enhancing download speed.

```{figure} img/concept_chronologue-relay-p2p-001.png
**P2P data sharing in the context of Chronologue Relay data flows.** P2P protocols enable you to gather Chronologue data from peers, without having to depend solely on OCTAVIA's Chronologue API. You store gathered data locally in your Chronologue Relay console to prepare it for 3D rendering in the Zaius Chronologue VR app and headset.
```

## Background

P2P sharing in the Chronologue Relay arises from the need to efficiently gather large volumes of Chronologue data on your local console to enable VR experiences.

```{dropdown} Chronologue-based VR events require terabytes of observational data.
:color: secondary
Why such a heavy volume? The Chronologue VR app structures virtual space in a grid. Each cubic cell must embody highly detailed cosmic conditions captured in spectroscopic, positional, image, and physical data. Spread this level of detail over a cosmic observation area of billions of kilometers in diameter, and a terabyte of underlying astronomical data from the Chronologue telescope becomes a minimum in most cases.
```

```{dropdown} Chronologue API rate limits impede access to VR-scale data.
:color: secondary
OCTAVIA manages its resources for serving Chronologue telescope data by rate limiting calls to the Chronologue API.

> **Learn more:**
> See [Chronologue API documentation](https://chronologue.dev/stub_page) for rate limit specifications.

The limits do not hamper casual users of the Chronologue API who require only small payloads of data. However, they do not support the large-payload data transmissions you need to create a VR experience with your Chronologue Relay.

To download the terabytes of data you need for VR, your solutions are:

| ❌ Option 1—SUBOPTIMAL | ⚠️ Option 2—Viable for some organizations | ✅ Option 3—OPTIMAL |
| ----------- | ----------- | ----------- |
| **Download the data with the Chronologue API in multiple sittings:** An extended time commitment (of perhaps days or even weeks for large Chronologue events like galactic collisions) means that most Chronologue Relay users find this option onerous if not prohibitive. | **Pay OCTAVIA to increase your Chronologue API data ceiling:** OCTAVIA's fee primarily envisions institutional or enterprise customers. | **Use an alternative source for Chronologue data:** Working around the Chronologue API enables you to reduce your exposure to OCTAVIA's rate limits. |
```

```{dropdown} P2P torrenting provides efficient access to VR-scale Chronologue data.
:color: secondary
Over time, Chronologue observation users from outside of OCTAVIA have gathered large volumes of data onto their local devices. In aggregate, this distributed data can power a wide range of VR experiences, but only if Chronologue data users share with each other. P2P protocols allow these data exchanges.

P2P torrenting is the ideal protocol for sharing **large data payloads**. You download different pieces of data from various sources at the same time, relieving any individual source from the burden of delivering the full load. In the Chronologue Relay, you sidestep the drag of the data flowing from only the Chronologue API.
```

```{dropdown} P2P streaming smooths the data-sharing experience.
:color: secondary
While torrenting is ideal for large data payloads, streaming enhances quick access to **small-payload** Chronologue data and facilitates effective data management.
```

## At a glance

The following table compares P2P streaming and torrenting usages in the Chronologue Relay:

|             | P2P streaming | P2P torrenting |
| ----------- | ----------- | ----------- |
| **2D videos (standard or high definition)** | ✅ Perfect for previewing Chronologue events. | ⚠️ Need to take the extra step of downloading before viewing. ✅ Good for keeping on your local console for future reference. |
| **Interactive 2D data visualizations** | ✅ Perfect for quick access. ❌ Does not permit design revisions. | ⚠️ Need to take the extra step of downloading before viewing. ✅ Great for enabling design revisions. |
| **Immersive stereoscopic 360° 3D VR** | ❌ Does not support VR. | ✅ Your go-to option for VR. |

## Use cases
Using P2P protocols in the Chronologue Relay, you can:

```{dropdown} Preview astronomical events from across time, to determine whether to download the complete data.
:color: secondary
*Example:* You **stream** a preview video of Halley's comet crossing Jupiter's orbit from a peer Relay in 2D standard definition. You like what you see, but not so much that you want to experience the event in VR. Therefore, you opt not to download the event's full data. You then preview another event, streaming a video of the birth of the sun. The event is impressive, so you decide you want to download the full data.

*The upshot:* These previews, enabled by P2P streaming, allowed you to (a) assess whether to download an event's full data and thereby (b) effectively manage the data resources on your local console.
```

```{dropdown} Download event data to your local console for an experience in immersive VR.
:color: secondary
*Example:* Having decided you want to experience the sun's birth in VR, you **torrent download** the raw data for the event into your console's internal database. You then use your Relay's processing software to transform it into an X3D file for the Chronologue VR app to render in stereoscopic 360° 3D in your VR headset.

*The upshot:* Enabled by P2P torrenting, you were able to efficiently access the data needed to experience the sun's birth in VR, irrespective of OCTAVIA's Chronologue API rate limit.
```

```{dropdown} View interactive data visualizations to present research or astrophysical concepts for an audience.
:color: secondary
*Example:* A remote Relay user has compiled a data set which contains the frequency at which black holes formed inside the Milky Way over its life span. They created an interactive graph to illustrate that data, and you **stream** that interactive graph as part of a larger presentation you are giving about black holes to an audience of astronomy enthusiasts.

Six months later, you are scheduled to give a new presentation on black holes. You decide you want to expand on earlier analysis by comparing black-hole-formation frequencies in (a) the Milky Way, (b) the Andromeda galaxy, and (c) the merged Milky Way-Andromeda galaxy that will form 4.5 billion years in the future after the two galaxies collide with one another. To do this, you **torrent download** the raw black-hole-formation frequency data for further manipulation, so you can then create a set of updated interactive graphs that incorporate the data newly organized for comparison purposes.

*The upshot:* Enabled by P2P streaming, you were able to expediently access an interactive data visualization for presentation purposes. With P2P torrenting, you were then able to reconfigure the underlying data into a visualization of expanded scope.
```

```{dropdown} Collaboratively harvest previously unseen astronomical data from OCTAVIA's Chronologue API to create a desired VR experience.
:color: secondary
*Example:* You want to witness in immersive VR the collision of a Seyfert galaxy and a radio galaxy, two exotic cosmic structures. Unfortunately, data for this event is not being shared over a P2P network. Nobody has the data stored on their own local device; it needs to be retrieved from OCTAVIA. The volume of data for this event is colossal, and the Chronologue API rate limit stands in the way of ready access. To solve this problem as efficiently as possible, you put out a call to P2P community peers who are interested in this event like you are. You team up to individually download increments of the event to your local devices using OCTAVIA's Chronologue API, harmonizing with its rate limit. You then subsequently share those data increments with one another by **torrent** to knit together a full VR experience of the event.

*The upshot:* Enabled by P2P torrenting, you were able to access novel astronomy data from OCTAVIA as expediently as possible for VR purposes.
```

```{dropdown} Contribute to the P2P community by serving as an additional data source for other people who want a copy of an event saved on your Chronologue Relay console.
:color: secondary
*Example:* Over time, you have acquired a robust collection of Chronologue events in your local console. You have experienced awe-inspiring astronomical events from the past, present, and future and, as a result, have gained a vastly expanded vision of the universe as compared with your pre-Chronologue Relay days. You want to support the community at large by showing the same spirit of sharing that others have shown with you. You ensure that you have made the data for your favorite Chronologue events saved on your console available for others to **stream and/or torrent**.
    
*The upshot:* Enabled by P2P streaming and torrenting, you shared data with the P2P community so they can experience rich observations of astronomical events from across time.
```