Social recovery

Social recovery lets a configurable set of guardians cooperate to rotate the signing key on a smart account when the user loses access. It is implemented as an ERC-7579 validator module (the Rhinestone Social Recovery validator) that you install on top of the Startale Smart Account.

Source: StartaleGroup/scs-aa-sdk. This page uses helpers from @rhinestone/module-sdk which is already a peer of the AA SDK; install it explicitly if your project does not have it yet (npm install @rhinestone/module-sdk).

How it works

A recovery is a UserOperation validated by the Social Recovery module instead of the default validator. The module checks that the bundle of guardian signatures meets the configured threshold; if it does, the UserOperation is executed and rotates the account’s owner key.

1. Pick guardians and a threshold

The configuration is intentionally small:

Parameter	Type	Notes
`guardians`	`Address[]`	Onchain addresses you trust to cooperate. They can be EOAs, multisigs, or other smart accounts.
`threshold`	`number`	How many guardian signatures are required for a recovery. Common choices are 2-of-3 and 3-of-5.
`hook`	`Address` (optional)	An ERC-7579 hook to gate recovery further (rate limits, cooldowns).

Validate the configuration before installing the module: ensure addresses are deduplicated, all guardians pass isAddress, and 1 <= threshold <= guardians.length.

2. Install the module

import { getSocialRecoveryValidator } from "@rhinestone/module-sdk"
import type { StartaleAccountClient } from "@startale-scs/aa-sdk"
import type { Address } from "viem"

async function installSocialRecovery(
  client: StartaleAccountClient,
  guardians: Address[],
  threshold: number,
) {
  const recoveryModule = getSocialRecoveryValidator({ guardians, threshold })

  const userOpHash = await client.installModule({ module: recoveryModule })
  return client.waitForUserOperationReceipt({ hash: userOpHash })
}

Symbol	Source	Role
`getSocialRecoveryValidator`	`@rhinestone/module-sdk`	Builds the validator descriptor and init data (encodes guardian addresses + threshold).
`installModule`	`StartaleAccountClient` (ERC-7579 actions)	Installs the module via a UserOperation.
`waitForUserOperationReceipt`	`StartaleAccountClient`	Polls the bundler for confirmation.

3. Manage guardians at runtime

After installation you can add or remove guardians and adjust the threshold without re-installing the module. The helpers return an Execution ({ to, data, value }), which you wrap in a UserOperation with sendUserOperation.

import {
  getAddSocialRecoveryGuardianAction,
  getRemoveSocialRecoveryGuardianAction,
  getSetSocialRecoveryThresholdAction,
} from "@rhinestone/module-sdk"
import type { Address } from "viem"

async function addGuardian(client: StartaleAccountClient, guardian: Address) {
  const exec = getAddSocialRecoveryGuardianAction({ guardian })
  const hash = await client.sendUserOperation({ calls: [exec] })
  return client.waitForUserOperationReceipt({ hash })
}

async function setThreshold(client: StartaleAccountClient, threshold: number) {
  const exec = getSetSocialRecoveryThresholdAction({ threshold })
  const hash = await client.sendUserOperation({ calls: [exec] })
  return client.waitForUserOperationReceipt({ hash })
}

async function removeGuardian(
  client: StartaleAccountClient,
  publicClient: import("viem").PublicClient,
  account: Parameters<typeof getRemoveSocialRecoveryGuardianAction>[0]["account"],
  guardian: Address,
) {
  const exec = await getRemoveSocialRecoveryGuardianAction({
    client: publicClient,
    account,
    guardian,
  })
  const hash = await client.sendUserOperation({ calls: [exec] })
  return client.waitForUserOperationReceipt({ hash })
}

Symbol	Source	Role
`getAddSocialRecoveryGuardianAction`	`@rhinestone/module-sdk`	Returns the `Execution` for adding one guardian.
`getRemoveSocialRecoveryGuardianAction`	`@rhinestone/module-sdk`	Returns the `Execution` for removing a guardian (reads onchain state, hence the `client` parameter).
`getSetSocialRecoveryThresholdAction`	`@rhinestone/module-sdk`	Returns the `Execution` for updating the threshold.

4. Read the current guardian set

import { getSocialRecoveryGuardians } from "@rhinestone/module-sdk"

const guardians = await getSocialRecoveryGuardians({
  client: publicClient,
  account: smartAccountClient.account,
})

guardians is an Address[] of every guardian currently registered on the account.

5. Execute a recovery

A recovery is a UserOperation that:

Targets the smart account itself.
Calls the account’s owner-rotation method (for example, swapping the active ECDSA validator key).
Is signed by enough guardians to meet the threshold.

The exact signing UX is up to you (each guardian signs typed data offchain, your backend aggregates the signatures, and you submit a single UserOperation). The module’s onchain logic verifies that the aggregated signature represents at least threshold distinct guardians from the registered set before the UserOperation is allowed to execute.

Recovery rotates the active validator key, not the smart account address. The address stays the same; the user just gains a new signer they control.

Operational guidance

Concern	Recommendation
Guardian selection	Diversify across people, devices, or services. Avoid choosing guardians who can collude.
Threshold	2-of-3 is the most common starting point. Higher thresholds increase safety at the cost of recovery friction.
Communication	Document the recovery process for your guardians in advance so they recognise a legitimate request.
Drills	Run a dry-run recovery on a test account before relying on the configuration in production.

Next steps

Smart sessions

Pair recovery with scoped session keys for daily UX.

Smart account setup

Refresh the underlying account and client setup.

Contracts and audits

Look up validator and account addresses on each network.

Overview

Getting started

Tutorials

Auth providers

Advanced

EIP-7702

Resources

FAQ

How it works

1. Pick guardians and a threshold

2. Install the module

3. Manage guardians at runtime

4. Read the current guardian set

5. Execute a recovery

Operational guidance

Next steps

Smart sessions

Sponsored paymaster

Smart account setup

Contracts and audits

​How it works

​1. Pick guardians and a threshold

​2. Install the module

​3. Manage guardians at runtime

​4. Read the current guardian set

​5. Execute a recovery

​Operational guidance

​Next steps

Smart sessions

Sponsored paymaster

Smart account setup

Contracts and audits

How it works

1. Pick guardians and a threshold

2. Install the module

3. Manage guardians at runtime

4. Read the current guardian set

5. Execute a recovery

Operational guidance

Next steps