sigil-core · recovery

pub const BLOCKS_PER_DAY: u64;

pub const MIN_RECOVERY_TIMELOCK_BLOCKS: u64;

pub const MAX_RECOVERY_TIMELOCK_BLOCKS: u64;

pub const DEFAULT_RECOVERY_TIMELOCK_BLOCKS: u64;

pub const MAX_RECOVERY_GUARDIANS: usize;

pub const MIN_RECOVERY_GUARDIANS: usize;

pub const RECOVERY_DOMAIN_TAG: &[u8];

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RecoveryGuardian {
pub guardian_did: String,
/// 32-byte Ed25519 public key, hex-encoded (no `0x` prefix).

pub guardian_pubkey_hex: String,
/// Vote weight. Default 1; weighted thresholds support tiered guardians

/// (e.g. 1 spouse weight 2 + 3 friends weight 1, threshold 3).

pub weight: u32
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RecoveryConfig {
pub subject_did: String,
pub guardians: Vec<RecoveryGuardian>,
/// Total weight required to authorize a recovery. Must be ≥ 1 and

/// ≤ sum(guardians.weight). Recommended floor: ⌈sum × 0.6⌉.

pub threshold: u32,
/// Number of blocks the timelock holds open after `InitiateRecovery`.

pub timelock_blocks: u64,
/// 32-byte Ed25519 public key (hex) of the panic-abort key. The user

/// holds the corresponding private key offline.

pub panic_pubkey_hex: String,
pub registered_at_height: u64
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum RecoveryStatus {
    /// Initiated; collecting guardian authorizations and waiting for timelock.
    Pending,
    /// Threshold met AND timelock elapsed; ready to finalize.
    Ready,
    /// Pubkey has been rotated; ceremony archived.
    Finalized,
    /// Aborted by the panic key, the original owner, or by guardian
    /// revocation. No further state changes.
    Aborted { reason: AbortReason },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum AbortReason {
    PanicKey,
    OriginalOwner,
    GuardianRevocation,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GuardianAuthorization {
pub guardian_did: String,
pub guardian_pubkey_hex: String,
/// 64-byte Ed25519 signature over the canonical payload (hex).

pub signature_hex: String,
pub recorded_at_height: u64
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RecoveryCeremony {
pub ceremony_id: String,
pub subject_did: String,
pub initiated_at_height: u64,
/// Earliest block at which `FinalizeRecovery` may succeed.

pub finalize_after_height: u64,
/// 32-byte Ed25519 public key (hex) that will replace the subject's

/// current pubkey on finalize.

pub new_pubkey_hex: String,
pub authorizations: Vec<GuardianAuthorization>,
pub status: RecoveryStatus
}

pub fn accumulated_weight(&self, config: &RecoveryConfig) -> u32;

pub fn threshold_met(&self, config: &RecoveryConfig) -> bool;

pub fn timelock_expired_at(&self, current_height: u64) -> bool;

pub fn finalizable_at(&self, current_height: u64, config: &RecoveryConfig) -> bool;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RegisterRecoveryData {
pub subject_did: String,
pub guardians: Vec<RecoveryGuardian>,
pub threshold: u32,
pub timelock_blocks: u64,
pub panic_pubkey_hex: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct InitiateRecoveryData {
pub subject_did: String,
pub new_pubkey_hex: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AddRecoveryAuthorizationData {
pub ceremony_id: String,
pub guardian_did: String,
pub guardian_pubkey_hex: String,
/// 64-byte Ed25519 signature over `recovery_signing_bytes(ceremony_id,

/// subject_did, new_pubkey_hex)`. Hex-encoded.

pub signature_hex: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AbortRecoveryData {
pub ceremony_id: String,
/// The Ed25519 public key that signed the abort. The executor checks

/// this matches either the registered panic key or the subject's

/// current pubkey.

pub aborter_pubkey_hex: String,
pub signature_hex: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FinalizeRecoveryData {
pub ceremony_id: String
}

pub fn recovery_signing_bytes(
    ceremony_id: &str,
    subject_did: &str,
    new_pubkey_hex: &str,
) -> Vec<u8>;

pub fn abort_signing_bytes(ceremony_id: &str) -> Vec<u8>;

pub fn compute_ceremony_id(subject_did: &str, initiated_at_height: u64) -> String;

pub fn validate_recovery_config(config: &RecoveryConfig) -> Result<(), CoreError>;