mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-03 18:01:39 +00:00
Prad Nukala
@@ -0,0 +1,15 @@
|
||||
---
|
||||
openapi: post /dex.v1.Msg/ProvideLiquidity
|
||||
title: Provide Liquidity to Pool
|
||||
description: Add liquidity to DEX pools and earn LP tokens
|
||||
og:title: Add Liquidity to Cross-Chain Pools
|
||||
tag: x/dex
|
||||
---
|
||||
|
||||
<Info>
|
||||
LP tokens represent your proportional share of the pool and accrue trading fees.
|
||||
</Info>
|
||||
|
||||
<Note>
|
||||
Impermanent loss may occur when providing liquidity. Research the risks before proceeding.
|
||||
</Note>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: post /dex.v1.Msg/CancelOrder
|
||||
title: Cancel Limit Order
|
||||
description: Cancel active orders on remote DEX chains
|
||||
og:title: Cancel Cross-Chain Orders
|
||||
tag: x/dex
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Order cancellation is not instant. There's a small window where the order
|
||||
might still be filled before cancellation is processed.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Monitor the IBC packet acknowledgment to confirm successful cancellation.
|
||||
</Tip>
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
openapi: post /dex.v1.Msg/RegisterDEXAccount
|
||||
title: Register Interchain DEX Account
|
||||
description: Create a new ICA account for cross-chain trading operations
|
||||
og:title: Setup Cross-Chain Trading Account
|
||||
tag: x/dex
|
||||
---
|
||||
|
||||
<Note>
|
||||
Account creation is asynchronous. Monitor the IBC packet acknowledgment to confirm the account address.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
Each DID is limited to a maximum number of DEX accounts as configured in module parameters.
|
||||
</Warning>
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
openapi: post /dex.v1.Msg/CreateLimitOrder
|
||||
title: Create Limit Order
|
||||
description: Place limit orders on remote DEX chains
|
||||
og:title: Place Cross-Chain Limit Orders
|
||||
tag: x/dex
|
||||
---
|
||||
|
||||
<Info>
|
||||
Limit orders allow you to specify the exact price at which you want to trade,
|
||||
providing better control over execution prices.
|
||||
</Info>
|
||||
|
||||
<Note>
|
||||
Orders are subject to maker fees on most DEXs. Check the specific DEX documentation
|
||||
for fee structures.
|
||||
</Note>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: post /dex.v1.Msg/ExecuteSwap
|
||||
title: Execute Cross-Chain Swap
|
||||
description: Perform token swaps on remote DEX chains with slippage protection
|
||||
og:title: Cross-Chain Token Swap
|
||||
tag: x/dex
|
||||
---
|
||||
|
||||
<Tip>
|
||||
For better execution prices, consider breaking large swaps into smaller transactions
|
||||
or using the multi-hop routing feature.
|
||||
</Tip>
|
||||
|
||||
<Warning>
|
||||
Platform fees apply to all swaps. Check the current fee structure in module parameters.
|
||||
</Warning>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: post /dex.v1.Msg/RemoveLiquidity
|
||||
title: Remove Liquidity from Pool
|
||||
description: Withdraw assets from DEX pools by burning LP tokens
|
||||
og:title: Withdraw Liquidity from Cross-Chain Pools
|
||||
tag: x/dex
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Removing liquidity during high volatility may result in receiving different asset ratios
|
||||
than initially provided.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Set appropriate minimum amounts to protect against unfavorable price movements.
|
||||
</Tip>
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/AddService
|
||||
title: Add Service Endpoint
|
||||
description: Associate services and interaction endpoints with your DID
|
||||
og:title: Add DID Service
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Tip>
|
||||
Service endpoints enable others to discover how to interact with
|
||||
your DID for specific purposes (messaging, data exchange, etc.).
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Service URLs should use HTTPS for security. Consider using
|
||||
decentralized storage for resilience.
|
||||
</Note>
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/AddVerificationMethod
|
||||
title: Add Verification Method
|
||||
description: Add cryptographic keys and authentication methods to your DID
|
||||
og:title: Enhance DID Security
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Info>
|
||||
Adding multiple verification methods provides redundancy and enables
|
||||
different use cases (signing, encryption, authentication).
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
Best practice: Add at least one backup verification method to prevent
|
||||
lockout if your primary method becomes unavailable.
|
||||
</Tip>
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/CreateDID
|
||||
title: Create W3C DID Document
|
||||
description: Create a new decentralized identifier with verification methods and services
|
||||
og:title: Create Decentralized Identity
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Note>
|
||||
DID creation requires an existing account with tokens unless using gasless WebAuthn registration.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Enable auto-vault creation to automatically set up secure credential storage.
|
||||
</Tip>
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/DeactivateDID
|
||||
title: Deactivate DID Document
|
||||
description: Permanently disable a decentralized identifier
|
||||
og:title: Deactivate Digital Identity
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Warning>
|
||||
**This operation is PERMANENT and IRREVERSIBLE.**
|
||||
Deactivated DIDs cannot be reactivated. Ensure you have migrated
|
||||
any necessary data before deactivation.
|
||||
</Warning>
|
||||
|
||||
<Info>
|
||||
Deactivation is useful for key compromise scenarios or when
|
||||
transitioning to a new identity.
|
||||
</Info>
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/IssueVerifiableCredential
|
||||
title: Issue W3C Verifiable Credential
|
||||
description: Create cryptographically signed credentials for identity claims
|
||||
og:title: Issue Digital Credentials
|
||||
---
|
||||
|
||||
<Note>
|
||||
Only DIDs with appropriate verification methods can issue credentials.
|
||||
The issuer's reputation affects credential trustworthiness.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Set reasonable expiration dates for credentials that represent
|
||||
time-bound claims (e.g., memberships, certifications).
|
||||
</Tip>
|
||||
|
||||
<Warning>
|
||||
Issued credentials cannot be modified. To update claims,
|
||||
revoke the old credential and issue a new one.
|
||||
</Warning>
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/LinkExternalWallet
|
||||
title: Link External Wallet to DID
|
||||
description: Connect MetaMask, Keplr, or other wallets to your decentralized identity
|
||||
og:title: External Wallet Integration
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Note>
|
||||
Each wallet can only be linked to one DID. Attempting to link the same wallet
|
||||
to multiple DIDs will fail.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
Ensure you have control of the wallet before linking. Lost wallet access
|
||||
means losing this verification method.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
After linking, you can use your external wallet to sign transactions
|
||||
and authenticate operations on behalf of your DID.
|
||||
</Tip>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/RemoveService
|
||||
title: Remove Service Endpoint
|
||||
description: Remove service associations from your DID
|
||||
og:title: Remove DID Service
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Note>
|
||||
Removing a service doesn't delete the actual service,
|
||||
only its association with the DID.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Consider deprecation notices before removing widely-used services.
|
||||
</Tip>
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/RemoveVerificationMethod
|
||||
title: Remove Verification Method
|
||||
description: Remove keys and authentication methods from your DID
|
||||
og:title: Remove DID Verification Method
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Ensure you have alternative verification methods before removing.
|
||||
Removing all methods locks you out of your DID.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Best practice: Add new verification methods before removing old ones
|
||||
to maintain continuous access.
|
||||
</Tip>
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/RevokeVerifiableCredential
|
||||
title: Revoke Verifiable Credential
|
||||
description: Permanently invalidate an issued credential
|
||||
og:title: Revoke Digital Credential
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Revocation is permanent. Revoked credentials cannot be reinstated.
|
||||
To restore credentials, issue a new one with updated information.
|
||||
</Warning>
|
||||
|
||||
<Info>
|
||||
Always provide a clear revocation reason for transparency and
|
||||
audit trail purposes.
|
||||
</Info>
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
openapi: post /did.v1.Msg/UpdateDID
|
||||
title: Update DID Document
|
||||
description: Modify verification methods, services, and controllers of your DID
|
||||
og:title: Update Decentralized Identity
|
||||
tag: x/did
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Updates are permanent and create a new version. Previous versions
|
||||
remain accessible for historical reference.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Use specific add/remove operations for individual changes rather
|
||||
than full document updates when possible.
|
||||
</Tip>
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Update DID Module Parameters
|
||||
description: Modify module parameters for decentralized identifier operations
|
||||
og:title: Update DID Module Parameters
|
||||
tag: x/did
|
||||
openapi: post /did.v1.Msg/UpdateParams
|
||||
---
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
openapi: post /dwn.v1.Msg/ProtocolsConfigure
|
||||
title: Configure DWN Protocol
|
||||
description: Define structured data models and access patterns for interoperable applications
|
||||
og:title: DWN Protocol Configuration
|
||||
---
|
||||
|
||||
<Info>
|
||||
Protocols are the foundation of data interoperability in DWN, enabling applications to share and understand structured data.
|
||||
</Info>
|
||||
|
||||
## Protocol Architecture
|
||||
|
||||
### Protocol Definition Structure
|
||||
```json
|
||||
{
|
||||
"protocol": "https://protocols.sonr.io/health/v1",
|
||||
"published": true,
|
||||
"types": {
|
||||
"vitals": {
|
||||
"schema": "https://schema.org/VitalSign",
|
||||
"dataFormats": ["application/json"]
|
||||
},
|
||||
"records": {
|
||||
"schema": "https://schema.org/MedicalRecord",
|
||||
"dataFormats": ["application/json", "application/pdf"]
|
||||
}
|
||||
},
|
||||
"structure": {
|
||||
"vitals": {},
|
||||
"records": {
|
||||
"vitals": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
- **Types**: Define record types with schemas and formats
|
||||
- **Structure**: Specify hierarchical relationships
|
||||
- **Permissions**: Control access patterns
|
||||
- **Actions**: Define allowed operations
|
||||
|
||||
## Publishing Protocols
|
||||
|
||||
<Tip>
|
||||
Set `published: true` to make your protocol discoverable and reusable by the community.
|
||||
</Tip>
|
||||
|
||||
### Benefits of Published Protocols
|
||||
- **Discoverability**: Others can find and adopt your protocol
|
||||
- **Standardization**: Create industry-standard data models
|
||||
- **Ecosystem Growth**: Enable app interoperability
|
||||
|
||||
## Common Protocol Patterns
|
||||
|
||||
### Healthcare Protocol
|
||||
- Patient records hierarchy
|
||||
- Encrypted by default
|
||||
- Granular permission model
|
||||
|
||||
### Social Protocol
|
||||
- Posts, comments, reactions
|
||||
- Public/private content mixing
|
||||
- Media attachments
|
||||
|
||||
### IoT Protocol
|
||||
- Device data streams
|
||||
- Time-series organization
|
||||
- Aggregation rules
|
||||
|
||||
<Warning>
|
||||
Protocol URIs must be unique. Consider using versioned URIs (e.g., `/v1`, `/v2`) for upgrades.
|
||||
</Warning>
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
openapi: post /dwn.v1.Msg/RecordsDelete
|
||||
title: Delete DWN Record
|
||||
description: Remove records from your personal data vault with optional cascading deletion
|
||||
og:title: DWN Record Deletion
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Record deletion is **permanent** and cannot be undone. Ensure you have backups if needed.
|
||||
</Warning>
|
||||
|
||||
## Deletion Options
|
||||
|
||||
### Standard Deletion
|
||||
- Removes only the specified record
|
||||
- Child records remain intact
|
||||
- Preserves hierarchical structure
|
||||
|
||||
### Pruned Deletion (`prune: true`)
|
||||
- Removes the record and all descendants
|
||||
- Cascades through entire subtree
|
||||
- Useful for removing complete data structures
|
||||
|
||||
## Authorization Requirements
|
||||
|
||||
You must have one of the following:
|
||||
- **Owner**: Be the record author
|
||||
- **Permission**: Have explicit delete permission
|
||||
- **Protocol Authority**: Have protocol-level delete rights
|
||||
|
||||
<Note>
|
||||
The `deletedCount` in the response includes all pruned child records.
|
||||
</Note>
|
||||
|
||||
## Safety Considerations
|
||||
|
||||
<Tip>
|
||||
Query child records before pruning to understand the impact:
|
||||
```bash
|
||||
snrd query dwn records-query --parent-id <record_id>
|
||||
```
|
||||
</Tip>
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
openapi: post /dwn.v1.Msg/PermissionsGrant
|
||||
title: Grant DWN Access Permission
|
||||
description: Authorize other users to access your data with fine-grained control
|
||||
og:title: DWN Permission Management
|
||||
---
|
||||
|
||||
<Info>
|
||||
DWN permissions enable secure data sharing with granular access control down to individual records.
|
||||
</Info>
|
||||
|
||||
## Permission Scopes
|
||||
|
||||
### Interface-Level
|
||||
Grant access to entire interfaces:
|
||||
- **Records**: Read/write any records
|
||||
- **Protocols**: Configure protocols
|
||||
- **Permissions**: Delegate permission management
|
||||
|
||||
### Method-Level
|
||||
Restrict to specific operations:
|
||||
- **Records.Write**: Create/update only
|
||||
- **Records.Query**: Read-only access
|
||||
- **Records.Delete**: Deletion rights
|
||||
|
||||
### Protocol-Level
|
||||
Scope to protocol-compliant records:
|
||||
```json
|
||||
{
|
||||
"protocol": "https://protocols.sonr.io/health/v1",
|
||||
"interfaceName": "Records",
|
||||
"method": "Query"
|
||||
}
|
||||
```
|
||||
|
||||
### Record-Level
|
||||
Grant access to specific records:
|
||||
```json
|
||||
{
|
||||
"recordId": "record_abc123",
|
||||
"method": "Write"
|
||||
}
|
||||
```
|
||||
|
||||
## Conditional Permissions
|
||||
|
||||
<Tip>
|
||||
Use conditions to create dynamic access rules that adapt to context.
|
||||
</Tip>
|
||||
|
||||
### Time-Based Conditions
|
||||
```json
|
||||
{
|
||||
"validFrom": "2024-01-01T00:00:00Z",
|
||||
"validUntil": "2024-12-31T23:59:59Z",
|
||||
"timezone": "UTC"
|
||||
}
|
||||
```
|
||||
|
||||
### Usage Limits
|
||||
```json
|
||||
{
|
||||
"maxReads": 100,
|
||||
"maxWrites": 10,
|
||||
"rateLimit": "10/hour"
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Rules
|
||||
```json
|
||||
{
|
||||
"ipWhitelist": ["192.168.1.0/24"],
|
||||
"requireMFA": true,
|
||||
"allowedActions": ["read", "query"]
|
||||
}
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
<Warning>
|
||||
Always set expiration times for permissions to limit exposure window.
|
||||
</Warning>
|
||||
|
||||
1. **Principle of Least Privilege**: Grant minimum necessary access
|
||||
2. **Time Limits**: Use `expiresAt` for temporary access
|
||||
3. **Scope Restriction**: Be specific about what's accessible
|
||||
4. **Regular Audits**: Review and revoke unused permissions
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Healthcare Data Sharing
|
||||
- Grant doctor temporary access to medical records
|
||||
- Scope to specific record types
|
||||
- Auto-expire after appointment
|
||||
|
||||
### Collaborative Apps
|
||||
- Share project documents with team
|
||||
- Allow comments but not edits
|
||||
- Revoke when project ends
|
||||
|
||||
### IoT Device Access
|
||||
- Grant device write-only permission
|
||||
- Restrict to sensor data protocol
|
||||
- Rate limit submissions
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
openapi: post /dwn.v1.Msg/PermissionsRevoke
|
||||
title: Revoke DWN Permission
|
||||
description: Immediately remove access rights previously granted to other users
|
||||
og:title: DWN Permission Revocation
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Permission revocation takes effect **immediately**. Active sessions using the permission will be terminated.
|
||||
</Warning>
|
||||
|
||||
## Revocation Process
|
||||
|
||||
### Immediate Effects
|
||||
- Permission becomes invalid instantly
|
||||
- Active operations are interrupted
|
||||
- Cached permissions are invalidated
|
||||
- No grace period provided
|
||||
|
||||
### What Gets Revoked
|
||||
- The specific permission identified by `permissionId`
|
||||
- All derived sub-permissions
|
||||
- Any delegated permissions from this grant
|
||||
|
||||
## Finding Permissions to Revoke
|
||||
|
||||
<Tip>
|
||||
Query your active permissions before revoking:
|
||||
```bash
|
||||
snrd query dwn permissions-request --grantor <your_did>
|
||||
```
|
||||
</Tip>
|
||||
|
||||
## Authorization Requirements
|
||||
|
||||
You must be either:
|
||||
- **Original Grantor**: The entity who created the permission
|
||||
- **Admin Permission Holder**: Have permission management rights
|
||||
|
||||
## Revocation Scenarios
|
||||
|
||||
### Security Incident
|
||||
```bash
|
||||
# Revoke all permissions for compromised account
|
||||
snrd tx dwn permissions-revoke --grantee <compromised_did> --all
|
||||
```
|
||||
|
||||
### Project Completion
|
||||
```bash
|
||||
# Revoke team access after project ends
|
||||
snrd tx dwn permissions-revoke --permission-id <team_permission>
|
||||
```
|
||||
|
||||
### Access Audit
|
||||
```bash
|
||||
# Revoke unused permissions discovered in audit
|
||||
snrd tx dwn permissions-revoke --permission-id <unused_permission>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Consider notifying affected users before revoking permissions to avoid disruption.
|
||||
</Note>
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
openapi: post /dwn.v1.Msg/RotateVaultKeys
|
||||
title: Rotate Vault Encryption Keys
|
||||
description: Perform cryptographic key rotation for enhanced vault security
|
||||
og:title: DWN Vault Key Rotation
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Key rotation is a **critical security operation** that requires validator consensus or governance approval.
|
||||
</Warning>
|
||||
|
||||
## Key Rotation Architecture
|
||||
|
||||
### WebAssembly Secure Enclave
|
||||
- Keys are rotated within WASM sandbox
|
||||
- Old keys archived for decryption only
|
||||
- New keys generated using quantum-resistant algorithms
|
||||
- Zero-knowledge proof of proper rotation
|
||||
|
||||
### Distributed Key Generation (DKG)
|
||||
- Requires `minValidatorsForKeyGen` participation
|
||||
- Threshold cryptography for key shares
|
||||
- No single point of failure
|
||||
- Automatic share distribution
|
||||
|
||||
## Rotation Triggers
|
||||
|
||||
### Scheduled Rotation
|
||||
- Automatic based on `keyRotationDays` parameter
|
||||
- Predictable security maintenance
|
||||
- Minimal user impact
|
||||
|
||||
### Emergency Rotation
|
||||
- Security incident response
|
||||
- Validator compromise detection
|
||||
- Governance-initiated action
|
||||
- Uses `force: true` flag
|
||||
|
||||
### Manual Rotation
|
||||
- User-requested for specific vaults
|
||||
- Compliance requirements
|
||||
- Pre-emptive security measures
|
||||
|
||||
## Rotation Process
|
||||
|
||||
<Info>
|
||||
The rotation process is designed to be seamless with zero downtime for users.
|
||||
</Info>
|
||||
|
||||
### Phase 1: Preparation
|
||||
1. Generate new key material in enclave
|
||||
2. Distribute shares to validators
|
||||
3. Verify threshold participation
|
||||
|
||||
### Phase 2: Transition
|
||||
1. Mark old keys as decrypt-only
|
||||
2. Activate new keys for encryption
|
||||
3. Update vault metadata
|
||||
|
||||
### Phase 3: Migration
|
||||
1. Re-encrypt recent hot data
|
||||
2. Schedule lazy migration for cold data
|
||||
3. Archive old key material
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Single-Node Fallback
|
||||
<Note>
|
||||
In development mode with `singleNodeFallback: true`, rotation uses local key generation.
|
||||
</Note>
|
||||
|
||||
### Production Requirements
|
||||
- Minimum validator participation (67% default)
|
||||
- Secure communication channels
|
||||
- Audit logging of all operations
|
||||
- Rollback capability for 24 hours
|
||||
|
||||
## Impact on Users
|
||||
|
||||
### Transparent Operation
|
||||
- No action required from users
|
||||
- Automatic key selection for decrypt
|
||||
- New encryptions use latest keys
|
||||
|
||||
### Performance
|
||||
- Slight latency during rotation (< 1s)
|
||||
- Background re-encryption process
|
||||
- No data availability impact
|
||||
|
||||
<Tip>
|
||||
Monitor rotation events via:
|
||||
```bash
|
||||
snrd query dwn vault-status --vault-id <id>
|
||||
```
|
||||
</Tip>
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
openapi: post /dwn.v1.Msg/UpdateParams
|
||||
title: Update DWN Module Parameters
|
||||
description: Configure module-wide settings for data storage, protocols, and security policies
|
||||
og:title: DWN Module Governance
|
||||
---
|
||||
|
||||
<Warning>
|
||||
This operation requires **governance approval** and is typically executed through on-chain proposals.
|
||||
</Warning>
|
||||
|
||||
## Parameter Categories
|
||||
|
||||
### Storage Limits
|
||||
- **maxRecordSize**: Maximum size for individual records (default: 10MB)
|
||||
- **maxProtocolsPerDwn**: Protocol configuration limit per DWN
|
||||
- **maxPermissionsPerDwn**: Active permission limit per DWN
|
||||
|
||||
### Vault Security
|
||||
- **vaultCreationEnabled**: Enable/disable new vault creation
|
||||
- **minVaultRefreshInterval**: Minimum blocks between key refreshes
|
||||
- **keyRotationDays**: Automatic rotation interval (default: 90 days)
|
||||
- **minValidatorsForKeyGen**: Validator threshold for distributed key generation
|
||||
|
||||
### Encryption Policies
|
||||
- **encryptionEnabled**: Enforce data encryption
|
||||
- **encryptedProtocols**: Protocol URIs requiring mandatory encryption
|
||||
- **encryptedSchemas**: Schema URIs requiring mandatory encryption
|
||||
|
||||
<Note>
|
||||
Changes to these parameters affect all DWN operations network-wide.
|
||||
</Note>
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
openapi: post /dwn.v1.Msg/RecordsWrite
|
||||
title: Write Data Record to DWN
|
||||
description: Store structured data in your personal data vault with encryption and access control
|
||||
og:title: DWN Record Storage
|
||||
---
|
||||
|
||||
<Info>
|
||||
Records are the fundamental unit of data storage in DWN, supporting any data type with optional encryption.
|
||||
</Info>
|
||||
|
||||
## Key Features
|
||||
|
||||
### Data Organization
|
||||
- **Hierarchical Structure**: Use `parentId` to create nested record relationships
|
||||
- **Protocol Compliance**: Conform to defined data structures via `protocol` and `protocolPath`
|
||||
- **Schema Validation**: Enforce data integrity with JSON Schema URIs
|
||||
|
||||
### Privacy & Security
|
||||
- **Encryption**: Client-side encryption before storage
|
||||
- **Published Flag**: Control public accessibility
|
||||
- **Attestations**: Cryptographic proofs of data integrity
|
||||
|
||||
### Common Use Cases
|
||||
- **Personal Documents**: Store encrypted files and documents
|
||||
- **Application Data**: Persist app-specific user data
|
||||
- **Social Content**: Share public posts or media
|
||||
- **Health Records**: Store sensitive medical data with encryption
|
||||
|
||||
<Tip>
|
||||
Use protocol definitions to ensure data interoperability across applications.
|
||||
</Tip>
|
||||
|
||||
## Example Record Types
|
||||
|
||||
```json
|
||||
{
|
||||
"protocol": "https://protocols.sonr.io/social/v1",
|
||||
"protocolPath": "/posts/2024",
|
||||
"schema": "https://schema.org/BlogPosting",
|
||||
"published": true,
|
||||
"data": "base64_encoded_content"
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Records exceeding `maxRecordSize` will be rejected. Large files should be stored in IPFS with only metadata on-chain.
|
||||
</Warning>
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
openapi: post /svc.v1.Msg/VerifyDomain
|
||||
title: Complete Domain Verification
|
||||
description: Validate DNS TXT record to prove domain ownership
|
||||
og:title: Finalize Domain Ownership
|
||||
---
|
||||
|
||||
<Info>
|
||||
This endpoint validates the DNS TXT record to permanently bind the domain to your address.
|
||||
</Info>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before calling this endpoint:
|
||||
1. **Initiated Verification**: Must have called `InitiateDomainVerification`
|
||||
2. **DNS Record Added**: TXT record with token must be present
|
||||
3. **DNS Propagation**: Record must be globally accessible (5-30 minutes)
|
||||
4. **Not Expired**: Within 7-day verification window
|
||||
|
||||
## Verification Check
|
||||
|
||||
The system performs these checks:
|
||||
```
|
||||
1. Query DNS TXT records for domain
|
||||
2. Look for: sonr-verification=<expected_token>
|
||||
3. Validate token matches initiated verification
|
||||
4. Confirm ownership and bind domain
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### DNS Not Propagated
|
||||
<Tip>
|
||||
Wait 5-30 minutes after adding the TXT record. Check propagation:
|
||||
```bash
|
||||
dig TXT example.com +short
|
||||
```
|
||||
</Tip>
|
||||
|
||||
#### Token Mismatch
|
||||
- Ensure exact token from initiation response
|
||||
- No extra spaces or quotes in DNS value
|
||||
- Format: `sonr-verification=token` (no brackets)
|
||||
|
||||
#### Multiple TXT Records
|
||||
- Other TXT records don't interfere
|
||||
- System searches all TXT records for match
|
||||
- SPF, DMARC, etc. can coexist
|
||||
|
||||
## Success Result
|
||||
|
||||
Once verified:
|
||||
- **Permanent Binding**: Domain bound to your address
|
||||
- **Service Ready**: Can register services with this domain
|
||||
- **Trust Established**: Domain ownership proven
|
||||
- **No Re-verification**: One-time process per domain
|
||||
|
||||
<Warning>
|
||||
Domain ownership is permanent. Ensure you're verifying with the correct address.
|
||||
</Warning>
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful verification:
|
||||
```bash
|
||||
# Register a service
|
||||
snrd tx svc register-service my-app example.com \
|
||||
dwn:read,dwn:write --from alice
|
||||
```
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
openapi: post /svc.v1.Msg/InitiateDomainVerification
|
||||
title: Start Domain Verification
|
||||
description: Generate DNS TXT record token for domain ownership proof
|
||||
og:title: Domain Ownership Verification
|
||||
---
|
||||
|
||||
<Info>
|
||||
Domain verification ensures only legitimate domain owners can register services, establishing trust in the ecosystem.
|
||||
</Info>
|
||||
|
||||
## Verification Process
|
||||
|
||||
### Step 1: Initiate Verification
|
||||
Call this endpoint to generate a unique verification token:
|
||||
```bash
|
||||
snrd tx svc initiate-domain-verification example.com --from alice
|
||||
```
|
||||
|
||||
### Step 2: Add DNS TXT Record
|
||||
Add the provided token to your domain's DNS:
|
||||
```
|
||||
Type: TXT
|
||||
Name: @ (or subdomain)
|
||||
Value: sonr-verification=<token>
|
||||
TTL: 300
|
||||
```
|
||||
|
||||
### Step 3: Complete Verification
|
||||
After DNS propagation (5-30 minutes), verify:
|
||||
```bash
|
||||
snrd tx svc verify-domain example.com --from alice
|
||||
```
|
||||
|
||||
## DNS Provider Examples
|
||||
|
||||
### Cloudflare
|
||||
1. Go to DNS settings
|
||||
2. Add record → Type: TXT
|
||||
3. Name: @ → Value: sonr-verification=<token>
|
||||
4. Save and wait for propagation
|
||||
|
||||
### Route53 (AWS)
|
||||
1. Navigate to Hosted zones
|
||||
2. Create record → Type: TXT
|
||||
3. Record name: (leave blank for root)
|
||||
4. Value: "sonr-verification=<token>"
|
||||
|
||||
<Tip>
|
||||
Use DNS lookup tools to verify your TXT record is propagated before completing verification:
|
||||
```bash
|
||||
dig TXT example.com
|
||||
nslookup -type=TXT example.com
|
||||
```
|
||||
</Tip>
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Valid TLD**: Must be a registered top-level domain
|
||||
- **DNS Access**: Ability to manage DNS records
|
||||
- **Unique Ownership**: Each domain can only have one owner
|
||||
- **Time Limit**: Complete within 7 days of initiation
|
||||
|
||||
<Warning>
|
||||
Verification tokens expire after 7 days. If expired, you must initiate a new verification.
|
||||
</Warning>
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
openapi: post /svc.v1.Msg/RegisterService
|
||||
title: Register Decentralized Service
|
||||
description: Create a new service with domain binding and UCAN permissions
|
||||
og:title: Service Registration
|
||||
---
|
||||
|
||||
<Info>
|
||||
Services are the foundation of decentralized applications in Sonr, providing trusted interaction points through verified domains.
|
||||
</Info>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before registering a service:
|
||||
1. **Domain Verified**: Complete domain verification process
|
||||
2. **Service ID Ready**: Choose unique identifier (lowercase, alphanumeric, hyphens)
|
||||
3. **Permissions Defined**: Plan required UCAN capabilities
|
||||
4. **Registration Fee**: Have sufficient funds for fee
|
||||
|
||||
## Service Architecture
|
||||
|
||||
### Service Identity
|
||||
```
|
||||
Service ID: my-app
|
||||
Domain: example.com
|
||||
Full Identity: my-app@example.com
|
||||
```
|
||||
|
||||
### Permission Model
|
||||
Services request permissions users must grant:
|
||||
- **dwn:read**: Read user's DWN data
|
||||
- **dwn:write**: Write to user's DWN
|
||||
- **identity:read**: Access identity information
|
||||
- **vault:access**: Interact with user's vault
|
||||
- **credentials:verify**: Verify user credentials
|
||||
|
||||
## Common Permission Patterns
|
||||
|
||||
### Social Application
|
||||
```json
|
||||
{
|
||||
"requestedPermissions": [
|
||||
"dwn:read",
|
||||
"dwn:write",
|
||||
"identity:read"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Financial Service
|
||||
```json
|
||||
{
|
||||
"requestedPermissions": [
|
||||
"vault:access",
|
||||
"credentials:verify",
|
||||
"identity:read"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Data Analytics
|
||||
```json
|
||||
{
|
||||
"requestedPermissions": [
|
||||
"dwn:read",
|
||||
"identity:read"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Request only necessary permissions. Users are more likely to grant minimal permission sets.
|
||||
</Tip>
|
||||
|
||||
## UCAN Integration
|
||||
|
||||
### Root Capability
|
||||
Upon registration, service receives:
|
||||
- **Root Capability CID**: IPFS identifier for UCAN root
|
||||
- **Authorization Chain**: Build delegations from root
|
||||
- **Permission Scope**: Act within granted permissions
|
||||
|
||||
### Optional Pre-authorization
|
||||
```json
|
||||
{
|
||||
"ucanDelegationChain": "eyJhbGciOiJFZERTQSI..."
|
||||
}
|
||||
```
|
||||
Provide existing UCAN chain for pre-authorized capabilities.
|
||||
|
||||
## Service Lifecycle
|
||||
|
||||
### Registration
|
||||
1. Submit registration with domain and permissions
|
||||
2. System validates domain ownership
|
||||
3. Service ID uniqueness checked
|
||||
4. Root capability generated
|
||||
5. Service activated and discoverable
|
||||
|
||||
### User Interaction Flow
|
||||
1. User discovers service by domain/ID
|
||||
2. Service requests permissions
|
||||
3. User reviews and grants via wallet
|
||||
4. Service receives UCAN capability
|
||||
5. Service acts on user's behalf
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Service ID Selection
|
||||
- **Descriptive**: `chat-app`, `vault-manager`
|
||||
- **Consistent**: Match your brand/product
|
||||
- **Permanent**: Cannot be changed after registration
|
||||
|
||||
### Permission Planning
|
||||
- **Minimal Scope**: Only what's needed
|
||||
- **Clear Purpose**: Document why each permission
|
||||
- **Future Growth**: Design for expansion
|
||||
|
||||
<Warning>
|
||||
Service registration is permanent. Choose your service ID carefully as it cannot be changed.
|
||||
</Warning>
|
||||
|
||||
## Post-Registration
|
||||
|
||||
After successful registration:
|
||||
```bash
|
||||
# Query your service
|
||||
snrd query svc service my-app
|
||||
|
||||
# View services by domain
|
||||
snrd query svc services-by-domain example.com
|
||||
|
||||
# Check root capability
|
||||
ipfs cat <root_capability_cid>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Services become immediately discoverable after registration. Ensure your application is ready to handle user interactions.
|
||||
</Note>
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
openapi: post /svc.v1.Msg/UpdateParams
|
||||
title: Update SVC Module Parameters
|
||||
description: Configure service registration limits, domain verification, and UCAN settings
|
||||
og:title: SVC Module Governance
|
||||
---
|
||||
|
||||
<Warning>
|
||||
This operation requires **governance approval** and is typically executed through on-chain proposals.
|
||||
</Warning>
|
||||
|
||||
## Parameter Categories
|
||||
|
||||
### Service Limits
|
||||
- **maxServicesPerAccount**: Services per account limit (default: 100)
|
||||
- **maxDomainsPerService**: Domains per service limit (default: 5)
|
||||
- **maxEndpointsPerService**: Endpoints per service limit (default: 10)
|
||||
|
||||
### Domain Verification
|
||||
- **domainVerificationTimeout**: Time allowed for DNS verification (default: 7 days)
|
||||
- **requireDomainOwnershipProof**: Cryptographic proof requirement
|
||||
- **allowLocalhost**: Development mode with localhost support
|
||||
|
||||
### UCAN Configuration
|
||||
- **maxDelegationChainDepth**: Maximum delegation depth (default: 10)
|
||||
- **ucanMaxLifetime**: Maximum token lifetime (30 days)
|
||||
- **supportedSignatureAlgorithms**: EdDSA, ES256, RS256
|
||||
|
||||
### Fee Structure
|
||||
- **serviceRegistrationFee**: Fee for new service registration
|
||||
- **domainVerificationFee**: Fee for domain verification
|
||||
- **minServiceStake**: Minimum stake to maintain service
|
||||
|
||||
<Note>
|
||||
Changes affect all service operations network-wide. Plan parameter updates carefully.
|
||||
</Note>
|
||||
Reference in New Issue
Block a user