mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-02 17:31:39 +00:00
Feat/add networks (#1303)
* No commit suggestions generated * No commit suggestions generated * No commit suggestions generated
This commit is contained in:
Prad Nukala
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Delegated Proof of Stake (DPoS)
|
||||
description: A decentralized, secure, and efficient consensus mechanism.
|
||||
---
|
||||
|
||||
Sonr leverages a Delegated Proof of Stake (DPoS) mechanism to optimize network security and user participation. DPoS imposes an opportunity cost for malicious behavior through slashing, but it also presents challenges that must be addressed for a sustainable design.
|
||||
|
||||
## Challenges in Staking Mechanisms
|
||||
|
||||
- **Token Value**: The token must have intrinsic value to incentivize staking.
|
||||
- **Wealth Concentration**: Staking can give an outsized advantage to wealthy users.
|
||||
- **Coordination Problems**: Staking mechanisms can be gamed by coordinated actors.
|
||||
|
||||
## Sonr's Approach to DPoS
|
||||
|
||||
We have designed our staking mechanism to address these challenges and create a sustainable and equitable system:
|
||||
|
||||
<CardGroup>
|
||||
<Card title="Low Barrier to Entry">
|
||||
The upfront capital required to stake is designed to not significantly
|
||||
discourage participation.
|
||||
</Card>
|
||||
<Card title="Slashing for Malice">
|
||||
If a stakeholder group makes decisions that materially harm the network,
|
||||
their stake is slashed.
|
||||
</Card>
|
||||
<Card title="Incentivizing Positive Growth">
|
||||
Stakeholders can make decisions that positively impact the future network
|
||||
health and token price, promoting long-term growth.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Network Architecture
|
||||
description: A detailed look at Sonr's three-tier system design.
|
||||
---
|
||||
|
||||
Our incorporation of embedded light nodes signifies a strategic move towards enhancing network robustness and efficiency. These nodes operate with a reduced resource footprint, ensuring a widespread and seamless network distribution. They form the bedrock of the infrastructure, interfacing directly with a series of validators. These validators are pivotal in maintaining the integrity and trustworthiness of the network, each playing an instrumental role in processing transactions and securing the network's protocol.
|
||||
|
||||
## Blockchain Services
|
||||
|
||||
Blockchain Services are instrumental in ensuring seamless interoperability and data exchange across the network.
|
||||
|
||||
<CardGroup>
|
||||
<Card title="IBC Relayer">
|
||||
The IBC Relayer stands at the forefront of inter-blockchain communication,
|
||||
enabling different blockchain protocols to transfer and share information
|
||||
effectively.
|
||||
</Card>
|
||||
<Card title="IPFS/Libp2p Routing">
|
||||
IPFS/Libp2p Routing underpins the decentralized routing of information,
|
||||
ensuring resilient and scalable data distribution across the network.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Interoperability Protocols
|
||||
|
||||
The overarching network architecture is designed with interoperability at its core, integrating protocols such as Matrix and Pinecone to facilitate communication and data exchange across disparate systems.
|
||||
|
||||
- **Matrix Protocol**: A new paradigm in secure, decentralized communication.
|
||||
- **Pinecone Routing**: A novel approach to establishing network pathways, enhancing the efficiency and reliability of data transmission.
|
||||
@@ -0,0 +1,238 @@
|
||||
---
|
||||
title: "WebAuthn Integration"
|
||||
description: "Comprehensive guide to Sonr's WebAuthn/FIDO2 implementation for passwordless authentication"
|
||||
icon: "key"
|
||||
sidebarTitle: "WebAuthn Integration"
|
||||
---
|
||||
|
||||
<Note>
|
||||
This documentation covers the WebAuthn implementation in the Sonr blockchain,
|
||||
providing a secure, passwordless authentication mechanism through
|
||||
W3C-compliant WebAuthn protocols.
|
||||
</Note>
|
||||
|
||||
## Overview
|
||||
|
||||
Sonr's WebAuthn implementation enables gasless onboarding and secure transaction authorization without requiring users to hold tokens initially. This document provides a comprehensive guide to understanding and using our WebAuthn client.
|
||||
|
||||
## Architecture
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="https://cdn.sonr.io/diagrams/passkey-jwt.png"
|
||||
alt="WebAuthn Architecture Diagram"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
The WebAuthn implementation is structured across three primary layers:
|
||||
|
||||
1. **Client Layer** (`client/auth/webauthn.go`)
|
||||
|
||||
- WebAuthnClient interface
|
||||
- Registration and Authentication flows
|
||||
- DID integration
|
||||
|
||||
2. **Internal WebAuthn Package** (`internal/webauthn/`)
|
||||
|
||||
- COSE key parsing
|
||||
- CBOR encoding/decoding
|
||||
- Attestation verification
|
||||
- Signature verification (ES256/RS256)
|
||||
|
||||
3. **DID Module Layer** (`x/did/keeper/`)
|
||||
- WebAuthn controller verifier
|
||||
- Credential storage in DID documents
|
||||
- Challenge generation and validation
|
||||
|
||||
## API Reference
|
||||
|
||||
### WebAuthnClient Interface
|
||||
|
||||
<CodeGroup>
|
||||
```go
|
||||
type WebAuthnClient interface {
|
||||
// Registration Operations
|
||||
BeginRegistration(ctx context.Context, opts *RegistrationOptions) (*RegistrationChallenge, error)
|
||||
CompleteRegistration(ctx context.Context, challenge *RegistrationChallenge, response *AuthenticatorAttestationResponse) (*WebAuthnCredential, error)
|
||||
|
||||
// Authentication Operations
|
||||
BeginAuthentication(ctx context.Context, opts *AuthenticationOptions) (*AuthenticationChallenge, error)
|
||||
CompleteAuthentication(ctx context.Context, challenge *AuthenticationChallenge, response *AuthenticatorAssertionResponse, credentialID string) (*AuthenticationResult, error)
|
||||
|
||||
// Credential Management Methods...
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Registration Flow
|
||||
|
||||
<CodeGroup>
|
||||
```go Registration Example
|
||||
func registerWebAuthn() error {
|
||||
client := auth.NewWebAuthnClient()
|
||||
ctx := context.Background()
|
||||
|
||||
// Begin registration
|
||||
regOpts := &auth.RegistrationOptions{
|
||||
UserID: "user123",
|
||||
Username: "alice@example.com",
|
||||
DisplayName: "Alice Smith",
|
||||
UserVerification: "preferred",
|
||||
}
|
||||
|
||||
challenge, err := client.BeginRegistration(ctx, regOpts)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Complete registration
|
||||
response := &auth.AuthenticatorAttestationResponse{
|
||||
ClientDataJSON: clientDataJSON,
|
||||
AttestationObject: attestationObject,
|
||||
}
|
||||
|
||||
credential, err := client.CompleteRegistration(ctx, challenge, response)
|
||||
return err
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
<CodeGroup>
|
||||
```go Authentication Example
|
||||
func authenticateWebAuthn(credentialID string) error {
|
||||
client := auth.NewWebAuthnClient()
|
||||
ctx := context.Background()
|
||||
|
||||
// Begin authentication
|
||||
authOpts := &auth.AuthenticationOptions{
|
||||
UserVerification: "required",
|
||||
AllowedCredentials: []*auth.CredentialDescriptor{
|
||||
{
|
||||
Type: "public-key",
|
||||
ID: []byte(credentialID),
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
challenge, err := client.BeginAuthentication(ctx, authOpts)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Complete authentication
|
||||
response := &auth.AuthenticatorAssertionResponse{
|
||||
ClientDataJSON: clientDataJSON,
|
||||
AuthenticatorData: authenticatorData,
|
||||
Signature: signature,
|
||||
UserHandle: userHandle,
|
||||
}
|
||||
|
||||
result, err := client.CompleteAuthentication(ctx, challenge, response, credentialID)
|
||||
return err
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Supported Algorithms
|
||||
|
||||
<Tabs>
|
||||
<Tab title="ES256">ECDSA with P-256 curve and SHA-256</Tab>
|
||||
<Tab title="RS256">RSASSA-PKCS1-v1_5 with SHA-256</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Attestation Formats
|
||||
|
||||
<Callout type="info">
|
||||
1. **none**: No attestation (development/testing) 2. **packed**:
|
||||
Self-attestation or certificate chain 3. **fido-u2f**: Legacy U2F
|
||||
authenticators 4. **android-safetynet**: Android device attestation
|
||||
</Callout>
|
||||
|
||||
### Security Features
|
||||
|
||||
- **Challenge uniqueness**: Each challenge is unique and time-bound
|
||||
- **Origin validation**: Ensures requests come from trusted origins
|
||||
- **User verification**: Requires biometric or PIN when configured
|
||||
- **Counter tracking**: Detects cloned credentials
|
||||
- **Credential isolation**: Each DID has separate credential namespace
|
||||
|
||||
## Configuration
|
||||
|
||||
### Chain Parameters
|
||||
|
||||
<CodeGroup>
|
||||
```json Configuration Example
|
||||
{
|
||||
"webauthn": {
|
||||
"rp_id": "sonr.io",
|
||||
"rp_name": "Sonr Network",
|
||||
"timeout": 60000,
|
||||
"user_verification": "preferred",
|
||||
"attestation": "none",
|
||||
"allowed_origins": [
|
||||
"https://sonr.io",
|
||||
"https://app.sonr.io"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordion title="Common WebAuthn Issues">
|
||||
- **"Invalid attestation format"**: Ensure authenticator supports the
|
||||
configured format - **"Challenge mismatch"**: Verify challenge hasn't expired
|
||||
- **"Origin validation failed"**: Check allowed origins list - **"User
|
||||
verification required"**: Ensure authenticator supports verification
|
||||
</Accordion>
|
||||
|
||||
## Contributing
|
||||
|
||||
### Development Setup
|
||||
|
||||
<CodeGroup>
|
||||
```bash Setup Commands
|
||||
# Clone repository
|
||||
git clone https://github.com/sonr-io/sonr.git
|
||||
|
||||
# Install dependencies
|
||||
|
||||
make install
|
||||
|
||||
# Run WebAuthn tests
|
||||
|
||||
make test-webauthn
|
||||
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## References
|
||||
|
||||
<Card
|
||||
title="WebAuthn Specifications"
|
||||
icon="link"
|
||||
href="https://www.w3.org/TR/webauthn/"
|
||||
>
|
||||
Official W3C WebAuthn Specification
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="FIDO2 CTAP"
|
||||
icon="lock"
|
||||
href="https://fidoalliance.org/specs/fido-v2.0/"
|
||||
>
|
||||
FIDO2 Client to Authenticator Protocol
|
||||
</Card>
|
||||
|
||||
## License
|
||||
|
||||
Copyright 2024 Sonr Inc. Licensed under the Apache License, Version 2.0.
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user