VCN Protocol Spec v1.3

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":               "12-byte GCM nonce (Base64-URL)",
  "salt":                "16-byte KDF salt (Base64-URL)",
  "kdf":                 "PBKDF2-SHA512",
  "kdf_iterations":      310000,
  "created_at":          unix_ms
}

Key derivation

The passphrase is converted to a 256-bit AES key using PBKDF2-SHA512 with the following parameters:

• Algorithm: PBKDF2 with HMAC-SHA512 (RFC 8018)
• Iterations: 310,000 minimum (matching the VFDS bundle KDF for ecosystem consistency)
• Salt: 16 bytes, generated from a cryptographically secure random source. Stored in the export file.
• Output length: 32 bytes (256 bits)
• Nonce: 12 bytes, generated from a cryptographically secure random source. Stored in the export file.

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. Implementations SHOULD enforce a minimum passphrase length of 12 characters.

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.

Organization Founder Identity

Added in VCN Protocol v1.1.

When a user creates an organization within a VCN application, a separate Ed25519 keypair MUST be generated for org ownership. This keypair is independent from the node identity defined in §2. The org founder key is used exclusively to sign org-scoped broadcasts. It MUST NOT be used for community packets, messages, or any other purpose.

Why separate keys

If the org founder key were the same as the node identity, any observer could correlate org broadcasts with the founder's pseudonymous community activity. Separating the keys ensures that knowing who leads an organization does not deanonymize their personal mesh activity.

Org founder key lifecycle

• Generated on org creation, stored in platform-appropriate secure storage.
• The public key is shared via the org QR code and stored by members as founder_node.
• Org-scoped broadcasts include an org_signature field in the payload, computed by signing the broadcast title with the org founder private key.
• Members verify org_signature against the stored founder_node public key.
• The org founder key MUST be included in identity export backups (§2 Identity Export).

Org-scoped broadcast payload fields

Verification behavior

Receiving nodes MUST verify org_signature against the stored org founder public key before displaying the broadcast. If verification fails, the packet MUST be discarded silently. If the receiving node has no stored founder key for the given org_scope (not a member), the packet MUST be ignored.

Org QR code format

Organizations share membership via QR code. The QR data MUST be a JSON object:

{
  "type": "vcn_org",
  "slug": "honey-for-humanity",
  "name": "Honey for Humanity",
  "founder_node": "Base64-URL org founder public key"
}

Scanning this QR code MUST create a local org membership with the provided slug, name, and founder key. The founder_node field contains the org founder PUBLIC key (not the VCN node_id), enabling broadcast verification. QR data MUST NOT exceed 2 KB.

Org signature test vector

Org founder public key: InjrkeV51Aox9zEKu61feig4GKFo9vy_tiN-gxPwe_k

Vector 1: Sign honey-for-humanity:Meeting this Saturday

Signature: HkhLse1ZtInb45yOMnlvcUwcUYE4rgF8Y39NbM2H5GK_3BWZnmPvVgbdNyBQQboPtkz-6K1bAGSlv9QMONDCAA

Vector 2 (empty title): Sign honey-for-humanity

Signature: 3wW0eCsWEyvPUl01AbGyTN5P4vfCv81Ibi6_HmXJ6wnMwbDvOW7-41Rx6B0ifrkr51wSCjxvaP91EwEMSML4Bw

Any correct Ed25519 implementation given the public key above MUST successfully verify both signatures.

Security considerations for org identity

Key compromise: If the org founder private key is compromised, the attacker can send verified broadcasts to all members. There is no revocation mechanism. The org founder SHOULD create a new org with a new keypair and redistribute the QR code. The old org slug becomes untrusted.

Spoofing: Any node can include org_scope in a packet payload. Without a valid org_signature, receiving nodes discard it. The signature is the proof, not the field.

Channel Patterns

Added in VCN Protocol v1.1.

VCN uses the area_tag field as a routing channel. In addition to geographic area tags, VCN defines the following special channel patterns:

Special channels (prefixed with _) are not geographic. They route globally via Tier 3 and propagate via BLE when devices are in proximity. The _sync_ pattern enables VCN to function as a serverless cross-device synchronization layer for any application.

Channel format rules

• Geographic area tags: lowercase ASCII, digits, underscores. Max 32 characters. Convention: {country}_{region}.
• _dm: fixed string. Direct messages include to and from fields in the payload for recipient filtering.
• _org_{slug}: slug follows the same rules as org_scope (lowercase ASCII, digits, hyphens, max 64 chars).
• _sync_{identifier}: identifier is a node_id or application-defined group key. Max 64 characters.

Tier 3 server-side filtering

