diff --git a/README.md b/README.md index 4b74490..7f5f61b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,9 @@ Welcome to the Internet of Peers ## Table of Contents -### Reference +### Pear runtime + +References for utilizing the Pear runtime. * [Command-Line-Interface (CLI)](./reference/cli.md) * [Application-Programming-Interface (API)](./reference/api.md) @@ -20,6 +22,8 @@ Welcome to the Internet of Peers ### Guides +Guides on using the pear runtime to build and share P2P applications. + * [Getting Started](./guide/getting-started.md) * [Starting a Pear Desktop Project](./guide/starting-a-pear-desktop-project.md) * [Making a Pear Desktop Application](./guide/making-a-pear-desktop-app.md) @@ -28,8 +32,21 @@ Welcome to the Internet of Peers * [Sharing a Pear Application](./guide/sharing-a-pear-app.md) * [Releasing a Pear Application](./guide/releasing-a-pear-app.md) +### Building blocks + +The essential building blocks for building powerful P2P applications using Pear. + +* [`hypercore`](./building-blocks/hypercore.md): A distributed, secure append-only log for creating fast and scalable applications without a backend, as it is entirely P2P. +* [`hyperbee`](./building-blocks/hyperbee.md): An append-only B-tree based on Hypercore. It provides a key/value-store API with methods to insert and get key/value pairs, perform atomic batch insertions, and create sorted iterators. +* [`hyperdrive`](./building-blocks/hyperdrive.md): A secure, real-time distributed file system that simplifies P2P file sharing that provides an efficient way to store and access data across multiple connected devices in a decentralized manner. +* [`autobase`](./building-blocks/autobase.md): A "virtual Hypercore" layer over many Hypercores owned by many different peers. +* [`hyperdht`](./building-blocks/hyperdht.md): The Distributed Hash Table (DHT) powering Hyperswarm. Through this DHT, each server is bound to a unique key pair, with the client connecting to the server using the server's public key. +* [`hyperswarm`](./building-blocks/hyperswarm.md): A high-level API for finding and connecting to peers who are interested in a "topic". + ### How-tos +Simple How-tos on using the essential builing blocks in Pear applications. + * [How to connect two peers by key with HyperDHT](./howto/connect-two-peers-by-key-with-hyperdht.md) * [How to connect to many peers by topic with Hyperswarm](./howto/connect-to-many-peers-by-topic-with-hyperswarm.md) * [How to replicate and persist with Hypercore](./howto/replicate-and-persist-with-hypercore.md) @@ -37,67 +54,7 @@ Welcome to the Internet of Peers * [How to share append-only databases with Hyperbee](./howto/share-append-only-databases-with-hyperbee.md) * [How to create a full peer-to-peer filesystem with Hyperdrive](./howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md) -## Building blocks - -| Module | Stability | -| ------------------------------------------------| :----------------------------------------------------------: | -| [`hypercore`](./building-blocks/hypercore.md) | **stable** | -| [`hyperbee`](./building-blocks/hyperbee.md) | **stable** | -| [`hyperdrive`](./building-blocks/hyperdrive.md) | **stable** | -| [`autobase`](./building-blocks/autobase.md) | **experimental** | -| [`hyperswarm`](./building-blocks/hyperswarm.md) | **stable** | -| [`hyperdht`](./building-blocks/hyperdht.md) | **stable** | - -### Hypercore - -The [`hypercore`](./building-blocks/hypercore.md) module is a distributed, secure append-only log for creating fast and scalable applications without a backend, as it is entirely peer-to-peer. - -Notable features include: - -* Improved fork detection in the replication protocol, to improve resilience. -* Optional on-disk encryption for blocks (in addition to the existing transport encryption). -* A write-ahead log in the storage layer to ensure that power loss or unexpected shutdown cannot lead to data corruption. -* The [`session`](./building-blocks/hypercore.md#core.session-options) and [`snapshot`](./building-blocks/hypercore.md#core.snapshot-options) methods for providing multiple views over the same underlying Hypercore, which simplifies resource management. -* A [`truncate`](./building-blocks/hypercore.md#await-core.truncate-newlength-forkid) method for intentionally creating a new fork, starting at a given length. We use this method extensively in [`autobase`](./building-blocks/autobase.md). - -### Hyperswarm - -The [`hyperswarm`](./building-blocks/hyperswarm.md) module is a high-level API for finding and connecting to peers who are interested in a "topic." - -Notable features include: - -* An improved UDP holepunching algorithm that uses arbitrary DHT nodes (optionally selected by the connecting peers) to proxy necessary metadata while being maximally privacy-preserving. -* A custom-built transport protocol, [UDX](https://github.com/hyperswarm/libudx), that takes advantage of the holepunching algorithm to avoid unnecessary overhead (it doesn't include handshaking since holepunching takes care of that, for example). It's blazing fast. -* A simplified DHT API that closely resembles NodeJS's `net` module, but using public keys instead of IP addresses. - -### Hyperdrive - -The [`hyperdrive`](./building-blocks/hyperdrive.md) module is a secure, real-time distributed file system that simplifies P2P file sharing that provides an efficient way to store and access data across multiple connected devices in a decentralized manner. - -* Uses Hyperbee internally for storing file metadata -* Major API simplification. Instead of mirroring POSIX APIs, the new API better captures the core requirements of P2P file transfer. -* Auxiliary tools, [`localdrive`](./helpers/localdrive.md) and [`mirrordrive`](./helpers/mirrordrive.md), that streamline import/export flows and make it easy to mirror drives to and from the local filesystem. - -### Autobase (experimental) - -The [`autobase`](./building-blocks/autobase.md) experimental module provides a "virtual Hypercore" layer over many Hypercores owned by many different peers. - -Notable features include: - -* automatic rebasing of multiple causally-linked Hypercores into a single, linearized Hypercore for multi-user collaboration -* low-friction integration into higher-level modules like Hyperbee and Hyperdrive: Autobase's output shares the familiar Hypercore API so peer-to-peer multi-user collaboration is achievable with little additional implementation effort. - -> Autobase is still experimental and is likely to change significantly in the near future. - -### Hyperdht - -The `hyperdht` module is the Distributed Hash Table (DHT) powering Hyperswarm. Through this DHT, each server is bound to a unique key pair, with the client connecting to the server using the server's public key. - -Notable features include: - -* lower-level module provides direct access to the DHT for connecting peers using key pairs - -## Helpers +### Helpers Helper modules can be used together with the building blocks to create cutting-edge P2P tools and applications. @@ -108,18 +65,21 @@ Helper modules can be used together with the building blocks to create cutting-e * [`compact-encoding`](./helpers/compact-encoding.md): A series of binary encoding schemes for building fast and small parsers and serializers. We use this in Keet to store chat messages and in Hypercore's replication protocol. * [`protomux`](./helpers/protomux.md): Multiplex multiple message oriented protocols over a stream. -## Tools +### Tools -The following tools are used extensively employed in the day-to-day development and operation of applications built on Pear +The following tools are used extensively employed in the day-to-day development and operation of applications built on Pear. -| Tools | Description | -| :----------------------------------------------------------: | :---------------------------------------------------------: | -| **[Hypershell](./tools/hypershell.md)** | A CLI to create and connect to P2P E2E encrypted shells.. | -| **[Hypertele](./tools/hypertele.md)** | A swiss-knife proxy powered by [HyperDHT](./building-blocks/hyperdht.md). | -| **[Hyperbeam](./tools/hyperbeam.md)** | A one-to-one and end-to-end encrypted internet pipe. | -| **[Hyperssh](./tools/hyperssh.md)** | A CLI to run SSH over the [HyperDHT](./building-blocks/hyperdht.md). | -| **[Drives](./tools/drives.md)** | CLI to download, seed, and mirror a [hyperdrive](./building-blocks/hyperdrive.md) or a [localdrive](./helpers/localdrive.md). | +* [Hypershell](./tools/hypershell.md): A CLI to create and connect to P2P E2E encrypted shells. +* [Hypertele](./tools/hypertele.md): A swiss-knife proxy powered by [HyperDHT](./building-blocks/hyperdht.md). +* [Hyperbeam](./tools/hyperbeam.md): A one-to-one and end-to-end encrypted internet pipe. +* [Hyperssh](./tools/hyperssh.md): A CLI to run SSH over the [HyperDHT](./building-blocks/hyperdht.md). +* [Drives](./tools/drives.md): CLI to download, seed, and mirror a [hyperdrive](./building-blocks/hyperdrive.md) or a [localdrive](./helpers/localdrive.md). +### Apps + +Applications built using Pear. + +- [Keet](./apps/keet.md): A peer-to-peer chat and video-conferencing application with end-to-end encryption. ## Stability indexing @@ -132,5 +92,4 @@ The following stability indices have been used: | **stable** | Unlikely to change or be removed in the foreseeable future. | | **experimental** | New, untested, or have known issues. | | **deprecated** | Being removed or replaced in the future. | -| **unstable** | May change or be removed without warning. | - +| **unstable** | May change or be removed without warning. | \ No newline at end of file diff --git a/SUMMARY.md b/SUMMARY.md index 9e2076a..7066e8c 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,7 +2,7 @@ * [Pear by Holepunch](./README.md) -### Reference +### Pear runtime * [Command-Line-Interface (CLI)](./reference/cli.md) * [Application-Programming-Interface (API)](./reference/api.md) @@ -19,6 +19,15 @@ * [Marking a Release](./guide/releasing-a-pear-app.md) * [Debugging a Pear Terminal Application](./guide/debugging-a-pear-terminal-app.md) +### Building blocks + +* [Hypercore](./building-blocks/hypercore.md) +* [Hyperbee](./building-blocks/hyperbee.md) +* [Hyperdrive](./building-blocks/hyperdrive.md) +* [Autobase](./building-blocks/autobase.md) +* [HyperDHT](./building-blocks/hyperdht.md) +* [Hyperswarm](./building-blocks/hyperswarm.md) + ### How-tos * [Connect two peers](./howto/connect-two-peers-by-key-with-hyperdht.md) @@ -28,17 +37,7 @@ * [Share append-only databases](./howto/share-append-only-databases-with-hyperbee.md) * [Create a p2p filesystem](./howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md) -## Building blocks - -* [Hypercore](./building-blocks/hypercore.md) -* [Hyperbee](./building-blocks/hyperbee.md) -* [Hyperdrive](./building-blocks/hyperdrive.md) -* [Autobase](./building-blocks/autobase.md) -* [HyperDHT](./building-blocks/hyperdht.md) -* [Hyperswarm](./building-blocks/hyperswarm.md) - - -## Helpers +### Helpers * [Corestore](./helpers/corestore.md) * [Localdrive](./helpers/localdrive.md) @@ -47,7 +46,7 @@ * [Compact encoding](./helpers/compact-encoding.md) * [Protomux](./helpers/protomux.md) -## Tools +### Tools * [Hypershell](tools/hypershell.md) * [Hypertele](tools/hypertele.md) @@ -55,4 +54,6 @@ * [Hyperssh](tools/hyperssh.md) * [Drives](tools/drives.md) +### Apps +* [Keet](apps/keet.md) \ No newline at end of file diff --git a/apps/keet.md b/apps/keet.md new file mode 100644 index 0000000..e5a7448 --- /dev/null +++ b/apps/keet.md @@ -0,0 +1,36 @@ +# Keet.io + +[Keet](https://keet.io) is a fully P2P communications tool that's built entirely on Holepunch. Give it a try! + +### Features + +|![Video Quality](../assets/keet/quality.png)| ![Secure](../assets/keet/secure.png)| ![File Handling](../assets/keet/filehandling.png)| +| --- | --- | --- | +|**Video quality that impresses! 🎥**|**Private and encrypted 🔒** | **Handle any file size 📂✅** | +|Keet video calls operate over direct connections between you and your friends, without using servers that can throttle your performance. You'll notice the difference.| Keet only shares end-to-end encrypted data between participants in your calls. Without middlemen, third-parties, or servers, there’s nobody left who can snoop or leak data. | When you share a file in Keet, you don’t have to wait for it to upload. Other peers can immediately download it straight from the source. Megabytes, gigabytes, or terabytes. No limits.| + + +> Built-in Bitcoin Lightning and USDt micro-payments make it easy to incorporate powerful paid features into apps. Peers control their data, including buying/selling, eliminating tokens, ads, incentives, and data harvesting. Future updates will introduce P2P payments to send tips, pay for services, bandwidth, storage, etc. + +### How it works + +What makes Keet so powerful? How does it allow users to securely exchange data over a distributed peer-to-peer network? + +Here is the step-by-step process of how it works: + +1. First, users generate and announce a cryptographic public key to a swarm of distributed computers, known as a Distributed Hash Table (DHT). No sign-ups are required when using Keet. +2. Using this public key, other Keet users can locate and, when authorized, connect to your computer. This process is called distributed hole punching, which makes it possible for computers on home networks to connect to each other without involving centralized servers. +3. During hole punching, Keet uses partial information from multiple peers in the network to ensure privacy. +4. Once connected, peers can safely and privately exchange chunks of data directly with each other without having to send the data to servers. +5. When you write a message in Keet, you don't have to directly send it to everyone. Any peer who receives it can relay it to others, and everyone can easily verify that the message came from you. +6. If you go offline, anyone can continue to serve your messages on your behalf. In fact, everything in Keet, including the app itself, is distributed this way, fully encrypted, private, and only shared with the people you want. + +### Join the Internet of Peers + +#### Desktop + +Keet is available for download on Windows, macOS, and Linux desktops. [Download](https://keet.io/) now and discover the power of communication without compromises! + +#### Mobile + +Experience P2P communications on your mobile devices. Download Keet Mobile on your [Android](https://play.google.com/store/apps/details?id=io.keet.app) and [iOS](https://apps.apple.com/us/app/keet-by-holepunch/id6443880549) mobile devices today! \ No newline at end of file diff --git a/assets/keet/filehandling.png b/assets/keet/filehandling.png new file mode 100644 index 0000000..5818780 Binary files /dev/null and b/assets/keet/filehandling.png differ diff --git a/assets/keet/quality.png b/assets/keet/quality.png new file mode 100644 index 0000000..ff306b5 Binary files /dev/null and b/assets/keet/quality.png differ diff --git a/assets/keet/secure.png b/assets/keet/secure.png new file mode 100644 index 0000000..fb2c475 Binary files /dev/null and b/assets/keet/secure.png differ diff --git a/building-blocks/autobase.md b/building-blocks/autobase.md index 61a0392..83c608e 100644 --- a/building-blocks/autobase.md +++ b/building-blocks/autobase.md @@ -6,6 +6,10 @@ Autobase is used to automatically rebase multiple causally-linked Hypercores int > Although Autobase is still under development, it finds application in many active projects. Keet rooms, for example, are powered by Autobase! This is a testament to the potential of Autobase, and we are excited to see what else it can achieve. +Notable features include: + +* automatic rebasing of multiple causally-linked Hypercores into a single, linearized Hypercore for multi-user collaboration +* low-friction integration into higher-level modules like Hyperbee and Hyperdrive: Autobase's output shares the familiar Hypercore API so peer-to-peer multi-user collaboration is achievable with little additional implementation effort. > [GitHub (Autobase)](https://github.com/holepunchto/autobase) diff --git a/building-blocks/hyperbee.md b/building-blocks/hyperbee.md index 08ef4aa..4fcc09f 100644 --- a/building-blocks/hyperbee.md +++ b/building-blocks/hyperbee.md @@ -6,7 +6,6 @@ Hyperbee is an append only B-tree based on [`Hypercore`](hypercore.md). It provi > As with the Hypercore, a Hyperbee can only have a **single writer on a single machine**; the creator of the Hyperdrive is the only person who can modify it as they're the only one with the private key. That said, the writer can replicate to **many readers**, in a manner similar to BitTorrent. - > [GitHub (Hyperbee)](https://github.com/holepunchto/hyperbee) * [Hyperbee](../building-blocks/hyperbee.md): diff --git a/building-blocks/hypercore.md b/building-blocks/hypercore.md index 37b01e6..a49d695 100644 --- a/building-blocks/hypercore.md +++ b/building-blocks/hypercore.md @@ -4,6 +4,14 @@ Hypercore is a secure, distributed append-only log built for sharing large datasets and streams of real-time data. It comes with a secure transport protocol, making it easy to build fast and scalable peer-to-peer applications. +Notable features include: + +* Improved fork detection in the replication protocol, to improve resilience. +* Optional on-disk encryption for blocks (in addition to the existing transport encryption). +* A write-ahead log in the storage layer to ensure that power loss or unexpected shutdown cannot lead to data corruption. +* The [`session`](#core.session-options) and [`snapshot`](#core.snapshot-options) methods for providing multiple views over the same underlying Hypercore, which simplifies resource management. +* A [`truncate`](#await-core.truncate-newlength-forkid) method for intentionally creating a new fork, starting at a given length. We use this method extensively in [`autobase`](../building-blocks/autobase.md). + > [GitHub (Hypercore)](https://github.com/holepunchto/hypercore) * [Hypercore](../building-blocks/hypercore.md) diff --git a/building-blocks/hyperdht.md b/building-blocks/hyperdht.md index 488db29..6e720bd 100644 --- a/building-blocks/hyperdht.md +++ b/building-blocks/hyperdht.md @@ -6,6 +6,10 @@ The DHT powering Hyperswarm and built on top of [dht-rpc](https://github.com/maf In the HyperDHT, peers are identified by a public key, not by an IP address. A public key can be connected regardless of where the peers are located, even if they move between different networks. +Notable features include: + +* lower-level module provides direct access to the DHT for connecting peers using key pairs + > [GitHub (Hyperdht)](https://github.com/holepunchto/hyperdht) * [HyperDHT](../building-blocks/hyperdht.md) diff --git a/building-blocks/hyperdrive.md b/building-blocks/hyperdrive.md index 0fd92db..5d3e8d7 100644 --- a/building-blocks/hyperdrive.md +++ b/building-blocks/hyperdrive.md @@ -4,6 +4,12 @@ Hyperdrive is a secure, real-time distributed file system designed for easy P2P file sharing. We use it extensively inside Holepunch; apps like Keet are distributed to users as Hyperdrives, as is the Holepunch platform itself. +Notable features include: + +* Uses Hyperbee internally for storing file metadata +* Major API simplification. Instead of mirroring POSIX APIs, the new API better captures the core requirements of P2P file transfer. +* Auxiliary tools, [`localdrive`](./helpers/localdrive.md) and [`mirrordrive`](./helpers/mirrordrive.md), that streamline import/export flows and make it easy to mirror drives to and from the local filesystem. + > [GitHub (Hyperdrive)](https://github.com/holepunchto/hyperdrive) * [Hyperdrive](../building-blocks/hyperdrive.md) diff --git a/building-blocks/hyperswarm.md b/building-blocks/hyperswarm.md index 21deb12..f394807 100644 --- a/building-blocks/hyperswarm.md +++ b/building-blocks/hyperswarm.md @@ -6,6 +6,12 @@ Hyperswarm helps to find and connect to peers announcing a common 'topic' that c Hyperswarm offers a simple interface to abstract away the complexities of underlying modules such as [HyperDHT](hyperdht.md) and [SecretStream](../helpers/secretstream.md). These modules can also be used independently for specialized tasks. +Notable features include: + +* An improved UDP holepunching algorithm that uses arbitrary DHT nodes (optionally selected by the connecting peers) to proxy necessary metadata while being maximally privacy-preserving. +* A custom-built transport protocol, [UDX](https://github.com/hyperswarm/libudx), that takes advantage of the holepunching algorithm to avoid unnecessary overhead (it doesn't include handshaking since holepunching takes care of that, for example). It's blazing fast. +* A simplified DHT API that closely resembles NodeJS's `net` module, but using public keys instead of IP addresses. + > [GitHub (Hyperswarm)](https://github.com/hyperswarm/hyperswarm) * [Hyperswarm](../building-blocks/hyperswarm.md)