Capability Discovery

A listing advertises a server and grants nothing by itself

Registration is per kernel and out of band. The operator admits a server through configuration or a control-plane API, after its signed manifest validates and verifies; the manifest carries tool schemas, side-effect flags, latency hints, required permissions, and advertised pricing. An update needs a fresh signed manifest, since there is no partial update.

A listing reaches further. The publishing operator signs a GenericListingArtifact (schema chio.registry.listing.v1, in the chio-listing crate) into a generic registry. Each listing has a status (Active, Suspended, Superseded, Revoked, Retired), an actor kind (ToolServer, CredentialIssuer, CredentialVerifier, LiabilityProvider), and a GenericListingBoundary that defaults to:

impl Default for GenericListingBoundary {
    fn default() -> Self {
        Self {
            visibility_only: true,
            explicit_trust_activation_required: true,
            automatic_trust_admission: false,
        }
    }
}

The listing crate's validate rejects a listing that drops these guarantees. A listing stays visible only, with no activation authority, until an operator activates it.

The provider signs the price separately, so listing and price rotate apart

A ListingPricingHint attaches price per call, SLA, recent receipt volume, and revocation rate to a published listing. The provider's key signs it and the publishing operator signs the listing, so publication and pricing rotate independently. Its schema is chio.marketplace.listing-pricing-hint.v1 (LISTING_PRICING_HINT_SCHEMA).

pub struct ListingPricingHint {
    pub schema: String,
    /// Listing this hint applies to.
    pub listing_id: String,
    /// Namespace of the listing (must match the listing body).
    pub namespace: String,
    /// Provider / operator advertising the price (must match the listing
    /// publisher).
    pub provider_operator_id: String,
    /// Capability scope prefix covered by this hint (e.g.
    /// `"tools:search"` or `"tools:search:*"`). Queries filter against this.
    pub capability_scope: String,
    /// Fixed price charged per invocation under the advertised scope.
    pub price_per_call: MonetaryAmount,
    /// Advertised SLA for invocations under this hint.
    pub sla: ListingSla,
    /// Rolling revocation rate over recent invocations, in basis points.
    /// `0` means "no revocations in the window"; `10_000` means "100%".
    pub revocation_rate_bps: u32,
    /// Number of receipts the provider has produced in the recent window.
    pub recent_receipts_volume: u64,
    /// Unix seconds when the hint was issued.
    pub issued_at: u64,
    /// Unix seconds when the hint expires. Past expiry, the hint is stale
    /// and the listing falls out of the marketplace.
    pub expires_at: u64,
}

Two fields let a caller judge operator activity without contacting a third party. revocation_rate_bps is the rolling revocation rate over recent invocations, in basis points; recent_receipts_volume counts receipts in the recent window. High volume with a low revocation rate marks an operationally healthy listing. Zero recent receipts on a long-lived hint marks a quiet operator, which a caller may still admit with a smaller initial budget.

Both numbers are operator-attested claims under the provider's signature, which an auditor can compare against the issuing operator's receipt log. Native reputation projections inform how an operator decides whether to trust a listing.

Read more in Reputation.

Search keeps only listings with a valid, fresh price under the caller's ceiling

chio_listing::discovery::search takes a slice of GenericListingReport replicas, a slice of SignedListingPricingHint, a ListingQuery, and the current time, and returns a signed ListingSearchResponse. The query filters on six dimensions.

The query has no jurisdiction field. Operators encode regulatory scope in the listing namespace and the policy reference on the underlying trust scope, and a catalog UI can filter on those fields.

A listing drops out of the results when any of these holds:

• No valid hint. It has no matching, signed, unexpired pricing hint. Past expires_at, a listing stays out until the provider publishes a fresh hint.
• Hint fails its checks. The hint fails validate() or signature verification; the error is recorded in ListingSearchResponse.errors.
• Price or currency. The price exceeds max_price_per_call, or its currency differs. A USD ceiling silently drops an EUR-priced hint, so a caller queries again in the other currency or converts at the consuming layer.
• Freshness. Its freshness is Stale, or Divergent because replicas disagree between mirrors, while require_fresh is true.
• Status. It is Suspended, Superseded, Revoked, or Retired.

