Decentralized Web Node implementation for user-controlled data storage, protocol management, and secure vault operations on Sonr blockchain

DWN Module (x/dwn)

Scope

This document covers the DWN module's implementation of Decentralized Web Nodes, including records management, protocol configuration, vault operations, and permission systems. It details data structures, messages, queries, and security architecture. This document does not cover deployment, client SDK usage, or IPFS integration details—see respective guides for those topics.

Audience

Blockchain developers implementing data storage features. Application developers building DWN-enabled applications. Security engineers evaluating data sovereignty solutions. Prerequisites: Understanding of decentralized storage concepts, Protocol Buffers, and capability-based authorization.

Summary

The DWN module implements Decentralized Web Nodes for user-controlled data storage on Sonr. It manages records (data units), protocols (interaction schemas), permissions (capability tokens), and vaults (secure key management). The module enables data sovereignty through user-owned nodes that store encrypted data and enforce access control. All operations require cryptographic authorization from data owners.

Module Features

The DWN module provides:

Personal Data Stores: User-controlled storage for structured records
Protocol Management: Schema-based data interaction patterns
Permission System: Capability-based access control with signed tokens
Vault Operations: Enclave-based key management and signing

Core Concepts

Decentralized Web Nodes

A DWN is a personal data store that users control independently. Each DWN:

Stores encrypted user data
Manages access permissions
Executes protocol rules
Operates as the user's agent

Component Overview

Records

Basic data units storing arbitrary content with optional schemas

Protocols

Schemas defining data structures and interaction patterns

Permissions

Signed capability tokens for delegated access control

Vaults

Secure enclaves for key management and transaction signing

Data Structures

DWN Record

Stores user data with metadata:

message DWNRecord {
  string record_id = 1;                  // Unique identifier
  string target = 2;                     // Target DWN (DID)
  DWNMessageDescriptor descriptor = 3;   // Message metadata
  string authorization = 4;              // JWT/signature
  bytes data = 5;                        // Record content
  string protocol = 6;                   // Protocol URI (optional)
  string protocol_path = 7;              // Protocol path (optional)
  string schema = 8;                     // Schema URI (optional)
  string parent_id = 9;                  // Parent record (optional)
  bool published = 10;                   // Public visibility
}

DWN Protocol

Defines interaction patterns:

message DWNProtocol {
  string protocol_uri = 1;               // Protocol identifier
  string target = 2;                     // Target DWN (DID)
  DWNMessageDescriptor descriptor = 3;   // Message metadata
  string authorization = 4;              // JWT/signature
  bytes definition = 5;                  // Protocol rules (JSON)
  bool published = 6;                    // Public visibility
}

Vault State

Tracks vault status:

message VaultState {
  string vault_id = 1;                   // Vault identifier
  string owner = 2;                      // Owner address
  string public_key = 3;                 // Vault public key
  string enclave_report = 4;             // Attestation report
  uint64 created_at = 5;                 // Creation time
  uint64 last_heartbeat = 6;             // Last activity
}

State Transitions

Record Operations

Message	Description	Authorization
`MsgRecordsWrite`	Creates or updates record	Owner/delegate signature
`MsgRecordsDelete`	Deletes record	Owner/delegate signature

message MsgRecordsWrite {
  string author = 1;                     // Message author
  string target = 2;                     // Target DWN
  DWNMessageDescriptor descriptor = 3;   // Metadata
  bytes data = 4;                        // Record data
  string authorization = 5;              // Auth token
}

Protocol Operations

Message	Description	Authorization
`MsgProtocolsConfigure`	Configures protocol	Owner signature

message MsgProtocolsConfigure {
  string author = 1;                     // Message author
  string target = 2;                     // Target DWN
  string protocol_uri = 3;               // Protocol ID
  bytes definition = 4;                  // Protocol rules
  DWNMessageDescriptor descriptor = 5;   // Metadata
  string authorization = 6;              // Auth token
  bool published = 7;                    // Public flag
}

Vault Operations

Message	Description	Authorization
`MsgCreateVault`	Creates new vault	Owner signature
`MsgSignWithVault`	Signs with vault	Owner signature
`MsgBroadcastTx`	Broadcasts transaction	Owner signature

message MsgCreateVault {
  string owner = 1;                      // Vault owner
  string vault_id = 2;                   // Vault ID
  string key_id = 3;                     // Key identifier
}

Query Interface

Record Queries

# List records for a DWN
snrd query dwn records did:sonr:alice123

# Filter by protocol
snrd query dwn records did:sonr:alice123 --protocol social.example/v1

# Get specific record
snrd query dwn record <record-id>

Protocol Queries

# List protocols for a DWN
snrd query dwn protocols did:sonr:alice123

# Get protocol definition
snrd query dwn protocol social.example/v1

Vault Queries

# Get vault by ID
snrd query dwn vault <vault-id>

# List vaults by owner
snrd query dwn vaults-by-owner sonr1abc...

Permission Queries

# List permissions for a DWN
snrd query dwn permissions did:sonr:alice123

# Filter by grantee
snrd query dwn permissions did:sonr:alice123 --grantee did:sonr:bob456

Security Model

Authorization Requirements

Write operations: Require JWT or signature from owner/delegate
Read operations: Require valid capability token
Protocol configuration: Require owner signature
Vault operations: Require owner authentication

Security Features

Client-Side Encryption

Encrypt data before storing in DWN

Hardware Enclaves

Protect vault keys from exposure

Capability Tokens

Grant minimal required permissions

Audit Trail

Track all access and modifications

Best Practices

Encrypt sensitive data before storage
Use protocol schemas for data validation
Grant minimal permissions to applications
Rotate vault keys periodically
Monitor access logs for anomalies

Implementation Guide

Create Protocol

Define interaction schema:

{
  "protocol": "social.example/v1",
  "published": true,
  "types": {
    "profile": {
      "schema": "https://social.example/schemas/profile",
      "dataFormats": ["application/json"]
    },
    "post": {
      "schema": "https://social.example/schemas/post",
      "dataFormats": ["application/json"]
    }
  },
  "structure": {
    "profile": {
      "$actions": [
        { "who": "anyone", "can": "read" },
        { "who": "author", "can": "write" }
      ]
    },
    "post": {
      "$actions": [
        { "who": "anyone", "can": "read" },
        { "who": "author", "can": "write" }
      ]
    }
  }
}

Write Record

Store data in DWN:

// Create record message
msg := &MsgRecordsWrite{
    Author: "did:sonr:alice123",
    Target: "did:sonr:alice123",
    Descriptor: &DWNMessageDescriptor{
        Method: "RecordsWrite",
        Protocol: "social.example/v1",
        ProtocolPath: "profile",
        Schema: "https://social.example/schemas/profile",
        DataFormat: "application/json",
    },
    Data: profileData,
    Authorization: authToken,
}

Query Records

Retrieve stored data:

// Query records
query := &QueryRecordsRequest{
    Target: "did:sonr:alice123",
    Filter: &RecordsFilter{
        Protocol: "social.example/v1",
        ProtocolPath: "post",
        Author: "did:sonr:alice123",
    },
}