mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-03 01:41:44 +00:00
Prad Nukala
@@ -0,0 +1,215 @@
|
||||
---
|
||||
title: "Decentralized Exchange (x/dex)"
|
||||
sidebarTitle: "Interchain Exchange"
|
||||
icon: "coins"
|
||||
tag: "x/dex"
|
||||
description: "Cross-chain trading through IBC Interchain Accounts with DID-based authorization"
|
||||
---
|
||||
|
||||
import { Card, CardGrid } from '@/components/mdx'
|
||||
import { Tabs, Tab } from '@/components/mdx'
|
||||
import { Accordion, AccordionItem } from '@/components/mdx'
|
||||
import { CodeGroup } from '@/components/mdx'
|
||||
import { Info } from '@/components/mdx'
|
||||
|
||||
# Sonr DEX Module
|
||||
|
||||
The Sonr Decentralized Exchange (DEX) module provides a powerful cross-chain trading infrastructure that enables seamless, secure, and self-sovereign trading across the Cosmos ecosystem.
|
||||
|
||||
## Overview
|
||||
|
||||
<CardGrid>
|
||||
<Card title="Cross-Chain Trading" icon="swap">
|
||||
Execute swaps on remote DEX chains via Interchain Accounts (ICA)
|
||||
</Card>
|
||||
<Card title="Liquidity Management" icon="wallet">
|
||||
Add and remove liquidity from pools across chains
|
||||
</Card>
|
||||
<Card title="DID-Controlled Accounts" icon="key">
|
||||
All operations authorized through Sonr DIDs
|
||||
</Card>
|
||||
<Card title="Multi-DEX Support" icon="globe">
|
||||
Connect to multiple DEX chains simultaneously
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
## Core Concepts
|
||||
|
||||
<Accordion>
|
||||
<AccordionItem title="Interchain Accounts (ICA)">
|
||||
The module leverages IBC's Interchain Accounts to create controlled accounts on remote DEX chains. Each account is linked to a Sonr DID and managed through ICA transactions.
|
||||
</AccordionItem>
|
||||
|
||||
<AccordionItem title="DID-Based Authorization">
|
||||
All DEX operations require authorization from a valid Sonr DID, ensuring that only authenticated users can perform trading operations.
|
||||
</AccordionItem>
|
||||
|
||||
<AccordionItem title="UCAN Tokens">
|
||||
User-Controlled Authorization Network (UCAN) tokens provide delegated authority for specific operations, enabling secure third-party integrations.
|
||||
</AccordionItem>
|
||||
</Accordion>
|
||||
|
||||
## Trading Operations
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Swaps">
|
||||
<CodeGroup>
|
||||
```bash
|
||||
# Execute a swap on Osmosis
|
||||
snrd tx dex swap \
|
||||
--did did:sonr:alice \
|
||||
--connection connection-0 \
|
||||
--source-denom uosmo \
|
||||
--target-denom uatom \
|
||||
--amount 1000000 \
|
||||
--min-amount-out 950000 \
|
||||
--ucan-token "eyJ0eXAiOi..." \
|
||||
--from alice
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info>
|
||||
Swap operations are protected against slippage with `min-amount-out` parameter.
|
||||
</Info>
|
||||
</Tab>
|
||||
|
||||
<Tab title="Liquidity">
|
||||
<CodeGroup>
|
||||
```bash
|
||||
# Provide liquidity to a pool
|
||||
snrd tx dex provide-liquidity \
|
||||
--did did:sonr:alice \
|
||||
--connection connection-0 \
|
||||
--pool-id 1 \
|
||||
--assets 1000000uosmo,500000uatom \
|
||||
--min-shares 100000 \
|
||||
--ucan-token "eyJ0eXAiOi..." \
|
||||
--from alice
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info>
|
||||
Liquidity providers receive LP tokens proportional to their contribution.
|
||||
</Info>
|
||||
</Tab>
|
||||
|
||||
<Tab title="Orders">
|
||||
<CodeGroup>
|
||||
```bash
|
||||
# Create a limit order
|
||||
snrd tx dex create-order \
|
||||
--did did:sonr:alice \
|
||||
--connection connection-0 \
|
||||
--sell-denom uosmo \
|
||||
--buy-denom uatom \
|
||||
--amount 1000000 \
|
||||
--price 1.2 \
|
||||
--expiration "2024-12-31T23:59:59Z" \
|
||||
--ucan-token "eyJ0eXAiOi..." \
|
||||
--from alice
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info>
|
||||
Limit orders can be created with precise price and expiration settings.
|
||||
</Info>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Security and Performance
|
||||
|
||||
<CardGrid>
|
||||
<Card title="DID Authentication" icon="shield">
|
||||
All operations require valid DID signatures
|
||||
</Card>
|
||||
<Card title="Rate Limiting" icon="lock">
|
||||
Protects against spam and DoS attacks
|
||||
</Card>
|
||||
<Card title="UCAN Authorization" icon="key">
|
||||
Fine-grained permissions prevent unauthorized operations
|
||||
</Card>
|
||||
<Card title="Batch Operations" icon="rocket">
|
||||
Multiple operations can be executed in a single transaction
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
## Supported DEX Chains
|
||||
|
||||
### Currently Supported
|
||||
- **Osmosis**: Full swap, liquidity, and order support
|
||||
- **Crescent**: Swap and liquidity operations
|
||||
- **Neutron**: Astroport DEX integration
|
||||
|
||||
### Planned Support
|
||||
- **Kujira**: FIN orderbook integration
|
||||
- **Injective**: Derivatives and spot trading
|
||||
- **Sei**: High-frequency trading support
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
<Accordion>
|
||||
<AccordionItem title="Advanced Trading Features">
|
||||
- Advanced Order Types (stop-loss, trailing stops)
|
||||
- Cross-Chain Arbitrage
|
||||
- Portfolio Management
|
||||
- Yield Farming Integration
|
||||
</AccordionItem>
|
||||
|
||||
<AccordionItem title="DeFi Innovations">
|
||||
- Derivatives Trading
|
||||
- MEV Protection
|
||||
- Analytics Dashboard
|
||||
- Social Trading Features
|
||||
</AccordionItem>
|
||||
</Accordion>
|
||||
|
||||
## Technical Details
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Protobuf Definitions">
|
||||
```protobuf
|
||||
message MsgExecuteSwap {
|
||||
string did = 1; // DID initiating the swap
|
||||
string connection_id = 2; // IBC connection to DEX chain
|
||||
string source_denom = 3; // Token to swap from
|
||||
string target_denom = 4; // Token to swap to
|
||||
string amount = 5; // Amount to swap
|
||||
string min_amount_out = 6; // Minimum amount out (slippage protection)
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Rate Limiting">
|
||||
```go
|
||||
// Per-block rate limiting
|
||||
if opsThisBlock >= params.RateLimits.MaxOpsPerBlock {
|
||||
return errorsmod.Wrap(ErrRateLimited, "max operations per block exceeded")
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Integration Guide
|
||||
|
||||
1. **Account Setup**: Register ICA accounts for target DEX chains
|
||||
2. **Permission Management**: Issue UCAN tokens for specific operations
|
||||
3. **Execute Trades**: Use the module's messages to perform DEX operations
|
||||
4. **Monitor Activity**: Subscribe to events for real-time updates
|
||||
5. **Query State**: Use queries to display balances and history
|
||||
|
||||
## Development
|
||||
|
||||
<CodeGroup>
|
||||
```bash
|
||||
# Run unit tests
|
||||
make test-dex
|
||||
|
||||
# Run integration tests with IBC
|
||||
make test-dex-ibc
|
||||
|
||||
# Start local chain with ICA enabled
|
||||
make localnet-dex
|
||||
```
|
||||
</CodeGroup>
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: "Decentralized Identity"
|
||||
sidebarTitle: "Universal Identifiers"
|
||||
description: "Sonr's Decentralized Identifier (DID) Module: W3C-Compliant Identity Management"
|
||||
icon: "fingerprint"
|
||||
tag: "x/did"
|
||||
---
|
||||
|
||||
# Decentralized Identifier (DID) Module
|
||||
|
||||
The Sonr DID module implements a comprehensive W3C DID specification, providing a decentralized identity layer that enables self-sovereign identity management across the Sonr blockchain ecosystem.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **W3C DID Documents**: Full implementation of the W3C DID Core specification
|
||||
- **Verifiable Credentials**: Issue and manage W3C Verifiable Credentials
|
||||
- **Multiple Verification Methods**: Support for various key types and WebAuthn
|
||||
- **Signature Verification**: Multi-algorithm cryptographic signature verification
|
||||
- **Service Endpoints**: Associate services with DIDs
|
||||
- **Decentralized Resolution**: On-chain DID resolution without external dependencies
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Decentralized Identifiers (DIDs)
|
||||
|
||||
DIDs are globally unique identifiers created and controlled by their owners without requiring a central authority. In Sonr, DIDs follow the format: `did:sonr:<unique-identifier>`.
|
||||
|
||||
### DID Documents
|
||||
|
||||
DID Documents are core data structures containing:
|
||||
- Verification methods (public keys, WebAuthn credentials)
|
||||
- Service endpoints
|
||||
- Controller relationships
|
||||
- Authentication and verification relationships
|
||||
|
||||
### Verifiable Credentials
|
||||
|
||||
Digital credentials that can be cryptographically verified, containing claims about subjects and issued by trusted authorities.
|
||||
|
||||
## Revolutionary WebAuthn Integration
|
||||
|
||||
### Gasless WebAuthn Registration
|
||||
|
||||
The DID module introduces a groundbreaking **gasless registration** system that allows users to create their first decentralized identity without requiring any cryptocurrency. This removes traditional Web3 onboarding barriers.
|
||||
|
||||
#### Key Benefits
|
||||
- **Zero Cost**: Create DIDs without tokens
|
||||
- **Biometric Authentication**: Use device biometrics for identity creation
|
||||
- **Instant Usability**: Immediate access to the Sonr ecosystem
|
||||
- **Cross-Platform**: Works across all major browsers and operating systems
|
||||
|
||||
### CLI Usage Example
|
||||
|
||||
```bash
|
||||
# Create DID with WebAuthn credential (no tokens required)
|
||||
snrd auth register --username alice
|
||||
|
||||
# Register with automatic vault creation
|
||||
snrd auth register --username bob --auto-vault
|
||||
```
|
||||
|
||||
## Supported Verification Methods
|
||||
|
||||
1. **Ed25519**: High-performance, compact signatures
|
||||
2. **JSON Web Signature**: Flexible web-compatible signature format
|
||||
3. **WebAuthn**: Device-based authentication with biometrics
|
||||
4. **ECDSA (Secp256k1)**: Blockchain-compatible signatures
|
||||
5. **RSA**: Legacy system compatibility
|
||||
|
||||
## External Wallet Integration
|
||||
|
||||
Link external wallets like MetaMask and Keplr directly to your DID, enabling cross-platform identity management.
|
||||
|
||||
### Supported Wallet Types
|
||||
- **Ethereum Wallets**: MetaMask, Coinbase Wallet
|
||||
- **Cosmos Wallets**: Keplr, Leap Wallet, Cosmostation
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Comprehensive Cryptographic Verification**
|
||||
- **Origin Validation**
|
||||
- **Anti-Replay Protection**
|
||||
- **Credential Uniqueness Enforcement**
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Passwordless Authentication**
|
||||
- **Cross-Platform Identity**
|
||||
- **Verifiable Credentials**
|
||||
- **Service Authentication**
|
||||
|
||||
## Standards Compliance
|
||||
|
||||
- W3C DID Core
|
||||
- W3C Verifiable Credentials
|
||||
- WebAuthn
|
||||
- JSON-LD
|
||||
- JSON Web Key/Signature
|
||||
|
||||
## Getting Started
|
||||
|
||||
### For Application Developers
|
||||
1. Generate DID and initial document
|
||||
2. Add verification methods
|
||||
3. Register application services
|
||||
4. Issue user credentials
|
||||
5. Implement WebAuthn login
|
||||
|
||||
### For Wallet Developers
|
||||
1. Implement DID resolution
|
||||
2. Build credential management UI
|
||||
3. Support WebAuthn authentication
|
||||
4. Implement key recovery mechanisms
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
- Off-chain DID resolution
|
||||
- Zero-knowledge proof credentials
|
||||
- Social key recovery
|
||||
- Cross-chain DID interoperability
|
||||
- Advanced credential schemas
|
||||
|
||||
## Documentation and Examples
|
||||
|
||||
Refer to the [Blockchain Documentation](/blockchain/) for detailed guides, API references, and integration tutorials.
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
title: "Decentralized Web Node (x/dwn)"
|
||||
sidebarTitle: "Smart Wallets"
|
||||
description: "Decentralized Web Node (DWN) Module: Personal Data Stores, Protocols, and Secure Vaults"
|
||||
icon: "wallet"
|
||||
tag: "x/dwn"
|
||||
---
|
||||
|
||||
# Decentralized Web Node (DWN) Module
|
||||
|
||||
The `x/dwn` module is the foundational engine of the Sonr ecosystem. It provides a comprehensive **Decentralized Web Node (DWN)** implementation that serves as the backbone for user-controlled data storage, protocol management, and secure vault operations. The module enables users to maintain sovereign control over their data while participating in a decentralized ecosystem.
|
||||
|
||||
## Overview
|
||||
|
||||
The DWN module implements the [Decentralized Web Node specification](https://identity.foundation/decentralized-web-node/spec/), providing:
|
||||
|
||||
- **Personal Data Stores**: User-controlled storage for structured data records
|
||||
- **Protocol-Based Interactions**: Define and enforce data schemas and interaction patterns
|
||||
- **Granular Permissions**: Fine-grained access control using capability-based authorization
|
||||
- **Secure Vaults**: Enclave-based key management and transaction signing via WebAssembly
|
||||
- **Multi-Chain Transaction Building**: Support for both Cosmos SDK and EVM transaction construction
|
||||
- **Enhanced Address Derivation**: BIP44 HD wallet address derivation for multiple blockchain networks
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Decentralized Web Nodes (DWNs)
|
||||
|
||||
A DWN is a personal data store that enables individuals to manage their data independently of centralized providers. Each user's DWN serves as their agent in the decentralized web, storing data, managing permissions, and executing protocols on their behalf.
|
||||
|
||||
### Records
|
||||
|
||||
Records are the fundamental unit of data storage in a DWN. Each record can:
|
||||
|
||||
- Store arbitrary data with optional encryption
|
||||
- Be organized hierarchically using parent-child relationships
|
||||
- Conform to specific protocols and schemas
|
||||
- Be published for public access or kept private
|
||||
|
||||
### Protocols
|
||||
|
||||
Protocols define structured ways for applications to interact with DWN data. They specify:
|
||||
|
||||
- Data schemas for validation
|
||||
- Permission models
|
||||
- Interaction patterns between different parties
|
||||
|
||||
### Permissions
|
||||
|
||||
The DWN uses a capability-based permission system where:
|
||||
|
||||
- Permissions are granted as signed tokens (JWTs)
|
||||
- Access can be scoped to specific interfaces, methods, protocols, or records
|
||||
- Permissions can be delegated and revoked
|
||||
|
||||
### Vaults
|
||||
|
||||
Vaults provide secure, enclave-based key management enabling:
|
||||
|
||||
- Hardware-backed key generation and storage
|
||||
- Secure transaction signing without exposing private keys
|
||||
- Multi-party computation capabilities
|
||||
- WebAssembly-based secure execution environment
|
||||
- Multi-chain transaction building for Cosmos SDK and EVM networks
|
||||
- BIP44 HD wallet address derivation with configurable coin types
|
||||
|
||||
## Integration Guide
|
||||
|
||||
### For Application Developers
|
||||
|
||||
1. **Define Your Protocol**: Create a protocol definition that describes your data structures and permissions
|
||||
2. **Configure Protocol**: Register your protocol with target DWNs
|
||||
3. **Request Permissions**: Use the SVC module to request necessary permissions from users
|
||||
4. **Store Data**: Write records that conform to your protocol
|
||||
5. **Query Data**: Read records based on granted permissions
|
||||
|
||||
### For Wallet Developers
|
||||
|
||||
1. **VaultKeeper Integration**:
|
||||
|
||||
- Use `CreateVault` for secure key generation in WebAssembly enclaves
|
||||
- Implement `RefreshVault` calls based on configured refresh intervals
|
||||
- Use `SignWithVault` for transaction signing without exposing private keys
|
||||
- Leverage `BroadcastTx` for direct transaction submission through vaults
|
||||
- Utilize multi-chain transaction building for both Cosmos SDK and EVM networks
|
||||
- Implement address derivation for multi-chain wallet support
|
||||
|
||||
2. **Vault Management UI**:
|
||||
- Display vault states and ownership information
|
||||
- Show vault public keys and enclave data
|
||||
- Provide refresh status and last refresh timestamps
|
||||
- Enable vault-based message signing interfaces
|
||||
- Show derived addresses for multiple blockchain networks
|
||||
- Display transaction building capabilities and fee estimations
|
||||
|
||||
## CLI Examples
|
||||
|
||||
### Records Operations
|
||||
|
||||
```bash
|
||||
# Write a new record
|
||||
snrd tx dwn records-write did:example:123 '{"interface_name":"Records","method":"Write"}' '{"name":"Alice","age":30}' \
|
||||
--protocol example.com/profile/v1 \
|
||||
--published \
|
||||
--from alice
|
||||
|
||||
# Query records
|
||||
snrd query dwn records did:example:123 --protocol example.com/profile/v1
|
||||
|
||||
# Delete a record
|
||||
snrd tx dwn records-delete did:example:123 record-123 '{"interface_name":"Records","method":"Delete"}' \
|
||||
--from alice
|
||||
```
|
||||
|
||||
### Vault Operations
|
||||
|
||||
```bash
|
||||
# Create a vault with enclave-based key generation
|
||||
snrd tx dwn create-vault my-vault key-1 --from alice
|
||||
|
||||
# Refresh vault enclave state (requires minimum interval)
|
||||
snrd tx dwn refresh-vault my-vault --from alice
|
||||
|
||||
# Sign a message with vault's secure enclave
|
||||
snrd tx dwn sign-with-vault my-vault "48656c6c6f20576f726c64" --from alice
|
||||
|
||||
# Broadcast a transaction using vault's enclave
|
||||
snrd tx dwn broadcast-tx my-vault "transaction-bytes" --from alice
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Authorization**: All write operations require proper authorization (JWT/signature)
|
||||
2. **Encryption**: Sensitive data should be encrypted before storage
|
||||
3. **Vault Security**:
|
||||
- Vaults use WebAssembly enclaves for tamper-resistant key protection
|
||||
- Private keys never leave the secure enclave environment
|
||||
- VaultKeeper enforces ownership verification for all operations
|
||||
- Refresh intervals prevent stale enclave states
|
||||
4. **Permission Scoping**: Grant minimal required permissions
|
||||
5. **Revocation**: Regularly review and revoke unused permissions
|
||||
|
||||
## Building and Testing
|
||||
|
||||
### Building the Motor Client
|
||||
|
||||
```bash
|
||||
# Build the motor WASM client
|
||||
make -C x/dwn motr
|
||||
|
||||
# Run unit tests
|
||||
make -C x/dwn test
|
||||
|
||||
# Generate coverage report
|
||||
make -C x/dwn test-cover
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- **Replication**: Multi-node data replication for availability
|
||||
- **Sync Protocol**: Efficient data synchronization between nodes
|
||||
- **Advanced Queries**: GraphQL-like query capabilities
|
||||
- **Compression**: Automatic data compression for efficiency
|
||||
- **IPFS Integration**: Content-addressed storage backend
|
||||
- **Cross-Chain Interoperability**: Enhanced cross-chain transaction capabilities
|
||||
- **Advanced MPC Features**: Extended multi-party computation capabilities
|
||||
|
||||
@@ -0,0 +1,244 @@
|
||||
---
|
||||
title: "On-Chain Authorization (x/svc)"
|
||||
sidebarTitle: "Web Service Registry"
|
||||
description: "Service registration and management with domain verification and UCAN integration"
|
||||
icon: "factory"
|
||||
tag: "x/svc"
|
||||
---
|
||||
|
||||
# Sonr Service (SVC) Module
|
||||
|
||||
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.
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
- **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
|
||||
|
||||
## System Architecture
|
||||
|
||||
<Mermaid
|
||||
chart={`graph TB
|
||||
subgraph "Client Layer"
|
||||
U[User]
|
||||
B[Browser]
|
||||
WA[WebAuthn API]
|
||||
end
|
||||
|
||||
subgraph "Application Layer"
|
||||
APP[App Frontend]
|
||||
SDK[Sonr SDK]
|
||||
SVC_SDK[Service SDK]
|
||||
end
|
||||
|
||||
subgraph "Blockchain Layer"
|
||||
BC[Sonr Blockchain]
|
||||
subgraph "Modules"
|
||||
DID[x/did]
|
||||
DWN[x/dwn]
|
||||
UCAN[x/ucan]
|
||||
SVC[x/svc]
|
||||
end
|
||||
end
|
||||
|
||||
subgraph "Storage Layer"
|
||||
IPFS[IPFS Network]
|
||||
VAULT[Vault Storage]
|
||||
end
|
||||
|
||||
U --> B
|
||||
B --> WA
|
||||
B --> APP
|
||||
APP --> SDK
|
||||
APP --> SVC_SDK
|
||||
SDK --> BC
|
||||
SVC_SDK --> BC
|
||||
BC --> DID
|
||||
BC --> DWN
|
||||
BC --> UCAN
|
||||
BC --> SVC
|
||||
DWN --> IPFS
|
||||
DWN --> VAULT
|
||||
`}
|
||||
/>
|
||||
|
||||
## Trust Model
|
||||
|
||||
<Mermaid
|
||||
chart={`graph LR
|
||||
subgraph "Trust Anchors"
|
||||
WA[WebAuthn<br/>Hardware]
|
||||
BC[Blockchain<br/>Consensus]
|
||||
DNS[DNS<br/>Domain Verification]
|
||||
end
|
||||
|
||||
subgraph "Identity Layer"
|
||||
DID[DID Documents]
|
||||
CRED[WebAuthn Credentials]
|
||||
end
|
||||
|
||||
subgraph "Authorization Layer"
|
||||
UCAN[UCAN Tokens]
|
||||
CAP[Capabilities]
|
||||
end
|
||||
|
||||
subgraph "Service Layer"
|
||||
SVC[Service Records]
|
||||
PERM[Permissions]
|
||||
end
|
||||
|
||||
WA --> CRED
|
||||
BC --> DID
|
||||
DNS --> SVC
|
||||
CRED --> DID
|
||||
DID --> UCAN
|
||||
UCAN --> CAP
|
||||
CAP --> PERM
|
||||
SVC --> PERM
|
||||
`}
|
||||
/>
|
||||
|
||||
## 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)
|
||||
|
||||
## Domain Verification Process
|
||||
|
||||
Domain verification follows a strict process to ensure legitimate ownership:
|
||||
|
||||
1. **Initiate Verification**:
|
||||
|
||||
```bash
|
||||
# Initiate domain verification
|
||||
snrd tx svc initiate-domain-verification example.com --from alice
|
||||
```
|
||||
|
||||
2. **Add DNS TXT Record**:
|
||||
|
||||
```
|
||||
Type: TXT
|
||||
Name: @ (or app if subdomain)
|
||||
Value: sonr-verification=<provided-token>
|
||||
TTL: 300 (5 minutes)
|
||||
```
|
||||
|
||||
3. **Complete Verification**:
|
||||
```bash
|
||||
# Verify domain after DNS propagation
|
||||
snrd tx svc verify-domain example.com --from alice
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
## Service Registration 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. **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
|
||||
```
|
||||
|
||||
### Common Permission Patterns
|
||||
|
||||
- `dwn:read,dwn:write` - Basic data access
|
||||
- `identity:read` - Read user identity
|
||||
- `vault:access` - Vault operations
|
||||
- `credentials:verify` - Verify credentials
|
||||
|
||||
## Service Discovery and Queries
|
||||
|
||||
### Querying Services
|
||||
|
||||
```bash
|
||||
# Query a specific 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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Service Developers
|
||||
|
||||
1. Choose meaningful service IDs
|
||||
2. Request minimal permissions
|
||||
3. Document why each permission is needed
|
||||
4. Plan for future permission model updates
|
||||
5. Monitor UCAN expiration times
|
||||
|
||||
### For Users
|
||||
|
||||
1. Verify service domain ownership
|
||||
2. Review permission scopes carefully
|
||||
3. Conduct regular permission audits
|
||||
4. Revoke unused service permissions
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Service categorization
|
||||
- Reputation system
|
||||
- Permission templates
|
||||
- Multi-sig service ownership
|
||||
- Service analytics
|
||||
- Enhanced subdomain support
|
||||
|
||||
Reference in New Issue
Block a user