For the _dm channel, Tier 3 endpoints SHOULD support a to query parameter to filter messages server-side by recipient node_id. Without this, clients receive all global DMs and filter locally, which does not scale. The recommended endpoint: GET /vcn/packets?area_tag=_dm&to={node_id}.

Contact exchange QR format

Nodes exchange contact information via QR code. The QR data MUST be a JSON object:

{
  "type": "vcn_contact",
  "node_id": "Base64-URL Ed25519 public key",
  "name": "Display name or null",
  "enc_key": "Base64-URL X25519 public key or null",
  "ts": 1775200000000
}

The enc_key field (added in v1.2) carries the node's X25519 encryption public key for end-to-end encrypted messaging. Contacts exchanged without enc_key fall back to plaintext messaging. The TOFU (Trust On First Use) mechanism backfills the key when the first encrypted message arrives from a contact.

Scanning adds the contact locally. The scanner SHOULD also emit a contact_exchange packet (including enc_key) so the scannee receives the scanner's identity and encryption key on next sync (two-way exchange).

BLE transport and channels

BLE discovery MUST use a universal service identifier (vcn.mesh) rather than an area-scoped identifier. All VCN devices connect to all nearby VCN devices regardless of area tag. The Bloom filter handshake (§6) exchanges ALL stored packets across ALL channels. Channel filtering occurs at the application layer, not the transport layer.

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 }

Payload schemas — v1.1 additions

message (VCN — direct messaging)

Messages use the _dm channel (see §2.2). The to field enables server-side recipient filtering. Two payload variants exist:

Plaintext (legacy/fallback):

{ "to": string,      // recipient node_id
  "from": string,    // sender node_id
  "text": string }

Encrypted (v1.2):

{ "to": string,      // recipient node_id
  "from": string,    // sender node_id
  "enc": string,     // Base64-URL: nonce(12) + AES-256-GCM ciphertext + mac(16)
  "enc_key": string, // sender's X25519 public key (Base64-URL, no padding)
  "v": 1 }

Encrypted messages use X25519 ECDH key agreement (derived from Ed25519 node keys via HKDF-SHA256 with info string vcn-x25519-encryption-v1) + AES-256-GCM. The sender's enc_key is included so the recipient can decrypt without prior contact exchange. See §10 for the full encryption protocol.

Senders MUST encrypt when the recipient's encryption key is known. Senders MUST fall back to plaintext when the recipient's encryption key is unavailable (pre-v1.2 contacts).

contact_exchange (VCN — two-way contact add)

{ "target": string,  // node_id of the intended recipient
  "name": string|null,
  "enc_key": string|null }

Emitted after scanning a contact QR to enable two-way discovery. The enc_key field (v1.2) carries the sender's X25519 encryption public key. Processed internally by the VCN layer, not displayed to users.

Org-scoped broadcast payload (any community type)

Any community packet type (bulletin, surplus, need, skills) MAY include org broadcast fields per §2.1:

{ ...type_payload,
  "org_scope": string,        // org slug
  "org_name": string|null,    // display name
  "org_signature": string }

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 specification

Parameters: 10,000 capacity, 1% false positive rate. This yields a bit array of 95,851 bits (~12 KB) with 7 hash functions. The hash algorithm is double hashing using SHA-256: h(i, item) = (SHA256(item)[0..15] + i * SHA256(item)[16..31]) mod m for i = 0..6. The bit array is transmitted as Base64-URL-encoded bytes, little-endian bit order.

False positives cause a missed sync for that packet — it will arrive in the next session. No data loss, only slight delay. The filter is rebuilt from the live seen_packets set at the start of each session.

SYNC wire format

Sync messages are length-prefixed JSON frames over the established transport connection (BLE, WiFi Direct TCP, or dedicated node TCP). Each frame is:

[4 bytes: payload length as big-endian uint32][N bytes: UTF-8 JSON payload]

Message types:

• SYNC_HELLO — {"type": "sync_hello", "vcn_version": "1.0", "area_tag": "...", "bloom": "Base64-URL...", "node_id": "..."}. If vcn_version major versions do not match, the receiving node closes the connection immediately.
• SYNC_PACKETS — {"type": "sync_packets", "packets": [...]}. Array of full VCN packet objects. Sent after both sides have exchanged SYNC_HELLO.
• SYNC_DONE — {"type": "sync_done"}. Signals completion. Both sides close the connection after sending and receiving SYNC_DONE.

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 Ed25519-signed headers: X-VCN-Node: {node_id}, X-VCN-Ts: {unix_ms_timestamp}, X-VCN-Sig: {base64url(sign(UTF-8("{image_hash}:{unix_ms_timestamp}")))}. The receiver MUST reject requests where the timestamp differs from the receiver's current time by more than 300 seconds.
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: Community packets (bulletins, surplus, needs, skills) are signed but not encrypted — they are public by design. Direct messages are end-to-end encrypted using X25519 + AES-256-GCM when both parties have exchanged encryption keys. Applications handling other sensitive data should encrypt payloads at the application layer.

