VCN Protocol Spec v1.0

Overview & Design Philosophy

The VCN Protocol governs the technical layer of the Veydrin Community Network — how devices running VCN-enabled applications find each other, exchange signed data packets, and form a regional mesh without any server that the Veydrin Order operates. The one external infrastructure dependency is the Tier 3 bootstrap endpoint (Cloudflare Workers + KV), used only during early regional adoption before the peer mesh fills in. Its source is published and it can be self-hosted by any community.

The protocol has two concerns addressed in separate sections:

• Intra-device routing — how apps on the same Android device communicate via URI deep links and Android Intents.
• Inter-device transport — how signed packets propagate between devices across six complementary sync tiers.

This spec governs software behavior. The organizational governance layer — the nine rules, node federation, trust badge, and enforcement framework — is a separate document: see the VCN Community Spec.

Relationship to VODS

All VCN member applications must implement VODS v1.0 as the data interoperability baseline. VODS defines the document envelope, privacy floor, and export schema that VCN packets carry as payloads. The VCN Protocol defines how those packets move. They are siblings — neither depends on the other, but both are required for full compliance.

Node Identity

Key generation

On first launch of any VCN-enabled application, the vcn_node package generates an Ed25519 key pair locally on the device. No network connection is required or used. No server is involved at any point.

• The public key is the node's permanent, globally unique identifier.
• The private key never leaves the device under any circumstances.
• The key pair is stored in the app's Hive CE AES-256-GCM encrypted box.
• The key pair is included in identity export and survives device migration.

Node ID format

The node ID is the Base64-URL-encoded Ed25519 public key, 44 characters in length without padding. This is the key itself — no hash, no truncation, no information loss.

node_id  ::=  base64url( ed25519_public_key )
example  ::=  "X9kLm2vQpR7wN4yZ1cFbDhEaG8sT0uIo3jK6xV5nMeA"

Packet signing

Every packet emitted by a node is signed with that node's Ed25519 private key. The signature covers the canonical JSON serialization of the packet body (all fields except the signature field itself). Recipients verify the signature before processing any packet. Packets that fail signature verification are silently discarded — no error is surfaced to the user.

Identity export and migration

A user may export their node identity to migrate to a new device or back up their keys. The export format is a JSON file encrypted with a user-chosen passphrase using AES-256-GCM:

{
  "vcn_identity_version": "1.0",
  "node_id":              "Base64-URL public key",
  "private_key_enc":      "AES-256-GCM encrypted private key (Base64-URL)",
  "nonce":               "AES nonce (Base64-URL)",
  "created_at":          unix_ms
}

The passphrase is never stored or transmitted. Import requires the correct passphrase. The existing key pair is replaced on import — apps must warn users before overwriting an existing identity.

Registered source_app identifiers

The source_app envelope field identifies the originating application. The following identifiers are registered for v1.0. Third-party VCN implementations must use a distinct identifier not listed here:

source_app is set at compile time as a package constant in each consuming app's vcn_node configuration. It is not user-configurable.

Packet Format

Envelope schema

Every VCN packet, regardless of originating app or content type, uses the following envelope. The payload field is app-specific; its schema is determined by packet_type (see §4).

{
  "vcn_version":   "1.0",               // REQUIRED — protocol version
  "source_app":    "eluvorim",          // REQUIRED — registered app ID
  "source_node":   "X9kLm2vQ...",       // REQUIRED — Base64-URL Ed25519 public key
  "packet_id":     "uuid-v4",           // REQUIRED — globally unique, UUID v4
  "packet_type":   "goods",             // REQUIRED — registered type string
  "area_tag":      "ph_cebu",           // REQUIRED — routing region identifier
  "timestamp":     1741478400000,       // REQUIRED — Unix milliseconds UTC
  "ttl":           72,                  // REQUIRED — hours, decremented per hop
  "location":      { /* see §5 */ },      // OPTIONAL — geohash location schema
  "payload":       { /* type-specific */ }, // REQUIRED — app data
  "deep_link":     "veydrin://...",     // OPTIONAL — in-app navigation URI
  "signature":     "Base64-URL..."      // REQUIRED — Ed25519 signature
}

Canonical serialization for signing

The signature is computed over the canonical form of the packet. Canonical form is defined as:

• JSON serialized with keys sorted alphabetically at all nesting levels.
• No whitespace between tokens (compact form).
• UTF-8 encoding.
• The signature field excluded from the serialized input.

canonical_input  ::=  json_compact_sorted( packet \ { signature } )
signature        ::=  base64url( ed25519_sign( private_key, canonical_input ) )

Deduplication

Every node maintains a seen_packets set of packet_id values. Before processing or forwarding any received packet, the node checks this set. If the packet_id is present, the packet is silently discarded. If not, the packet_id is added and processing proceeds. The set is pruned of entries older than max_ttl (720 hours) to prevent unbounded growth.

