Skip to content

Commit f913ad3

Browse files
Jared-dzJared-dz
committed
Draft: Potential Geo Docs
Experimental docs about an ephemeral item.
1 parent 4b7c4e3 commit f913ad3

2 files changed

Lines changed: 234 additions & 0 deletions

File tree

‎docs/geolocation.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Geolocation
2+
3+
DoubleZero Geolocation is a service for verifying the physical location of devices using latency measurements. RTT (round-trip time) measurements between known-location infrastructure and a target device provide cryptographically-signed, onchain proof that a device is within a certain distance of a given point.
4+
5+
Use cases include regulatory compliance (e.g., GDPR — proving validators operate within the EU), geographic distribution audits, and any application that needs verifiable proof of where a device is running.
6+
7+
---
8+
9+
## How it works
10+
11+
12+
```mermaid
13+
flowchart LR
14+
subgraph DZ["DoubleZero Network"]
15+
DZD["DZD\n(known location)"]
16+
Probe["geoProbe\n(bare metal server)"]
17+
DZD -- "TWAMP\n(continuous latency)" --> Probe
18+
end
19+
20+
subgraph Target["Target Device"]
21+
T["Target\n(validator / server)"]
22+
end
23+
24+
Probe -- "RTT measurement" --> T
25+
T -- "signed response" --> Probe
26+
27+
Ledger[("DoubleZero\nLedger")]
28+
Probe -- "signed measurements\n(onchain)" --> Ledger
29+
```
30+
31+
And here's a second one showing the inbound vs outbound distinction, which might be more useful:
32+
33+
```mermaid
34+
flowchart TB
35+
DZD["DZD (known location)"]
36+
Probe["geoProbe"]
37+
DZD -- "TWAMP" --> Probe
38+
39+
subgraph out["Outbound Flow"]
40+
direction LR
41+
P1["geoProbe"] -- "probe packets" --> T1["Target"]
42+
T1 -- "reply" --> P1
43+
end
44+
45+
subgraph in["Inbound Flow (NAT-friendly)"]
46+
direction LR
47+
T2["Target"] -- "signed packets" --> P2["geoProbe"]
48+
P2 -- "reply" --> T2
49+
end
50+
```
51+
52+
Geolocation uses a three-tier measurement chain:
53+
54+
```
55+
DZD (known location) ──TWAMP──► geoProbe ──RTT──► Target device
56+
```
57+
58+
- **DZD ↔ geoProbe**: TWAMP continuously measures latency between the DoubleZero Device and the probe. DZDs have known, fixed geographic coordinates.
59+
- **geoProbe ↔ Target**: RTT is measured between the probe and the device being located.
60+
61+
All measurements are cryptographically signed and recorded onchain.
62+
63+
**Important:** Geolocation reports RTT only — not inferred distance or coordinates. The speed of light through fiber (~124 miles per millisecond) provides a physical upper bound on how far a device can be from a probe. RTT is not divided by two, since round-trip asymmetry cannot be assumed. How you interpret RTT (e.g., computing a maximum-distance radius) is up to you.
64+
65+
### Inbound vs outbound probe flows
66+
67+
There are two ways a probe can measure a target:
68+
69+
| Flow | Who initiates the connection | Use when |
70+
|------|------------------------------|----------|
71+
| **Outbound** | Probe → Target | Target has a public IP with an open inbound port |
72+
| **Inbound** | Target → Probe | Target is behind NAT or cannot accept inbound connections |
73+
74+
In both cases, the DZD ↔ probe measurement happens the same way. Only the direction of the probe ↔ target communication differs.
75+
76+
---
77+
78+
## Prerequisites
79+
80+
### 1. DoubleZero ID with credits
81+
82+
Geolocation users need a funded DoubleZero ID. You do not need to connect to the DoubleZero network (no access pass required), but your key needs credits on the DoubleZero ledger to create a user account and manage targets — each add/remove target operation costs credits.
83+
84+
If you don't have a DoubleZero ID:
85+
86+
```bash
87+
doublezero keygen
88+
doublezero address # get your pubkey
89+
```
90+
91+
Contact the DoubleZero team with your pubkey to get your ID funded. Fund it to a higher-than-typical amount if you expect to add and remove targets dynamically.
92+
93+
### 2. 2Z token account
94+
95+
You need a 2Z token account. Service fees are deducted from this account on a per-epoch basis.
96+
97+
---
98+
99+
## Installation
100+
101+
```bash
102+
sudo apt install doublezero-geolocation
103+
```
104+
105+
This installs two binaries:
106+
107+
- **`doublezero-geolocation`** — CLI for managing users, probes, and targets on the DoubleZero ledger
108+
- **`doublezero-geoprobe-target-sender`** — runs on the device being measured; used for inbound probe flows
109+
110+
---
111+
112+
## Check your balance
113+
114+
```bash
115+
doublezero balance --env testnet
116+
```
117+
118+
Geolocation costs approximately **0.0021 Credits per probe cycle**.
119+
120+
---
121+
122+
## Setup
123+
124+
### Step 1: Create a geolocation user
125+
126+
```bash
127+
doublezero-geolocation user create \
128+
--env testnet \
129+
--code <your-user-code> \
130+
--token-account <your-2Z-token-account>
131+
```
132+
133+
- `--code`: a short, unique identifier for your account (e.g. `myorg`)
134+
- `--token-account`: the public key of your 2Z token account — service fees are deducted from here
135+
136+
!!! note "Account activation"
137+
After creating a user, contact the DoubleZero Foundation to activate your account. Payment status must be marked active before probing begins.
138+
139+
### Step 2: List available probes
140+
141+
```bash
142+
doublezero-geolocation probe list --env testnet
143+
```
144+
145+
Note the **code**, **IP address**, and **public key** of the probe you want to use.
146+
147+
### Step 3: Add a target
148+
149+
=== "Inbound (target sends to probe)"
150+
151+
Use this flow if your target is behind NAT or cannot accept inbound connections.
152+
153+
```bash
154+
doublezero-geolocation user add-target \
155+
--env testnet \
156+
--user <your-user-code> \
157+
--type inbound \
158+
--probe <probe-code> \
159+
--target-pk <target-keypair-pubkey>
160+
```
161+
162+
- `--probe`: the code of the geoProbe that will measure the target (e.g. `ams-tn-gp1`)
163+
- `--target-pk`: public key of the keypair the target will use to sign messages — the probe only accepts messages from registered public keys
164+
165+
=== "Outbound (probe sends to target)"
166+
167+
Use this flow if your target has a public IP and an open inbound port.
168+
169+
```bash
170+
doublezero-geolocation user add-target \
171+
--env testnet \
172+
--user <your-user-code> \
173+
--type outbound \
174+
--probe <probe-code> \
175+
--ip-address <target-public-ip> \
176+
--location-offset-port <port>
177+
```
178+
179+
- `--ip-address`: the public IPv4 address of the target device
180+
- `--location-offset-port`: the port on the target that the probe will send measurements to
181+
182+
### Step 4: Run the target sender (inbound flow only)
183+
184+
For inbound probing, the target device must run software that sends signed messages to the probe. Reference implementations are available in Go and Rust — you can run them directly or use them as a starting point for your own integration.
185+
186+
On the device being measured:
187+
188+
```bash
189+
doublezero-geoprobe-target-sender \
190+
-probe-ip <probe-ip> \
191+
-probe-pk <probe-pubkey> \
192+
-keypair <path-to-keypair.json>
193+
```
194+
195+
- `-probe-ip`: IP address of the geoProbe (from `probe list`)
196+
- `-probe-pk`: public key of the geoProbe (from `probe list`)
197+
- `-keypair`: path to the keypair whose public key was registered as `--target-pk` in Step 3
198+
199+
---
200+
201+
## Command reference
202+
203+
### `doublezero-geolocation user`
204+
205+
| Subcommand | Description |
206+
|------------|-------------|
207+
| `create` | Create a new geolocation user account |
208+
| `get` | Get details of a specific user |
209+
| `list` | List all geolocation users |
210+
| `delete` | Delete a user |
211+
| `add-target` | Add a target to a user |
212+
| `remove-target` | Remove a target from a user |
213+
| `update-payment` | Update payment status (foundation use) |
214+
215+
### `doublezero-geolocation probe`
216+
217+
| Subcommand | Description |
218+
|------------|-------------|
219+
| `create` | Register a new geoProbe |
220+
| `get` | Get details of a specific probe |
221+
| `list` | List all probes |
222+
| `update` | Update probe configuration |
223+
| `delete` | Delete a probe |
224+
| `add-parent` | Link a DZD as a parent of the probe |
225+
| `remove-parent` | Remove a parent DZD |
226+
227+
### Global flags
228+
229+
| Flag | Description |
230+
|------|-------------|
231+
| `--env` | Network environment: `testnet`, `devnet`, or `mainnet-beta` |
232+
| `--rpc-url` | Custom Solana RPC endpoint |
233+
| `--keypair` | Path to signing keypair (required for write operations) |

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ nav:
6868
- Requirements & Architecture: contribute.md
6969
- Device Provisioning: contribute-provisioning.md
7070
- Operations: contribute-operations.md
71+
- Geolocation: geolocation.md
7172
- Architecture: architecture.md
7273
- Glossary: glossary.md
7374
markdown_extensions:

0 commit comments

Comments
 (0)