mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-02 17:31:39 +00:00
Prad Nukala
+299
-70
@@ -1,114 +1,343 @@
|
||||
# `x/svc`
|
||||
|
||||
The svc module is responsible for managing the registration and authorization of services within the Sonr ecosystem. It provides a secure and verifiable mechanism for registering and authorizing services using Decentralized Identifiers (DIDs) and now incorporates UCAN (User Controlled Authorization Networks) for enhanced authorization capabilities.
|
||||
The Service (SVC) module manages the registration and operation of decentralized services within the Sonr ecosystem. It provides a comprehensive framework for services to register with verified domains, define their permission requirements, and integrate with the broader Sonr authorization system through UCAN capabilities.
|
||||
|
||||
## Concepts
|
||||
## Overview
|
||||
|
||||
- **Service**: A decentralized svc on the Sonr Blockchain with properties such as ID, authority, origin, name, description, category, tags, and expiry height.
|
||||
- **Profile**: Represents a DID alias with properties like ID, subject, origin, and controller.
|
||||
- **Metadata**: Contains information about a svc, including name, description, category, icon, and tags.
|
||||
- **UCAN Authorization**: The module utilizes UCANs for a decentralized and user-centric authorization mechanism.
|
||||
The SVC module provides:
|
||||
|
||||
### Dependencies
|
||||
- **Domain Verification**: DNS-based domain ownership verification
|
||||
- **Service Registration**: Register services with verified domains
|
||||
- **Permission Management**: Define and request specific UCAN permissions
|
||||
- **Service Discovery**: Query services by owner, domain, or ID
|
||||
- **Capability Integration**: Seamless integration with the UCAN module
|
||||
|
||||
- [x/did](https://github.com/sonr-io/snrd/tree/master/x/did)
|
||||
- [x/group](https://github.com/sonr-io/snrd/tree/master/x/group)
|
||||
- [x/nft](https://github.com/sonr-io/snrd/tree/master/x/nft)
|
||||
## Core Concepts
|
||||
|
||||
### Domain Verification
|
||||
|
||||
Services must verify ownership of their domain through DNS TXT records before registration. This ensures that only legitimate domain owners can register services.
|
||||
|
||||
### Service Registration
|
||||
|
||||
Once domain ownership is verified, services can be registered with:
|
||||
|
||||
- Unique service ID
|
||||
- Verified domain binding
|
||||
- Requested permissions (UCAN capabilities)
|
||||
- Service metadata (name, description)
|
||||
|
||||
### Permission Model
|
||||
|
||||
Services request specific permissions during registration, which are granted as UCAN capabilities. These permissions define what actions the service can perform on behalf of users.
|
||||
|
||||
### Service Identity
|
||||
|
||||
Each service has a unique identity composed of:
|
||||
|
||||
- Service ID (chosen identifier)
|
||||
- Domain (verified TLD)
|
||||
- Owner (blockchain address)
|
||||
|
||||
## State
|
||||
|
||||
The module uses the following state structures:
|
||||
### Domain Verification
|
||||
|
||||
### Metadata
|
||||
```protobuf
|
||||
message DomainVerification {
|
||||
string domain = 1; // Domain being verified
|
||||
string owner = 2; // Address initiating verification
|
||||
string token = 3; // Verification token
|
||||
VerificationStatus status = 4; // Pending, Verified, Failed
|
||||
int64 initiated_at = 5; // Timestamp
|
||||
int64 expires_at = 6; // Token expiration
|
||||
}
|
||||
```
|
||||
|
||||
Stores information about services:
|
||||
### Service
|
||||
|
||||
- Primary key: `id` (auto-increment)
|
||||
- Unique index: `origin`
|
||||
- Fields: id, origin, name, description, category, icon (URI), tags
|
||||
|
||||
### Profile
|
||||
|
||||
Stores DID alias information:
|
||||
|
||||
- Primary key: `id`
|
||||
- Unique index: `subject,origin`
|
||||
- Fields: id, subject, origin, controller
|
||||
```protobuf
|
||||
message Service {
|
||||
string service_id = 1; // Unique service identifier
|
||||
string domain = 2; // Verified domain
|
||||
string owner = 3; // Service owner address
|
||||
string name = 4; // Human-readable name
|
||||
string description = 5; // Service description
|
||||
repeated string permissions = 6; // Requested permissions
|
||||
string ucan_delegation_chain = 7; // UCAN authorization
|
||||
int64 created_at = 8; // Creation timestamp
|
||||
int64 updated_at = 9; // Last update timestamp
|
||||
}
|
||||
```
|
||||
|
||||
## Messages
|
||||
|
||||
### MsgUpdateParams
|
||||
### Domain Verification
|
||||
|
||||
Updates the module parameters, including UCAN-related parameters. Can only be executed by the governance account.
|
||||
#### MsgInitiateDomainVerification
|
||||
|
||||
### MsgRegisterService
|
||||
Initiates domain verification by generating a DNS TXT record token.
|
||||
|
||||
Registers a new svc on the blockchain. Requires a valid TXT record in DNS for the origin and may be subject to UCAN authorization checks.
|
||||
```protobuf
|
||||
message MsgInitiateDomainVerification {
|
||||
string owner = 1;
|
||||
string domain = 2;
|
||||
}
|
||||
```
|
||||
|
||||
## Params
|
||||
#### MsgVerifyDomain
|
||||
|
||||
The module has the following parameters:
|
||||
Verifies domain ownership by checking DNS TXT records.
|
||||
|
||||
- `categories`: List of allowed svc categories
|
||||
- `types`: List of allowed svc types
|
||||
- `UcanPermissions`: Specifies the required UCAN permissions for various actions within the module, such as registering a service.
|
||||
```protobuf
|
||||
message MsgVerifyDomain {
|
||||
string owner = 1;
|
||||
string domain = 2;
|
||||
}
|
||||
```
|
||||
|
||||
## Query
|
||||
### Service Management
|
||||
|
||||
The module provides the following query:
|
||||
#### MsgRegisterService
|
||||
|
||||
### Params
|
||||
Registers a new service with a verified domain.
|
||||
|
||||
Retrieves all parameters of the module, including UCAN-related parameters.
|
||||
```protobuf
|
||||
message MsgRegisterService {
|
||||
string owner = 1;
|
||||
string service_id = 2;
|
||||
string domain = 3;
|
||||
string name = 4;
|
||||
string description = 5;
|
||||
repeated string requested_permissions = 6;
|
||||
string ucan_delegation_chain = 7; // Optional UCAN authorization
|
||||
}
|
||||
```
|
||||
|
||||
## Client
|
||||
### Governance
|
||||
|
||||
### gRPC
|
||||
#### MsgUpdateParams
|
||||
|
||||
The module provides a gRPC Query svc with the following RPC:
|
||||
Updates module parameters (governance only).
|
||||
|
||||
- `Params`: Get all parameters of the module, including UCAN-related parameters.
|
||||
```protobuf
|
||||
message MsgUpdateParams {
|
||||
string authority = 1;
|
||||
Params params = 2;
|
||||
}
|
||||
```
|
||||
|
||||
### CLI
|
||||
## Queries
|
||||
|
||||
(TODO: Add CLI commands for interacting with the module)
|
||||
### Domain Queries
|
||||
|
||||
- `DomainVerification`: Check domain verification status
|
||||
|
||||
### Service Queries
|
||||
|
||||
- `Service`: Get a specific service by ID
|
||||
- `ServicesByOwner`: List all services owned by an address
|
||||
- `ServicesByDomain`: List all services for a domain
|
||||
|
||||
### Module Queries
|
||||
|
||||
- `Params`: Get module parameters
|
||||
|
||||
## CLI Examples
|
||||
|
||||
### Domain Verification
|
||||
|
||||
```bash
|
||||
# Initiate domain verification
|
||||
snrd tx svc initiate-domain-verification example.com --from alice
|
||||
|
||||
# Check verification status
|
||||
snrd query svc domain-verification example.com
|
||||
|
||||
# The system will provide a token like: sonr-verification=abc123xyz
|
||||
# Add this as a TXT record to your domain's DNS
|
||||
|
||||
# Verify domain after DNS propagation
|
||||
snrd tx svc verify-domain example.com --from alice
|
||||
```
|
||||
|
||||
### Service Registration
|
||||
|
||||
```bash
|
||||
# Register a service with basic permissions
|
||||
snrd tx svc register-service my-app example.com \
|
||||
dwn:read,dwn:write,identity:read \
|
||||
--from alice
|
||||
|
||||
# Register with UCAN delegation
|
||||
snrd tx svc register-service vault-service vault.example.com \
|
||||
vault:access,identity:read \
|
||||
--ucan-delegation-chain="<jwt-token>" \
|
||||
--from alice
|
||||
|
||||
# Query service
|
||||
snrd query svc service my-app
|
||||
|
||||
# Query services by owner
|
||||
snrd query svc services-by-owner $(snrd keys show alice -a)
|
||||
|
||||
# Query services by domain
|
||||
snrd query svc services-by-domain example.com
|
||||
```
|
||||
|
||||
## Integration Guide
|
||||
|
||||
### For Service Developers
|
||||
|
||||
1. **Domain Setup**:
|
||||
- Register your domain with a DNS provider
|
||||
- Ensure you have access to manage DNS TXT records
|
||||
- Choose a unique service ID
|
||||
|
||||
2. **Verification Process**:
|
||||
|
||||
```bash
|
||||
# Step 1: Initiate verification
|
||||
snrd tx svc initiate-domain-verification your-domain.com --from your-key
|
||||
|
||||
# Step 2: Add TXT record to DNS
|
||||
# Record: sonr-verification=<provided-token>
|
||||
|
||||
# Step 3: Wait for DNS propagation (usually 5-30 minutes)
|
||||
|
||||
# Step 4: Complete verification
|
||||
snrd tx svc verify-domain your-domain.com --from your-key
|
||||
```
|
||||
|
||||
3. **Service Registration**:
|
||||
- Define required permissions carefully
|
||||
- Use descriptive service names and descriptions
|
||||
- Consider permission scope and user privacy
|
||||
|
||||
4. **Permission Planning**:
|
||||
Common permission patterns:
|
||||
- `dwn:read,dwn:write` - Basic data access
|
||||
- `identity:read` - Read user identity
|
||||
- `vault:access` - Vault operations
|
||||
- `credentials:verify` - Verify credentials
|
||||
|
||||
### For Application Integrators
|
||||
|
||||
1. **Service Discovery**:
|
||||
|
||||
```bash
|
||||
# Find services by domain
|
||||
snrd query svc services-by-domain app.example.com
|
||||
|
||||
# Get service details
|
||||
snrd query svc service service-id
|
||||
```
|
||||
|
||||
2. **Permission Verification**:
|
||||
- Check service permissions before integration
|
||||
- Validate UCAN delegation chains
|
||||
- Ensure permissions match your requirements
|
||||
|
||||
3. **User Authorization Flow**:
|
||||
- Service requests permissions from user
|
||||
- User reviews and approves via wallet
|
||||
- Service receives UCAN capability
|
||||
- Service can act on user's behalf
|
||||
|
||||
## Domain Verification Process
|
||||
|
||||
### DNS TXT Record Format
|
||||
|
||||
```
|
||||
sonr-verification=<token>
|
||||
```
|
||||
|
||||
### Verification Requirements
|
||||
|
||||
- Domain must be a valid TLD
|
||||
- DNS TXT record must match the generated token
|
||||
- Verification expires after 7 days if not completed
|
||||
- Each domain can only be verified by one owner
|
||||
|
||||
### Example DNS Configuration
|
||||
|
||||
```
|
||||
# For domain: app.example.com
|
||||
# Add TXT record:
|
||||
Type: TXT
|
||||
Name: @ (or app if subdomain)
|
||||
Value: sonr-verification=1234567890abcdef
|
||||
TTL: 300 (5 minutes)
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Domain Ownership**: Only verified domain owners can register services
|
||||
2. **Permission Scope**: Services can only request, not grant permissions
|
||||
3. **UCAN Validation**: All capability chains are validated
|
||||
4. **Unique Domains**: Each domain can only have one owner
|
||||
5. **Service Isolation**: Services cannot access data from other services
|
||||
|
||||
## Module Parameters
|
||||
|
||||
- `verification_timeout`: Domain verification timeout (default: 7 days)
|
||||
- `max_services_per_owner`: Maximum services per owner (default: 100)
|
||||
- `allowed_permissions`: List of permissions services can request
|
||||
- `service_registration_fee`: Fee for service registration (default: 1000usnr)
|
||||
|
||||
## Events
|
||||
|
||||
(TODO: List and describe event tags used by the module, including those related to UCAN authorization)
|
||||
The module emits the following events:
|
||||
|
||||
## UCAN Authorization
|
||||
- `domain_verification_initiated`: When verification starts
|
||||
- `domain`, `owner`, `token`, `expires_at`
|
||||
- `domain_verified`: When domain is successfully verified
|
||||
- `domain`, `owner`, `verified_at`
|
||||
- `service_registered`: When a new service is registered
|
||||
- `service_id`, `domain`, `owner`, `permissions`
|
||||
- `service_updated`: When service is updated
|
||||
- `service_id`, `fields_updated`
|
||||
|
||||
This module utilizes UCAN (User Controlled Authorization Networks) to provide a decentralized and user-centric authorization mechanism. UCANs are self-contained authorization tokens that allow users to delegate specific capabilities to other entities without relying on a central authority.
|
||||
## Building and Testing
|
||||
|
||||
### UCAN Integration
|
||||
### Running Tests
|
||||
|
||||
- The module parameters include a `UcanPermissions` field that defines the default UCAN permissions required for actions within the module.
|
||||
- Message handlers in the `MsgServer` perform UCAN authorization checks by:
|
||||
- Retrieving the UCAN permissions from the context (injected by a middleware).
|
||||
- Retrieving the required UCAN permissions from the module parameters.
|
||||
- Verifying that the provided UCAN permissions satisfy the required permissions.
|
||||
- A dedicated middleware is responsible for:
|
||||
- Parsing incoming requests for UCAN tokens.
|
||||
- Verifying UCAN token signatures and validity.
|
||||
- Extracting UCAN permissions.
|
||||
- Injecting UCAN permissions into the context.
|
||||
- UCAN verification logic involves:
|
||||
- Checking UCAN token signatures against the issuer's public key (resolved via the `x/did` module).
|
||||
- Validating token expiration and other constraints.
|
||||
- Parsing token capabilities and extracting relevant permissions.
|
||||
```bash
|
||||
# Run unit tests
|
||||
make -C x/svc test
|
||||
|
||||
## Future Improvements
|
||||
# Run tests with race detection
|
||||
make -C x/svc test-race
|
||||
|
||||
- Implement svc discovery mechanisms
|
||||
- Add support for svc reputation and rating systems
|
||||
- Enhance svc metadata with more detailed information
|
||||
- Implement svc update and deactivation functionality
|
||||
# Generate coverage report
|
||||
make -C x/svc test-cover
|
||||
|
||||
## Tests
|
||||
# Run benchmarks
|
||||
make -C x/svc benchmark
|
||||
```
|
||||
|
||||
(TODO: Add acceptance tests for the module)
|
||||
## Best Practices
|
||||
|
||||
## Appendix
|
||||
### For Service Developers
|
||||
|
||||
This module is part of the Sonr blockchain project and interacts with other modules such as DID and NFT modules to provide a comprehensive decentralized svc ecosystem.
|
||||
1. **Choose Meaningful IDs**: Use descriptive service IDs that reflect your service
|
||||
2. **Request Minimal Permissions**: Only request what you need
|
||||
3. **Document Permissions**: Clearly explain why each permission is needed
|
||||
4. **Plan for Updates**: Design your permission model for future growth
|
||||
5. **Monitor Expiration**: Keep track of UCAN expiration times
|
||||
|
||||
### For Users
|
||||
|
||||
1. **Verify Services**: Check domain ownership before granting permissions
|
||||
2. **Review Permissions**: Understand what each permission allows
|
||||
3. **Regular Audits**: Review granted permissions periodically
|
||||
4. **Revoke When Needed**: Remove permissions from unused services
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- **Service Categories**: Categorization for better discovery
|
||||
- **Reputation System**: User ratings and reviews
|
||||
- **Permission Templates**: Pre-defined permission sets
|
||||
- **Multi-sig Ownership**: Support for team-owned services
|
||||
- **Service Analytics**: Usage statistics and monitoring
|
||||
- **Subdomain Support**: Hierarchical service structures
|
||||
|
||||
Reference in New Issue
Block a user