TTL propagation

When a node forwards a packet, it decrements the ttl field by 1. The signature is not recomputed on forward — the original emitter's signature remains intact. The TTL decrement is the only permitted modification to a packet in transit. At ttl = 0 the packet is not forwarded further.

Default TTL values

All TTL values are user-configurable within the stated max. Apps should expose TTL as a simple duration selector, not a raw number.

Packet Type Map & Payload Schemas

Type map — registered types v1.0

Area tag format

Area tags are human-readable routing region identifiers. Format rules:

• Lowercase ASCII only. Letters, digits, and underscores. No spaces.
• Maximum 32 characters.
• Convention (not enforced): {country_code}_{region} — e.g., ph_cebu, us_richmond_va, hn_tegucigalpa.
• Area tags are community-defined — there is no central registry. Any string meeting the format rules is a valid area tag.
• Area tags are distinct from geohashes. A geohash encodes geographic coordinates. An area tag is a community's chosen name for their region. Both coexist: the area tag is used for filtering; the geohash (in the location field) is used for DHT routing and map rendering.

Area tag filtering

The type map lookup is the first delivery filter. The second is the area tag. Even if packet_type maps to an installed handler, the packet is only delivered if the receiving node's configured area_tag matches the packet's area_tag field. Matching is exact string equality in v1.0. No wildcards. No hierarchical prefix matching. See §6 for the forwarding and sync logic that governs how packets move between nodes before delivery.

Deep link — handler not installed

When a Veydrin app fires a deep link and the target app is not installed, the firing app must catch the failed intent and present a non-intrusive prompt offering the target app's Codeberg release page or F-Droid listing. It must not error, crash, or surface a system-level "no app" dialog.

Payload schemas — normative v1.0

All string fields are UTF-8. Fields marked optional may be omitted entirely — receiving apps must tolerate their absence gracefully.

goods / services / skills

{ "title": string, "value": number|null, "notes": string|null,
  "currency": string|null, "image_hash": string|null }

need

{ "title": string, "notes": string|null, "offer": string|null }

groupbuy

{ "title": string, "min_count": integer, "unit_value": number|null,
  "deadline": unix_ms|null, "notes": string|null }

surplus (shared across apps)

{ "species": string, "quantity": string, "unit": string|null,
  "contact": string, "expires": unix_ms, "intent": "trade"|"sell"|"give"|"barter"|"ask",
  "notes": string|null, "image_hash": string|null }

harvest (Chinara)

{ "crop": string, "quantity": number, "unit": string,
  "value": number|null, "harvest_date": unix_ms, "notes": string|null,
  "image_hash": string|null }

hive (Apiara)

{ "product": string, "quantity": number, "unit": string,
  "value": number|null, "notes": string|null, "ohds_ref": string|null }

observation (Numaka)

{ "guild_type": string, "layer": string, "succession_state": string|null,
  "notes": string|null, "image_hash": string|null, "opds_ref": string|null }

bulletin / update

{ "title": string, "body": string,
  "target_app": string|null, "version": string|null, "url": string|null }

Location Schema & Privacy Model

Location is a first-class field in the VCN packet format. Every app that attaches location to a packet uses this schema. Exact GPS coordinates never appear in any VCN packet under any circumstances — the geohash is the privacy floor.

What a geohash is

A geohash converts GPS coordinates into a short text code. Longer codes describe smaller, more precise areas. The code for any location is a prefix of the code for any smaller area it contains — enabling natural geographic hierarchy without central configuration.

Location packet schema

{
  "location": {
    "geohash":           "w3gv",     // routing key at chosen precision
    "geohash_precision": 4,          // number of chars used
    "coords_available":  false       // exact coords never in packet unless explicit opt-in
  }
}

Privacy rules — normative

• Exact GPS coordinates must never appear in a VCN packet payload unless the user has explicitly opted in for that specific packet type on that specific send.
• The geohash is computed on-device from GPS, then GPS is discarded before packet construction.
• Apps render the center point of the geohash cell on OSM maps — never an exact pin — unless exact coordinates are explicitly included.
• The default precision is 4 characters (~40 km). Users may tighten to 5 characters for neighborhood-level sharing. Loosening to 3 characters is available for sparse rural networks.

Edge cell handling

Geohash cells have hard edges. A device near a cell boundary should store and forward packets for all 8 neighboring cells automatically, in addition to its own cell. This prevents listings from being invisible to users just across a geohash boundary. No user configuration required — this is automatic behavior in vcn_node.

OSM rendering

All VCN-enabled apps that display location use OpenStreetMap tiles via flutter_map. Offline tile caching is required — users must be able to download their region's tiles for use without connectivity. The app-level community map is an emergent property of VCN packets with location fields: each app registers which packet types it renders as map pins. The shared OSM layer makes the mesh visible.

