mars-protocol · api

Package: mars-protocol · Workspace version: 0.1.0 · Module: api

This reference follows declared modules and public syntax, including public implementation methods. Function bodies and constant values are omitted. Feature conditions are retained. Private-module re-exports and trait resolution require the compiler; not every declaration is a root import.

api::DiscoverRequest

Request body for POST /v1/discover.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct DiscoverRequest {
/// Exact canonical [`crate::entry::EntryType`] name. Omit to search every

/// entry type; clause fragments and aliases are rejected.

pub entry_type: Option<String>,
/// Filter conditions joined with logical AND.

#[serde(default)]
pub conditions: Vec<DiscoverCondition>,
/// Maximum number of results.

pub limit: Option<u64>,
/// Opaque, expiring HMAC-authenticated keyset cursor from the preceding page.

#[serde(skip_serializing_if = "Option::is_none")]
pub cursor: Option<String>
}

Source line: 19.

api::DiscoverCondition

A single structured discovery filter.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct DiscoverCondition {
/// Allowlisted canonical field path evaluated by the structured API.

/// Arbitrary `itemData` traversal is available only through raw MARS-QL.

pub field: String,
/// Canonical operator compatible with the selected field's value type.

pub op: String,
/// Typed scalar or bounded array required by the selected field/operator.

pub value: serde_json::Value
}

Source line: 37.

api::MarsQlRequest

Request body for POST /v1/discover/marsql.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct MarsQlRequest {
/// A MARS-QL `DISCOVER` expression.

pub query: String
}

Source line: 51.

api::TransferOfferRequest

Request body for creating a signed transfer offer.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct TransferOfferRequest {
/// DID invited to become the entry's publisher.

pub recipient_did: String,
/// Current entry sequence covered by the owner's signature.

pub entry_sequence: u64,
/// Server-verifiable expiry for this offer.

pub expires_at: chrono::DateTime<chrono::Utc>,
/// Owner signature over the canonical transfer-offer payload.

pub signature: EntrySignature
}

Source line: 60.

api::TransferRequest

Backward-compatible Rust alias for the former direct-transfer request.

The HTTP route now creates an offer; it never changes ownership directly.

pub type TransferRequest = TransferOfferRequest;

Source line: 74.

api::TransferOffer

Persisted transfer-offer state returned by transfer endpoints.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct TransferOffer {
/// Registry-generated immutable offer identifier.

pub offer_id: String,
/// Entry whose ownership may change.

pub entry_did: String,
/// Current owner derived from the authenticated principal.

pub owner_did: String,
/// Intended recipient.

pub recipient_did: String,
/// Entry sequence signed by the owner.

pub entry_sequence: u64,
/// Offer creation time.

pub created_at: chrono::DateTime<chrono::Utc>,
/// Offer expiry.

pub expires_at: chrono::DateTime<chrono::Utc>,
/// Current state.

pub status: TransferOfferStatus,
/// Owner's signature over the offer payload.

pub owner_signature: EntrySignature
}

Source line: 80.

api::TransferOfferStatus

Closed transfer-offer state machine.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum TransferOfferStatus {
    Offered,
    Accepted,
    Declined,
    Expired,
}

Source line: 105.

api::TransferAcceptRequest

Request body for accepting a transfer offer.

entry must preserve every publisher-authored field from the offered snapshot, bind publisherDid and its signature key controller to the authenticated recipient, advance the registry sequence, and omit registry-managed verifiableAttestations. The recipient must re-sign the complete canonical publisher payload; the owner's offer signature never substitutes for the recipient entry signature.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct TransferAcceptRequest {
/// Complete replacement entry signed by the recipient.

pub entry: MarsEntry
}

Source line: 123.

api::TransferDeclineRequest

Request body for declining a transfer offer.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct TransferDeclineRequest {
/// Optional non-authoritative explanation retained in private audit data.

pub reason: Option<String>
}

Source line: 132.

api::AttestationRequest

Request body for POST /v1/attestations.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct AttestationRequest {
/// DID of the entry receiving the attestation.

pub entry_did: String,
/// Verifiable attestation payload.

pub attestation: serde_json::Value
}

Source line: 141.

api::AttestationQuery

Query controls for reading separately stored attestations.

#[derive(Debug, Clone, Copy, 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 AttestationQuery {
/// Include credentials whose expiration date has passed.

