Blockchain

Service Module

Service registration and management through DNS domain verification and UCAN capability integration on Sonr blockchain

Service Module (x/svc)

Scope

This document covers the Service module's implementation of service registration, DNS domain verification, permission management, and UCAN integration. It details data structures, messages, queries, and security considerations. This document does not cover service deployment, client SDK usage, or governance proposals—see respective guides for those topics.

Audience

Service developers registering applications on Sonr. System integrators connecting services to the blockchain. Security engineers evaluating service authorization. Prerequisites: Understanding of DNS verification, UCAN capabilities, and Protocol Buffers.

Summary

The Service module manages decentralized service registration on Sonr. It verifies domain ownership through DNS TXT records, registers services with specific permissions, and integrates with UCAN for capability-based authorization. Services must prove domain control before registration. The module enforces permission scoping and provides service discovery mechanisms. All operations require cryptographic signatures from service owners.

Module Features

The Service module provides:

  • Domain Verification: DNS TXT record validation for ownership proof
  • Service Registration: On-chain registration with verified domains
  • Permission Management: UCAN capability requests and definitions
  • Service Discovery: Query services by owner, domain, or ID
  • Capability Integration: Native UCAN module integration

Core Concepts

Domain Verification

Services prove domain ownership through DNS verification:

  1. Generate verification token
  2. Add TXT record to DNS
  3. Validate record on-chain

Only verified domain owners can register services.

Service Registration

After verification, services register with:

  • Unique service ID
  • Verified domain
  • Requested permissions (UCAN capabilities)
  • Service metadata (name, description)

Permission Model

Services request permissions during registration. These UCAN capabilities define:

  • What actions services can perform
  • Resource access scope
  • Time-based constraints

Users must explicitly grant requested permissions.

Data Structures

Domain Verification

Tracks domain verification state:

message DomainVerification {
  string domain = 1;                     // Domain to verify
  string owner = 2;                      // Owner address
  string token = 3;                      // DNS TXT token
  VerificationStatus status = 4;         // Status: Pending/Verified/Failed
  int64 initiated_at = 5;                // Start timestamp
  int64 expires_at = 6;                  // Expiration timestamp
}

enum VerificationStatus {
  VERIFICATION_STATUS_PENDING = 0;
  VERIFICATION_STATUS_VERIFIED = 1;
  VERIFICATION_STATUS_FAILED = 2;
}

Service

Stores registered service data:

message Service {
  string service_id = 1;                 // Unique identifier
  string domain = 2;                     // Verified domain
  string owner = 3;                      // Owner address
  string name = 4;                       // Display name
  string description = 5;                // Service description
  repeated string permissions = 6;        // UCAN capabilities
  string ucan_delegation_chain = 7;      // Authorization chain
  int64 created_at = 8;                  // Creation time
  int64 updated_at = 9;                  // Last update
}

State Transitions

Domain Operations

MessageDescriptionAuthorization
MsgInitiateDomainVerificationGenerates verification tokenAny account
MsgVerifyDomainValidates DNS TXT recordDomain owner

Service Operations

MessageDescriptionAuthorization
MsgRegisterServiceRegisters service with domainVerified domain owner
MsgUpdateServiceUpdates service metadataService owner
MsgDeleteServiceRemoves service registrationService owner

Governance Operations

MessageDescriptionAuthorization
MsgUpdateParamsUpdates module parametersGovernance only

Domain Verification Process

Step 1: Initiate Verification

Generate verification token:

snrd tx svc initiate-domain-verification example.com --from alice

Returns:

{
  "domain": "example.com",
  "token": "sonr-verification=abc123xyz",
  "expires_at": "2024-01-15T00:00:00Z"
}

Step 2: Add DNS Record

Add TXT record to your DNS provider:

Type: TXT
Name: @ (or root domain)
Value: sonr-verification=abc123xyz
TTL: 300 (5 minutes)

Wait for DNS propagation (typically 5-30 minutes).

Step 3: Complete Verification

Verify domain ownership:

snrd tx svc verify-domain example.com --from alice

Verification tokens expire after 7 days. Complete the process before expiration.

Query Interface

Domain Queries

# Check verification status
snrd query svc domain-verification example.com

# List all verifications by owner
snrd query svc verifications-by-owner sonr1abc...

Service Queries

# Get service by ID
snrd query svc service my-app-123

# List services by owner
snrd query svc services-by-owner sonr1abc...

# List services by domain
snrd query svc services-by-domain example.com

# Search services by permission
snrd query svc services-by-permission "dwn:write"

Module Queries

# Get module parameters
snrd query svc params

# Get service statistics
snrd query svc stats

Security Model

Security Features

Domain Ownership

Only verified domain owners can register services

Permission Isolation

Services request but cannot grant permissions

UCAN Validation

Cryptographic validation of all capability chains

Service Boundaries

Isolated execution contexts per service

Best Practices

  1. Verify DNS propagation before domain verification
  2. Request minimal permissions for service operation
  3. Rotate service keys periodically
  4. Monitor permission usage through logs
  5. Implement rate limiting for API calls

Module Parameters

| Parameter | Description | Default | |-----------|-------------|---------|| | verification_timeout | Token expiration period | 7 days | | max_services_per_owner | Service limit per account | 100 | | allowed_permissions | Permitted UCAN capabilities | See governance | | service_registration_fee | Registration fee | 100 SNR | | dns_check_retries | DNS validation attempts | 3 | | min_ttl | Minimum DNS record TTL | 300 seconds |

Implementation Example

Register Service

Complete service registration flow:

// 1. Initiate domain verification
initMsg := &MsgInitiateDomainVerification{
    Owner:  "sonr1abc...",
    Domain: "app.example.com",
}

// 2. After DNS setup, verify domain
verifyMsg := &MsgVerifyDomain{
    Owner:  "sonr1abc...",
    Domain: "app.example.com",
}

// 3. Register service
registerMsg := &MsgRegisterService{
    Owner:       "sonr1abc...",
    Domain:      "app.example.com",
    ServiceId:   "my-app-v1",
    Name:        "My Application",
    Description: "Decentralized social platform",
    Permissions: []string{
        "dwn:read",
        "dwn:write",
        "ucan:delegate",
    },
}

Query Service

// Query service details
service, err := queryClient.Service(ctx, &QueryServiceRequest{
    ServiceId: "my-app-v1",
})

// Check permissions
for _, perm := range service.Service.Permissions {
    fmt.Printf("Permission: %s\n", perm)
}

Next Steps

Ready to Register?

Service Developers: Follow the Service Registration Guide to register your application.

Integrators: Review the UCAN Integration Guide for permission management.

Validators: Understand Service Verification requirements.