End-to-end encrypted messaging (v1.2)

VCN provides standard E2E encryption for direct messages between nodes:

• Key derivation: Each node derives an X25519 keypair from its Ed25519 master seed using HKDF-SHA256 with info string vcn-x25519-encryption-v1 and empty salt. This is deterministic — the same master seed always produces the same encryption key.
• Key agreement: X25519 ECDH between sender and recipient produces a shared secret.
• Encryption: AES-256-GCM using the shared secret directly as the key. Nonce is random (12 bytes). The encrypted payload is packed as nonce(12) + ciphertext + mac(16) and encoded as Base64-URL without padding.
• Key exchange: Encryption keys are exchanged via contact QR codes and contact_exchange packets (see §2.2).
• TOFU (Trust On First Use): When a node receives an encrypted message from a contact whose encryption key is not yet stored, the sender's enc_key from the message payload is automatically saved. This enables encryption without prior explicit contact exchange.
• Key rotation detection: If a received message's enc_key differs from the stored key for that contact, the receiver SHOULD flag the message to the user as a potential key change. Decryption proceeds using the sender-provided key.
• Encryption downgrade detection: If a node has previously received an encrypted message from a contact (i.e., the contact's encryption key is stored), and subsequently receives a plaintext message from the same source_node, the receiver SHOULD flag the message to the user as a potential downgrade. The message is still delivered but visually distinguished. This prevents silent stripping of encryption by a relay or attacker.
• Plaintext fallback: When the recipient's encryption key is unknown (pre-v1.2 contact, no TOFU yet), messages are sent in plaintext with the text field. Receivers MUST accept both formats.

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).
• Replay: The seen_packets set is pruned of entries older than 720 hours. Packets replayed after pruning could be accepted as new. Mitigation: receivers SHOULD reject packets whose timestamp is older than the packet type's maximum TTL. For packet types with TTLs exceeding 720 hours (e.g., surplus at 2160 hours), the seen_packets retention for those entries SHOULD be extended to match.
• Packet ordering: The mesh provides no ordering guarantees. Receivers MUST NOT assume packets arrive in timestamp order. Applications that need ordering MUST sort locally after receipt.

Trust & Safety

Added in VCN Protocol v1.3.

VCN has no central authority and no global moderation. Trust and safety are enforced locally by each device and collectively by each community. The following mechanisms form the trust layer.

Local block list

Receivers MAY maintain a list of blocked source_node identifiers. Packets from blocked nodes MUST be dropped on receive before any other processing. Blocked nodes' packets MUST NOT be forwarded — the blocking device does not relay them to any tier. Blocks are local to the device and are not broadcast to the mesh. Blocks SHOULD auto-expire after 90 days of inactivity to prevent stale lists.

Community flagging

When a user blocks a node, the application SHOULD emit a flag packet to the local area channel:

{ "target": string }  // source_node ID of the flagged node

Receivers tally flag packets per target from unique source nodes. A flag is only counted if the flagging node has contributed 3 or more non-flag packets to the local store (anti-Sybil gate). When the count reaches a community threshold (default: 5 unique flaggers), the target is permanently blocked with no expiry. This is local consensus; each device makes its own decision based on the flags it has received. There is no global ban. A flagged node retains access to other areas and to direct messaging.

Flag packets use the same area_tag as community posts and propagate via all tiers. They have a TTL of 720 hours (30 days).

Per-node rate limiting

Tier 3 relays MUST enforce per-source_node rate limits in addition to per-IP limits. Recommended limits:

• Community post types (bulletin, surplus, need, skills, etc.): 60 per hour per node
• Direct messages: 200 per hour per node
• Other types (flag, contact_exchange): 30 per hour per node

Tier 1 (BLE) implementations SHOULD limit inbound connections to 10 per minute to prevent handshake flooding.

Proof-of-participation

Tier 3 relays MAY require proof-of-participation for community post types. A node must have a valid VRS counter record (from any Veydrin application) before its community posts are accepted. Direct messages and contact exchange packets are exempt — they always route. This prevents drive-by spam from freshly generated node identities.

Packet size limit

Packet payloads MUST NOT exceed 8,192 bytes (8 KB) when serialized as JSON. Receivers MUST reject packets exceeding this limit. Tier 3 relays enforce a 16 KB total request body limit which encompasses the full envelope.

Bloom filter validation

