Account abstraction and recovery

Because an ONCHAINID is an ERC-7579 smart account, it is a wallet in its own right. Its owner signs with the device it has, does not need the gas token of the chain, and can recover access if its keys are lost. This page describes how an identity takes part in ERC-4337 account abstraction, and how social recovery works.

Account abstraction

What it changes for the owner

Without it	With it
The owner needs an externally owned account and its private key	The owner signs with any registered key: a passkey, a platform authenticator, a contract wallet, an ECDSA key
The owner holds the chain's gas token to transact	A paymaster pays. The owner holds the asset and nothing else.
One transaction, one call	One operation carries a batch of calls
The account holding the assets and the identity are two things	The identity holds the assets and is the account

The authentication and the economics are both configurable, and the identity remains the same identity the register checks for eligibility.

The life of a user operation

The validator makes three checks, in this order.

Check	Fails when
Membership	The signer is not a key of this identity, or it is the key of a module. No signature is verified for an unknown signer.
Signature	The signature does not verify for that signer, by ECDSA, by ERC-1271 or by the signer's ERC-7913 verifier.
Scope	The purpose of the key does not allow the target of the call, or of any call in a batch.

The signature field of the operation carries the signer and its signature together, so the validator knows which key is claimed before it verifies anything. When an operation validates, the validator emits KeyUsed with the identity, the key and the operation, so every action is attributable to a key.

What a key can do in a user operation

Key purpose	Calls it can make
MANAGEMENT	Any call: to the identity itself (keys, modules), to the IdentityFactory (wallet links), to any other contract.
ACTION	Calls to other contracts, single or in a batch. Not the identity, not the factory, not the key registry.
Any other purpose	None.

An ACTION key is what an investor uses day to day: transfer a token the identity holds, approve a venue, order a transfer from a linked wallet.

Some operations do not go through user operations. They are direct calls to the identity by the key holder: the ERC-734 execute and approve of the execution queue, and the claim functions addClaim, removeClaim, addClaimTo and revokeClaimByDigest. See Keys, purposes and signers.

Passkeys

A passkey is registered as a key whose signer data is the address of a WebAuthn verifier followed by the public key. The private key never leaves the device. Signing a user operation is a biometric prompt.

An identity typically carries one passkey per device, each with the purposes its owner chooses. Adding a device is adding a key. Losing a device is removing one.

An identity always starts from an address: the wallet it is created from, or created for. Passkeys are added to it as keys. The reason is durability. A passkey is bound to a device and is lost with it far more easily than a wallet, so every identity has at least one wallet behind it.

Sponsored fees

A paymaster is a contract that agrees to pay the fees of an operation. Who sponsors, and under what conditions, is decided by the party that runs the paymaster: a Platform for the holders it serves, an Issuer for its investors. The identity does not need to be configured for it. The protocol does not depend on any particular paymaster.

Recovery

Three different recoveries

The word covers three situations that the protocol handles in three different places.

Situation	What is lost	Who acts	Mechanism
A wallet is compromised or lost	One linked wallet	The Identity Owner	Revoke the wallet in the IdentityFactory. See Wallet linking and the global identity registry.
The tokens in that wallet must be moved	Access to a position	The Identity Owner, or an agent of the asset	identityTransfer ordered by the identity, for free tokens. Or recoveryAddress by an agent, which also moves frozen tokens.
The keys of the identity are lost	Control of the identity	The guardians	Social recovery, through the RecoveryModule

The rest of this page is about the third.

Guardians

Social recovery lets a set of guardians restore control of an identity whose MANAGEMENT keys are lost. Guardians recover the identity. They are not a backup of a key.

Setting	Meaning
Guardians	The signers that can take part in a recovery. Any signer type: another ONCHAINID's key, a friend's wallet, an institution's multisig, a passkey.
Weights	The weight of each guardian's signature.
Threshold	The total weight a set of signatures must reach.
Delay	The time between scheduling a recovery and being able to execute it.
Expiration	The time after which a scheduled recovery that was not executed lapses.

