sigil-core · mandate

pub type MandateId = String;

pub type JobCategory = String;

pub type TokenId = String;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MandateStatus {
    Active,
    Paused,
    Expired,
    Revoked,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", content = "data", rename_all = "snake_case")]
pub enum AllowedCounterparties {
    /// Any DID allowed.
    Any,
    /// Restricted to an explicit allowlist of DIDs.
    Allowlist { dids: Vec<String> },
    /// Restricted to specific entity classes.
    Classes { classes: Vec<CounterpartyClass> },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CounterpartyClass {
    Human,
    Agent,
    Dao,
    Committee,
    AriseProvider,
    Contract,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SpendLimits {
/// Maximum amount permitted in a single transaction.

pub per_transaction_max: u128,
/// Maximum aggregate spend per epoch (or `None` for no per-period cap).

pub per_epoch_max: Option<u128>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MandateBudget {
/// Total amount granted.

pub total_amount: u128,
/// Amount already spent (recorded on-chain via `RecordMandateSpend`).

pub spent_amount: u128
}

pub fn remaining(&self) -> u128;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MandateScope {
/// Job categories the mandate may engage with (e.g., "audit",

/// "explorer-frontend", "infra-ops"). Empty means "any".

pub job_categories: Vec<JobCategory>,
/// Free-form tag commitments for explorer/UI.

pub tag_commitments: Vec<String>,
/// If `Some(true)` the mandate may *post* jobs; otherwise post-only flows

/// are denied. Used to distinguish hiring-only vs paying-only mandates.

pub may_post_jobs: bool,
/// If `Some(true)` the mandate may *accept* jobs as a worker.

pub may_accept_jobs: bool
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MilestonePolicy {
    /// Pay each milestone independently as it is attested.
    PerMilestone,
    /// Final lump-sum payment after all milestones are attested.
    LumpSumOnCompletion,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", content = "data", rename_all = "snake_case")]
pub enum ApprovalPolicy {
    /// Single signer (employer DID).
    Employer,
    /// Threshold of named DIDs.
    Committee {
        members: Vec<String>,
        threshold: u32,
    },
    /// Single trusted oracle DID.
    Oracle { oracle_did: String },
    /// Automated rule executed by a deterministic verifier (e.g., a CI hash
    /// match). The string is a verifier identifier.
    Automated { verifier_id: String },
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", content = "data", rename_all = "snake_case")]
pub enum DisputePolicy {
    /// DAO governance resolves disputes.
    DaoGovernance,
    /// Threshold of a named arbitration committee.
    Committee {
        members: Vec<String>,
        threshold: u32,
    },
    /// Single oracle resolves disputes.
    Oracle { oracle_did: String },
    /// Random selection from staked jurors. Selection rule is consensus-defined.
    StakedJury { minimum_stake: u128 },
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", content = "data", rename_all = "snake_case")]
pub enum RevocationPolicy {
    /// Issuer may revoke at any time.
    IssuerAtWill,
    /// Issuer may revoke only after a notice period in blocks.
    IssuerWithNotice { notice_blocks: u64 },
    /// Revocation requires DAO governance.
    DaoGovernance,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReputationImpactPolicy {
    /// Successful completion grants reputation; failure deducts.
    Standard,
    /// Successful completion grants reputation; failure has no impact.
    UpsideOnly,
    /// No reputation effect.
    None,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DelegationPolicy {
/// May the authorized actor issue sub-mandates?

pub allow_subdelegation: bool,
/// Max remaining-budget percentage that may be sub-delegated, in basis

/// points (0..=10_000).

pub max_subdelegated_basis_points: u16
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Mandate {
pub mandate_id: MandateId,
pub issuer_did: String,
pub authorized_actor_did: String,
pub scope: MandateScope,
pub budget: MandateBudget,
pub token_id: TokenId,
pub spend_limits: SpendLimits,
pub allowed_counterparties: AllowedCounterparties,
pub milestone_policy: MilestonePolicy,
pub approval_policy: ApprovalPolicy,
pub dispute_policy: DisputePolicy,
pub revocation_policy: RevocationPolicy,
pub reputation_impact: ReputationImpactPolicy,
pub revenue_share: Option<DistributionPolicy>,
pub delegation_policy: DelegationPolicy,
/// Optional inclusive expiration epoch. None means "no expiration"

/// (still subject to revocation).

pub expires_at_epoch: Option<u64>,
/// Per-mandate spend nonce, monotonically increasing.

pub nonce: u64,
pub status: MandateStatus
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SpendRequest<'a> {
/// DID of the actor attempting the spend.

pub actor_did: &'a str,
/// DID of the counterparty receiving funds.

pub counterparty_did: &'a str,
/// Counterparty class (used when allowed_counterparties is `Classes`).

pub counterparty_class: CounterpartyClass,
/// Token requested.

pub token_id: &'a str,
/// Amount requested.

pub amount: u128,
/// Job category for this spend.

pub job_category: &'a str,
/// Current chain epoch.

pub current_epoch: u64
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MandateClearance {
pub mandate_id: MandateId,
pub authorized_amount: u128,
pub remaining_after: u128
}

#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum MandateError {
    #[error("mandate is not active")]
    NotActive,
    #[error("mandate has expired")]
    Expired,
    #[error("actor does not match authorized actor")]
    UnauthorizedActor,
    #[error("token does not match mandate token")]
    TokenMismatch,
    #[error("amount exceeds per-transaction limit")]
    PerTxLimitExceeded,
    #[error("amount exceeds remaining budget")]
    BudgetExhausted,
    #[error("counterparty not allowed by mandate")]
    CounterpartyNotAllowed,
    #[error("job category not in mandate scope")]
    CategoryOutOfScope,
    #[error("mandate scope forbids this action")]
    ActionOutOfScope,
    #[error("subdelegation not permitted")]
    SubdelegationNotPermitted,
    #[error("subdelegation exceeds permitted fraction")]
    SubdelegationExceedsCap,
    #[error("revenue shares must total 10000 basis points")]
    RevenueShareInvalid,
}

pub fn authorize_spend(
        &self,
        req: &SpendRequest<'_>,
    ) -> Result<MandateClearance, MandateError>;

pub fn authorize_subdelegation(&self, child: &Mandate) -> Result<(), MandateError>;