During Tier 1 BLE sync handshake, receivers MUST reject bloom filters exceeding 16 KB (approximately 21,334 Base64-URL characters). This prevents memory exhaustion from malicious peers transmitting oversized filter data.

Organization signature pinning

Once a receiver has successfully verified an org_signature for a given org_scope against a founder public key, that key is pinned locally. Subsequent packets claiming the same org_scope but signed by a different key MUST be rejected. This prevents org impersonation even if the org slug is known. Pinning is local and does not require a central registry.

Conformance

This section defines what it means to be a conforming VCN implementation. Four conformance targets exist. An implementation MAY satisfy one or more targets.

VCN Emitter

An application that creates and signs VCN packets. MUST satisfy:

• E1
  Valid identity. Generate Ed25519 key pair per §2. Node ID is the Base64-URL public key, 44 characters, no padding.
• E2
  Valid envelope. Every emitted packet includes all required envelope fields per §3 with correct types.
• E3
  Canonical signature. Sign using the canonical serialization defined in §3 (sorted keys, compact JSON, UTF-8, signature field excluded).
• E4
  Unique packet ID. Every packet has a fresh UUID v4 packet_id. Never reused.
• E5
  Location privacy. Exact GPS coordinates MUST NOT appear in packets. Use geohash per §5.

VCN Receiver

An application that accepts and processes VCN packets. MUST satisfy:

• R1
  Verify before processing. Verify the Ed25519 signature against source_node before delivering any packet to application handlers. Discard silently on failure.
• R2
  Deduplicate. Maintain a seen_packets set. Discard packets with a previously seen packet_id.
• R3
  Filter by relevance. Deliver community packets matching the node's configured area_tag. Also deliver packets on subscribed special channels: _dm (filtered by recipient node_id), _org_{slug} (filtered by org membership), _sync_{id} (filtered by sync group). See §2.2 for channel patterns.
• R4
  Handle unknown types. Packets with an unrecognized packet_type MUST be forwarded (if the node forwards) but MUST NOT cause errors. Silently ignore for local delivery.

VCN Forwarder

A node that relays packets to other nodes. Every forwarder MUST also satisfy VCN Receiver rules. Additionally:

• W1
  Forward all valid packets. Forward every packet that passes signature verification and deduplication, regardless of whether the node can deliver it locally. Selective forwarding breaks the mesh.
• W2
  Decrement TTL. Reduce ttl by 1 on forward. Do not forward packets with ttl = 0.
• W3
  No modification. TTL is the only field a forwarder MAY change. The original signature MUST remain intact.

VCN Dedicated Node

A persistent, always-on regional anchor. MUST satisfy all Forwarder rules plus:

• D1
  DHT presence. Advertise in the Mainline DHT under the node's 4-character geohash key. Re-announce every 15 minutes.
• D2
  Accept incoming sync. Accept inbound sync connections and complete the Bloom filter handshake per §6.
• D3
  Regional storage. Store packets for the local geohash cell and all 8 adjacent cells. Enforce a configurable storage cap (default 500 MB).
• D4
  Auto-trim. When storage approaches the cap, trim oldest packets first, then by geohash distance from the node's primary cell.

VCN Org Broadcaster (v1.1)

An application that supports organization broadcasts. MUST satisfy:

• O1
  Separate org keypair. Generate a dedicated Ed25519 keypair for org ownership per §2.1. MUST NOT reuse the VCN node identity.
• O2
  Sign broadcasts. Every org-scoped broadcast MUST include org_scope, org_signature, and the signature MUST be computed per §2.1 (sign org_scope:title).
• O3
  Verify on receive. Receiving nodes MUST verify org_signature against the stored founder key. Discard on failure. Ignore if not a member.
• O4
  Include org key in identity export. The org founder keypair MUST be included in identity export backups per §2.
• O5
  Standalone org key export (v1.2). Applications SHOULD support exporting the org keypair independently of the full identity, enabling org signing authority to be shared with other administrators while each retains their own VCN node identity. Format: PBKDF2-SHA512 (310,000 iterations) + AES-256-GCM encrypted JSON with fields vcn_org_key_version, slug, public_key, private_key_enc, nonce, salt, kdf, kdf_iterations.

VCN Identity (v1.1)

All VCN applications SHOULD support identity portability:

• I1
  Export support. Support identity export in the format defined in §2 (PBKDF2-SHA512 + AES-256-GCM encrypted JSON).
• I2
  Import support. Support identity import from the same format. Warn before overwriting existing identity.
• I3
  Interoperable format. Exported files MUST be importable by any conforming VCN application.
• I4
  Include all keys. Export MUST include all identity-related keys: VCN node keypair and any org founder keypairs.

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.

Glossary

Normative References

Changelog