The recovery ceremony rotates a user’s signing key when the original key is lost. It is coordinated by a pre-registered guardian group under FROST threshold signatures. A 30-day timelock and a panic-abort key protect against guardian compromise. This page covers the on-chain protocol surface. For an end-to-end walkthrough, see Set up social recovery.

​
Components

ComponentWhere it lives
FROST primitives (DKG, threshold signing, ceremony state machine)aegis/aegis-keys/src/{threshold,recovery}.rs
On-chain types and transactionsnode/sigil-core/src/recovery.rs
Executor and state transitionsnode/sigil-node/src/executor_recovery.rs
Wallet UXFirst-party SDK + future hardware-wallet integrations

​
Why 30 days

The 30-day default timelock balances guardian compromise risk against operator inconvenience. Shorter timelocks (e.g. 7 days) leave too little window to detect malicious guardian collusion. The default is configurable per registration; operators that need shorter windows for service accounts can set the timelock to as short as 24 hours, but the default for human users is 30 days.

​
Transactions

VariantPurpose
RegisterRecoveryRegister a guardian group, threshold, panic-key pubkey, and timelock.
UpdateRecoveryUpdate guardian membership or threshold (requires guardian signatures).
InitiateRecoveryStart a recovery with the guardian threshold signature. Starts the timelock.
AbortRecoveryCancel a recovery using the pre-registered panic key.
FinalizeRecoveryAfter timelock expiry, rotate the DID’s signing key to the new public key.

​
Recovery state

pub enum RecoveryState {
    None,
    Registered {
        guardians: Vec<Did>,
        threshold: u32,
        panic_pubkey: PublicKey,
        timelock_blocks: u64,
    },
    InProgress {
        new_pubkey: PublicKey,
        initiated_at_height: u64,
        finalisable_at_height: u64,
    },
}

​
Address stability

Because Sigil derives addresses from DIDs (not from public keys), recovery rotates the signing key while leaving the address unchanged. Balances, NFTs, mailbox capabilities, mandates, and every other state reference stay intact. The DID’s signing material is updated; nothing else moves.

​
Guardian dynamics

  • Guardian membership is mutable through UpdateRecovery signed by the existing threshold. Adding or removing a guardian requires the current threshold to approve.
  • A revoked guardian’s DID record is checked at recovery initiation; revoked guardians cannot participate in a recovery signature.
  • Guardians can themselves be MHRs operating under their own FROST thresholds.

​
Panic abort

The panic key is registered alongside the guardian group. During the 30-day timelock, a single signature from the panic key cancels the in-progress recovery. The panic key:
  • Should be held in a different medium than the primary signing key (paper, safe-deposit box, separate hardware wallet).
  • Has no other authority. It cannot sign transfers, register mandates, or initiate transactions other than AbortRecovery.
After a panic abort, the recovery state returns to Registered and the guardian group is flagged for review.

​
Multi-human roots

For mhr DIDs, recovery is rarely needed — the FROST threshold is itself a redundancy mechanism. When a participant loses their share, the remaining t participants can authorise a DKG refresh through UpdateRecovery.

​
RPC

MethodReturns
sigil_getRecoveryRegistrationThe registered recovery group for a DID.
sigil_getRecoveryStatusThe current recovery state.
sigil_getRecoveryGuardiansThe guardian list (also accessible via the registration record).

​
Implementation

  • FROST primitives: aegis/aegis-keys/src/{threshold,recovery}.rs.
  • On-chain types: node/sigil-core/src/recovery.rs.
  • Executor: node/sigil-node/src/executor_recovery.rs.

​
See also