> For the complete documentation index, see [llms.txt](https://docs.nearby.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nearby.finance/architecture/system-architecture.md).

# System Architecture

### A Unified Stack for Real-World Coordination

Nearby Protocol is built as a layered system that connects physical presence, local communication and value transfer into a single coordinated infrastructure stack.

Each layer operates independently, but also contributes to a unified flow of trust, communication and settlement.

The system is designed around a simple principle:

**Physical reality → cryptographic verification → local coordination → global settlement**

***

### High-Level Architecture

At a system level, Nearby Protocol is composed of three primary layers:

#### 1. Proof of Location Layer

Responsible for verifying physical presence using zero-knowledge cryptography, device attestation and secure hardware execution environments.

#### 2. Nearby Mesh Layer

Responsible for enabling local communication between nearby devices through decentralized, peer-to-peer networking.

#### 3. OfflinePay Layer

Responsible for enabling value transfer in disconnected environments with delayed global settlement on-chain.

***

### End-to-End Data Flow

A typical interaction within the Nearby ecosystem follows this flow:

#### Step 1: Physical Presence Detection

A device collects multiple location signals through secure system APIs, including:

* GPS / GNSS signals
* Network-based positioning
* Device integrity checks
* Environmental consistency signals

These inputs remain on-device and are never directly exposed as raw data.

***

#### Step 2: Proof Generation (Proof of Location)

Inside a Trusted Execution Environment (TEE), the device:

* Validates signal consistency
* Applies protocol-defined location constraints
* Generates a zero-knowledge proof
* Attests to device integrity using hardware-backed mechanisms

The output is a compact cryptographic proof of location validity.

This proof can be verified without revealing underlying raw location data.

***

#### Step 3: Local Network Discovery (Nearby Mesh)

Once proximity is established, the device can:

* Discover nearby peers
* Join context-specific networks (e.g. events, venues, zones)
* Establish encrypted peer-to-peer communication channels

Network formation is dynamic and based on physical proximity rather than centralized membership lists.

***

#### Step 4: Local Communication and Coordination

Within the Nearby Mesh layer:

* Messages are propagated between devices using peer-to-peer relay
* Communication is scoped to local context (event, region or zone)
* Devices may act as relay nodes for message propagation
* Content remains encrypted where applicable

This enables coordination without relying on centralized infrastructure.

***

#### Step 5: Offline Value Transfer (OfflinePay)

If value exchange is required, devices can initiate OfflinePay transactions:

* Payment notes are transferred between devices
* Transactions are signed locally by the sender
* Recipient verifies validity through local validation rules
* No internet connection is required at transaction time

This enables immediate exchange of value in disconnected environments.

***

#### Step 6: Witness Observation (Optional Layer)

Nearby devices can optionally act as witnesses:

* Observing proof generation events
* Observing offline transactions
* Signing attestation records

These witness records are stored as auxiliary evidence for later reconciliation.

***

#### Step 7: Global Reconciliation (Base Settlement)

When connectivity is restored:

* All local transaction histories are submitted to the network
* Proofs and transactions are aggregated
* Conflicts (such as double-spends) are detected
* Witness attestations are used as supporting evidence
* Final state is computed deterministically

The final result is committed on-chain via the Base network.

***

### System State Model

Nearby Protocol operates across three states:

#### 1. Connected State

* Full internet connectivity available
* Real-time verification and settlement possible
* Mesh and OfflinePay act as optional enhancements

***

#### 2. Partially Connected State

* Intermittent or unstable connectivity
* Local mesh communication becomes primary channel
* OfflinePay enables fallback transaction execution
* Proofs are generated locally and queued for later verification

***

#### 3. Fully Offline State

* No internet connectivity available
* All operations occur locally
* Mesh networking enables communication
* OfflinePay enables value transfer
* Proofs and transactions are stored for later reconciliation

***

### Layer Interdependencies

Each layer strengthens the others:

#### Proof of Location → Mesh Access Control

Location proofs can define:

* Who can join a network
* What content is accessible
* Which participants are eligible for interaction

***

#### Mesh → OfflinePay Transport Layer

The mesh network enables:

* Delivery of transaction data without internet
* Peer-to-peer propagation of payment notes
* Local validation distribution

***

#### OfflinePay → Economic Incentives

Payment activity drives:

* Network participation
* Witness incentives
* Node operator rewards
* Ecosystem activity growth

***

### Trust Flow Model

Trust in Nearby Protocol is not centralized but distributed across multiple layers:

* **Cryptographic Trust** → zk proofs validate location claims
* **Hardware Trust** → device attestation ensures integrity
* **Network Trust** → mesh propagation ensures redundancy
* **Economic Trust** → incentives align participant behavior
* **Settlement Trust** → final correctness enforced on-chain

No single layer is required to be fully trusted in isolation.

Security emerges from their combination.

***

### Failure Handling

Nearby Protocol is designed to degrade gracefully rather than fail.

#### If Proof of Location fails:

* Mesh and OfflinePay continue operating without location-based constraints

#### If Mesh network is unavailable:

* Devices fall back to direct peer-to-peer or delayed communication

#### If internet is unavailable:

* OfflinePay continues local execution
* Proofs and transactions are queued for later settlement

#### If reconciliation is delayed:

* Local state remains valid until global settlement occurs

The system prioritizes continuity of operation over immediate global consistency.

***

### Design Summary

Nearby Protocol architecture can be summarized as:

**A physical-world coordination stack built on three principles:**

* Verify presence without exposing identity
* Communicate without centralized infrastructure
* Exchange value without continuous connectivity

These principles are implemented through:

* Zero-knowledge geolocation proofs
* Decentralized mesh networking
* Offline-first payment execution
* Eventual on-chain settlement

***

### Final System View

In simplified form:

```
Physical World
      ↓
Proof of Location (zk + TEE)
      ↓
Nearby Mesh (P2P communication)
      ↓
OfflinePay (local settlement)
      ↓
Base (global reconciliation)
```

This stack enables coordination in environments where traditional digital infrastructure is unavailable, unreliable or unnecessary.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nearby.finance/architecture/system-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.