Contracts

Bidding API

The legs come from the two entry points of chio_open_market::bidding: bid mints the ask from a signed bid, and accept builds the acceptance from an ask and a verified reservation.

pub fn bid(
    request: &SignedBidRequest,
    context: BidMintContext<'_>,
) -> Result<SignedAskResponse, BiddingError>;

pub fn accept(
    ask: &SignedAskResponse,
    reservation: &VerifiedReservationReceipt,
    acceptor_keypair: &Keypair,
    accepted_at: u64,
) -> Result<SignedAcceptedBid, BiddingError>;

chio-open-market is pure logic, with no I/O and no runtime state, under #![forbid(unsafe_code)]. It takes already-fetched signed artifacts and judges, fail closed, whether they satisfy market rules. It holds no balances, dispatches no tools, issues no receipts, and has no dependency on a receipt store.

Leg fields

Every string field on the bid is rejected when empty or when it carries surrounding whitespace. The three market bodies serialize their fields as camelCase; the capability token nested in the ask keeps snake_case on the wire.

Leg one: bidRequest

Schema chio.marketplace.bid-request.v1, wrapped as SignedBidRequest and signed by the buying agent.

RequestedScope carries server_id, tool_name, an optional max_invocations: Option<u32>, and capability_scope_prefix. All three strings are required and nonempty.

Leg two: askResponse

Schema chio.marketplace.ask-response.v1, wrapped as SignedAskResponse and signed by the provider's issuer keypair. The provider assembles it inside a BidMintContext, which pairs the resolved listing with the issuer key, the buyer's subject key, an opaque token_id, and the evaluation time now.

Leg three: acceptedBid

Schema chio.marketplace.accepted-bid.v1, wrapped as SignedAcceptedBid and signed by the acceptor, whose public key must equal ask.body.token_offer.subject. It is the settlement-facing leg.

The three legs below are an outside buyer's bid for your pricing.quote listing at USD 0.01 a call, in their wire field names. Amounts are minor units, so the ceiling of 2 is USD 0.02 and the reservation of 100 covers 100 quotes; keys and digests are shortened.

{
  "bidRequest": {
    "body": {
      "schema": "chio.marketplace.bid-request.v1",
      "agentId": "did:chio:z6MkbY4…e1R",
      "listingId": "listing-pricing-quote",
      "maxPricePerCall": { "units": 2, "currency": "USD" },
      "windowSeconds": 300,
      "requestedScope": {
        "serverId": "pricing",
        "toolName": "quote",
        "maxInvocations": 100,
        "capabilityScopePrefix": "pricing:quote"
      },
      "issuedAt": 120
    },
    "signerKey": "3f9a…e1R",
    "signature": "b71c…5e08"
  },
  "askResponse": {
    "body": {
      "schema": "chio.marketplace.ask-response.v1",
      "listingId": "listing-pricing-quote",
      "agentId": "did:chio:z6MkbY4…e1R",
      "bidDigest": "6c1f…a7d3",
      "quotedPrice": { "units": 1, "currency": "USD" },
      "tokenOffer": {
        "schema": "chio.capability.v1",
        "id": "cap-01ab…77d1",
        "issuer": "4f1c…a2e9",
        "subject": "3f9a…e1R",
        "scope": {
          "grants": [
            {
              "server_id": "pricing",
              "tool_name": "quote",
              "operations": ["invoke"],
              "max_invocations": 100,
              "max_cost_per_invocation": { "units": 1, "currency": "USD" },
              "max_total_cost": { "units": 100, "currency": "USD" }
            }
          ]
        },
        "issued_at": 120,
        "expires_at": 420
      },
      "issuedAt": 120,
      "expiresAt": 420
    },
    "signerKey": "4f1c…a2e9",
    "signature": "5d2b…c86f"
  },
  "acceptedBid": {
    "body": {
      "schema": "chio.marketplace.accepted-bid.v1",
      "listingId": "listing-pricing-quote",
      "agentId": "did:chio:z6MkbY4…e1R",
      "bidDigest": "6c1f…a7d3",
      "askDigest": "e8b3…41d0",
      "bidReceiptId": "rsv-01c2…9b10",
      "quotedPrice": { "units": 1, "currency": "USD" },
      "acceptedAt": 180,
      "tokenId": "cap-01ab…77d1",
      "tokenSubject": "3f9a…e1R",
      "tokenExpiresAt": 420
    },
    "signerKey": "3f9a…e1R",
    "signature": "9a17…30e4"
  }
}

Bidding errors

Each denial is a named BiddingError variant a caller can match on.