#[serde(default)]
pub include_expired: bool,
/// Include credentials revoked in the local registry.

#[serde(default)]
pub include_revoked: bool
}

Source line: 156.

api::VerifiableAttestationRecord

Canonical, separately stored OAS verifiable attestation.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct VerifiableAttestationRecord {
/// SHA-256 identifier of the JCS-canonical credential.

pub attestation_id: String,
/// Subject entry DID.

pub entry_did: String,
/// Issuer DID derived from and bound to the authenticated principal.

pub issuer_did: String,
/// Canonical OAS Verifiable Credential.

pub credential: serde_json::Value,
/// Credential issuance time.

pub issued_at: chrono::DateTime<chrono::Utc>,
/// Optional credential expiration time.

pub expires_at: Option<chrono::DateTime<chrono::Utc>>,
/// Local revocation time, when revoked.

pub revoked_at: Option<chrono::DateTime<chrono::Utc>>,
/// Registry acceptance time.

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

Source line: 169.

api::ReportRequest

Request body for POST /v1/report.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ReportRequest {
/// DID of the reported entry.

pub entry_did: String,
/// Human-readable report reason.

pub reason: String,
/// Optional supporting evidence.

pub evidence: Option<serde_json::Value>
}

Source line: 192.

api::BondProvisionRequest

Admin request for provisioning a registry-local bond.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct BondProvisionRequest {
pub bond_id: String,
pub publisher_did: String,
pub entry_did: String,
pub amount: BondAmount,
pub currency: String,
pub status: BondStatus
}

Source line: 205.

api::FederationPeerUpdateRequest

Peer-controlled request for registering or changing its endpoint metadata.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederationPeerUpdateRequest {
pub endpoint: String,
pub grpc_endpoint: Option<String>,
#[serde(default)]
pub agreement_ids: Vec<String>
}

Source line: 218.

api::ReportResponse

Response body for a successfully accepted report.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct ReportResponse {
/// Stable acceptance state.

pub status: ReportStatus,
/// DID of the reported entry.

pub entry_did: String
}

Source line: 229.

api::ReportStatus

Closed state set for accepted reports.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub enum ReportStatus {
    /// The report was accepted and recorded.
    Reported,
}

Source line: 240.

api::EntryVersionsQuery

Query parameters for GET /v1/entries/{did}/versions.

#[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 EntryVersionsQuery {
/// Maximum number of versions 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>,
/// Registry sequence of the last version returned by the preceding page.

///

/// Clients must treat the value as opaque and echo it unchanged.

#[cfg_attr(feature = "contracts", schemars(regex(pattern = r"^[1-9][0-9]*$")))]
#[cfg_attr(feature = "contracts", param(pattern = r"^[1-9][0-9]*$"))]
pub cursor: Option<String>
}

Source line: 253.

api::EntryVersionsResponse

Response body for GET /v1/entries/{did}/versions.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct EntryVersionsResponse {
/// DID shared by every returned version.

pub entry_did: String,
/// Entry snapshots ordered newest first.

pub versions: Vec<MarsEntry>,
/// Total number of stored versions for this DID.

pub total_count: u64,
/// Last-seen registry sequence 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
}

Source line: 271.

api::EntryLineageResponse

Response body for GET /v1/entries/{did}/lineage.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct EntryLineageResponse {
/// DID of the resolved entry.

pub entry_did: String,
/// Publisher lineage summary, or `null` when the entry has no lineage.

pub lineage: Option<LineageReference>
}

Source line: 289.

api::HealthResponse

Response body for GET /v1/health.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct HealthResponse {
/// Service status.

pub status: String,
/// MARS protocol version.

pub version: String,
/// DID of the serving registry.

pub registry_did: String
}

Source line: 300.

api::DeepHealthResponse

Response body for GET /v1/health/deep.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct DeepHealthResponse {
/// Aggregate status: `ok`, `degraded`, or `down`.

pub status: String,
/// Stable, lexicographically keyed subsystem results.

pub checks: BTreeMap<String, String>
}

Source line: 313.

api::ErrorResponse

Canonical JSON error body returned by MARS HTTP endpoints.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct ErrorResponse {
/// Machine-readable MARS error code such as `MARS-008`.

pub error_code: String,
/// Human-readable diagnostic.

pub message: String,
/// HTTP status echoed in the body.

pub http_status: u16
}

