# Recovery Service SDK Reference The Safe Recovery Service SDK provides TypeScript classes for interacting with the [Safe Recovery Service](https://docs.candide.dev/wallet/recovery/overview.md). It covers three main workflows: self-managed guardian recovery, custodial guardian recovery (email/SMS), and recovery alert notifications. tip Looking for the on-chain Social Recovery Module SDK? See the [Module SDK Reference](https://docs.candide.dev/wallet/plugins/recovery-module-reference.md). ## Install[​](#install "Direct link to Install") * npm * yarn ``` npm i safe-recovery-service-sdk ``` ``` yarn add safe-recovery-service-sdk ``` ## Import[​](#import "Direct link to Import") ``` import { RecoveryByGuardian, RecoveryByCustodialGuardian, Alerts, generateSIWEMessage, SafeRecoveryServiceSdkError, SocialRecoveryModuleGracePeriodSelector, } from "safe-recovery-service-sdk"; ``` *** ## RecoveryByGuardian[​](#recoverybyguardian "Direct link to RecoveryByGuardian") Service client for managing recovery flows using self-managed guardians. Handles creating recovery requests, collecting guardian signatures, and executing/finalizing recovery. ### Initialize[​](#initialize "Direct link to Initialize") ``` import { RecoveryByGuardian, SocialRecoveryModuleGracePeriodSelector } from "safe-recovery-service-sdk"; const recoveryService = new RecoveryByGuardian( "https://safe-recovery.candide.dev", 1n, // chainId SocialRecoveryModuleGracePeriodSelector.After3Days ); ``` * Param Types | key | type | description | | :---------------------- | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `serviceEndpoint` | `string` | The URL of the Safe Recovery Service endpoint | | `chainId` | `bigint` | The chain ID of the network (e.g. 1n for Ethereum mainnet) | | `recoveryModuleAddress` | `SocialRecoveryModuleGracePeriodSelector` | The address of the Social Recovery Module with the desired grace period. Options: After3Minutes, After3Days, After7Days, After14Days | ### createRecoveryRequest[​](#createrecoveryrequest "Direct link to createRecoveryRequest") Creates a new recovery request with the specified new owners and threshold. Requires a guardian signature authorizing the recovery. * Param Types * Return Types | key | type | description | | :------------------ | :--------- | :--------------------------------------------------------------- | | `accountAddress` | `string` | The Safe account address to recover | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `guardianAddress` | `string` | The guardian address initiating the recovery request | | `guardianSignature` | `string` | The EIP-712 signature from the guardian authorizing the recovery | Promise\ | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | ### submitGuardianSignatureForRecoveryRequest[​](#submitguardiansignatureforrecoveryrequest "Direct link to submitGuardianSignatureForRecoveryRequest") Submits an additional guardian signature for an existing recovery request. Used when multiple guardian approvals are required. * Param Types * Return Types | key | type | description | | :------------------ | :------- | :-------------------------------------------- | | `id` | `string` | The recovery request ID | | `guardianAddress` | `string` | The guardian address submitting the signature | | `guardianSignature` | `string` | The EIP-712 signature from the guardian | Promise\ Returns true if the signature was accepted. ### executeRecoveryRequest[​](#executerecoveryrequest "Direct link to executeRecoveryRequest") Triggers the execution of a recovery request. Once executed, the grace period countdown begins before the recovery can be finalized. * Param Types * Return Types | key | type | description | | :--- | :------- | :--------------------------------- | | `id` | `string` | The recovery request ID to execute | Promise\ Returns true once the execution transaction is submitted. ### finalizeRecoveryRequest[​](#finalizerecoveryrequest "Direct link to finalizeRecoveryRequest") Finalizes a recovery request after the grace period has elapsed. This completes the ownership transfer. * Param Types * Return Types | key | type | description | | :--- | :------- | :---------------------------------- | | `id` | `string` | The recovery request ID to finalize | Promise\ Returns true once the finalization transaction is submitted. ### getRecoveryRequests[​](#getrecoveryrequests "Direct link to getRecoveryRequests") Queries recovery requests for a specific account and nonce. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :--------------------------------- | | `accountAddress` | `string` | The Safe account address | | `recoveryNonce` | `bigint` | The recovery module nonce to query | Promise\ | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | ### getRecoveryRequestsForLatestNonce[​](#getrecoveryrequestsforlatestnonce "Direct link to getRecoveryRequestsForLatestNonce") Fetches recovery requests for the latest on-chain nonce, filtered by status. Automatically queries the RPC node for the current nonce. * Param Types * Return Types | key | type | description | | :--------------- | :--------------------------------------- | :------------------------------------------- | | `rpcNode` | `string` | The RPC node URL to query the on-chain nonce | | `accountAddress` | `string` | The Safe account address | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Filter recovery requests by status | Promise\ | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | ### getPendingRecoveryRequestsForLatestNonce[​](#getpendingrecoveryrequestsforlatestnonce "Direct link to getPendingRecoveryRequestsForLatestNonce") Convenience method that fetches pending recovery requests for the latest nonce. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :------------------------------------------- | | `rpcNode` | `string` | The RPC node URL to query the on-chain nonce | | `accountAddress` | `string` | The Safe account address | Promise\ | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | ### getExecutedRecoveryRequestForLatestNonce[​](#getexecutedrecoveryrequestforlatestnonce "Direct link to getExecutedRecoveryRequestForLatestNonce") Fetches the executed recovery request for the latest nonce, if one exists. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :------------------------------------------- | | `rpcNode` | `string` | The RPC node URL to query the on-chain nonce | | `accountAddress` | `string` | The Safe account address | Promise\ | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | ### getFinalizedRecoveryRequestForLatestNonce[​](#getfinalizedrecoveryrequestforlatestnonce "Direct link to getFinalizedRecoveryRequestForLatestNonce") Fetches the finalized recovery request for the latest nonce, if one exists. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :------------------------------------------- | | `rpcNode` | `string` | The RPC node URL to query the on-chain nonce | | `accountAddress` | `string` | The Safe account address | Promise\ | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | *** ## RecoveryByCustodialGuardian[​](#recoverybycustodialguardian "Direct link to RecoveryByCustodialGuardian") Interface for managing recovery using custodial guardians via email or SMS. Handles channel registration, OTP verification, and recovery execution through Candide's custodial guardian service. ### Initialize[​](#initialize-1 "Direct link to Initialize") ``` import { RecoveryByCustodialGuardian } from "safe-recovery-service-sdk"; const custodialRecovery = new RecoveryByCustodialGuardian( "https://safe-recovery.candide.dev", 1n, // chainId ); ``` You can optionally override the SIWE domain and URI: ``` const custodialRecovery = new RecoveryByCustodialGuardian( "https://safe-recovery.candide.dev", 1n, { siweDomain: "myapp.com", siweUri: "https://myapp.com" } ); ``` * Param Types | key | type | description | | :---------------- | :-------------------- | :------------------------------------------------------------------------------------------------ | | `serviceEndpoint` | `string` | The URL of the Safe Recovery Service endpoint | | `chainId` | `bigint` | The chain ID of the network (e.g. 1n for Ethereum mainnet) | | `overrides` | `object \| undefined` | Optional overrides for SIWE message generation. Contains siweDomain (string) and siweUri (string) | ### Registration Management[​](#registration-management "Direct link to Registration Management") #### getRegistrationsSiweStatementToSign[​](#getregistrationssiwestatementtosign "Direct link to getRegistrationsSiweStatementToSign") Returns the SIWE statement string that needs to be signed to fetch registrations. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :----------------------- | | `accountAddress` | `string` | The Safe account address | string The SIWE statement to sign. #### getRegistrations[​](#getregistrations "Direct link to getRegistrations") Fetches active email/SMS recovery registrations for a Safe account. * Param Types * Return Types | key | type | description | | :----------------------------- | :------- | :--------------------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `eip1271SiweContractSignature` | `string` | The EIP-1271 contract signature for the SIWE message | Promise\ | key | type | description | | :-------- | :------- | :------------------------------------------- | | `id` | `string` | Unique registration ID | | `channel` | `string` | The recovery channel: "email" or "sms" | | `target` | `string` | The email address or phone number registered | #### createRegistrationToEmailRecoverySiweStatementToSign[​](#createregistrationtoemailrecoverysiwestatementtosign "Direct link to createRegistrationToEmailRecoverySiweStatementToSign") Returns the SIWE statement for registering an email recovery method. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :----------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `email` | `string` | The email address to register for recovery | string The SIWE statement to sign. #### createRegistrationToEmailRecovery[​](#createregistrationtoemailrecovery "Direct link to createRegistrationToEmailRecovery") Registers an email address as a recovery channel. Returns a challenge ID for OTP verification. * Param Types * Return Types | key | type | description | | :----------------------------- | :------- | :--------------------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `email` | `string` | The email address to register for recovery | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `eip1271SiweContractSignature` | `string` | The EIP-1271 contract signature for the SIWE message | Promise\ The challenge ID to use with submitRegistrationChallenge. #### createRegistrationToSmsRecoverySiweStatementToSign[​](#createregistrationtosmsrecoverysiwestatementtosign "Direct link to createRegistrationToSmsRecoverySiweStatementToSign") Returns the SIWE statement for registering an SMS recovery method. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :---------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `phoneNumber` | `string` | The phone number to register for recovery | string The SIWE statement to sign. #### createRegistrationToSmsRecovery[​](#createregistrationtosmsrecovery "Direct link to createRegistrationToSmsRecovery") Registers a phone number as a recovery channel. Returns a challenge ID for OTP verification. * Param Types * Return Types | key | type | description | | :----------------------------- | :------- | :--------------------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `phoneNumber` | `string` | The phone number to register for recovery | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `eip1271SiweContractSignature` | `string` | The EIP-1271 contract signature for the SIWE message | Promise\ The challenge ID to use with submitRegistrationChallenge. #### createRegistrationToRecoverySiweStatementToSign[​](#createregistrationtorecoverysiwestatementtosign "Direct link to createRegistrationToRecoverySiweStatementToSign") Generic method that returns the SIWE statement for registering any recovery channel. * Param Types * Return Types | key | type | description | | :--------------- | :----------------- | :-------------------------------- | | `accountAddress` | `string` | The Safe account address | | `channel` | `"sms" \| "email"` | The recovery channel type | | `channelTarget` | `string` | The email address or phone number | string The SIWE statement to sign. #### createRegistrationToRecovery[​](#createregistrationtorecovery "Direct link to createRegistrationToRecovery") Generic method that registers a recovery channel. Returns a challenge ID for OTP verification. * Param Types * Return Types | key | type | description | | :----------------------------- | :----------------- | :--------------------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `channel` | `"sms" \| "email"` | The recovery channel type | | `channelTarget` | `string` | The email address or phone number | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `eip1271SiweContractSignature` | `string` | The EIP-1271 contract signature for the SIWE message | Promise\ The challenge ID to use with submitRegistrationChallenge. #### submitRegistrationChallenge[​](#submitregistrationchallenge "Direct link to submitRegistrationChallenge") Submits the OTP code to verify a registration. Returns the registration ID and the assigned custodial guardian address. * Param Types * Return Types | key | type | description | | :------------- | :------- | :--------------------------------------------------- | | `challengeId` | `string` | The challenge ID received from the registration step | | `otpChallenge` | `string` | The OTP code received via email or SMS | Promise\ | key | type | description | | :---------------- | :------- | :----------------------------------------------------------- | | `registrationId` | `string` | The unique registration ID for the verified channel | | `guardianAddress` | `string` | The custodial guardian address assigned to this registration | #### deleteRegistrationSiweStatementToSign[​](#deleteregistrationsiwestatementtosign "Direct link to deleteRegistrationSiweStatementToSign") Returns the SIWE statement for deleting a registration. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :---------------------------- | | `accountAddress` | `string` | The Safe account address | | `registrationId` | `string` | The registration ID to delete | string The SIWE statement to sign. #### deleteRegistration[​](#deleteregistration "Direct link to deleteRegistration") Removes an email or SMS recovery registration. * Param Types * Return Types | key | type | description | | :----------------------------- | :------- | :--------------------------------------------------- | | `registrationId` | `string` | The registration ID to delete | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `eip1271SiweContractSignature` | `string` | The EIP-1271 contract signature for the SIWE message | Promise\ Returns true if the deletion was successful. ### Recovery Flow[​](#recovery-flow "Direct link to Recovery Flow") #### requestCustodialGuardianSignatureChallenge[​](#requestcustodialguardiansignaturechallenge "Direct link to requestCustodialGuardianSignatureChallenge") Initiates a recovery request through the custodial guardian. Sends OTP challenges to all registered recovery channels. * Param Types * Return Types | key | type | description | | :--------------- | :--------- | :------------------------------------- | | `accountAddress` | `string` | The Safe account address to recover | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | Promise\ | key | type | description | | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | | `requestId` | `string` | Unique signature request ID | | `requiredVerifications` | `number` | Minimum number of OTP challenges required to obtain the guardian signature | | `auths` | `key type descriptionchallengeId string The challenge ID for this authentication method channel string The channel type: "email" or "sms" target string The email address or phone number to verify` | List of authentication methods that can be used for verification | #### submitCustodialGuardianSignatureChallenge[​](#submitcustodialguardiansignaturechallenge "Direct link to submitCustodialGuardianSignatureChallenge") Submits an OTP code for a specific authentication challenge. When all required verifications are collected, returns the custodial guardian address and signature. * Param Types * Return Types | key | type | description | | :------------- | :------- | :----------------------------------------------------------------------- | | `requestId` | `string` | The signature request ID from requestCustodialGuardianSignatureChallenge | | `challengeId` | `string` | The challenge ID for the specific authentication method | | `otpChallenge` | `string` | The OTP code received via email or SMS | Promise\ | key | type | description | | :--------------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------- | | `success` | `boolean` | Whether the OTP verification was successful | | `custodianGuardianAddress` | `string \| undefined` | The custodial guardian address (returned when all required verifications are collected) | | `custodianGuardianSignature` | `string \| undefined` | The recovery signature from the custodial guardian (returned when all required verifications are collected) | #### createAndExecuteRecoveryRequest[​](#createandexecuterecoveryrequest "Direct link to createAndExecuteRecoveryRequest") Creates a recovery request and immediately triggers execution using the custodial guardian's signature. Combines createRecoveryRequest and executeRecoveryRequest into a single call. * Param Types * Return Types | key | type | description | | :--------------------------- | :--------- | :--------------------------------------------------------------- | | `accountAddress` | `string` | The Safe account address to recover | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `custodianGuardianAddress` | `string` | The custodial guardian address obtained from signature challenge | | `custodianGuardianSignature` | `string` | The recovery signature from the custodial guardian | Promise\ | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | *** ## Alerts[​](#alerts "Direct link to Alerts") Service class for managing email and SMS alert subscriptions for recovery events on Safe accounts. Account owners receive notifications when recovery actions are initiated. ### Initialize[​](#initialize-2 "Direct link to Initialize") ``` import { Alerts } from "safe-recovery-service-sdk"; const alerts = new Alerts( "https://safe-recovery.candide.dev", 1n, // chainId ); ``` * Param Types | key | type | description | | :---------------- | :-------------------- | :------------------------------------------------------------------------------------------------ | | `serviceEndpoint` | `string` | The URL of the Safe Recovery Service endpoint | | `chainId` | `bigint` | The chain ID of the network (e.g. 1n for Ethereum mainnet) | | `overrides` | `object \| undefined` | Optional overrides for SIWE message generation. Contains siweDomain (string) and siweUri (string) | ### createEmailSubscriptionSiweStatementToSign[​](#createemailsubscriptionsiwestatementtosign "Direct link to createEmailSubscriptionSiweStatementToSign") Returns the SIWE statement for creating an email alert subscription. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :---------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `ownerAddress` | `string` | The owner address of the Safe account | | `email` | `string` | The email address for alert notifications | string The SIWE statement to sign. ### createEmailSubscription[​](#createemailsubscription "Direct link to createEmailSubscription") Creates an email alert subscription. Returns a subscription ID for OTP activation. * Param Types * Return Types | key | type | description | | :------------------- | :------- | :------------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `ownerAddress` | `string` | The owner address of the Safe account | | `email` | `string` | The email address for alert notifications | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `siweOwnerSignature` | `string` | The owner's signature for the SIWE message | Promise\ The subscription ID to use with activateSubscription. ### createSubscriptionSiweStatementToSign[​](#createsubscriptionsiwestatementtosign "Direct link to createSubscriptionSiweStatementToSign") Generic method that returns the SIWE statement for creating an alert subscription on any channel. * Param Types * Return Types | key | type | description | | :--------------- | :----------------- | :------------------------------------ | | `accountAddress` | `string` | The Safe account address | | `ownerAddress` | `string` | The owner address of the Safe account | | `channel` | `"sms" \| "email"` | The notification channel type | | `channelTarget` | `string` | The email address or phone number | string The SIWE statement to sign. ### createSubscription[​](#createsubscription "Direct link to createSubscription") Generic method that creates an alert subscription on any channel. Returns a subscription ID for OTP activation. * Param Types * Return Types | key | type | description | | :------------------- | :----------------- | :------------------------------------------- | | `accountAddress` | `string` | The Safe account address | | `ownerAddress` | `string` | The owner address of the Safe account | | `channel` | `"sms" \| "email"` | The notification channel type | | `channelTarget` | `string` | The email address or phone number | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `siweOwnerSignature` | `string` | The owner's signature for the SIWE message | Promise\ The subscription ID to use with activateSubscription. ### activateSubscription[​](#activatesubscription "Direct link to activateSubscription") Verifies and activates a subscription using the OTP code sent to the email or phone number. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :------------------------------------- | | `subscriptionId` | `string` | The subscription ID to activate | | `otpChallenge` | `string` | The OTP code received via email or SMS | Promise\ Returns true if the subscription was activated. ### getSubscriptionsSiweStatementToSign[​](#getsubscriptionssiwestatementtosign "Direct link to getSubscriptionsSiweStatementToSign") Returns the SIWE statement for fetching active subscriptions. * Param Types * Return Types | key | type | description | | :------------- | :------- | :------------------------------------ | | `ownerAddress` | `string` | The owner address of the Safe account | string The SIWE statement to sign. ### getActiveSubscriptions[​](#getactivesubscriptions "Direct link to getActiveSubscriptions") Fetches all active alert subscriptions for a Safe account. * Param Types * Return Types | key | type | description | | :------------------- | :------- | :-------------------------------------------------- | | `accountAddress` | `string` | The Safe account address to query subscriptions for | | `ownerAddress` | `string` | The owner address of the Safe account | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `siweOwnerSignature` | `string` | The owner's signature for the SIWE message | Promise\ | key | type | description | | :-------- | :----------------- | :-------------------------------------------------------- | | `id` | `string` | Unique subscription ID | | `channel` | `"email" \| "sms"` | The notification delivery channel | | `target` | `string` | The email address or phone number receiving notifications | ### unsubscribeSiweStatementToSign[​](#unsubscribesiwestatementtosign "Direct link to unsubscribeSiweStatementToSign") Returns the SIWE statement for removing a subscription. * Param Types * Return Types | key | type | description | | :------------- | :------- | :------------------------------------ | | `ownerAddress` | `string` | The owner address of the Safe account | string The SIWE statement to sign. ### unsubscribe[​](#unsubscribe "Direct link to unsubscribe") Removes an alert subscription. * Param Types * Return Types | key | type | description | | :------------------- | :------- | :------------------------------------------- | | `subscriptionId` | `string` | The subscription ID to remove | | `ownerAddress` | `string` | The owner address of the Safe account | | `siweMessage` | `string` | The SIWE message to authenticate the request | | `siweOwnerSignature` | `string` | The owner's signature for the SIWE message | Promise\ Returns true if the unsubscription was successful. *** ## Utility Functions[​](#utility-functions "Direct link to Utility Functions") ### generateSIWEMessage[​](#generatesiwemessage "Direct link to generateSIWEMessage") Generates a Sign-In with Ethereum (EIP-4361) message. Used internally by `RecoveryByCustodialGuardian` and `Alerts`, but also available for custom integrations. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :--------------------------------------------------------- | | `accountAddress` | `string` | The account address for the SIWE message | | `statement` | `string` | The human-readable statement for the SIWE message | | `chainId` | `bigint` | The chain ID of the network | | `siweDomain` | `string` | The domain for the SIWE message (e.g. 'example.com') | | `siweUri` | `string` | The URI for the SIWE message (e.g. 'https\://example.com') | string The formatted SIWE message ready for signing. *** ## Types[​](#types "Direct link to Types") ### RecoveryByGuardianRequest[​](#recoverybyguardianrequest "Direct link to RecoveryByGuardianRequest") Represents a recovery request with its current state and metadata. | key | type | description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | | `id` | `string` | Unique recovery request ID | | `emoji` | `string` | Emoji identifier associated with the recovery request | | `account` | `string` | The Safe account address being recovered | | `newOwners` | `string[]` | The new owners for the Safe account | | `newThreshold` | `number` | The new threshold for the Safe account | | `chainId` | `number` | The chain ID of the network | | `nonce` | `bigint` | Recovery module contract nonce | | `signatures` | `string[]` | Guardian signatures collected for this recovery request | | `executeData` | `key type descriptionsponsored boolean Whether the execution transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the execution (if available)` | Data about the recovery execution transaction | | `finalizeData` | `key type descriptionsponsored boolean Whether the finalization transaction is gas-sponsored transactionHash string \| undefined The transaction hash of the finalization (if available)` | Data about the recovery finalization transaction | | `status` | `"PENDING" \| "EXECUTED" \| "FINALIZED"` | Current status of the recovery request | | `discoverable` | `boolean` | Whether the recovery request is publicly discoverable | | `createdAt` | `string` | ISO 8601 timestamp of when the request was created | | `updatedAt` | `string` | ISO 8601 timestamp of the last update | ### Registration[​](#registration "Direct link to Registration") Represents an email or SMS recovery channel registration. | key | type | description | | :-------- | :------- | :------------------------------------------- | | `id` | `string` | Unique registration ID | | `channel` | `string` | The recovery channel: "email" or "sms" | | `target` | `string` | The email address or phone number registered | ### SignatureRequest[​](#signaturerequest "Direct link to SignatureRequest") Represents a custodial guardian signature request with its OTP challenges. | key | type | description | | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | | `requestId` | `string` | Unique signature request ID | | `requiredVerifications` | `number` | Minimum number of OTP challenges required to obtain the guardian signature | | `auths` | `key type descriptionchallengeId string The challenge ID for this authentication method channel string The channel type: "email" or "sms" target string The email address or phone number to verify` | List of authentication methods that can be used for verification | ### AlertsSubscription[​](#alertssubscription "Direct link to AlertsSubscription") Represents an active alert subscription. | key | type | description | | :-------- | :----------------- | :-------------------------------------------------------- | | `id` | `string` | Unique subscription ID | | `channel` | `"email" \| "sms"` | The notification delivery channel | | `target` | `string` | The email address or phone number receiving notifications | ### SocialRecoveryModuleGracePeriodSelector[​](#socialrecoverymodulegraceperiodselector "Direct link to SocialRecoveryModuleGracePeriodSelector") Enum of deployed Social Recovery Module addresses with different grace periods. | key | type | description | | :-------------- | :------- | :-------------------------------------------------------------- | | `After3Minutes` | `string` | 0x949d01d424bE050D09C16025dd007CB59b3A8c66 (useful for testing) | | `After3Days` | `string` | 0x38275826E1933303E508433dD5f289315Da2541c | | `After7Days` | `string` | 0x088f6cfD8BB1dDb1BB069CCb3fc1A98927D233f2 | | `After14Days` | `string` | 0x9BacD92F4687Db306D7ded5d4513a51EA05df25b | *** ## Error Handling[​](#error-handling "Direct link to Error Handling") ### SafeRecoveryServiceSdkError[​](#saferecoveryservicesdkerror "Direct link to SafeRecoveryServiceSdkError") All SDK methods throw `SafeRecoveryServiceSdkError` on failure. The error includes a code, message, and optional context for debugging. ``` import { SafeRecoveryServiceSdkError } from "safe-recovery-service-sdk"; try { await recoveryService.createRecoveryRequest(/* ... */); } catch (error) { if (error instanceof SafeRecoveryServiceSdkError) { console.log(error.code); // e.g. "HTTP_BAD_REQUEST" console.log(error.message); // Human-readable message console.log(error.context); // Additional context console.log(error.stringify()); // Serialized error (useful for React Native) } } ``` | key | type | description | | :-------- | :---------------------- | :-------------------------------------------------------------------------------------------------- | | `code` | `BasicErrorCode` | The error code identifying the type of error (e.g. HTTP\_BAD\_REQUEST, SIWE\_ERROR, UNKNOWN\_ERROR) | | `message` | `string` | Human-readable error message | | `context` | `Jsonable \| undefined` | Additional context about the error (e.g. URL, request options) | | `errno` | `number \| undefined` | Numeric error code (typically the HTTP status code) | **Error Codes:** | Code | Description | | -------------------------- | ------------------------------------------- | | `UNKNOWN_ERROR` | An unexpected error occurred | | `TIMEOUT` | The request timed out | | `SIWE_ERROR` | Error generating or validating SIWE message | | `BAD_DATA` | Invalid data provided | | `HTTP_BAD_REQUEST` | 400: Invalid request parameters | | `HTTP_UNAUTHORIZED` | 401: Authentication required | | `HTTP_FORBIDDEN` | 403: Insufficient permissions | | `HTTP_NOT_FOUND` | 404: Resource not found | | `HTTP_CONFLICT` | 409: Conflicting request | | `HTTP_TOO_MANY_REQUESTS` | 429: Rate limit exceeded | | `HTTP_INTERNAL_ERROR` | 500: Server error | | `HTTP_BAD_GATEWAY` | 502: Bad gateway | | `HTTP_SERVICE_UNAVAILABLE` | 503: Service temporarily unavailable | | `HTTP_GATEWAY_TIMEOUT` | 504: Gateway timeout |