# API Specification: Safe Recovery Service

## Reference links

- Recovery Explainer: https://docs.candide.dev/blog/making-accounts-recoverable/
- Account Recovery Contracts and Audits: https://github.com/candidelabs/candide-contracts
- SDK Recovery Docs: https://docs.candide.dev/wallet/plugins/recovery-with-guardians/

## Diagram

## Features

### Signature Aggregation
The backend aggregates guardians' signatures so that only one address executes the recovery transaction and pays the gas fees. This is similar to how the Gnosis-Safe frontend works when multiple owners for a multisig sign transactions before submitting them.

### Gas Sponsorship
Sponsoring transaction fees of the `confirmation` and `finilization` of the recovery will be a configurable option, allowing the backend service to optionally pay for the gas fees or requiring the guardians to cover the gas fees.

### Recovery Request Monitoring
The backend listens for recovery requests from and asks guardians to sign, tracking the owner's address.

### Signature Storage
The backend stores guardian signatures until all are collected, ensuring the recovery process proceeds securely

### Confirmation Execution
Once all signatures are gathered, the backend has the option to automatically executes the recovery transaction and sponsoring the gas fees.

### Finalization After Grace Period
After a grace period, the backend has the option to finalize the recovery by executing the finilization tx and sponsoring the gas fees, requiring no further action from guardians.

## Endpoints

### POST /recoveries/create
- Creates a new recovery request by a guardian with a lost signer of a Safe account. Can only be initated by guardians of the account.
- Body parameters:
- `account` (`EthereumAddress`): The Safe account address that the owner wants to recover
- `newOwners` (`EthereumAddress[]`): The new owners to the safe account
- `newThreshold` (`number`): The new threshold to the safe account
- `network` (`chainId`): The network where the safe account resides
- `signature`: A signature from the guardian for a message containing the address of the safe, new owners of the safe, chainId, module address, and a nonce.

### GET /recoveries/fetchByAddress
- Fetches recovery requests made by end-users of their Safe account
- Query parameters:
- `account` (`EthereumAddress`): The Safe account address that the owner wants to recover
- `network` (`chainId`): The network where the safe account resides
- `nonce` (`number`): Recovery module contract nonce
- Response: `IRecoveryRequest`

[{ 
    emoji: { type: String, required: true },
    account: { type: String, required: true },
    chainId: { type: number, required: true },
    newOwners: { type: String[], required: true },
    newThreshold: { type: number, required: true },
    nonce: { type: Number, required: true },
    signatures: [[{ type: String, required: true }]],
    executeTransactionHash: { type: String, required: false, default: "" },
    finalizeTransactionHash: { type: String, required: false, default: "" },
    status: { type: String, required: true },
    discoverable: { type: Boolean, default: true },
  },
  { timestamps: true }
}]

type IStatus = "PENDING" | "EXECUTED" | "FINALIZED" | 'FINALIZATION-IN-PROGRESS' | "FAILED";

### GET /recoveries/fetchById
- Fetch a recovery request by ID
- Query parameters:
- `id`: Recovery request ID
- Response: `IRecoveryRequest`

{ 
    emoji: { type: String, required: true },
    account: { type: String, required: true },
    network: { type: String, required: true },
    newOwners: { type: String[], required: true },
    newThreshold: { type: number, required: true },
    nonce: { type: Number, required: true },
    signatures: [[{ type: String, required: true }]],
    executeTransactionHash: { type: String, required: false, default: "" },
    finalizeTransactionHash: { type: String, required: false, default: "" },
    status: { type: String, required: true },
    discoverable: { type: Boolean, default: true },
  },
  { timestamps: true }
}

type IStatus = "PENDING" | "EXECUTED" | "FINALIZED" | 'FINALIZATION-IN-PROGRESS' | "FAILED";

### POST /recoveries/sign
- Collects a guardian siganture to store for later confirmation and finilization
- Body parameters:
- `id`: Recovery request ID
- `signer`: The guardian public address
- `signature`: The signature for the message hash of the guardian confirmation of recovery

### POST /recoveries/finalize/{id}
- Finalize a recovery request by ID
- Query parameters:
- `id`: recovery request ID

### POST /alerts/subscribe
- Subscribes to any recovery attempt to his account, whether through the backend or onchain
- Query parameters:
- `account`: The Safe account address that should be monitored
- `email`: The email target to receive those alerts
- `signature`: A signature from the account containing the email and a nonce

## Error Handling
- The API uses standard HTTP status codes to indicate the success or failure of a request.
- Error responses will include a JSON object with the following structure:

  {
    "error": {
      "code": 404,
      "message": "Recovery request not found"
    }
  }

## Versioning
- The current version of the API is `v1`.
- The version is included in the URL path (e.g., `/v1/recoveries`).

## Documentation

- Detailed documentation for the API will be available at https://docs.candide.dev.