Source line: 324.

api::SiwsChallengeRequest

Request body for POST /v1/auth/siws/challenge.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SiwsChallengeRequest {
/// Required audience shown to the signer.

#[cfg_attr(feature = "contracts", schemars(length(min = 1)))]
pub audience: String,
/// HMR DID required to satisfy the challenge.

#[cfg_attr(feature = "contracts", schemars(inner(regex(pattern = r"^did:oas:"))))]
pub hmr_did: Option<String>,
/// Optional HMR, MHR, or ENR root DID.

pub root_did: Option<String>,
/// Sigil chain identifier.

pub chain_id: Option<String>,
/// Browser or application origin.

pub origin: Option<String>
}

Source line: 337.

api::SiwsChallenge

SIWS challenge issued by MARS and signed by a Sigil wallet.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SiwsChallenge {
/// Protocol discriminator. Current value is `sigil.signin`.

#[cfg_attr(feature = "contracts", schemars(regex(pattern = r"^sigil\.signin$")))]
pub kind: String,
/// SIWS wire version. Current value is `1`.

#[cfg_attr(feature = "contracts", schemars(range(min = 1, max = 1)))]
pub version: u8,
/// Request origin.

pub origin: String,
/// Sign-in audience.

pub audience: String,
/// Sigil chain identifier.

pub chain_id: String,
/// Single-use challenge nonce.

pub nonce: String,
/// Single-use request identifier.

pub request_id: String,
/// HMR DID expected to sign.

#[cfg_attr(feature = "contracts", schemars(regex(pattern = r"^did:oas:")))]
pub hmr_did: String,
/// Optional authorizing HMR, MHR, or ENR root DID.

#[serde(skip_serializing_if = "Option::is_none")]
pub root_did: Option<String>,
/// Challenge issue time in Unix milliseconds.

pub issued_at_ms: i64,
/// Challenge expiry time in Unix milliseconds.

pub expires_at_ms: i64
}

Source line: 356.

api::SiwsChallengeResponse

Response body for POST /v1/auth/siws/challenge.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SiwsChallengeResponse {
/// Challenge that must be echoed during verification.

pub challenge: SiwsChallenge
}

Source line: 389.

api::SiwsSignedResponse

Signed SIWS response produced by a Sigil wallet.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SiwsSignedResponse {
/// Response discriminator. Current value is `message`.

#[cfg_attr(feature = "contracts", schemars(regex(pattern = r"^message$")))]
pub kind: String,
/// Origin copied from the challenge.

pub origin: String,
/// Chain identifier copied from the challenge.

pub chain_id: String,
/// DID of the HMR signer.

#[cfg_attr(feature = "contracts", schemars(regex(pattern = r"^did:oas:")))]
pub signer_did: String,
/// Canonical SIWS message.

pub message: String,
/// Hex-encoded Ed25519 signature.

pub signature: String,
/// Hex-encoded Ed25519 public key.

pub signer_public_key: String,
/// Hex-encoded BLAKE3 transcript digest.

pub digest: String,
/// Canonical transcript signed by the wallet.

pub transcript: String
}

Source line: 398.

api::SiwsVerifyRequest

Request body for POST /v1/auth/siws/verify.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SiwsVerifyRequest {
/// Originally issued challenge.

pub challenge: SiwsChallenge,
/// Wallet-signed response.

pub response: SiwsSignedResponse,
/// Expected audience; must equal the challenge audience.

pub audience: String
}

Source line: 425.

api::SiwsVerifyResponse

Response body for a successful SIWS verification.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SiwsVerifyResponse {
pub hmr_did: String,
pub root_did: String,
pub root_kind: String,
pub signer_public_key: String,
pub expires_at_ms: i64,
pub session_token: String,
pub session_expires_at_ms: i64
}

Source line: 438.

api::SiwsSessionResponse

Response body for GET /v1/auth/session.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SiwsSessionResponse {
pub hmr_did: String,
pub root_did: String,
pub root_kind: String,
pub expires_at_ms: i64
}

Source line: 452.

Source provenance

Source: mars-protocol/src/api.rs · SHA-256 b60a5e1d511b3d6f4ed513601d45c699a842160a170ca6f3cee225814617b5a4. Package overview.

mars-protocol · api

On this page