GDB's Advanced Synchronization and Security Architecture

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/estebanrfp/gdb/llms.txt

Use this file to discover all available pages before exploring further.

​

GDB’s Advanced Synchronization and Security Architecture

​

A Technical Deep Dive into the Hybrid Delta Protocol and the Zero-Trust Security Layer

​

1. The Hybrid Synchronization Engine: Optimizing for Speed and Reliability

​

A. High-Efficiency Delta Sync: The Primary Path

1. Operation Logging (Oplog): Every local mutation (put, remove, link) is recorded as an entry in a capped, sliding-window log persisted in localStorage. Each entry contains the operation’s essential metadata: its type, the affected node id, and a precise Hybrid Logical Clock (HLC) timestamp ensuring causal ordering.
2. Sync Handshake: When a peer connects or wants to catch up, it broadcasts a sync request. This message contains the HLC timestamp of the last operation it successfully processed (its globalTimestamp). A brand-new peer, having no history, will send a globalTimestamp of null.
3. Delta Calculation & Hydration: Upon receiving a sync request, a peer consults its Oplog. It calculates the “delta” by filtering its log for all operations with a timestamp greater than the globalTimestamp sent by the requesting peer.
   • Hydration: Since the Oplog only stores minimal metadata for efficiency, the peer then “hydrates” any upsert operations in the delta set. It fetches the full, current value of the corresponding node from its main graph and attaches it to the operation. This ensures the delta is a self-contained, complete set of changes.
4. Minimal & Compressed Transfer: This array of hydrated delta operations is serialized using MessagePack and compressed with pako (deflate). This minimal binary payload is then sent to the requesting peer inside a deltaSync message.
5. Efficient Application: The receiving peer decompresses the payload and applies the batch of operations, rapidly bringing its graph state up to date with minimal bandwidth and processing overhead.

​

B. Guaranteed Consistency Fallback: The Infallible Safety Net

1. A peer receives a sync request with a globalTimestamp that is older than the oldest operation in its Oplog, indicating the requesting peer is too far behind.
2. A peer receives a sync request from a new peer, where the globalTimestamp is null.

1. Full-State Transmission: Instead of a delta, the up-to-date peer serializes and compresses its entire current graph state. This is sent in a syncReceive message.
2. State Reconciliation & Reset: The desynchronized peer receives the full graph and performs a critical reconciliation process:
   • It completely discards its outdated local graph state, replacing it with the new one.
   • It clears its own Oplog, as its previous history is now invalid.
   • It scans the newly received graph to find the highest HLC timestamp among all nodes. It updates its own HybridClock and sets its globalTimestamp to this value. This crucial step ensures it is correctly “fast-forwarded” in time and can immediately participate in future delta syncs from a known-good state.

​

2. The Integrated Zero-Trust Security Layer: The Security Manager (SM) Module

​

A. Identity: Cryptographic & Sovereign

• Management (SoftwareWalletManager): The SWM factory handles the creation, recovery, and management of these identities. It supports high-security WebAuthn (hardware-bound keys) for seamless sessions and traditional Mnemonic Phrases for account recovery.
• Sovereignty: This model provides users with true ownership of their digital identity, free from any central authority.

​

B. Authorization: Distributed, In-Graph RBAC

• Role-Based Access Control (RBAC): The system uses a configurable set of roles (e.g., superadmin, admin, user) with explicit permissions (can: ['write', 'deleteAny']).
• In-Graph Roles: A user’s role is stored in a publicly readable user:[eth_address] node within the GDB graph. Security rules are distributed and agreed upon with the same eventual consistency as the data they protect.
• The SoftwareSecurityManager (SSM) - The Enforcement Engine: The SSM is the core enforcement point on every peer. It operates through a GDB middleware that intercepts all incoming data.
  1. Signing at Origin: Before any batch of operations is sent over the network, the syncChannel.send method is wrapped. This wrapper calls ssm.signOutgoingOperations, which cryptographically signs each operation with the user’s private key and embeds the signature and public address. This provides an unforgeable proof of origin.
  2. Verification at Destination (The Middleware): Upon receiving any message containing operations (including a decompressed deltaSync package), the SSM middleware on the receiving peer executes a rigorous, multi-step verification for every single operation in the batch:
     • Verify Signature: It confirms the cryptographic signature matches the operation’s content and the sender’s public address. If invalid, the operation is discarded.
     • Resolve Permissions: It looks up the sender’s role in its local copy of the GDB graph (user:[eth_address] node).
     • Authorize Action: It checks if the resolved role has permission for the requested action (e.g., does a 'user' have 'delete' permission?).
     • Sanitization: Any operation that fails verification is silently filtered out of the batch. Only the sanitized, fully-verified set of operations is passed to the core GDB engine for application.

​

C. Privacy: Transparent End-to-End Encryption

• Secure Wrappers: When a developer uses db.sm.put(), the data is not stored in plaintext. It is first encrypted using a key derived from the user’s unique private key.
• Secure Payload Format: The value stored in the GDB graph is a specific wrapper object, _gdbSecurePayloadV1. This object contains the _payload (the ciphertext) and public _meta data, including the owner’s Ethereum address.
• Conditional Decryption: When db.sm.get() is called, the module inspects the wrapper. If the currently logged-in user’s address matches the owner in the metadata, it derives the correct key and decrypts the ciphertext on the fly. For all other users, the method returns the unintelligible ciphertext along with a decrypted: false flag, allowing applications to handle the protected data appropriately.

​

Conclusion