sigil-wasm · host

pub mod capability;

pub const STATE_GET: &str;

pub const STATE_SET: &str;

pub const STATE_DELETE: &str;

pub const CALLER_DID: &str;

pub const BLOCK_HEIGHT: &str;

pub const NATIVE_TRANSFER: &str;

pub const LOG: &str;

pub const EMIT_EVENT: &str;

pub const RESOLVE_IDENTITY: &str;

pub const VERIFY_LINEAGE: &str;

pub const SEND_ZONE_MESSAGE: &str;

pub const DISPATCH_COMPUTE: &str;

pub const RECORD_MANDATE_SPEND: &str;

pub const READ_COMPUTE_RECEIPT: &str;

pub const READ_MACA_QUORUM_PROOF: &str;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostLogLevel {
    Debug = 0,
    Info = 1,
    Warn = 2,
    Error = 3,
}

pub fn from_u32(v: u32) -> Self;

pub trait HostBackend: Send + Sync {
    /// The DID of the contract currently executing. The runtime passes
    /// this on every call so the backend can scope state, events, and
    /// authorization checks per contract.
    fn contract_did(&self) -> &str;

    /// Returns `true` if `host_fn` is in the contract's allowlist.
    /// Implementations should always check the live contract record;
    /// this is consulted by the runtime as a defense-in-depth gate
    /// before invoking the actual backend method.
    fn allows_host_fn(&self, host_fn: &str) -> bool;

    /// DID of the account/app that submitted the current contract call.
    ///
    /// This is consensus input carried by the signed `CallContract`
    /// transaction, not ambient process state.
    fn caller_did(&self) -> &str ;

    /// Current finalized block height visible to this contract call.
    fn block_height(&self) -> Result<u64, HostError> ;

    /// Transfer native micro-MINT from this contract's account to `recipient`.
    ///
    /// Backends must stage the debit/credit and commit it only if the enclosing
    /// WASM call succeeds.
    fn native_transfer(&mut self, _recipient: &str, _amount: u64) -> Result<(), HostError> ;

    // --- State (always permitted; gated by allowlist anyway) -------

    fn state_get(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>, HostError>;
    fn state_set(&mut self, key: &[u8], value: &[u8]) -> Result<(), HostError>;
    fn state_delete(&mut self, key: &[u8]) -> Result<(), HostError>;

    // --- Logging + events -----------------------------------------

    fn log(&mut self, level: HostLogLevel, message: &str);
    fn emit_event(
        &mut self,
        topic: &str,
        indexed: &[(String, Vec<u8>)],
        data: &[u8],
    ) -> Result<(), HostError>;

    // --- Identity (read-only) -------------------------------------

    /// Resolve the OAS identity document for `did`. `None` if not
    /// registered. Consensus-deterministic implementations must read
    /// from on-chain identity storage, not from off-chain resolvers.
    fn resolve_identity(&self, did: &str) -> Result<Option<Vec<u8>>, HostError>;

    /// Verify that `did` has a valid lineage chain back to a registered
    /// human root. Returns `true` if the chain validates against
    /// on-chain identity storage. Pure read-only.
    fn verify_lineage(&self, did: &str) -> Result<bool, HostError>;

    // --- Cross-zone messaging -------------------------------------

    /// Queue a message for `target_zone`. Must NOT execute the target
    /// inline — message delivery is a separate consensus step.
    fn send_zone_message(
        &mut self,
        target_zone: &str,
        target_module: Option<&str>,
        payload: &[u8],
    ) -> Result<(), HostError>;

    // --- Compute marketplace (privileged) -------------------------

    /// Dispatch a compute job into the marketplace. The backend must
    /// verify that:
    ///   - the contract has an active mandate / budget
    ///   - the requested verification tier is supported by at least one
    ///     registered provider
    ///   - the call site holds the `dispatch_compute` capability
    ///
    /// Returns the assigned `job_id` on success.
    fn dispatch_compute(&mut self, request: &ComputeDispatchRequest) -> Result<String, HostError>;

    /// Charge the contract's mandate by `amount` micro-MINT. Used by
    /// non-compute spend paths (e.g. paying a service contract).
    fn record_mandate_spend(
        &mut self,
        mandate_id: &str,
        amount: u64,
        memo: Option<&str>,
    ) -> Result<(), HostError>;

    // --- Verified read paths --------------------------------------

    /// Return the receipt record for `receipt_id`, or `None`. The
    /// backend MUST only return receipts that are settled and within
    /// the chain's challenge window (or already past it).
    fn read_compute_receipt(&self, receipt_id: &str) -> Result<Option<ReceiptView>, HostError>;

    /// Return a MACA quorum proof for a (epoch_id, work_id) tuple, or
    /// `None`. The backend MUST only return finalised quorum proofs.
    fn read_maca_quorum_proof(
        &self,
        epoch_id: u64,
        work_id: &SigilHash,
    ) -> Result<Option<MacaQuorumProofView>, HostError>;
}

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ReceiptView {
pub receipt_id: String,
pub job_id: String,
pub provider_did: String,
pub consumer_did: String,
pub model_id: String,
pub output_commitment: SigilHash,
pub input_commitment: SigilHash,
pub model_commitment: Option<SigilHash>,
pub verification_tier: String,
pub cost_micro_mint: u64,
pub settled: bool
}

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct MacaQuorumProofView {
pub epoch_id: u64,
pub work_id: SigilHash,
pub agreeing: u32,
pub total_validators: u32,
pub finalised: bool
}

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ComputeDispatchRequest {
pub model_id: String,
pub input_commitment: SigilHash,
pub code_commitment: Option<SigilHash>,
pub model_commitment: Option<SigilHash>,
pub max_cost_micro_mint: u64,
pub verification_tier: String,
pub mandate_id: String
}