> For the complete documentation index, see [llms.txt](https://docs.t-rex.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.t-rex.network/identity-onchainid/account-abstraction-and-recovery.md). # 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 ```mermaid sequenceDiagram participant O as Owner device participant B as Bundler participant EP as EntryPoint participant ID as ONCHAINID participant V as ERC734Validator participant T as Target contract O->>B: user operation, signed by a key of the identity B->>EP: submit EP->>ID: validateUserOp ID->>V: validate V->>V: signer is a registered key, and not a module key V->>V: signature verifies V->>V: the key's purpose allows every call in the operation V-->>EP: valid EP->>ID: execute ID->>T: call Note over EP: the paymaster, if any, pays the fees ``` 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](/identity-onchainid/keys-purposes-and-signers.md). ### 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](/identity-onchainid/wallet-linking-and-the-global-identity-registry.md). | | **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 ```mermaid sequenceDiagram participant G as Guardians participant X as Anyone participant R as RecoveryModule participant ID as ONCHAINID G-->>X: signatures over the recovery operation X->>R: startRecovery(identity, salt, mode, recoveryData, multisignature) R->>R: signers are guardians, weights reach the threshold Note over R,ID: delay: the owner or the guardians can cancel X->>R: executeRecovery(identity, salt, mode, recoveryData) R->>ID: execute the operation ID->>ID: new MANAGEMENT key added ``` 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](/guides/identity/28.-install-the-recovery-module-and-manage-guardians.md). ### 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.t-rex.network/identity-onchainid/account-abstraction-and-recovery.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.