> For the complete documentation index, see [llms.txt](https://shinkalabs.gitbook.io/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shinkalabs.gitbook.io/hub/andromeda/guides/run-recovery.md).

# Run a recovery

Two paths, both governed by the on-chain [`rules-policy`](/hub/andromeda/guides/deploy-policy/rules-policy.md) program: a single-transaction **primary** path, and a staged **M-of-N quorum** path. Both are challenge-based and gas-sponsored: the user signs a 32-byte challenge off-chain, Andromeda pays the gas and submits.

{% hint style="info" %}
Recovery is opt-in per deployment. Exact paths and bodies are in the [OpenAPI spec](https://api.andromedainfra.pro/openapi.json).
{% endhint %}

## Primary recovery (one transaction)

1. `POST /v1/recovery/primary/challenge` with the dWallet address and the 32-byte message hash. Returns `challengeBase64`, `expectedNonce`, and the primary's scheme.
2. The user signs `challengeBase64` with the primary owner credential (any wallet, a passkey, an OAuth-linked identity).
3. `POST /v1/recovery/primary/submit` with `signatureBase64` and `expectedNonce`. Andromeda assembles the transaction, adds a precompile instruction to verify the signature, pays the gas, broadcasts, and returns `txSignature` and `messageApprovalAddress`.

See the quickstart in [Recovery flow](/hub/andromeda/getting-started/recovery.md).

## Quorum recovery (staged, unbounded size)

A single Solana transaction cannot carry an arbitrary number of signatures, so the quorum path stages member contributions in a program-derived account (PDA). See [Quorum via PDA staging](/hub/andromeda/on-chain-programs/quorum-staging.md) for the on-chain mechanics.

1. **Open a session.** `POST /v1/recovery/quorum/session/open/challenge` returns a challenge for the session opener; the opener signs it; `POST /v1/recovery/quorum/session/open` creates the session PDA and snapshots the current roster into it. The snapshot means a roster change made after this point does not race the session.
2. **Members contribute.** For each member: `POST /v1/recovery/quorum/session/contribute/challenge` returns that member's challenge and the expected nonce; the member signs it; `POST /v1/recovery/quorum/session/contribute` records the signature in the PDA. Each contribution is its own transaction, so the number of members is not bounded by transaction size.
3. **Track progress.** `GET /v1/recovery/quorum/session/{address}` shows how many of the M required contributions are in.
4. **Finalize.** Once M contributions are recorded, `POST /v1/recovery/quorum/session/finalize` runs the cross-program call into Ika. Heavier call, longer timeout.
5. **Close.** `POST /v1/recovery/quorum/session/close` reclaims the PDA rent.

## What is verified on-chain

* Every member signature and the primary signature is checked by a Solana runtime precompile (Ed25519, Secp256k1, Secp256r1, or full WebAuthn for quorum members). Andromeda only assembles and submits; it cannot forge a recovery. See [Zero attestor](/hub/andromeda/concepts/zero-attestor.md).
* The daily limit and cooldown configured on the policy are enforced using the Solana clock.
* Per-flow replay nonces (`next_primary_recover_nonce`, `next_session_nonce`) block replays. Always read the nonce from the `challenge` response.

## Operational notes

* Use [`Idempotency-Key`](/hub/andromeda/guides/idempotency.md) on every submit and contribute, so a retry does not double-record.
* If a session stalls (not enough members contribute), close it to reclaim the rent and open a fresh one.
* Configuration (who the primary is, the roster, the thresholds, the limits) is set separately. See [Configure recovery](/hub/andromeda/guides/configure-recovery.md).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shinkalabs.gitbook.io/hub/andromeda/guides/run-recovery.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.