The limit defaults to 100 and is clamped to MAX_MARKETPLACE_SEARCH_LIMIT, which equals MAX_GENERIC_LISTING_LIMIT (200). Surviving rows come back in rank order, each pairing the signed listing, the verified hint, the publisher, and the freshness record. compare projects a set of Listing entries into a ListingComparison with a price index in basis points, so callers see relative cost at a glance.

pub struct ListingQuery {
    /// Capability scope prefix to match against the hint's
    /// `capability_scope`. Matching is a literal prefix match after trim.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub capability_scope_prefix: Option<String>,
    /// Namespace filter. Same normalization as [`GenericListingQuery`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub namespace: Option<String>,
    /// Actor-kind filter. Defaults to `ToolServer` when unset.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub actor_kind: Option<GenericListingActorKind>,
    /// Only return listings whose price per call is less than or equal to
    /// this ceiling. Currency must match; listings with differing currency
    /// are filtered out.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_price_per_call: Option<MonetaryAmount>,
    /// Require a specific provider operator id (matches hint and publisher).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider_operator_id: Option<String>,
    /// Require fresh listings only. When set to `true` any stale/divergent
    /// listing is rejected. Defaults to `true`.
    #[serde(default = "default_require_fresh")]
    pub require_fresh: bool,
    /// Maximum number of results to return.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<usize>,
}

Applications search in process or over the public registry endpoint

In process, an application calls chio_listing::discovery::search and chio_listing::discovery::compare against local replicas and pricing hints. Over HTTP, the trust control plane serves GET /v1/public/registry/listings/search, which takes a GenericListingQuery as query parameters and returns a signed GenericListingReport.

curl "$REGISTRY_URL/v1/public/registry/listings/search?actorKind=tool_server&namespace=tools.search&limit=25"

The public endpoint filters on listing metadata: namespace, actorKind, actorId, status, and limit. The query type renames to camelCase, so the endpoint ignores a snake_case parameter. Filtering joined to pricing hints (scope prefix, price ceiling, currency-strict matching, and the freshness gate) runs in the in-process search, which pairs each listing with its verified SignedListingPricingHint before ranking.

An activation record turns a visible listing into one the operator trusts

Single-operator admission review produces a GenericTrustActivationArtifact (schema chio.registry.trust-activation.v1). Each activation carries four parts:

• Admission class. GenericTrustAdmissionClass: PublicUntrusted, Reviewable, BondBacked, or RoleGated.
• Disposition. GenericTrustActivationDisposition: PendingReview, Approved, or Denied.
• Eligibility. GenericTrustActivationEligibility: allowed actor kinds, publisher roles, statuses, and bond-backing and freshness constraints.
• Review context. The publisher and the replica freshness, pinned at review time.

Activation across organizations uses a different record, FederationActivationExchangeArtifact, exchanged between federated operators.

Partner listings cross one federation pair at a time

Reach across organizations runs peer to peer, between operators that have each added the other's partner card. No central directory links operators.

• Per-pair listings. A partner publishes listings into the other's registry replica through normal generic-listing publication, under the pair's FederationImportControl.
• Visible only on import. An imported listing stays visible only until the receiving operator activates it, so discovery leaves runtime authority where it was.
• No transitive pull. A listing that operator A imports from partner B stays with A; A's other partners see it only if B publishes to them directly. Each pair carries its own evidence.

The FederationActivationExchangeArtifact bundles a listing reference, a trust scope, delegation controls, and import controls. The trust control plane stores and signs it when an operator approves a partner listing for local use.

Read more in Two-Org Worked Example.

A bid buys a scoped grant against a listing that search returned

Search and compare are the read side of the marketplace. The write side is the bid, ask, and accept protocol in the chio-open-market crate: bid() resolves the listing through chio_listing::search, applies the discovered pricing hint, mints a scoped CapabilityToken, and returns a signed ask, which the buyer accepts against a verified funds reservation. The same crate sets the fee schedules, bonds, and penalties for a namespace of listings, with sanctions decided through chio-governance.

Read more in Bidding in the Open Market.

Next: buy access to a listed tool