• BidSignatureInvalid: the bid envelope fails verification against its own signer key.
• ListingSignatureInvalid, PricingSignatureInvalid: the listing or the pricing hint fails verification. accept reuses PricingSignatureInvalid for an ask envelope that fails verification.
• ListingNotActive: the listing status is suspended, superseded, revoked, or retired.
• PricingExpired: the pricing hint is outside [issued_at, expires_at), or accepted_at has reached the ask expiry.
• ListingStale: the listing is inadmissible for a reason other than expired pricing, such as a replica that is not fresh.
• CurrencyMismatch, BidCeilingTooLow: the bid currency differs from the advertised currency, or the ceiling is below the advertised price.
• ScopeOutsideListing: the requested scope prefix falls outside the advertised scope, or the requested server_id is not the listing subject.
• WindowOutOfBounds: a zero or overflowing window, or a token window that fails to cover the ask window.
• TotalCostOverflow: the advertised price times max_invocations exceeds u64.
• TokenSignatureInvalid, AuthorityMismatch: the token offer fails verification, or a key sits where the flow requires a different one.
• ReservationReceiptInvalid: the funds reservation is unverifiable, unbound, or insufficient.

Terms: scope, window, and SLA

A contract's economic terms are the price, the scope, the window, and the service level. The bid flow enforces the first three. The listing publishes the fourth, and a commerce order commits it separately.

Scope may only narrow

The requested capability_scope_prefix is compared segment by segment against the listing's advertised capability_scope, splitting on :. Empty segments on either side fail. The advertised scope has no more segments than the request, and every advertised segment equals the request's segment at the same position. An advertised tools:search therefore admits tools:search and tools:search:web, and refuses tools and tools:index. The requested server_id must equal the listing subject's actor_id.

The minted grant takes server_id from the listing subject, tool_name from the request, operations: vec![Operation::Invoke], an empty constraints list, max_cost_per_invocation equal to the advertised price, max_total_cost equal to price times invocations, and dpop_required: None. The token scope carries no resource_grants and no prompt_grants, and its delegation_chain is empty. Binding a purchase to a specific output digest belongs to The Cognition Market.

One window governs three things

window_seconds sets the ask expiry, the token expiry, and the acceptance deadline at once. All three land on issued_at + window_seconds, computed with a checked add. Acceptance before ask.issued_at is an invalid request, and acceptance at or after ask.expires_at is PricingExpired. The contract runs on the provider's clock, now.

The SLA rides the listing

The advertised service level lives on the signed pricing hint, chio.marketplace.listing-pricing-hint.v1, as a ListingSla with max_latency_ms, availability_bps (basis points, where 10000 means 100 percent), and throughput_rps. Validation requires a nonzero latency budget, availability in (0, 10000], and nonzero throughput. The same hint carries revocation_rate_bps and recent_receipts_volume, which a buyer reads to price reliability before it bids. Because the contract references the listing by id, its terms are recoverable from the registry and no leg copies them.

A commerce order states its service level as its own signed artifact, chio.commerce.sla-commitment.v1, which requires order_id, provider_subject, buyer_subject, at least one entry in metric_definitions, a measurement_policy_ref, an effective_window, a collateral_position_ref, a guarantee_decision_ref, and a signature. An order reaches it through trust_market_requirement.sla_commitment_ref on chio.commerce.order-context.v1. That requirement also carries collateral_position_ref, guarantee_decision_ref, and adjudication_jurisdiction_ref, while the order context binds the price at quote_id, quote_amount_minor, quote_currency, and quote_sha256.

Bonds and remedies

Remedies attach to the listing and its publishing operator, never to an individual trade. An OpenMarketPenaltyArtifact is keyed by listing_id, case_id, and fee_schedule_id and carries no bid or ask digest; the unit of remedy is the posted bond.

The signed OpenMarketFeeScheduleArtifact (chio.registry.market-fee-schedule.v1) fixes a publication_fee, a dispute_fee, a market_participation_fee, and a nonempty list of bond_requirements. Each OpenMarketBondRequirement carries a bond_class (Publication, Listing, or Dispute), a required_amount, a collateral_reference_kind (CreditBond or ExternalReference), and a slashable flag.

HoldBond and SlashBond require the governance case to be a Sanction in state Enforced, and SlashBond also requires a slashable bond requirement. ReverseSlash requires an Appeal case, a supersedes_penalty_id, and a prior_penalty that is an enforced hold or slash for the same listing, fee schedule, and bond class; the artifact validates only when a ReverseSlash carries that supersession target and the Reversed state. The penalty amount matches the bond currency and is at most required_amount.units.

evaluate_open_market_penalty verifies every signed input, checks trusted-signer membership, cross-checks namespace and operator linkage, and rejects expired artifacts. A failed check returns a successful OpenMarketPenaltyEvaluation carrying exactly one OpenMarketFinding, with a code such as BondRequirementNotSlashable, PenaltyAmountExceedsBond, or GovernanceCaseKindInvalid. The outer Result is Err only when the request's own listing or publisher shape is malformed. Every penalty carries a nonempty evidence_refs list of OpenMarketEvidenceReference entries, each with a kind, a reference id, and an optional 64-character SHA-256 digest.