mars-protocol · anchoring

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum AnchorState {
    /// No anchor has been requested for the current entry snapshot.
    #[default]
    Unanchored,
    /// Durable work exists and is ready for a worker.
    Pending,
    /// A provider accepted the submission but has not confirmed it.
    Submitted,
    /// The provider reported final confirmation.
    Confirmed,
    /// The latest attempt failed and is eligible for a bounded retry.
    Failed,
    /// Retry policy or an administrator ended processing permanently.
    Abandoned,
}

#[must_use]
pub const fn as_str(self) -> &'static str;

#[must_use]
pub const fn is_confirmed(self) -> bool;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum AnchorOutboxState {
    Pending,
    Claimed,
    Submitted,
    Confirmed,
    Failed,
    Abandoned,
}

#[must_use]
pub const fn as_str(self) -> &'static str;

#[must_use]
pub const fn projection(self) -> AnchorState;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum AnchorOperation {
    Create,
    Update,
    Revoke,
    Transfer,
    Attest,
}

#[must_use]
pub const fn as_str(self) -> &'static str;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum AnchorReceiptState {
    Submitted,
    Confirmed,
}

#[must_use]
pub const fn as_str(self) -> &'static str;

#[must_use]
pub const fn outbox_state(self) -> AnchorOutboxState;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct AnchorReceiptRecord {
/// Adapter-defined idempotency key for this observation.

pub receipt_key: String,
/// Provider-neutral external transaction or operation identifier.

pub transaction_id: String,
/// Submitted or confirmed state represented by this receipt.

pub state: AnchorReceiptState,
/// Optional finalized ledger height.

#[serde(skip_serializing_if = "Option::is_none")]
pub block_height: Option<u64>,
/// Optional provider-neutral proof document.

#[serde(skip_serializing_if = "Option::is_none")]
pub proof: Option<serde_json::Value>,
/// Time the adapter observed this state.

pub observed_at: chrono::DateTime<chrono::Utc>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct AnchorStatusRecord {
pub intent_id: String,
pub entry_did: String,
pub sequence: u64,
pub operation: AnchorOperation,
pub state: AnchorOutboxState,
pub attempts: u32,
pub available_at: chrono::DateTime<chrono::Utc>,
#[serde(skip_serializing_if = "Option::is_none")]
pub transaction_id: Option<String>,
pub created_at: chrono::DateTime<chrono::Utc>,
pub updated_at: chrono::DateTime<chrono::Utc>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub receipts: Vec<AnchorReceiptRecord>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(
    feature = "contracts",
    derive(schemars::JsonSchema, utoipa::IntoParams)
)]
#[cfg_attr(feature = "contracts", into_params(parameter_in = Query))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct AnchorListQuery {
/// Maximum number of anchor records to return. The server clamps this to

/// its configured maximum page size.

#[cfg_attr(feature = "contracts", schemars(range(min = 1)))]
#[cfg_attr(feature = "contracts", param(minimum = 1))]
pub limit: Option<u64>,
/// Opaque URL-safe cursor returned by the preceding page.

///

/// The cursor identifies the last-seen `(sequence, createdAt, intentId)`

/// tuple. Clients must echo it unchanged and must not construct cursors.

#[cfg_attr(
        feature = "contracts",
        schemars(length(min = 1, max = 2048), regex(pattern = r"^[A-Za-z0-9_-]+$"))
    )]
#[cfg_attr(
        feature = "contracts",
        param(min_length = 1, max_length = 2048, pattern = r"^[A-Za-z0-9_-]+$")
    )]
pub cursor: Option<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct AnchorListResponse {
pub entry_did: String,
pub anchor_state: AnchorState,
/// Anchor records in stable ascending `(sequence, createdAt, intentId)`

/// order.

pub records: Vec<AnchorStatusRecord>,
/// Opaque last-seen tuple to pass to the next request, or `null` on the

/// final page.

pub cursor: Option<String>,
/// Whether another page exists after this response.

pub has_more: bool
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct AnchorControlResponse {
pub intent_id: String,
pub state: AnchorState
}