Sync Transport Tiers

All six tiers use the same packet format, signing, verification, deduplication, and type-map routing logic. They are complementary, not alternatives. A device uses all available tiers simultaneously. Tiers are listed in priority order for the target population.

TLS baseline

All VCN communication over any network transport (Tiers 2, 3, 5, and 6) must use TLS 1.3 minimum. Certificate validation is enforced. No fallback to plaintext under any circumstances. Tier 1 (physical proximity via Android Nearby Connections API) and Tier 4 (QR) do not use TLS — they are local channel transports that operate entirely off-network.

Forward vs deliver

// FORWARDING — happens first, regardless of local handler
forward_packet(p):
  if p.ttl <= 0: drop
  if p.packet_id in seen_packets: drop
  seen_packets.add(p.packet_id)
  deliver_packet(p)         // deliver BEFORE decrement — handler sees original TTL
  p.ttl -= 1
  if p.ttl > 0:
    queue_for_all_transports(p)

// DELIVERY — only for packets we can handle locally
deliver_packet(p):
  handler = type_map[p.packet_type]
  if handler == null: return       // no handler — not an error, packet still forwarded
  if p.area_tag != local_area_tag: return
  if handler_app_not_installed: return
  route_to(handler, p)

Sync negotiation — P2P Bloom filter handshake (Tiers 1, 2, 4)

When two nodes connect via a peer-to-peer tier (physical proximity, dedicated node, or QR), they negotiate what to exchange using a Bloom filter handshake. This avoids retransmitting packets the other node already has. This applies to Tiers 1, 2, and 4 only — Tier 3 (Cloudflare Workers) uses incremental HTTP polling via ?since=unix_ms and does not use this handshake.

// Both sides exchange their seen_packets Bloom filters
A → B: SYNC_HELLO { area_tag, bloom_filter(seen_packet_ids), node_id }
B → A: SYNC_HELLO { area_tag, bloom_filter(seen_packet_ids), node_id }

