Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 3 additions & 3 deletions .obsidian/workspace.json
Original file line number Diff line number Diff line change
Expand Up @@ -189,11 +189,11 @@
"Explore/Pubky Core/Homeservers.md",
"Explore/Pubky Core/Pkarr/ELI5.md",
"Explore/Technologies/DoH.md",
"Explore/Pubky Core/Pkarr/4.Architecture.md",
"Explore/Pubky Core/Pkarr/3.Expectations.md",
"Explore/Pubky Core/Pkarr/Architecture.md",
"Explore/Pubky Core/Pkarr/Expectations.md",
"Pubky Core/Pkarr/1.Why PKARR?.md",
"Pubky Core/Pkarr/2.Getting Started with PKARR.md",
"Explore/Pubky Core/Pkarr/0.Introduction.md",
"Explore/Pubky Core/Pkarr/Introduction.md",
"Explore/Pubky Core/ELI5.md",
"Explore/Technologies/DHT.md",
"Explore/Pubky App/Backend/Introduction.md",
Expand Down
2 changes: 1 addition & 1 deletion Architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ The foundation of Pubky is cryptographic identity based on **[[KeyPair|key pairs
The discovery layer enables finding Homeservers and resolving identities without central servers.

**Components:**
- **[[0.Introduction|PKARR]]**: Public Key Addressable Resource Records
- **[[Explore/PubkyCore/Pkarr/Introduction|PKARR]]**: Public Key Addressable Resource Records
- **[[MainlineDHT|Mainline DHT]]**: Distributed Hash Table (10M+ nodes)
- **[[PKDNS]]**: DNS servers for resolving public-key domains

Expand Down
2 changes: 1 addition & 1 deletion Explore/PubkyApp/Client/Features/Tags.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ aliases:
- "../../../Pubky-App/Client/Features/Tags"
---

Tags are free-text labels that any user can publicly assign to **users** or **[[Posts|posts]]**. They are a core building block of the [[Semantic Social Graph|Semantic Social Graph]], turning everyday social interactions into structured, queryable metadata that powers discovery, filtering, and personalized feeds.
Tags are free-text labels that any user can publicly assign to **users** or **[[Posts|posts]]**. They are a core building block of the [[SemanticSocialGraph|Semantic Social Graph]], turning everyday social interactions into structured, queryable metadata that powers discovery, filtering, and personalized feeds.

Unlike traditional hashtags where only an author labels their own content, Pubky tags can be applied **by anyone** — you can tag your own profile and posts, and others can tag them too — making them a form of collaborative, crowd-sourced annotation.

Expand Down
2 changes: 1 addition & 1 deletion Explore/PubkyApp/Introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,5 +46,5 @@ It is the part of the Pubky App that you interact with directly. It's responsibl

The early versions of Pubky app take some shortcuts over the [[Explore/PubkyCore/Introduction|Pubky Core]] design. The MVP app is centralized, therefore we saved time and complexity by aggregating functionality into fewer components. The main two components are the `Homeserver` and the `Indexer`

- The [[Homeserver|Homeservers]] fulfils the function of `data stores`, republishing users keys to [[0.Introduction|PKARR]] and it acts also as an identity-provider (Oauth-like sign-in). Users maintain a trust relationship with the Homeserver.
- The [[Homeserver|Homeservers]] fulfils the function of `data stores`, republishing users keys to [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] and it acts also as an identity-provider (Oauth-like sign-in). Users maintain a trust relationship with the Homeserver.
- The `Indexer` fulfils the function of the [[Explore/PubkyApp/Backend/Introduction|backend]] for the Pubky App. [[PubkyNexus|Pubky Nexus]] is the production implementation of this indexer, providing real-time social graph aggregation, high-performance search, and a comprehensive REST API.
6 changes: 3 additions & 3 deletions Explore/PubkyCore/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ aliases:

# Pubky Core API Reference

The [[Introduction|Pubky Core]] protocol defines a RESTful HTTP API for storing and retrieving data on [[Homeserver|Homeservers]]. This document describes the complete API specification.
The [[Explore/PubkyCore/Introduction|Pubky Core]] protocol defines a RESTful HTTP API for storing and retrieving data on [[Homeserver|Homeservers]]. This document describes the complete API specification.

## Base URL

Expand All @@ -15,7 +15,7 @@ All API endpoints are relative to the Homeserver base URL:
https://homeserver.example.com
```

Homeserver URLs are discovered via [[0.Introduction|PKARR]] records published to the [[Explore/Technologies/MainlineDHT|Mainline DHT]].
Homeserver URLs are discovered via [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] records published to the [[Explore/Technologies/MainlineDHT|Mainline DHT]].

## Authentication

Expand Down Expand Up @@ -467,7 +467,7 @@ async function putWithRetry(session, path, data, retries = 3) {

## Resources

- **[[Introduction|Pubky Core Overview]]**: Main documentation
- **[[Explore/PubkyCore/Introduction|Pubky Core Overview]]**: Main documentation
- **[[SDK|SDK Documentation]]**: Client libraries
- **[[Homeserver|Homeserver Documentation]]**: Server setup
- **Official Docs**: [pubky.github.io/pubky-core](https://pubky.github.io/pubky-core/)
Expand Down
4 changes: 2 additions & 2 deletions Explore/PubkyCore/Homeserver.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ aliases:

The Pubky network allows multiple, independent data stores, known as "Homeservers." This improves [[Censorship|censorship-resistance]] and prevents any single entity from controlling the flow of information, or locking people & data in as a walled garden.

Homeservers are meant to represent a primary place to retrieve data from a specific [[0.Introduction|PKARR]] public key, but the user can redefine the location of their Homeserver at will by updating their [[0.Introduction|PKARR]] record in the [[MainlineDHT|Mainline DHT]].
Homeservers are meant to represent a primary place to retrieve data from a specific [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] public key, but the user can redefine the location of their Homeserver at will by updating their [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] record in the [[MainlineDHT|Mainline DHT]].

## Architecture

Expand Down Expand Up @@ -38,7 +38,7 @@ Native Pubky clients connect via PubkyTLS; browsers and legacy clients connect v
- Anyone can run their own Homeserver and set their own terms
- Homeserver operators can use [[Homegate]] for signup verification, implementing SMS or Lightning Network verification to prevent spam while preserving user privacy
- For true [[CredibleExit|credible exit]], users should maintain local backups via [[PubkyBackup|Pubky Backup]]. Homeserver mirroring is planned but not yet implemented
- Users can migrate to a new Homeserver at any time by moving their data and updating their [[0.Introduction|PKARR]] record
- Users can migrate to a new Homeserver at any time by moving their data and updating their [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] record

See [[SecurityModel|Security Model]] for the full trust analysis and failure recovery scenarios.

Expand Down
10 changes: 5 additions & 5 deletions Explore/PubkyCore/Introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ aliases:

## Overview

Pubky Core combines a [censorship-resistant public-key-based alternative to DNS](https://github.com/pubky/pkarr) ([[0.Introduction|PKARR]]) with conventional, tried-and-tested web technologies. This keeps users in control of their identities and data while enabling developers to build software with the availability of web apps, without the costs of managing a central database.
Pubky Core combines a [censorship-resistant public-key-based alternative to DNS](https://github.com/pubky/pkarr) ([[Explore/PubkyCore/Pkarr/Introduction|PKARR]]) with conventional, tried-and-tested web technologies. This keeps users in control of their identities and data while enabling developers to build software with the availability of web apps, without the costs of managing a central database.

**The Core Philosophy:**
> "The Web, long centralized, must decentralize; Long decentralized, must centralize."
Expand All @@ -31,15 +31,15 @@ The open protocol that defines:
- Public key-based authentication
- Capability-based authorization
- Key-value storage semantics
- Homeserver discovery via [[0.Introduction|PKARR]]
- Homeserver discovery via [[Explore/PubkyCore/Pkarr/Introduction|PKARR]]
- RESTful API standards

### 2. Homeserver Implementation
A production-ready server application that:
- Hosts user data in key-value stores
- Provides RESTful HTTP API
- Handles authentication and sessions
- Publishes to [[0.Introduction|PKARR]] for discovery
- Publishes to [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] for discovery
- Supports multiple persistence backends (Files, LMDB, SQL)
- Includes admin and metrics endpoints

Expand All @@ -53,9 +53,9 @@ Client libraries for developers:
## Core Concepts

### [[Homeserver|Homeserver]]
Decentralized data storage nodes that host user data. Each user can choose their Homeserver or run their own. Data is stored per public key, and users can migrate between Homeservers by updating their [[0.Introduction|PKARR]] record.
Decentralized data storage nodes that host user data. Each user can choose their Homeserver or run their own. Data is stored per public key, and users can migrate between Homeservers by updating their [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] record.

### [[0.Introduction|PKARR]]
### [[Explore/PubkyCore/Pkarr/Introduction|PKARR]]
Self-issued public keys that function as sovereign, publicly addressable domains. PKARR records published to the [[Explore/Technologies/MainlineDHT|Mainline DHT]] point to Homeserver locations, enabling decentralized discovery.

### [[Authentication]]
Expand Down
4 changes: 2 additions & 2 deletions Explore/PubkyCore/Pkarr/1.WhyPkarr.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: "Why PKARR?"
aliases:
- "../../Pubky-Core/Pkarr/1.Why-Pkarr"
- "../../Pubky-Core/Pkarr/Why-Pkarr"
---

This note explores the motivation behind [[0.Introduction|PKARR]], addressing the challenges of distributed semantics, databases, and discovery.
This note explores the motivation behind [[Explore/PubkyCore/Pkarr/Introduction|PKARR]], addressing the challenges of distributed semantics, databases, and discovery.

In pursuit of a sovereign, distributed, and open web, we identify three challenges:

Expand Down
10 changes: 5 additions & 5 deletions Explore/PubkyCore/Pkarr/2.GettingStartedWithPkarr.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: "Getting Started with PKARR"
aliases:
- "../../Pubky-Core/Pkarr/2.Getting-Started-with-Pkarr"
- "../../Pubky-Core/Pkarr/Getting-Started-with-Pkarr"
---

This guide will help you understand how to publish and resolve resource records using [[0.Introduction|PKARR]].
This guide will help you understand how to publish and resolve resource records using [[Explore/PubkyCore/Pkarr/Introduction|PKARR]].

## Publishing Resource Records

Expand All @@ -16,12 +16,12 @@ To resolve some key's resources, applications can query the [[DHT]] directly or

## DNS Queries Over HTTPS

Existing applications unaware of [[0.Introduction|PKARR]] can make normal [[DNS]] Queries over [[HTTPS]] ([[DoH]]) to [[0.Introduction|PKARR]] servers.
Existing applications unaware of [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] can make normal [[DNS]] Queries over [[HTTPS]] ([[DoH]]) to [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] servers.

## Caching and Scalability

Clients and [[0.Introduction|PKARR]] servers cache records extensively to minimize [[DHT]] traffic and improve scalability. The [[DHT]] drops records after a few hours, so it's important to republish records periodically.
Clients and [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] servers cache records extensively to minimize [[DHT]] traffic and improve scalability. The [[DHT]] drops records after a few hours, so it's important to republish records periodically.

## Next Steps

For more technical details on [[0.Introduction|PKARR]]'s architecture and how it works, refer to the [[4.Architecture|architecture]] note.
For more technical details on [[Explore/PubkyCore/Pkarr/Introduction|PKARR]]'s architecture and how it works, refer to the [[Explore/PubkyCore/Pkarr/4.Architecture|architecture]] note.
11 changes: 6 additions & 5 deletions Explore/PubkyCore/Pkarr/3.Expectations.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,18 @@
---
title: "Expectations"
aliases:
- "../../Pubky-Core/Pkarr/3.Expectations"
- "../../Pubky-Core/Pkarr/Expectations"
---

Understanding the expectations and limitations of [[0.Introduction|PKARR]] is crucial for effective use. This note outlines what [[0.Introduction|PKARR]] is not and what users should expect.
Understanding the expectations and limitations of [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] is crucial for effective use. This note outlines what [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] is not and what users should expect.

## Not a Storage Platform

[[0.Introduction|PKARR]] is not a storage platform. Records are ephemeral and need to be refreshed regularly to remain on the DHT.
[[Explore/PubkyCore/Pkarr/Introduction|PKARR]] is not a storage platform. Records are ephemeral and need to be refreshed regularly to remain on the DHT.

## Not a Real-time Communication Medium

[[0.Introduction|PKARR]] is not designed for real-time communication. It is optimized for infrequent updates and heavy caching to reduce traffic.
[[Explore/PubkyCore/Pkarr/Introduction|PKARR]] is not designed for real-time communication. It is optimized for infrequent updates and heavy caching to reduce traffic.

## Rate Limiting and Proof of Work

Expand All @@ -23,4 +24,4 @@ Records are heavily cached, and updates might take some time to propagate. In ca

## Next Steps

For a deeper understanding of why [[0.Introduction|PKARR]] was created and its motivation, refer to the [[1.WhyPkarr|why PKARR?]] note.
For a deeper understanding of why [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] was created and its motivation, refer to the [[Explore/PubkyCore/Pkarr/1.WhyPkarr|why PKARR?]] note.
17 changes: 9 additions & 8 deletions Explore/PubkyCore/Pkarr/4.Architecture.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
---
title: "Architecture"
aliases:
- "../../Pubky-Core/Pkarr/4.Architecture"
- "../../Pubky-Core/Pkarr/Architecture"
---

In-depth look at the architecture of [[0.Introduction|PKARR]], including its components, data formats, and how they interact.
In-depth look at the architecture of [[Explore/PubkyCore/Pkarr/Introduction|PKARR]], including its components, data formats, and how they interact.

## Components

- **Client**: Applications or users that publish or query [[0.Introduction|PKARR]] records. The main Rust crate provides `Keypair`/`PublicKey` types, `SignedPacket` builder, and `Client` for publishing/resolving.
- **Client**: Applications or users that publish or query [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] records. The main Rust crate provides `Keypair`/`PublicKey` types, `SignedPacket` builder, and `Client` for publishing/resolving.
- **Relay**: HTTP relay for environments without UDP access (browsers, firewalled networks). Also serves as intermediary for services on major cloud providers (AWS, GCP, Azure), whose IP ranges are often blocked by DHT nodes.
- **[[MainlineDHT|Mainline DHT]]**: The peer-to-peer network used to announce and resolve [[0.Introduction|PKARR]] records.
- **Republisher**: Keeps [[0.Introduction|PKARR]] records alive on the [[MainlineDHT|Mainline DHT]] by [periodically republishing](https://github.com/pubky/pkarr-churn/blob/main/results-node_decay.md) them (~hourly). The `pkarr-republisher` component handles this for Homeserver operators.
- **[[MainlineDHT|Mainline DHT]]**: The peer-to-peer network used to announce and resolve [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] records.
- **Republisher**: Keeps [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] records alive on the [[MainlineDHT|Mainline DHT]] by [periodically republishing](https://github.com/pubky/pkarr-churn/blob/main/results-node_decay.md) them (~hourly). The `pkarr-republisher` component handles this for Homeserver operators.

## SignedPacket Format

Expand All @@ -24,9 +25,9 @@ See the [PKARR repository](https://github.com/pubky/pkarr) for the full format s

## Interaction Flow

1. **Publishing**: Clients publish [[0.Introduction|PKARR]] to the [[MainlineDHT|Mainline DHT]], either directly or through a relay (required for browsers since the DHT uses UDP).
1. **Publishing**: Clients publish [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] to the [[MainlineDHT|Mainline DHT]], either directly or through a relay (required for browsers since the DHT uses UDP).
2. **Republishing**: Homeservers and relays republish records for their users to [keep them available](https://github.com/pubky/pkarr-churn/blob/main/results-node_decay.md) on the [[MainlineDHT|Mainline DHT]]. Records degrade over hours to days without republishing, so hourly republishing is recommended.
3. **Querying**: Clients query the [[MainlineDHT|Mainline DHT]] for [[0.Introduction|PKARR]] using the SHA1 hash of the public key, either directly or through a relay.
3. **Querying**: Clients query the [[MainlineDHT|Mainline DHT]] for [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] using the SHA1 hash of the public key, either directly or through a relay.

## Supported DNS Record Types

Expand All @@ -49,6 +50,6 @@ See [[SecurityModel#Scenario: DHT Unreachable|DHT outages]], [[MainlineDHT#Data

## Key Technologies

- **[[MainlineDHT|Mainline DHT]]**: A global, censorship-resistant p2p network of 10+ million peers. [[0.Introduction|PKARR]] records are announced here using BEP44.
- **[[MainlineDHT|Mainline DHT]]**: A global, censorship-resistant p2p network of 10+ million peers. [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] records are announced here using BEP44.

See [[SecurityModel|Security Model]] for the DHT threat model and the [pkarr repository](https://github.com/pubky/pkarr) for code examples and multi-platform support details.
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
aliases:
- "../../Pubky-Core/Pkarr/0.Introduction"
- "../../Pubky-Core/Pkarr/Introduction"
---

## Public-Key Addressable Resource Records
Expand All @@ -24,7 +24,7 @@ The core idea is to streamline the process of publishing and resolving resource
3. **Fallback for Existing Applications**: Applications unaware of PKARR can make normal [[DNS]] Queries over [[HTTPS]] (DoH) to PKARR servers, ensuring accessibility.
4. **Caching and Republishing**: Both clients and PKARR servers cache records extensively to improve scalability. The [[DHT]] drops records after a few hours, necessitating periodic republishing to keep records alive.

For more technical details on PKARR's architecture and how it works, refer to the [[4.Architecture|architecture]] note.
For more technical details on PKARR's architecture and how it works, refer to the [[Explore/PubkyCore/Pkarr/4.Architecture|architecture]] note.

## Getting Started

Expand Down
6 changes: 3 additions & 3 deletions Explore/PubkyCore/SDK.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ aliases:

# Pubky SDK: Client Libraries for Decentralized Applications

The Pubky SDK provides client libraries for building applications on [[Introduction|Pubky Core]]. Available in multiple languages with consistent APIs across platforms.
The Pubky SDK provides client libraries for building applications on [[Explore/PubkyCore/Introduction|Pubky Core]]. Available in multiple languages with consistent APIs across platforms.

## Supported Platforms

Expand Down Expand Up @@ -104,7 +104,7 @@ Every user is identified by an Ed25519 public key:

### Homeserver Discovery

The SDK uses [[0.Introduction|PKARR]] to discover where a user's data is hosted:
The SDK uses [[Explore/PubkyCore/Pkarr/Introduction|PKARR]] to discover where a user's data is hosted:
1. Query [[Explore/Technologies/MainlineDHT|Mainline DHT]] for public key
2. Retrieve PKARR record with Homeserver URL
3. Connect to Homeserver via HTTPS
Expand Down Expand Up @@ -767,7 +767,7 @@ try {
- **React Native Repository**: [github.com/pubky/react-native-pubky](https://github.com/pubky/react-native-pubky)
- **iOS/Android FFI**: [github.com/pubky/pubky-core-ffi](https://github.com/pubky/pubky-core-ffi) - Native bindings via UniFFI
- **Examples**: [github.com/pubky/pubky-core/tree/main/examples](https://github.com/pubky/pubky-core/tree/main/examples)
- **[[Introduction|Pubky Core Overview]]**: Main documentation
- **[[Explore/PubkyCore/Introduction|Pubky Core Overview]]**: Main documentation
- **[[API|API Reference]]**: HTTP API specification

---
Expand Down
Loading