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:
- Generate verification token
- Add TXT record to DNS
- 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
Message | Description | Authorization |
---|---|---|
MsgInitiateDomainVerification | Generates verification token | Any account |
MsgVerifyDomain | Validates DNS TXT record | Domain owner |
Service Operations
Message | Description | Authorization |
---|---|---|
MsgRegisterService | Registers service with domain | Verified domain owner |
MsgUpdateService | Updates service metadata | Service owner |
MsgDeleteService | Removes service registration | Service owner |
Governance Operations
Message | Description | Authorization |
---|---|---|
MsgUpdateParams | Updates module parameters | Governance 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
- Verify DNS propagation before domain verification
- Request minimal permissions for service operation
- Rotate service keys periodically
- Monitor permission usage through logs
- 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.