mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-02 17:31:39 +00:00
Prad Nukala
@@ -0,0 +1,11 @@
|
||||
---
|
||||
openapi: get /sonr/dex/v1/account/{did}/{connectionId}
|
||||
title: Query DEX Account Details
|
||||
description: Get information about a specific Interchain Account for DEX operations
|
||||
og:title: DEX Account Information
|
||||
---
|
||||
|
||||
<Note>
|
||||
Account addresses are only available after successful IBC acknowledgment.
|
||||
Pending accounts will have an empty address field.
|
||||
</Note>
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
openapi: get /sonr/dex/v1/params
|
||||
title: DEX Module Parameters
|
||||
description: Retrieve current configuration and operational limits for the DEX module
|
||||
og:title: Query DEX Module Configuration
|
||||
---
|
||||
|
||||
<Tip>
|
||||
Cache parameter responses client-side as they change infrequently.
|
||||
Refresh periodically or after governance proposals.
|
||||
</Tip>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: get /sonr/dex/v1/pool/{connectionId}/{poolId}
|
||||
title: Query Liquidity Pool Details
|
||||
description: Get comprehensive information about DEX liquidity pools
|
||||
og:title: Liquidity Pool Information
|
||||
---
|
||||
|
||||
<Info>
|
||||
Pool information is essential for calculating optimal liquidity provision
|
||||
amounts and understanding potential returns.
|
||||
</Info>
|
||||
|
||||
<Warning>
|
||||
Pool compositions can change rapidly. Always fetch current data
|
||||
before providing liquidity.
|
||||
</Warning>
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
openapi: get /sonr/dex/v1/balance/{did}/{connectionId}
|
||||
title: Query Remote Chain Balances
|
||||
description: Check token balances in your ICA account on remote chains
|
||||
og:title: Cross-Chain Balance Query
|
||||
---
|
||||
|
||||
<Tip>
|
||||
Use the optional `denom` parameter to check specific token balances
|
||||
without fetching the entire balance list.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Balances are fetched in real-time from the remote chain via IBC queries.
|
||||
</Note>
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
openapi: get /sonr/dex/v1/history/{did}
|
||||
title: Query Trading History
|
||||
description: Access complete cross-chain trading history for a DID
|
||||
og:title: DEX Transaction History
|
||||
---
|
||||
|
||||
<Info>
|
||||
Transaction history is stored permanently on the Sonr chain,
|
||||
providing a complete audit trail of all DEX operations.
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
Export historical data regularly for tax reporting and portfolio analysis.
|
||||
Use filters to focus on specific time periods or operation types.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Large histories may require multiple paginated requests.
|
||||
Use the pagination key for efficient retrieval.
|
||||
</Note>
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
openapi: get /sonr/dex/v1/accounts/{did}
|
||||
title: List User's DEX Accounts
|
||||
description: Retrieve all Interchain Accounts associated with a DID
|
||||
og:title: List Cross-Chain Trading Accounts
|
||||
---
|
||||
|
||||
<Info>
|
||||
Each DID can have multiple accounts across different chains,
|
||||
subject to the `maxAccountsPerDid` parameter limit.
|
||||
</Info>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: get /sonr/dex/v1/orders/{did}/{connectionId}
|
||||
title: List User Orders
|
||||
description: Retrieve limit orders for a DID on specific DEX chains
|
||||
og:title: Query Cross-Chain Orders
|
||||
---
|
||||
|
||||
<Tip>
|
||||
Use the `status` filter to query only active orders for portfolio management
|
||||
or historical orders for tax reporting.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Order history is retained for a limited time on most DEXs.
|
||||
Archive important order data locally.
|
||||
</Note>
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
openapi: get /did/v1/credentials/did/{did}
|
||||
title: Get All DID Credentials
|
||||
description: Retrieve complete credential portfolio for a decentralized identity
|
||||
og:title: DID Credential Portfolio
|
||||
---
|
||||
|
||||
<Info>
|
||||
This endpoint provides a complete view of all credentials associated
|
||||
with a DID, useful for identity wallets and credential management.
|
||||
</Info>
|
||||
|
||||
<Note>
|
||||
WebAuthn credentials are device-specific and cannot be transferred
|
||||
between devices, unlike verifiable credentials.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Use filter parameters to retrieve only the credential types your
|
||||
application needs, reducing response size and processing time.
|
||||
</Tip>
|
||||
|
||||
<Warning>
|
||||
Sensitive credential data may be encrypted when stored in vaults.
|
||||
Ensure proper decryption keys are available for encrypted credentials.
|
||||
</Warning>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: get /did/v1/documents/controller/{controller}
|
||||
title: Query DIDs by Controller
|
||||
description: Find all decentralized identities controlled by an address
|
||||
og:title: Controller DID Lookup
|
||||
---
|
||||
|
||||
<Info>
|
||||
A single address can control multiple DIDs, useful for managing
|
||||
different identity contexts (personal, professional, etc.).
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
Use this endpoint to build identity management interfaces that
|
||||
show all DIDs a user controls from a single account.
|
||||
</Tip>
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
openapi: get /did/v1/document/{did}
|
||||
title: Get DID Document
|
||||
description: Retrieve DID document with implementation details
|
||||
og:title: DID Document Query
|
||||
---
|
||||
|
||||
<Tip>
|
||||
Use ResolveDID for W3C-compliant resolution. Use this endpoint
|
||||
when you need Sonr-specific implementation details.
|
||||
</Tip>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: get /did/v1/params
|
||||
title: DID Module Parameters
|
||||
description: Retrieve configuration settings and limits for the DID system
|
||||
og:title: Query DID Module Configuration
|
||||
---
|
||||
|
||||
<Tip>
|
||||
Check module parameters before creating DIDs to understand current
|
||||
limits and supported features.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Parameters can be updated through governance proposals.
|
||||
Monitor changes that might affect your application.
|
||||
</Note>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: get /did/v1/service/{did}/{serviceId}
|
||||
title: Get Service Endpoint
|
||||
description: Retrieve interaction endpoints and service definitions
|
||||
og:title: Query DID Service
|
||||
---
|
||||
|
||||
<Info>
|
||||
Service endpoints tell others how to interact with the DID subject
|
||||
for specific purposes like messaging or data exchange.
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
Check service types to understand the interaction protocol before
|
||||
attempting to connect to service endpoints.
|
||||
</Tip>
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
openapi: get /did/v1/credential/{credentialId}
|
||||
title: Get Verifiable Credential
|
||||
description: Retrieve W3C verifiable credentials with cryptographic proofs
|
||||
og:title: Query Digital Credential
|
||||
---
|
||||
|
||||
<Info>
|
||||
Verifiable credentials are cryptographically signed claims that can
|
||||
be independently verified without contacting the issuer.
|
||||
</Info>
|
||||
|
||||
<Warning>
|
||||
Always check the `revoked` field and expiration date before
|
||||
accepting a credential as valid.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Verify the issuer's DID to ensure the credential comes from a
|
||||
trusted authority in your trust framework.
|
||||
</Tip>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: get /did/v1/verification-method/{did}/{methodId}
|
||||
title: Get Verification Method
|
||||
description: Retrieve specific cryptographic keys or authentication methods
|
||||
og:title: Query DID Verification Method
|
||||
---
|
||||
|
||||
<Note>
|
||||
Verification methods contain public keys only. Private keys are
|
||||
never stored on-chain and must be managed securely off-chain.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Use this endpoint to retrieve specific keys for signature verification
|
||||
or encryption operations.
|
||||
</Tip>
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
openapi: get /did/v1/documents
|
||||
title: List All DID Documents
|
||||
description: Browse all decentralized identifiers in the system
|
||||
og:title: DID Directory
|
||||
---
|
||||
|
||||
<Note>
|
||||
This endpoint returns all DIDs including deactivated ones.
|
||||
Filter by the `deactivated` field for active DIDs only.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
For large systems, use pagination parameters to retrieve documents
|
||||
in manageable chunks. Start with a reasonable limit like 50-100.
|
||||
</Tip>
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
openapi: get /did/v1/credentials
|
||||
title: List Verifiable Credentials
|
||||
description: Browse and filter W3C verifiable credentials
|
||||
og:title: Credential Registry
|
||||
---
|
||||
|
||||
<Note>
|
||||
By default, revoked credentials are excluded. Set `includeRevoked=true`
|
||||
to include them in results.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Use issuer filtering to find all credentials from trusted authorities
|
||||
in your ecosystem.
|
||||
</Tip>
|
||||
|
||||
<Info>
|
||||
Large credential sets should use pagination to avoid timeout issues.
|
||||
Start with a reasonable limit like 50-100 credentials per page.
|
||||
</Info>
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
openapi: get /did/v1/resolve/{did}
|
||||
title: Resolve W3C DID Document
|
||||
description: Retrieve complete DID document with verification methods and services
|
||||
og:title: DID Resolution
|
||||
---
|
||||
|
||||
<Info>
|
||||
DID resolution is the primary way to discover how to interact with
|
||||
a decentralized identity, including available keys and services.
|
||||
</Info>
|
||||
|
||||
<Warning>
|
||||
Deactivated DIDs cannot be resolved. The query will return an error
|
||||
indicating the DID has been permanently disabled.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Cache resolved DID documents client-side with appropriate TTL based
|
||||
on your security requirements and update frequency needs.
|
||||
</Tip>
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
openapi: get /dwn/v1/encryption/status
|
||||
title: Query Encryption Status
|
||||
description: Monitor the health and state of the consensus encryption system
|
||||
og:title: DWN Encryption System Status
|
||||
---
|
||||
|
||||
<Info>
|
||||
The encryption system uses validator consensus to generate keys that no single party controls.
|
||||
</Info>
|
||||
|
||||
## System Components
|
||||
|
||||
### Key Management
|
||||
- **currentKeyVersion**: Active encryption key version
|
||||
- **lastRotation**: Timestamp of last rotation
|
||||
- **nextRotation**: Scheduled rotation time
|
||||
|
||||
### Validator Participation
|
||||
- **validatorSet**: Active validator addresses
|
||||
- **singleNodeMode**: Development mode flag
|
||||
- **minValidatorsForKeyGen**: Required threshold
|
||||
|
||||
### System Metrics
|
||||
- **totalEncryptedRecords**: Global encrypted record count
|
||||
|
||||
## Health Monitoring
|
||||
|
||||
<Tip>
|
||||
Set up alerts for upcoming key rotations to ensure smooth operations.
|
||||
</Tip>
|
||||
|
||||
### Health Checks
|
||||
|
||||
```javascript
|
||||
// Check rotation schedule
|
||||
const rotationDue = nextRotation < Date.now();
|
||||
|
||||
// Verify validator participation
|
||||
const hasQuorum = validatorSet.length >= minValidatorsForKeyGen;
|
||||
|
||||
// Monitor growth
|
||||
const recordGrowthRate = totalEncryptedRecords / daysSinceLaunch;
|
||||
```
|
||||
|
||||
## Key Rotation Schedule
|
||||
|
||||
### Automatic Rotation
|
||||
- Triggered by `keyRotationDays` parameter
|
||||
- Requires validator consensus
|
||||
- Zero-downtime process
|
||||
|
||||
### Manual Rotation
|
||||
- Governance proposals
|
||||
- Security incidents
|
||||
- Validator changes
|
||||
|
||||
<Warning>
|
||||
Key rotation requires sufficient validator participation. Monitor validator set health.
|
||||
</Warning>
|
||||
|
||||
## Development vs Production
|
||||
|
||||
### Production Mode
|
||||
- Full validator consensus
|
||||
- Distributed key generation
|
||||
- No single point of failure
|
||||
|
||||
### Single-Node Mode
|
||||
- Local key generation
|
||||
- Simplified consensus
|
||||
- For development only
|
||||
|
||||
## Monitoring Dashboard
|
||||
|
||||
<Note>
|
||||
Create monitoring dashboards using these metrics for operational visibility.
|
||||
</Note>
|
||||
|
||||
### Key Metrics
|
||||
```bash
|
||||
# Query status
|
||||
STATUS=$(snrd query dwn encryption-status -o json)
|
||||
|
||||
# Extract metrics
|
||||
echo "Key Version: $(echo $STATUS | jq .currentKeyVersion)"
|
||||
echo "Validators: $(echo $STATUS | jq '.validatorSet | length')"
|
||||
echo "Records: $(echo $STATUS | jq .totalEncryptedRecords)"
|
||||
echo "Next Rotation: $(echo $STATUS | jq .nextRotation)"
|
||||
```
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
openapi: get /dwn/v1/ipfs/{cid}
|
||||
title: Retrieve IPFS Content
|
||||
description: Fetch distributed content using its Content Identifier
|
||||
og:title: IPFS Content Retrieval
|
||||
---
|
||||
|
||||
<Info>
|
||||
Content Identifiers (CIDs) are cryptographic hashes that uniquely identify content in IPFS.
|
||||
</Info>
|
||||
|
||||
## CID Resolution
|
||||
|
||||
### Resolution Process
|
||||
1. Query local IPFS node cache
|
||||
2. Search connected peers
|
||||
3. Fetch from distributed network
|
||||
4. Return raw content data
|
||||
|
||||
### CID Formats
|
||||
- **CIDv0**: Legacy format (starts with 'Qm')
|
||||
- **CIDv1**: Modern format (starts with 'bafy')
|
||||
|
||||
Example CIDs:
|
||||
```
|
||||
CIDv0: QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
|
||||
CIDv1: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
<Tip>
|
||||
Pin frequently accessed content to your local IPFS node for faster retrieval.
|
||||
</Tip>
|
||||
|
||||
### Caching Strategy
|
||||
- Hot data: Keep pinned locally
|
||||
- Warm data: Cache with TTL
|
||||
- Cold data: Fetch on demand
|
||||
|
||||
<Warning>
|
||||
Large files may take time to retrieve if not cached locally or on nearby peers.
|
||||
</Warning>
|
||||
|
||||
## Error Handling
|
||||
|
||||
Common errors:
|
||||
- **404**: CID not found in network
|
||||
- **408**: Timeout fetching content
|
||||
- **507**: Local storage full
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
openapi: get /dwn/v1/ipfs
|
||||
title: Query IPFS Node Status
|
||||
description: Check connectivity and status of the distributed storage layer
|
||||
og:title: IPFS Node Information
|
||||
---
|
||||
|
||||
<Info>
|
||||
IPFS provides distributed storage for large objects, vault exports, and encrypted backups.
|
||||
</Info>
|
||||
|
||||
## IPFS Integration
|
||||
|
||||
### Node Information
|
||||
- **Peer ID**: Unique identifier for the IPFS node
|
||||
- **Peer Name**: Human-readable node name
|
||||
- **Peer Type**: Node configuration (gateway, full, light)
|
||||
- **Version**: IPFS daemon version
|
||||
|
||||
### Use Cases
|
||||
- **Large Files**: Store files exceeding `maxRecordSize`
|
||||
- **Vault Exports**: Backup encrypted vault data
|
||||
- **Protocol Assets**: Store protocol-related media
|
||||
- **Public Content**: Distribute public records efficiently
|
||||
|
||||
<Tip>
|
||||
Store only metadata and CIDs on-chain for gas efficiency, with actual data in IPFS.
|
||||
</Tip>
|
||||
|
||||
## Common Patterns
|
||||
|
||||
```bash
|
||||
# Upload to IPFS first
|
||||
ipfs add large_file.pdf
|
||||
# Store CID in DWN record
|
||||
snrd tx dwn records-write --data-cid <cid>
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ensure IPFS node is running and accessible before storing large objects.
|
||||
</Warning>
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
openapi: get /dwn/v1/params
|
||||
title: Query DWN Module Parameters
|
||||
description: Get current configuration settings for the DWN module
|
||||
og:title: DWN Module Configuration
|
||||
---
|
||||
|
||||
<Info>
|
||||
Module parameters control the global behavior of all DWN operations on the network.
|
||||
</Info>
|
||||
|
||||
## Parameter Categories
|
||||
|
||||
### Storage Configuration
|
||||
- **maxRecordSize**: Maximum bytes per record (default: 10MB)
|
||||
- **maxProtocolsPerDwn**: Protocol limit per DWN
|
||||
- **maxPermissionsPerDwn**: Permission limit per DWN
|
||||
|
||||
### Vault Security
|
||||
- **vaultCreationEnabled**: Whether new vaults can be created
|
||||
- **minVaultRefreshInterval**: Blocks between key refreshes
|
||||
- **keyRotationDays**: Automatic rotation schedule
|
||||
- **minValidatorsForKeyGen**: Validator consensus threshold
|
||||
|
||||
### Encryption Policies
|
||||
- **encryptionEnabled**: Global encryption enforcement
|
||||
- **encryptedProtocols**: Protocols requiring encryption
|
||||
- **encryptedSchemas**: Schemas requiring encryption
|
||||
- **singleNodeFallback**: Development mode setting
|
||||
|
||||
<Tip>
|
||||
Query parameters before designing your application to ensure compliance with network limits.
|
||||
</Tip>
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
openapi: get /dwn/v1/permissions/{target}
|
||||
title: Query DWN Permissions
|
||||
description: Audit and manage access control for your data
|
||||
og:title: DWN Permission Management
|
||||
---
|
||||
|
||||
<Info>
|
||||
Regular permission audits are essential for maintaining data security and compliance.
|
||||
</Info>
|
||||
|
||||
## Permission Queries
|
||||
|
||||
### Filter Options
|
||||
- **grantor**: Who gave the permission
|
||||
- **grantee**: Who received the permission
|
||||
- **interfaceName**: Scope to interface (Records, Protocols)
|
||||
- **method**: Specific operation (Write, Query, Delete)
|
||||
- **includeRevoked**: Show revoked permissions
|
||||
|
||||
### Common Queries
|
||||
|
||||
```bash
|
||||
# All active permissions I've granted
|
||||
?grantor=did:sonr:alice&includeRevoked=false
|
||||
|
||||
# Permissions given to specific user
|
||||
?grantee=did:sonr:bob
|
||||
|
||||
# All write permissions
|
||||
?method=Write
|
||||
|
||||
# Protocol-specific permissions
|
||||
?interfaceName=Records&method=Write
|
||||
```
|
||||
|
||||
## Permission Auditing
|
||||
|
||||
<Tip>
|
||||
Schedule regular audits to review and revoke unnecessary permissions.
|
||||
</Tip>
|
||||
|
||||
### Audit Checklist
|
||||
1. **Review Active Permissions**
|
||||
```bash
|
||||
?includeRevoked=false&pagination.limit=100
|
||||
```
|
||||
|
||||
2. **Check Expired Permissions**
|
||||
- Filter by `expiresAt` < current time
|
||||
- Revoke if still active
|
||||
|
||||
3. **Verify Grantee Activity**
|
||||
- Check last access times
|
||||
- Revoke inactive permissions
|
||||
|
||||
4. **Protocol Compliance**
|
||||
- Ensure permissions align with protocols
|
||||
- Update for protocol changes
|
||||
|
||||
## Permission States
|
||||
|
||||
### Active Permission
|
||||
- Not revoked
|
||||
- Not expired
|
||||
- Valid conditions met
|
||||
|
||||
### Inactive Permission
|
||||
- Revoked by grantor
|
||||
- Past expiration time
|
||||
- Conditions not met
|
||||
|
||||
<Warning>
|
||||
Permissions with no expiration should be reviewed more frequently.
|
||||
</Warning>
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Principle of Least Privilege
|
||||
- Grant minimum necessary access
|
||||
- Use specific scopes
|
||||
- Set expiration times
|
||||
|
||||
### Regular Reviews
|
||||
```bash
|
||||
# Weekly: Check high-privilege permissions
|
||||
?interfaceName=Permissions
|
||||
|
||||
# Monthly: Full audit
|
||||
?includeRevoked=true&pagination.countTotal=true
|
||||
|
||||
# Quarterly: Protocol permission alignment
|
||||
?interfaceName=Protocols
|
||||
```
|
||||
|
||||
<Note>
|
||||
Use `pagination.countTotal=true` to track total permission growth over time.
|
||||
</Note>
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
openapi: get /dwn/v1/protocols/{target}
|
||||
title: Query DWN Protocols
|
||||
description: Discover configured protocols and their data models
|
||||
og:title: DWN Protocol Discovery
|
||||
---
|
||||
|
||||
<Info>
|
||||
Protocols enable interoperable data structures across applications and users.
|
||||
</Info>
|
||||
|
||||
## Protocol Discovery
|
||||
|
||||
### Finding Protocols
|
||||
- **User Protocols**: Query specific user's DWN
|
||||
- **Published Protocols**: Filter by `publishedOnly=true`
|
||||
- **Private Protocols**: Require permissions to view
|
||||
|
||||
### Protocol Registry
|
||||
Common protocol namespaces:
|
||||
- `https://protocols.sonr.io/social/*` - Social media
|
||||
- `https://protocols.sonr.io/health/*` - Healthcare
|
||||
- `https://protocols.sonr.io/iot/*` - IoT devices
|
||||
- `https://protocols.sonr.io/finance/*` - Financial
|
||||
|
||||
## Protocol Adoption
|
||||
|
||||
<Tip>
|
||||
Browse published protocols to find existing standards before creating custom ones.
|
||||
</Tip>
|
||||
|
||||
### Adopting a Protocol
|
||||
1. Query published protocols
|
||||
2. Review protocol definition
|
||||
3. Configure in your DWN
|
||||
4. Start creating compliant records
|
||||
|
||||
```bash
|
||||
# Find social protocols
|
||||
snrd query dwn protocols did:sonr:community --published-only
|
||||
|
||||
# Adopt a protocol
|
||||
snrd tx dwn protocols-configure --from <discovered_protocol>
|
||||
```
|
||||
|
||||
## Protocol Versioning
|
||||
|
||||
### Version Strategies
|
||||
- **URL Versioning**: `/v1`, `/v2` in URI
|
||||
- **Semantic Versioning**: `1.0.0`, `2.0.0`
|
||||
- **Date Versioning**: `/2024`, `/2025`
|
||||
|
||||
<Warning>
|
||||
Breaking protocol changes should use new URIs to maintain backward compatibility.
|
||||
</Warning>
|
||||
|
||||
## Pagination
|
||||
|
||||
<Note>
|
||||
Large DWNs may have many protocols. Use pagination for efficient retrieval.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
?pagination.limit=10&pagination.offset=0
|
||||
```
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
openapi: get /dwn/v1/records/{target}
|
||||
title: Query DWN Records
|
||||
description: Search and retrieve data records with advanced filtering
|
||||
og:title: DWN Record Query
|
||||
---
|
||||
|
||||
<Info>
|
||||
This endpoint provides powerful querying capabilities for exploring DWN data with multiple filter options.
|
||||
</Info>
|
||||
|
||||
## Query Filters
|
||||
|
||||
### Protocol Filter
|
||||
Query records conforming to specific protocols:
|
||||
```bash
|
||||
?protocol=https://protocols.sonr.io/social/v1
|
||||
```
|
||||
|
||||
### Schema Filter
|
||||
Find records matching schema types:
|
||||
```bash
|
||||
?schema=https://schema.org/BlogPosting
|
||||
```
|
||||
|
||||
### Hierarchical Queries
|
||||
Get child records of a parent:
|
||||
```bash
|
||||
?parentId=record_parent_123
|
||||
```
|
||||
|
||||
### Visibility Filter
|
||||
Show only public records:
|
||||
```bash
|
||||
?publishedOnly=true
|
||||
```
|
||||
|
||||
## Pagination Strategy
|
||||
|
||||
<Tip>
|
||||
Use cursor-based pagination with `pagination.key` for optimal performance on large datasets.
|
||||
</Tip>
|
||||
|
||||
### Efficient Pagination
|
||||
```bash
|
||||
# First page
|
||||
?pagination.limit=20
|
||||
|
||||
# Next page using cursor
|
||||
?pagination.key=<next_key_from_response>
|
||||
```
|
||||
|
||||
### Offset Pagination
|
||||
```bash
|
||||
# Less efficient but simpler
|
||||
?pagination.offset=20&pagination.limit=20
|
||||
```
|
||||
|
||||
## Common Query Patterns
|
||||
|
||||
### Social Media Posts
|
||||
```bash
|
||||
?protocol=https://protocols.sonr.io/social/v1&schema=https://schema.org/SocialMediaPosting&publishedOnly=true
|
||||
```
|
||||
|
||||
### Medical Records
|
||||
```bash
|
||||
?protocol=https://protocols.sonr.io/health/v1&schema=https://schema.org/MedicalRecord
|
||||
```
|
||||
|
||||
### File System Structure
|
||||
```bash
|
||||
?parentId=folder_root&pagination.limit=100
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Encrypted records will return encrypted data unless you have decryption permissions.
|
||||
</Warning>
|
||||
|
||||
## Response Handling
|
||||
|
||||
### Record States
|
||||
- **Published**: Publicly accessible
|
||||
- **Private**: Requires permissions
|
||||
- **Encrypted**: Needs decryption keys
|
||||
- **Deleted**: Tombstone markers
|
||||
|
||||
<Note>
|
||||
Use `pagination.countTotal=true` sparingly as it impacts query performance.
|
||||
</Note>
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
openapi: get /dwn/v1/protocols/{target}/{protocolUri}
|
||||
title: Query Specific Protocol
|
||||
description: Get detailed protocol definition and configuration
|
||||
og:title: DWN Protocol Details
|
||||
---
|
||||
|
||||
<Info>
|
||||
Protocol definitions specify the complete data model and access rules for structured interactions.
|
||||
</Info>
|
||||
|
||||
## Protocol Structure
|
||||
|
||||
### Definition Components
|
||||
```json
|
||||
{
|
||||
"types": {
|
||||
"post": {
|
||||
"schema": "https://schema.org/BlogPosting",
|
||||
"dataFormats": ["application/json"]
|
||||
},
|
||||
"comment": {
|
||||
"schema": "https://schema.org/Comment",
|
||||
"dataFormats": ["application/json"]
|
||||
}
|
||||
},
|
||||
"structure": {
|
||||
"post": {
|
||||
"comment": {}
|
||||
}
|
||||
},
|
||||
"permissions": {
|
||||
"post": ["author", "admin"],
|
||||
"comment": ["anyone"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Key Elements
|
||||
- **Types**: Record type definitions with schemas
|
||||
- **Structure**: Hierarchical relationships
|
||||
- **Permissions**: Access control rules
|
||||
- **Actions**: Allowed operations per type
|
||||
|
||||
## Protocol Analysis
|
||||
|
||||
<Tip>
|
||||
Examine existing protocols to understand best practices before creating your own.
|
||||
</Tip>
|
||||
|
||||
### Understanding a Protocol
|
||||
1. **Review Types**: What data can be stored?
|
||||
2. **Check Structure**: How is data organized?
|
||||
3. **Verify Permissions**: Who can access what?
|
||||
4. **Test Compatibility**: Does it meet your needs?
|
||||
|
||||
## Common Protocol Patterns
|
||||
|
||||
### Social Media Protocol
|
||||
- Posts, comments, reactions hierarchy
|
||||
- Public read, authenticated write
|
||||
- Media attachment support
|
||||
|
||||
### Healthcare Protocol
|
||||
- Patient records, visits, prescriptions
|
||||
- Strict access control
|
||||
- Mandatory encryption
|
||||
|
||||
### IoT Protocol
|
||||
- Device registry, telemetry, commands
|
||||
- Time-series data structure
|
||||
- Rate-limited writes
|
||||
|
||||
<Warning>
|
||||
Protocol URIs must be URL-encoded when used as path parameters.
|
||||
</Warning>
|
||||
|
||||
## Integration Example
|
||||
|
||||
```bash
|
||||
# Get protocol definition
|
||||
PROTOCOL_URI="https://protocols.sonr.io/social/v1"
|
||||
snrd query dwn protocol did:sonr:alice "$PROTOCOL_URI"
|
||||
|
||||
# Parse and adopt
|
||||
snrd tx dwn protocols-configure --copy-from did:sonr:alice --protocol "$PROTOCOL_URI"
|
||||
```
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
openapi: get /dwn/v1/records/{target}/{recordId}
|
||||
title: Query Specific Record
|
||||
description: Retrieve a single record by its unique identifier
|
||||
og:title: DWN Record Retrieval
|
||||
---
|
||||
|
||||
<Info>
|
||||
Direct record access provides the most efficient way to retrieve known records.
|
||||
</Info>
|
||||
|
||||
## Record Components
|
||||
|
||||
### Core Fields
|
||||
- **recordId**: Unique identifier (usually a CID)
|
||||
- **data**: Actual payload (base64 encoded)
|
||||
- **descriptor**: DWN message metadata
|
||||
- **authorization**: Access proof
|
||||
|
||||
### Metadata Fields
|
||||
- **protocol**: Conforming protocol URI
|
||||
- **schema**: Data validation schema
|
||||
- **parentId**: Hierarchical relationship
|
||||
- **published**: Visibility status
|
||||
|
||||
### Encryption Details
|
||||
- **isEncrypted**: Encryption status
|
||||
- **encryptionMetadata**: Consensus encryption info
|
||||
- **keyVersion**: Key rotation tracking
|
||||
|
||||
## Access Patterns
|
||||
|
||||
<Tip>
|
||||
Cache frequently accessed record IDs to avoid repeated queries.
|
||||
</Tip>
|
||||
|
||||
### Public Records
|
||||
```bash
|
||||
# No authorization needed
|
||||
snrd query dwn record did:sonr:alice record_public_123
|
||||
```
|
||||
|
||||
### Private Records
|
||||
```bash
|
||||
# Requires permission or ownership
|
||||
snrd query dwn record did:sonr:alice record_private_456
|
||||
```
|
||||
|
||||
### Encrypted Records
|
||||
```bash
|
||||
# Auto-decrypts if authorized
|
||||
snrd query dwn encrypted-record did:sonr:alice record_encrypted_789
|
||||
```
|
||||
|
||||
<Warning>
|
||||
404 errors may indicate either non-existence or lack of permissions.
|
||||
</Warning>
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
openapi: get /dwn/v1/vaults/{vaultId}
|
||||
title: Query Vault Details
|
||||
description: Get comprehensive information about a secure vault instance
|
||||
og:title: DWN Vault Information
|
||||
---
|
||||
|
||||
<Info>
|
||||
Vaults provide hardware-backed secure key management through WebAssembly enclaves.
|
||||
</Info>
|
||||
|
||||
## Vault Components
|
||||
|
||||
### Core Information
|
||||
- **vaultId**: Unique identifier
|
||||
- **owner**: DID or address of owner
|
||||
- **publicKey**: Public key for verification
|
||||
- **createdAt**: Creation timestamp
|
||||
- **lastRefreshed**: Last key rotation
|
||||
|
||||
### Enclave Data
|
||||
- **enclaveId**: WASM enclave identifier
|
||||
- **version**: Enclave version number
|
||||
- **privateData**: Encrypted key material
|
||||
|
||||
### Security Metadata
|
||||
- **encryptionMetadata**: Consensus encryption details
|
||||
- **keyVersion**: Current key version
|
||||
- **validatorSet**: Participating validators
|
||||
|
||||
## Vault Health Check
|
||||
|
||||
<Tip>
|
||||
Monitor vault refresh intervals to ensure keys are rotated on schedule.
|
||||
</Tip>
|
||||
|
||||
### Health Indicators
|
||||
```javascript
|
||||
// Check if refresh is due
|
||||
const refreshDue =
|
||||
(currentBlock - lastRefreshed) > minVaultRefreshInterval;
|
||||
|
||||
// Check key age
|
||||
const keyAge =
|
||||
(currentTime - lastRefreshed) / (24 * 60 * 60);
|
||||
const needsRotation = keyAge > keyRotationDays;
|
||||
```
|
||||
|
||||
## Security Features
|
||||
|
||||
### WebAssembly Isolation
|
||||
- Sandboxed execution environment
|
||||
- No direct memory access
|
||||
- Deterministic operations
|
||||
|
||||
### Hardware Security
|
||||
- TPM integration when available
|
||||
- Secure enclave support
|
||||
- Hardware key storage
|
||||
|
||||
<Warning>
|
||||
Never expose or log vault private data. It's encrypted for a reason.
|
||||
</Warning>
|
||||
|
||||
## Vault Operations
|
||||
|
||||
### Key Rotation Status
|
||||
```bash
|
||||
# Check rotation schedule
|
||||
snrd query dwn vault vault_alice_123
|
||||
|
||||
# Compare with module params
|
||||
snrd query dwn params
|
||||
```
|
||||
|
||||
### Export/Import
|
||||
```bash
|
||||
# Export vault to IPFS (encrypted)
|
||||
snrd tx dwn vault-export vault_alice_123
|
||||
|
||||
# Import from IPFS backup
|
||||
snrd tx dwn vault-import <ipfs_cid>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Vault queries return public metadata only. Private keys remain encrypted in the enclave.
|
||||
</Note>
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
openapi: get /dwn/v1/vaults
|
||||
title: Query Vaults
|
||||
description: List secure vaults with optional owner filtering
|
||||
og:title: DWN Vault Listing
|
||||
---
|
||||
|
||||
<Info>
|
||||
Users typically have one primary vault, but may have multiple for different security contexts.
|
||||
</Info>
|
||||
|
||||
## Query Patterns
|
||||
|
||||
### List My Vaults
|
||||
```bash
|
||||
?owner=did:sonr:alice
|
||||
```
|
||||
|
||||
### List All Vaults (Governance)
|
||||
```bash
|
||||
# No filter - requires admin permissions
|
||||
?pagination.limit=100
|
||||
```
|
||||
|
||||
## Vault Management
|
||||
|
||||
<Tip>
|
||||
Create separate vaults for different security levels (personal, business, high-security).
|
||||
</Tip>
|
||||
|
||||
### Vault Strategy
|
||||
|
||||
#### Primary Vault
|
||||
- Daily operations
|
||||
- Standard security
|
||||
- Regular key rotation
|
||||
|
||||
#### High-Security Vault
|
||||
- Sensitive operations
|
||||
- Enhanced encryption
|
||||
- Frequent rotation
|
||||
|
||||
#### Archive Vault
|
||||
- Long-term storage
|
||||
- Infrequent access
|
||||
- Extended rotation
|
||||
|
||||
## Vault Creation
|
||||
|
||||
### Prerequisites
|
||||
- `vaultCreationEnabled` must be true
|
||||
- Sufficient gas for creation
|
||||
- Valid DID or account
|
||||
|
||||
### Creation Process
|
||||
```bash
|
||||
# Create new vault
|
||||
snrd tx dwn vault-create --from alice
|
||||
|
||||
# Verify creation
|
||||
snrd query dwn vaults --owner did:sonr:alice
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Vault creation may be disabled by governance. Check module parameters first.
|
||||
</Warning>
|
||||
|
||||
## Pagination
|
||||
|
||||
### Efficient Queries
|
||||
```bash
|
||||
# First page
|
||||
?owner=did:sonr:alice&pagination.limit=10
|
||||
|
||||
# Next page
|
||||
?owner=did:sonr:alice&pagination.key=<next_key>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Most users have 1-3 vaults. Pagination is mainly for system-wide queries.
|
||||
</Note>
|
||||
@@ -0,0 +1,134 @@
|
||||
---
|
||||
openapi: get /dwn/v1/encryption/vrf-contributions
|
||||
title: Query VRF Contributions
|
||||
description: Monitor validator participation in consensus key generation
|
||||
og:title: DWN VRF Consensus Tracking
|
||||
---
|
||||
|
||||
<Info>
|
||||
VRF contributions ensure distributed key generation where no single validator knows the complete key.
|
||||
</Info>
|
||||
|
||||
## VRF Consensus Process
|
||||
|
||||
### How It Works
|
||||
1. **Round Initiation**: New consensus round begins
|
||||
2. **VRF Generation**: Each validator generates random value
|
||||
3. **Proof Creation**: Cryptographic proof of randomness
|
||||
4. **Contribution Submit**: Broadcast to network
|
||||
5. **Threshold Check**: Wait for minimum contributions
|
||||
6. **Key Derivation**: Combine for consensus key
|
||||
|
||||
### Contribution Components
|
||||
- **validatorAddress**: Contributing validator
|
||||
- **randomness**: VRF output (32 bytes)
|
||||
- **proof**: VRF proof for verification
|
||||
- **blockHeight**: Submission height
|
||||
- **timestamp**: Contribution time
|
||||
|
||||
## Query Filters
|
||||
|
||||
<Tip>
|
||||
Filter by validator to track specific node participation.
|
||||
</Tip>
|
||||
|
||||
### By Validator
|
||||
```bash
|
||||
?validatorAddress=sonrvaloper1abc...
|
||||
```
|
||||
|
||||
### By Block Height
|
||||
```bash
|
||||
?blockHeight=1000000
|
||||
```
|
||||
|
||||
### Current Round
|
||||
```bash
|
||||
# No filters shows current round
|
||||
/dwn/v1/encryption/vrf-contributions
|
||||
```
|
||||
|
||||
## Consensus Round Status
|
||||
|
||||
### Round States
|
||||
- **waiting_for_contributions**: Collecting VRF inputs
|
||||
- **complete**: Threshold reached, key generated
|
||||
- **expired**: Timeout without consensus
|
||||
- **single_node_mode**: Development mode
|
||||
|
||||
### Round Metadata
|
||||
- **roundNumber**: Sequential round identifier
|
||||
- **keyVersion**: Target key version
|
||||
- **requiredContributions**: Threshold count
|
||||
- **receivedContributions**: Current count
|
||||
- **expiryHeight**: Timeout block height
|
||||
|
||||
<Warning>
|
||||
Rounds expire if threshold isn't met. Monitor contribution progress.
|
||||
</Warning>
|
||||
|
||||
## Validator Monitoring
|
||||
|
||||
### Participation Tracking
|
||||
```javascript
|
||||
// Calculate participation rate
|
||||
const participationRate =
|
||||
receivedContributions / requiredContributions * 100;
|
||||
|
||||
// Check specific validator
|
||||
const hasContributed = contributions
|
||||
.some(c => c.validatorAddress === myValidator);
|
||||
|
||||
// Time to expiry
|
||||
const blocksRemaining = expiryHeight - currentHeight;
|
||||
```
|
||||
|
||||
### Missing Validators
|
||||
```bash
|
||||
# Get active validator set
|
||||
VALIDATORS=$(snrd query staking validators -o json | jq -r '.validators[].operator_address')
|
||||
|
||||
# Check contributions
|
||||
CONTRIBUTIONS=$(snrd query dwn vrf-contributions -o json)
|
||||
|
||||
# Find missing validators
|
||||
# (Compare lists to identify non-participants)
|
||||
```
|
||||
|
||||
## Security Properties
|
||||
|
||||
### Verifiability
|
||||
- Each contribution includes proof
|
||||
- Proofs cryptographically verifiable
|
||||
- Prevents manipulation
|
||||
|
||||
### Unpredictability
|
||||
- Output unpredictable before threshold
|
||||
- No single party controls result
|
||||
- Combines all contributions
|
||||
|
||||
### Threshold Security
|
||||
- Requires minimum participation
|
||||
- Prevents minority attacks
|
||||
- Ensures decentralization
|
||||
|
||||
<Note>
|
||||
VRF contributions are public but the derived key remains secure through threshold cryptography.
|
||||
</Note>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Low Participation
|
||||
- Check validator connectivity
|
||||
- Verify consensus parameters
|
||||
- Review validator logs
|
||||
|
||||
### Expired Rounds
|
||||
- Increase timeout parameters
|
||||
- Improve validator coordination
|
||||
- Check network latency
|
||||
|
||||
### Single-Node Fallback
|
||||
- Enabled in development
|
||||
- Bypasses consensus requirement
|
||||
- Not for production use
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
openapi: get /svc/v1/domain/{domain}
|
||||
title: Check Domain Verification Status
|
||||
description: Monitor domain ownership verification progress and status
|
||||
og:title: Domain Verification Status
|
||||
---
|
||||
|
||||
<Info>
|
||||
Use this endpoint to track your domain verification progress and troubleshoot issues.
|
||||
</Info>
|
||||
|
||||
## Verification States
|
||||
|
||||
### PENDING
|
||||
- Verification initiated
|
||||
- Token generated
|
||||
- Waiting for DNS TXT record
|
||||
- Has expiration deadline
|
||||
|
||||
### VERIFIED
|
||||
- DNS record confirmed
|
||||
- Domain permanently bound
|
||||
- Ready for service registration
|
||||
- No expiration
|
||||
|
||||
### EXPIRED
|
||||
- 7-day window exceeded
|
||||
- Must initiate new verification
|
||||
- Previous token invalid
|
||||
|
||||
### FAILED
|
||||
- DNS lookup error
|
||||
- Token mismatch
|
||||
- Technical failure
|
||||
|
||||
## Response Fields
|
||||
|
||||
### For Pending Verifications
|
||||
```json
|
||||
{
|
||||
"domain": "example.com",
|
||||
"owner": "sonr1xyz...",
|
||||
"verificationToken": "abc123xyz",
|
||||
"status": "PENDING",
|
||||
"expiresAt": "1704672000"
|
||||
}
|
||||
```
|
||||
|
||||
### For Verified Domains
|
||||
```json
|
||||
{
|
||||
"domain": "example.com",
|
||||
"owner": "sonr1xyz...",
|
||||
"status": "VERIFIED",
|
||||
"verifiedAt": "1704067200"
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Check Verification Progress
|
||||
```bash
|
||||
# Query status
|
||||
snrd query svc domain example.com
|
||||
|
||||
# Check if DNS is visible
|
||||
dig TXT example.com +short | grep sonr-verification
|
||||
```
|
||||
|
||||
### Monitoring Script
|
||||
```bash
|
||||
# Poll until verified
|
||||
while true; do
|
||||
STATUS=$(snrd query svc domain example.com -o json | jq -r '.status')
|
||||
if [ "$STATUS" = "VERIFIED" ]; then
|
||||
echo "Domain verified!"
|
||||
break
|
||||
fi
|
||||
echo "Status: $STATUS, waiting..."
|
||||
sleep 30
|
||||
done
|
||||
```
|
||||
|
||||
<Tip>
|
||||
If status remains PENDING after adding DNS record, wait for propagation (5-30 minutes typical).
|
||||
</Tip>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Still Pending After DNS Add
|
||||
1. Verify record is live: `dig TXT example.com`
|
||||
2. Check exact format: `sonr-verification=token`
|
||||
3. Ensure no typos in token
|
||||
4. Wait for global propagation
|
||||
|
||||
### Expired Status
|
||||
- Initiate new verification
|
||||
- Add new token to DNS
|
||||
- Complete within 7 days
|
||||
|
||||
<Warning>
|
||||
Verification tokens are single-use. Each verification attempt requires a new token.
|
||||
</Warning>
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
openapi: get /svc/v1/params
|
||||
title: Query SVC Module Parameters
|
||||
description: Get current service registration and domain verification settings
|
||||
og:title: SVC Module Configuration
|
||||
---
|
||||
|
||||
<Info>
|
||||
Module parameters define the operational constraints and requirements for all services on the network.
|
||||
</Info>
|
||||
|
||||
## Parameter Overview
|
||||
|
||||
### Service Constraints
|
||||
- **maxServicesPerAccount**: How many services one account can register
|
||||
- **maxDomainsPerService**: Domain binding limits per service
|
||||
- **maxEndpointsPerService**: API endpoint limits
|
||||
- **maxServiceDescriptionLength**: Description character limit
|
||||
|
||||
### Verification Settings
|
||||
- **domainVerificationTimeout**: Time window for DNS verification
|
||||
- **requireDomainOwnershipProof**: Cryptographic proof requirement
|
||||
- **requireHttps**: HTTPS enforcement for endpoints
|
||||
- **allowLocalhost**: Development mode support
|
||||
|
||||
### UCAN Configuration
|
||||
- **maxDelegationChainDepth**: How deep delegation chains can go
|
||||
- **ucanMaxLifetime**: Maximum token validity period
|
||||
- **ucanMinLifetime**: Minimum token validity period
|
||||
- **supportedSignatureAlgorithms**: Accepted signing algorithms
|
||||
|
||||
### Economic Parameters
|
||||
- **serviceRegistrationFee**: Cost to register a service
|
||||
- **domainVerificationFee**: Cost to verify a domain
|
||||
- **minServiceStake**: Stake required to maintain service
|
||||
|
||||
### Rate Limits
|
||||
- **maxRegistrationsPerBlock**: Registration spam prevention
|
||||
- **maxUpdatesPerBlock**: Update spam prevention
|
||||
- **maxCapabilityGrantsPerBlock**: Grant spam prevention
|
||||
|
||||
<Tip>
|
||||
Check these parameters before designing your service to ensure compliance with network limits.
|
||||
</Tip>
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
openapi: get /svc/v1/service/{serviceId}
|
||||
title: Query Service Details
|
||||
description: Get comprehensive information about a registered service
|
||||
og:title: Service Information
|
||||
---
|
||||
|
||||
<Info>
|
||||
This endpoint provides complete service details needed for integration and trust verification.
|
||||
</Info>
|
||||
|
||||
## Service Information
|
||||
|
||||
### Core Identity
|
||||
- **id**: Unique service identifier
|
||||
- **domain**: DNS-verified domain binding
|
||||
- **owner**: Blockchain address of owner
|
||||
- **status**: ACTIVE, SUSPENDED, or REVOKED
|
||||
|
||||
### Authorization
|
||||
- **rootCapabilityCid**: IPFS CID for UCAN root
|
||||
- **permissions**: List of requested capabilities
|
||||
|
||||
### Timestamps
|
||||
- **createdAt**: Registration timestamp
|
||||
- **updatedAt**: Last modification time
|
||||
|
||||
## Service Status Values
|
||||
|
||||
### ACTIVE
|
||||
- Fully operational
|
||||
- Can interact with users
|
||||
- Accepts new authorizations
|
||||
|
||||
### SUSPENDED
|
||||
- Temporarily disabled
|
||||
- Usually for violations
|
||||
- May be reactivated
|
||||
|
||||
### REVOKED
|
||||
- Permanently disabled
|
||||
- Cannot be reactivated
|
||||
- Historical record only
|
||||
|
||||
## Integration Guide
|
||||
|
||||
### Verify Service Trust
|
||||
```javascript
|
||||
// 1. Query service
|
||||
const service = await queryService(serviceId);
|
||||
|
||||
// 2. Verify domain ownership
|
||||
if (service.domain !== expectedDomain) {
|
||||
throw new Error('Domain mismatch');
|
||||
}
|
||||
|
||||
// 3. Check status
|
||||
if (service.status !== 'ACTIVE') {
|
||||
throw new Error('Service not active');
|
||||
}
|
||||
|
||||
// 4. Validate permissions
|
||||
const hasRequired = requiredPerms.every(p =>
|
||||
service.permissions.includes(p)
|
||||
);
|
||||
```
|
||||
|
||||
### Retrieve UCAN Root
|
||||
```bash
|
||||
# Get service details
|
||||
SERVICE=$(snrd query svc service my-app -o json)
|
||||
|
||||
# Extract root capability CID
|
||||
CID=$(echo $SERVICE | jq -r '.rootCapabilityCid')
|
||||
|
||||
# Fetch from IPFS
|
||||
ipfs cat $CID
|
||||
```
|
||||
|
||||
## Permission Verification
|
||||
|
||||
<Tip>
|
||||
Always verify service permissions match your security requirements before granting access.
|
||||
</Tip>
|
||||
|
||||
### Common Permission Sets
|
||||
|
||||
#### Read-Only Service
|
||||
```json
|
||||
["dwn:read", "identity:read"]
|
||||
```
|
||||
|
||||
#### Interactive Application
|
||||
```json
|
||||
["dwn:read", "dwn:write", "identity:read"]
|
||||
```
|
||||
|
||||
#### Vault Manager
|
||||
```json
|
||||
["vault:access", "identity:read", "credentials:verify"]
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Service Discovery
|
||||
```bash
|
||||
# By service ID
|
||||
snrd query svc service chat-app
|
||||
|
||||
# Parse for integration
|
||||
snrd query svc service chat-app -o json | jq '.permissions'
|
||||
```
|
||||
|
||||
### Trust Verification
|
||||
```bash
|
||||
# Verify domain binding
|
||||
SERVICE_DOMAIN=$(snrd query svc service my-app -o json | jq -r '.domain')
|
||||
EXPECTED="example.com"
|
||||
|
||||
if [ "$SERVICE_DOMAIN" = "$EXPECTED" ]; then
|
||||
echo "Domain verified"
|
||||
fi
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Never trust a service without verifying its domain binding and active status.
|
||||
</Warning>
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
openapi: get /svc/v1/services/domain/{domain}
|
||||
title: Query Services by Domain
|
||||
description: Discover all services registered under a specific domain
|
||||
og:title: Domain Service Discovery
|
||||
---
|
||||
|
||||
<Info>
|
||||
Domain-based discovery helps users find and trust services through verified domain ownership.
|
||||
</Info>
|
||||
|
||||
## Discovery Patterns
|
||||
|
||||
### Find Services by Domain
|
||||
```bash
|
||||
# Query services for a domain
|
||||
snrd query svc services-by-domain example.com
|
||||
|
||||
# Parse service IDs
|
||||
snrd query svc services-by-domain example.com -o json |
|
||||
jq -r '.services[].id'
|
||||
```
|
||||
|
||||
### Trust Verification
|
||||
Domain binding provides trust through:
|
||||
- **DNS Ownership**: Proven control of domain
|
||||
- **Brand Association**: Services linked to known domains
|
||||
- **Discovery Path**: Find services via familiar domains
|
||||
|
||||
## Integration Scenarios
|
||||
|
||||
### Service Discovery Flow
|
||||
```javascript
|
||||
async function discoverServices(domain) {
|
||||
// 1. Query services by domain
|
||||
const services = await queryServicesByDomain(domain);
|
||||
|
||||
// 2. Filter active services
|
||||
const active = services.filter(s =>
|
||||
s.status === 'ACTIVE'
|
||||
);
|
||||
|
||||
// 3. Categorize by permissions
|
||||
return {
|
||||
dataServices: active.filter(s =>
|
||||
s.permissions.includes('dwn:read')
|
||||
),
|
||||
vaultServices: active.filter(s =>
|
||||
s.permissions.includes('vault:access')
|
||||
),
|
||||
identityServices: active.filter(s =>
|
||||
s.permissions.includes('identity:read')
|
||||
)
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Service Domains
|
||||
```json
|
||||
{
|
||||
"services": [
|
||||
{
|
||||
"id": "chat",
|
||||
"domain": "example.com",
|
||||
"permissions": ["dwn:read", "dwn:write"]
|
||||
},
|
||||
{
|
||||
"id": "storage",
|
||||
"domain": "example.com",
|
||||
"permissions": ["dwn:write", "vault:access"]
|
||||
},
|
||||
{
|
||||
"id": "auth",
|
||||
"domain": "example.com",
|
||||
"permissions": ["identity:read", "credentials:verify"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Domain Organization
|
||||
|
||||
### Service Naming Conventions
|
||||
|
||||
#### By Function
|
||||
- `auth@example.com` - Authentication service
|
||||
- `storage@example.com` - Storage service
|
||||
- `api@example.com` - API gateway
|
||||
|
||||
#### By Product
|
||||
- `chat@social.example.com` - Chat application
|
||||
- `vault@secure.example.com` - Vault manager
|
||||
- `wallet@finance.example.com` - Wallet service
|
||||
|
||||
<Tip>
|
||||
Use subdomains to organize services by category or security level.
|
||||
</Tip>
|
||||
|
||||
## Trust Establishment
|
||||
|
||||
### Verify Domain Services
|
||||
```bash
|
||||
# Check domain ownership
|
||||
DOMAIN_STATUS=$(snrd query svc domain example.com -o json)
|
||||
|
||||
# If verified, query services
|
||||
if [ $(echo $DOMAIN_STATUS | jq -r '.status') = "VERIFIED" ]; then
|
||||
snrd query svc services-by-domain example.com
|
||||
fi
|
||||
```
|
||||
|
||||
### Service Validation
|
||||
```javascript
|
||||
// Validate service belongs to expected domain
|
||||
function validateService(service, expectedDomain) {
|
||||
return service.domain === expectedDomain &&
|
||||
service.status === 'ACTIVE';
|
||||
}
|
||||
|
||||
// Check all services for domain
|
||||
async function auditDomain(domain) {
|
||||
const services = await queryServicesByDomain(domain);
|
||||
return services.map(s => ({
|
||||
id: s.id,
|
||||
valid: validateService(s, domain),
|
||||
permissions: s.permissions
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Enterprise Domains
|
||||
Multiple services under corporate domain:
|
||||
- `api@company.com` - Public API
|
||||
- `admin@company.com` - Admin panel
|
||||
- `user@company.com` - User portal
|
||||
|
||||
### Development Domains
|
||||
Test services on subdomains:
|
||||
- `test@dev.example.com` - Test service
|
||||
- `staging@dev.example.com` - Staging service
|
||||
- `prod@example.com` - Production service
|
||||
|
||||
<Warning>
|
||||
Always verify domain ownership status before trusting services bound to that domain.
|
||||
</Warning>
|
||||
|
||||
## Usage Analytics
|
||||
|
||||
### Service Count by Domain
|
||||
```bash
|
||||
# Count services per domain
|
||||
snrd query svc services-by-domain example.com -o json |
|
||||
jq '.services | length'
|
||||
```
|
||||
|
||||
### Permission Summary
|
||||
```bash
|
||||
# Aggregate permissions across domain services
|
||||
snrd query svc services-by-domain example.com -o json |
|
||||
jq '[.services[].permissions] | flatten | unique'
|
||||
```
|
||||
|
||||
<Note>
|
||||
Domains can host multiple services, each with unique IDs and permission sets. Plan your service architecture accordingly.
|
||||
</Note>
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
openapi: get /svc/v1/services/owner/{owner}
|
||||
title: Query Services by Owner
|
||||
description: List all services registered by a specific account
|
||||
og:title: Owner Service Portfolio
|
||||
---
|
||||
|
||||
<Info>
|
||||
This endpoint helps owners manage their service portfolio and monitor service health.
|
||||
</Info>
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Portfolio Management
|
||||
- View all owned services
|
||||
- Monitor service status
|
||||
- Track domain bindings
|
||||
- Audit permissions
|
||||
|
||||
### Service Administration
|
||||
- Identify services needing updates
|
||||
- Check for suspended services
|
||||
- Plan new registrations
|
||||
- Manage service lifecycle
|
||||
|
||||
## Query Examples
|
||||
|
||||
### List Your Services
|
||||
```bash
|
||||
# Using your address
|
||||
MY_ADDR=$(snrd keys show alice -a)
|
||||
snrd query svc services-by-owner $MY_ADDR
|
||||
|
||||
# Direct address query
|
||||
snrd query svc services-by-owner sonr1xyz...
|
||||
```
|
||||
|
||||
### Parse Service List
|
||||
```javascript
|
||||
// Get all active services
|
||||
const services = await queryServicesByOwner(ownerAddr);
|
||||
const activeServices = services.filter(s =>
|
||||
s.status === 'ACTIVE'
|
||||
);
|
||||
|
||||
// Group by domain
|
||||
const byDomain = services.reduce((acc, svc) => {
|
||||
acc[svc.domain] = acc[svc.domain] || [];
|
||||
acc[svc.domain].push(svc);
|
||||
return acc;
|
||||
}, {});
|
||||
```
|
||||
|
||||
## Response Structure
|
||||
|
||||
Returns array of services:
|
||||
```json
|
||||
{
|
||||
"services": [
|
||||
{
|
||||
"id": "chat-app",
|
||||
"domain": "example.com",
|
||||
"owner": "sonr1xyz...",
|
||||
"permissions": ["dwn:read", "dwn:write"],
|
||||
"status": "ACTIVE"
|
||||
},
|
||||
{
|
||||
"id": "vault-manager",
|
||||
"domain": "secure.example.com",
|
||||
"owner": "sonr1xyz...",
|
||||
"permissions": ["vault:access"],
|
||||
"status": "ACTIVE"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Management Patterns
|
||||
|
||||
### Service Health Check
|
||||
```bash
|
||||
# Check for non-active services
|
||||
SERVICES=$(snrd query svc services-by-owner $ADDR -o json)
|
||||
echo $SERVICES | jq '.services[] | select(.status != "ACTIVE")' ```
|
||||
|
||||
### Permission Audit
|
||||
```bash
|
||||
# List all permissions across services
|
||||
echo $SERVICES | jq '.services[].permissions' |
|
||||
jq -s 'flatten | unique'
|
||||
```
|
||||
|
||||
### Domain Coverage
|
||||
```bash
|
||||
# List all domains with services
|
||||
echo $SERVICES | jq -r '.services[].domain' | sort | uniq
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Regularly audit your services to ensure they're active and permissions are appropriate.
|
||||
</Tip>
|
||||
|
||||
## Limits and Constraints
|
||||
|
||||
### Service Limits
|
||||
- Maximum services per owner defined by `maxServicesPerAccount`
|
||||
- Default limit: 100 services
|
||||
- Check current limit: `snrd query svc params`
|
||||
|
||||
### Best Practices
|
||||
- **Organize by Purpose**: Group related services
|
||||
- **Document Services**: Maintain service documentation
|
||||
- **Regular Audits**: Review inactive services
|
||||
- **Clean Up**: Remove unused services
|
||||
|
||||
<Warning>
|
||||
Approaching the service limit? Consider consolidating services or requesting limit increase through governance.
|
||||
</Warning>
|
||||
Reference in New Issue
Block a user