Wallet Connections

A guide to setting up and managing wallet connections with the Sonr decentralized identity system.

Sonr provides a seamless and secure way for users to connect their wallets to decentralized applications. This guide covers the different methods for establishing and managing wallet connections, from simple browser-based interactions to backend service integrations.

The Sonr Connection Model

Unlike traditional Web3 wallets that require browser extensions, Sonr uses a combination of WebAuthn and Decentralized Identifiers (DIDs) to create a secure, passwordless connection experience.

User-Centric

Users control their identity and grant permissions to applications, not the other way around.

Passwordless

WebAuthn enables biometric and security key authentication, eliminating the need for seed phrases.

Multi-Device

Users can securely access their Vault from any device with a modern web browser.

Connecting in the Browser

For web applications, the Sonr SDK provides a simple way to initiate a wallet connection.

1. Initialize the SDK

First, initialize the Sonr SDK in your application. For this example, we'll use the CDN version.

<script type="module">
  import { Sonr } from "https://cdn.jsdelivr.net/npm/@sonr/sdk";
  const sonr = new Sonr({ httpUrl: "http://localhost:1317" });
</script>

2. Request Authentication

Use the sonr.authenticate() method to prompt the user to connect their wallet. This will trigger the browser's WebAuthn flow.

async function connectWallet() {
  try {
    const session = await sonr.authenticate();
    console.log("Wallet connected!", session);
    // You now have a secure session with the user's Vault
  } catch (error) {
    console.error("Failed to connect wallet:", error);
  }
}

3. Handle the Session

The session object returned from authenticate() contains the user's DID and a UCAN token with the requested permissions. You can use this session to interact with the user's Vault.

// Example: Get the user's balance
const balance = await session.vault.getAccountBalance();
console.log("User balance:", balance);

Backend Wallet Connections

For backend services, you can use the Sonr SDK to interact with user Vaults on behalf of your application.

1. Service Registration

Your backend service must be registered on the Sonr network. This provides your service with its own DID and allows it to request permissions from users.

See the Service Registration Guide for more details.

2. Requesting Permissions

Your service can request permissions from users by generating a UCAN request. This is typically done through a user-facing application.

// Example: Requesting permission to read a user's profile
const ucanRequest = await sonr.ucan.request({
  audience: "did:sonr:your-service-did",
  resource: `dwn://user-did/profile/read`,
});

// Present this request to the user to be signed by their Vault

3. Using Delegated Capabilities

Once a user has approved your request, you will receive a delegated UCAN token. You can use this token to perform actions on the user's behalf.

// Example: Using a delegated UCAN in a Go backend
import "github.com/sonr-io/sonr/x/sonr/pkgs/sdk"

func GetUserProfile(userDID string, delegatedUcan string) (*Profile, error) {
    sonr, _ := sdk.NewSonr(rpcEndpoint, "")

    // Use the delegated UCAN to access the user's profile
    profile, err := sonr.GetUserProfile(userDID, delegatedUcan)
    if err != nil {
        return nil, err
    }

    return profile, nil
}

Managing Connections

Checking Connection Status

You can check the current connection status at any time:

const session = await sonr.getSession();

if (session) {
  console.log("User is connected:", session.did);
} else {
  console.log("User is not connected.");
}

Disconnecting

To disconnect a wallet, simply clear the session from your application's state:

await sonr.logout();
console.log("User has been disconnected.");

This will revoke the current session's UCAN token, but it will not remove any permissions the user has granted to your service.

Security Considerations

UCAN Scopes: Always request the minimum permissions necessary for your application to function.
Token Storage: Securely store delegated UCAN tokens on your backend. Never expose them on the client-side.
Revocation: Your application should handle UCAN revocations gracefully.