Skip to content

Some rephrasing in the overview. Mostly about relay servers #299

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 21, 2025
Merged

Some rephrasing in the overview. Mostly about relay servers #299

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10195fe
Some rephrasing in the overview. Mostly about relay servers
flub Feb 21, 2025
caf69a3
Apply suggestions from code review
flub Feb 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions src/app/docs/overview/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ export const metadata = {
# Overview

Iroh lets you establish direct peer-to-peer connections whenever possible, falling back to relay servers if necessary.
This gives you fast, reliable connections that are authenticated and encrypted end-to-end using QUIC. {{className: 'lead'}}
This gives you fast, reliable QUIC connections that are authenticated and encrypted end-to-end. {{className: 'lead'}}


## Iroh is "dial by public key"
Expand All @@ -17,15 +17,25 @@ In the iroh world, you dial another node by its `NodeId`, a 32-byte ed25519 publ
You won't have to think about NATs getting in your way, iroh traverses them for you.
Basing connections on asymmetric public keys is what allows iroh to *always* end-to-end encrypt and authenticate connections.

## How it works

It's built on peer-to-peer QUIC using both relays and holepunching.
## Peer to peer

Peer to peer connectivity is established with the help of a relay server. The relay server provides Session Traversal Utilities for NAT (STUN) for the peers. If no direct connection can be established, the connection is relayed via the server.
Iroh is built on peer-to-peer QUIC using both relays and holepunching.

Peers must know and do verify the PeerID of each other before they can connect. When using a relay server to aid the connection establishment they will register with a home relay server using their PublicKey. Other peers which can not establish a direct connection can then establish connection via this relay server. This will try to assist establishing a direct connection using STUN and holepunching but continue relaying if not possible.
Peers must know the NodeId of a peer before connecting to it.
They verify this NodeId during the connection handshake to provide end-to-end encryption and authentication.

Peers can also connect directly without using a relay server. For this, however the listening peer must be directly reachable by the connecting peer via one of it's addresses.
Peer to peer connectivity is established with the help of a relay server.
On startup peers register their NodeId with a home relay server.
The relay server provides assistance to traverse firewalls,
NATs or others alike.
If no direct connection can be established,
the connection is relayed via the server.

Peers can also connect directly without using a relay server.
For this,
however,
the listening peer must be directly reachable by the connecting peer via one of it's addresses.
Comment on lines +35 to +38
Copy link
Member

@matheus23 matheus23 Feb 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Erm. That's some pretty aggressive newlining :D
Personally I like to do one line per sentence.

Copy link
Contributor Author

@flub flub Feb 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

heh, yeah. I thought the convention is also for commas. But in this case it's a bit aggressive, sure. Probably not needed, but doesn't do any harm either.



## Iroh is built on QUIC
Expand Down
Loading