The module is installed by a MANAGEMENT key of the identity, with these settings, and is granted the MANAGEMENT purpose so that it can change the identity's keys when a recovery executes.

How a recovery runs

1. The guardians sign. They sign the exact operation the recovery performs. The usual operation adds a new MANAGEMENT key to the identity.

2. The recovery is scheduled. Anyone can submit the signatures. The authorization is in the signatures, not in the sender. The module checks that the signers are guardians and that their weights reach the threshold.

3. The delay runs. Nothing happens to the identity during the delay.

4. The recovery executes. After the delay and before the expiration, anyone can trigger the execution. The identity performs the operation the guardians signed, and the new key has full management authority.

Cancelling

A scheduled recovery can be stopped before it executes, in two ways.

• By the identity. A MANAGEMENT key cancels it. This is the owner's protection against guardians acting without cause: the delay is the window in which the owner sees the recovery coming and refuses it.

• By the guardians. A set of guardians reaching the threshold signs a cancellation.

Changing the settings

The identity adds and removes guardians and changes their weights, the threshold, the delay and the expiration. Each of these requires a MANAGEMENT key. A change of delay does not apply at once. A longer delay takes effect after the new delay itself, capped at 5 days. A shorter delay takes effect after the difference between the current delay and the new one, so a recovery never executes sooner than the delay that applied when the change was made. The installation and these changes are documented in 28 Install the recovery module and manage guardians.

The functions

Function	Called by	Effect
startRecovery(account, salt, mode, recoveryData, multisignature)	Anyone holding the guardians' signatures	Schedules the operation. Reverts with ERC7579SocialRecoveryExecutorInvalidSchedule when the signatures are not those of guardians of the account or do not reach the threshold.
executeRecovery(account, salt, mode, recoveryData)	Anyone	Executes the scheduled operation once the delay has elapsed.
cancelRecovery(account, salt, mode, recoveryData)	The identity	Cancels the scheduled operation.
cancelRecovery(account, salt, mode, recoveryData, multisignature)	Anyone holding the guardians' signatures	Cancels it on the guardians' authority. Reverts with ERC7579SocialRecoveryExecutorInvalidCancel when the caller is not the account and the signatures are not valid.
addGuardians(guardians), removeGuardians(guardians), setSignerWeights(guardians, weights)	The identity	Change the set of guardians and their weights.
setThreshold(threshold), setDelay(delay), setExpiration(expiration)	The identity	Change the other settings.
state(account, salt, mode, recoveryData), getSchedule(account, salt, mode, recoveryData)	Anyone	Read the state of a recovery, and when it can execute and expires.
getGuardians(account, start, end), getGuardianCount(account), isGuardian(account, guardian)	Anyone	Read the guardians of an identity.
signerWeight(account, guardian), totalWeight(account), threshold(account), getDelay(account), getExpiration(account)	Anyone	Read the other settings.

The guardians sign ERC-712 typed data in the domain of the identity: ScheduleRecover(address executor, bytes32 salt, bytes32 mode, bytes recoveryCalldata) to schedule, and CancelRecover with the same fields to cancel. The executor field is the address of the module. One RecoveryModule serves every identity, and a signature is bound to the identity whose domain it was made in.

Properties

• Scoped to one identity. Guardians sign in the ERC-712 domain of the identity they recover. A signature cannot be replayed against another identity that uses the same module.

• Scoped to one purpose. A signature that schedules a recovery cannot be used to cancel one, and the reverse.

• Exact. The guardians authorize one specific operation. The module executes that operation and no other.

Trust statement. Guardians that reach the threshold can take control of the identity once the delay has passed, if the owner does not cancel. Choosing guardians is choosing who could do that. A short delay favors quick recovery. A long delay favors the owner's ability to react.

Without guardians

An identity with no recovery module and no remaining MANAGEMENT key cannot be managed again. Its claims and its linked wallets stay as they are. The positions it holds are not lost to the register: the agents of each asset can move them to an address of a new identity, with a forced transfer, under the Issuer's own procedure for verifying the holder.