// Each side sends only packets the other node probably lacks
A → B: SYNC_PACKETS [ packets not in B's bloom filter ]
B → A: SYNC_PACKETS [ packets not in A's bloom filter ]

// Session closes
A ↔ B: SYNC_DONE

Bloom filter parameters: 10,000 capacity, 1% false positive rate. False positives cause a missed sync for that packet — it will arrive in the next session. No data loss, only slight delay. Filter is rebuilt from the live seen_packets set on each session open.

Dedicated Node Mode

Dedicated Node Mode is a first-class feature of the VCN protocol — not a hidden setting, not a developer tool. Any user with a spare Android device can strengthen their community's network by enabling it. The device becomes a persistent regional anchor that serves all VCN-enabled apps in the area.

What a dedicated node does

• Advertises in the regional DHT under the device's 4-character geohash key.
• Accepts direct sync connections from mobile devices in the area when they come online.
• Stores regional packets up to the configured storage cap.
• Gossips packets to other dedicated nodes and mobile devices that connect.
• Solves cold start for every new user in the region — they sync to the dedicated node on first WiFi connection and immediately have the community's packet history.

Activation requirements

• Device charging — required. Node Mode is automatically suspended when unplugged.
• WiFi connected — required. Node Mode does not operate on mobile data.
• User opt-in — always. Node Mode is never enabled without explicit user action.
• User-disableable at any time — instantly, from the main Node Mode status screen.

Node Mode UX

When Node Mode is active, the app collapses to a minimal status screen showing: packets stored, last sync timestamp, peers seen in the last 24 hours, and storage used. No advanced configuration required. UPnP handles port forwarding automatically on consumer routers — no manual setup.

Storage management

Auto-trim runs two passes when storage approaches the configured cap (default 500 MB):

• Pass 1 — TTL: Packets older than their TTL are flagged for removal.
• Pass 2 — Geohash distance: Packets from geohash cells furthest from the node's own cell are trimmed next.

The node's own locally-generated packets are never trimmed regardless of age or cap.

Resource usage

Image Transfer

Images are never included in sync packets propagated through any tier. This is a firm protocol-level constraint, not a recommendation. Packet size limits and low-bandwidth target environments make inline images incompatible with reliable sync.

When a listing or record includes an image, the emitting node stores the image locally and includes only the SHA-256 hex digest (image_hash field) in the packet payload. Image transfer is a separate, out-of-band, bilateral, on-demand operation using direct HTTP over whichever transport tier connects the two nodes:

1. Receiving node sends an image request to the source node: GET /image/{image_hash}. The request is authenticated by an Ed25519-signed request header: X-VCN-Node: {node_id}, X-VCN-Sig: {base64url(sign(image_hash + timestamp))}.
2. Source node verifies the request signature, retrieves the image from local storage, and transmits it as the response body with Content-Type: image/*.
3. Receiving node verifies that SHA-256(received bytes) == image_hash.
4. On match: image is stored and displayed. On mismatch: image is discarded silently.

Transport: Image requests route via the best available tier — Tier 2 (dedicated node relay) preferred for cross-WiFi requests, Tier 1 (direct device-to-device) for proximity requests. Tier 3 (Cloudflare) is not used for image transfer. If no transport path exists to the source node at the time of request, the request is deferred until a sync session with the source node (or a node that has cached the image) becomes available.

The source node may decline any image request with HTTP 403. Declining does not affect packet delivery or listing visibility. Images are optional — listings without images are fully valid.

vcn_node Package Interface

The vcn_node shared Flutter/Dart package is the single implementation of this protocol. All Veydrin apps import it. No app reimplements any part of the protocol directly.

Extraction boundary

All protocol logic lives in vcn_node: identity generation, packet format, signing, type map, transport, sync. All app-specific UX stays in the consuming app: community tab layout, listing rendering, partner card display, deep link handling UI. This boundary must be respected — coupling app UX to protocol logic makes extraction impossible.

Development sequence: vcn_node is built and proven in Eluvorim (first implementation) before extraction as a standalone published package. The extraction boundary defined here must be implemented before Eluvorim scaffolding begins.

VcnConfig (initialization — call before start)

VcnConfig.init({
  required String sourceApp,   // registered source_app identifier (compile-time constant)
  required String areaTag,     // community area tag — set once, persisted in Hive CE
})

sourceApp is a compile-time constant defined per app (e.g., "eluvorim"). areaTag is set during onboarding and stored in the app's local Hive CE box. It is also writable later via VcnSync.setAreaTag(). Both values are automatically attached to every emitted packet envelope — VcnEmitter.emit() does not require them as parameters.

VcnEmitter

VcnEmitter.emit({
  required String packetType,
  required Map<String, dynamic> payload,
  Map<String, dynamic>? location,  // geohash schema — see §5
  String? deepLink,
  int ttl = 72,
})

Builds the envelope, attaches source_node and source_app from local identity, signs, adds to the outbound queue for all active transports, returns the packet_id.

VcnReceiver

VcnReceiver.register(
  String packetType,
  Future<void> Function(VcnPacket packet) handler,
)

Registers a callback for a given packet_type. Multiple handlers may be registered for the same type. Called after area tag filtering and deduplication pass.

VcnSync

VcnSync.start()                    // Begin all available transport tiers
VcnSync.stop()                     // Graceful shutdown
VcnSync.setAreaTag(tag)            // Update active area tag filter
VcnSync.enableNodeMode(cap)        // Activate dedicated node (charging + WiFi required)
VcnSync.disableNodeMode()          // Deactivate dedicated node

// Returns current transport tier availability
VcnSyncStatus VcnSync.status() → {
  tier1_active: bool,   // BLE/WiFi Direct advertising
  tier2_active: bool,   // DHT connected to at least one dedicated node
  tier3_active: bool,   // Cloudflare endpoint reachable
  tier4_active: bool,   // always true — QR available when app is open
  tier5_active: bool,   // Tor circuit established
  tier6_active: bool,   // pluggable transport active
  node_mode:    bool,   // dedicated node mode running
  last_sync:    int,    // unix ms of last successful sync on any tier
}

Security Properties & Known Limitations

Properties

• Packet authenticity: All packets are signed by their originating node. Any modification in transit is detectable.
• No central authority: No server can issue, revoke, or block a node identity. The network cannot be administratively shut down.
• Location privacy: Exact coordinates never leave the device. Geohash is the privacy floor for all location data.
• Content privacy: Packets are signed, not encrypted in transit by default. Sensitive content should be encrypted at the application layer before placement in the payload field.

Known limitations

• TTL integrity: TTL is decremented in transit and cannot be verified against the original signature. Advisory only.
• Area tag spoofing: A malicious node can set any area tag. Area tags are routing hints, not access control. Applications must not make security decisions based on area tag alone.
• Sybil resistance: A device can generate multiple node IDs by reinstalling. Partial mitigation via transaction history and packet age — does not prevent Sybil attacks entirely.
• Tier 3 availability: The Cloudflare Workers endpoint is a single point of failure for the online bootstrap tier. Loss (Cloudflare outage, account suspension) degrades to Tiers 1, 2, and 4. Core offline functionality is entirely unaffected. Communities requiring full independence may self-host the Worker (source published in the VCN protocols repository).

Versioning

VCN Protocol Spec uses semantic versioning (MAJOR.MINOR). The vcn_version envelope field is the designated compatibility mechanism.

The VCN Protocol Spec and the VCN Community Spec version independently. Protocol changes do not require community governance changes and vice versa.