arkhai-core 0.1.0__py3-none-any.whl

arkhai_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: arkhai-core
+Version: 0.1.0
+Summary: Core market wire models and orchestration-neutral helpers
+Requires-Python: <3.14,>=3.10
+Requires-Dist: pydantic>=2

arkhai_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+market_core/__init__.py,sha256=R6tT0NXfJIf8bFresHue7oDw02Sgtz7bPPV10LvpIFc,78
+market_core/schemas.py,sha256=1SidnJdKRZw3wH_MwiEuWmrPaVON-G-Dtwu3keeXyxM,32656
+arkhai_core-0.1.0.dist-info/METADATA,sha256=lt6BKIBkDs4kkQ0HsgpUwh4ETTwo49aNpZQ6zWK3XbU,179
+arkhai_core-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+arkhai_core-0.1.0.dist-info/RECORD,,

arkhai_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

market_core/__init__.py

@@ -0,0 +1,2 @@
+"""Core market models shared by buyers, storefronts, and settlement kits."""
+

market_core/schemas.py

@@ -0,0 +1,799 @@
+"""Domain-agnostic negotiation/settlement wire carriers.
+
+This is the protocol-carrier wheel: the shapes both sides of
+``/negotiate/*`` must derive identically from the shared message
+history (escrow proposals/terms, rate slots, provision-terms envelope).
+Both role shells (``core_storefront.models``) and the domain adapters
+on either side (buyer client, storefront runtime, provisioning terms)
+import from here, so any change is a cross-package wire break.
+
+Rules: zero domain vocabulary (explicitly marked legacy wire shims are
+the only exception, and they leave with the client-wheel wire bump) and
+no dependencies beyond pydantic — the wheel must stay importable by
+every role without dragging in role or kit code.
+
+Settlement mechanisms: the negotiated outcome is carried as a
+``SettlementPlan`` — per obligation, lifecycle universals
+(payer/claimant, amount/asset, expiration, conditions) as typed fields
+and everything mechanism-specific behind a ``{mechanism, params}``
+envelope whose deterministic interpretation lives in kit codecs
+(``kit/alkahest`` first; fiat providers later). The flat alkahest
+shapes (``EscrowTerms``; proposals keyed on chain + contract address)
+predate the envelope: ``EscrowTerms`` survives as the typed params
+shape of the ``alkahest.v1`` mechanism and as a marked legacy wire
+coercion into the envelope (work item I.1 of
+``docs/development/ARCHITECTURE.md, "Settlement Lifecycle"``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import (
+    BaseModel,
+    Field,
+    SerializeAsAny,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
+
+
+class ERC20TokenMetadata(BaseModel):
+    """Resolved ERC-20 token metadata used by token-priced listings."""
+
+    symbol: str
+    name: str | None = None
+    contract_address: str
+    decimals: int
+    chain_id: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# uint256 wire helpers
+# ---------------------------------------------------------------------------
+# Amounts (token amount, price-per-hour) live in the uint256 domain on chain
+# and routinely exceed 2^53 for 18-decimal tokens. JSON numbers can't carry
+# uint256 safely (most non-Python parsers treat them as IEEE-754 doubles),
+# and SQLite INTEGER is int64 — both lossy past ~9.2e18 base units.
+# Pattern: keep Python ``int`` internally (arbitrary precision) and emit
+# decimal-digit strings on serialization. Validators accept either form so
+# already-stored Python-int data round-trips without a migration.
+
+
+def _parse_uint256_str(v: Any, field_name: str) -> int | None:
+    """Coerce a wire value (int|str|None) into a Python int.
+
+    Accepts:
+      * ``None`` — passes through (used for tristate "no advertised value").
+      * ``int`` — passes through (back-compat with existing Python callers).
+      * decimal-digit ``str`` — parses to int (the canonical wire form).
+
+    Rejects floats, negative values, and anything that doesn't look like a
+    non-negative decimal integer.
+    """
+    if v is None:
+        return None
+    if isinstance(v, bool):  # bool is a subclass of int — exclude explicitly
+        raise ValueError(f"{field_name}: expected non-negative decimal, got bool")
+    if isinstance(v, int):
+        if v < 0:
+            raise ValueError(f"{field_name}: must be non-negative, got {v}")
+        return v
+    if isinstance(v, str):
+        s = v.strip()
+        if not s:
+            return None
+        if not s.isdigit():
+            raise ValueError(
+                f"{field_name}: must be a non-negative decimal-digit string, "
+                f"got {v!r}"
+            )
+        return int(s)
+    raise ValueError(
+        f"{field_name}: must be int, decimal string, or None — got "
+        f"{type(v).__name__}"
+    )
+
+
+def _serialize_uint256_str(v: int | None) -> str | None:
+    return None if v is None else str(v)
+
+
+class Resource(BaseModel):
+    """Domain-agnostic base resource model."""
+
+    @classmethod
+    def parse_from_dict(cls, data: Any) -> "Resource":
+        """Parse core-known resource shapes.
+
+        Core only understands universally valid resources. Domain-specific
+        resources should be parsed by domain adapters that extend this method.
+        """
+        if isinstance(data, Resource):
+            return data
+        if not isinstance(data, dict):
+            return data
+        if "token" in data:
+            return TokenResource(**data)
+        raise ValueError("Unsupported resource payload for core Resource parser")
+
+
+class TokenResource(Resource):
+    """Describes a given value and amount of a token used for trade/payment.
+
+    ``amount`` is tristate:
+      * positive integer — the public price (the seller advertises this
+        floor and uses it as the negotiation anchor).
+      * ``0`` — free / public-test offering (the seller advertises zero
+        cost; strategy accepts any non-negative offer).
+      * ``None`` — hidden reserve (the seller publishes the listing without
+        advertising a price; the negotiation strategy falls back to
+        ``[seller.pricing].default_min_price`` for the floor; buyer must
+        propose ``--initial-price`` and ``--max-price`` explicitly).
+    """
+
+    token: SerializeAsAny[ERC20TokenMetadata] = Field(
+        description="Token metadata resolved from registry"
+    )
+    amount: int | None = Field(
+        default=None,
+        description=(
+            "Non-negative amount in base units (token amount × 10**decimals). "
+            "0 = free; null = hidden reserve (negotiate); >0 = public price. "
+            "On the wire as a decimal-digit string (uint256-safe); Python int "
+            "internally."
+        ),
+    )
+
+    @field_validator("amount", mode="before")
+    @classmethod
+    def _parse_amount(cls, v: Any) -> int | None:
+        return _parse_uint256_str(v, "amount")
+
+    @field_serializer("amount")
+    def _serialize_amount(self, v: int | None) -> str | None:
+        return _serialize_uint256_str(v)
+
+
+class ProvisionTerms(BaseModel):
+    """Opaque off-chain delivery terms negotiated alongside escrow terms.
+
+    The core protocol treats provision terms as a schema-tagged payload:
+    ``kind`` identifies the market/schema-specific interpreter and
+    ``payload`` carries that interpreter's data. Core code treats
+    ``payload`` as opaque; interpreting it (and constructing it) is the
+    job of domain adapters — e.g. ``domains.vms.provisioning.terms`` for
+    the ``compute.v1`` payload shape.
+    """
+
+    kind: str = Field(
+        description="Schema/interpreter for this provision payload.",
+    )
+    payload: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Schema-specific provision terms. Opaque to market core.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_legacy_wire_shapes(cls, value: Any) -> Any:
+        """LEGACY wire compatibility — not part of the carrier contract.
+
+        Early compute clients (including the current ``storefront-client``
+        wheel) send a flat ``{duration_seconds, ssh_public_key,
+        compute_resource}`` dict with no ``kind``/``payload`` envelope,
+        and some transitional payloads used ``schema``/``terms`` key
+        names. Normalize all of those into the envelope here so old wire
+        data and run logs keep parsing. The ``compute.v1`` literal below
+        is a legacy wire tag, not a core interpretation of the payload.
+        Remove once no deployed client sends the flat shape.
+        """
+        if not isinstance(value, dict):
+            return value
+
+        data = dict(value)
+        if "schema" in data and "kind" not in data:
+            data["kind"] = data.pop("schema")
+        if "terms" in data and "payload" not in data:
+            data["payload"] = data.pop("terms")
+
+        legacy_keys = {"duration_seconds", "ssh_public_key", "compute_resource"}
+        if "payload" not in data and legacy_keys.intersection(data):
+            payload: dict[str, Any] = {}
+            for key in legacy_keys:
+                if key in data:
+                    raw = data.pop(key)
+                    if key == "duration_seconds" and raw is not None:
+                        try:
+                            raw = int(raw)
+                        except (TypeError, ValueError):
+                            pass
+                    payload[key] = raw
+            data["kind"] = data.get("kind") or "compute.v1"
+            data["payload"] = payload
+        return data
+
+
+class EscrowTerms(BaseModel):
+    """One on-chain escrow obligation in flat, self-describing form.
+
+    Mirrors the call shape of any alkahest escrow contract's
+    ``doObligation(data, expirationTime)`` entry point. The
+    ``obligation_data`` dict is literally the ``ObligationData`` struct
+    for whichever contract ``escrow_contract`` points to — different
+    contracts have different shapes, but every one begins with
+    ``(address arbiter, bytes demand, …)`` followed by payment fields
+    specific to that contract (token+amount for ERC20, tokenId for
+    ERC721, native amount, bundle arrays, attestation refs, etc.).
+
+    Readers extract universal fields by key: ``obligation_data["arbiter"]``
+    and ``obligation_data["demand"]`` are present on every escrow kind.
+    The rest is contract-specific; consumers that need typed access
+    parse the dict against whichever ``ObligationData`` shape goes with
+    ``escrow_contract``.
+
+    Stored flat (not wrapped in a kind+params discriminator) so that:
+      * settlement verification is a byte-compare against the chain-read
+        obligation, with no codec dispatch needed on the read path.
+      * adding new escrow kinds (ERC721, native, bundle, attestation)
+        does not change this type — only the keys present in
+        ``obligation_data`` differ.
+
+    Role since the settlement-plan generalization: the negotiated
+    outcome travels as a ``SettlementPlan`` whose obligations carry a
+    ``{mechanism, params}`` envelope; this type is the *typed params
+    shape* of the ``alkahest.v1`` mechanism (its fields minus ``maker``
+    are exactly that envelope's params) and the source shape of the
+    marked legacy coercions on ``SettlementObligation`` /
+    ``SettlementPlan``, which keep pre-plan artifacts (flat terms dicts
+    and bare terms lists) parsing.
+    """
+
+    maker: Literal["buyer", "seller"] = Field(
+        description=(
+            "Which side calls ``doObligation`` for this escrow. ``buyer`` "
+            "for the standard payment escrow; ``seller`` for cases like "
+            "penalty deposits the seller posts as bond."
+        ),
+    )
+    chain_name: str | None = Field(
+        default=None,
+        description=(
+            "Alkahest chain identifier for this escrow. New negotiated "
+            "artifacts carry it explicitly; old run logs may omit it and "
+            "fall back to the caller's configured chain."
+        ),
+    )
+    escrow_contract: str = Field(
+        description=(
+            "Address of the on-chain escrow obligation contract — e.g. "
+            "ERC20EscrowObligation, ERC721EscrowObligation, "
+            "NativeTokenEscrowObligation, TokenBundleEscrowObligation, "
+            "AttestationEscrowObligation. The address determines the "
+            "expected shape of ``obligation_data``."
+        ),
+    )
+    obligation_data: dict[str, Any] = Field(
+        description=(
+            "The literal ``ObligationData`` struct passed to "
+            "``escrow_contract.doObligation``. Always contains at least "
+            "``arbiter`` (address) and ``demand`` (bytes, hex-encoded for "
+            "transport); the remaining keys are payment fields specific "
+            "to the escrow kind."
+        ),
+    )
+    expiration_unix: int = Field(
+        gt=0,
+        description=(
+            "Absolute UTC unix-time at which the escrow expires on-chain. "
+            "Buyer commits to creating the escrow before this moment; "
+            "seller verifies the on-chain attestation's ``expirationTime`` "
+            "equals this value. Absolute (not relative-to-creation) so "
+            "both sides have a single agreed timestamp with no clock-drift "
+            "tolerance window."
+        ),
+    )
+
+
+_ALKAHEST_MECHANISM = "alkahest.v1"
+"""Mechanism tag for the legacy flat-``EscrowTerms`` wire coercions below.
+
+A legacy wire tag, not a core interpretation of the params — core never
+dispatches on it. The matching codec lives in ``kit/alkahest``.
+"""
+
+
+class SettlementObligation(BaseModel):
+    """One obligation in a settlement plan.
+
+    The lifecycle universals every settlement mechanism shares are typed
+    fields: who funds it, who collects it, how much of what, when the
+    collect-vs-reclaim boundary falls, and what conditions gate
+    collection. Everything needed to *materialize and verify* the
+    obligation under a particular mechanism — chain + contract address
+    and the ``ObligationData`` struct for alkahest; provider + payment
+    refs for a fiat escrow — rides in ``params``, interpreted by the kit
+    codec registered for ``mechanism``. Core code drives obligations
+    through injected per-mechanism hooks and never reads ``params``.
+
+    ``amount``/``asset`` are the *display/lifecycle* view of the
+    obligation's value (None when the mechanism's value isn't a scalar,
+    e.g. a token-bundle escrow); the mechanism params remain the
+    authoritative materialization input, and the codec's verification is
+    responsible for their consistency.
+
+    ``conditions`` carries declared condition descriptors for the deal
+    servicing engine (lifecycle doc work item I.3). Opaque to core;
+    empty means "whatever the mechanism params already encode" — for
+    alkahest the arbiter demand tree inside ``params`` is authoritative
+    and is decoded by the kit codec on demand.
+    """
+
+    payer: Literal["buyer", "seller"] = Field(
+        description=(
+            "Which side funds/materializes this obligation (calls "
+            "``doObligation`` for alkahest; creates the hold/intent for a "
+            "fiat mechanism)."
+        ),
+    )
+    claimant: Literal["buyer", "seller"] = Field(
+        description=(
+            "Which side collects when the condition set passes. The payer "
+            "reclaims after ``expiration_unix`` if the claimant never "
+            "collected. Payment escrow: buyer pays, seller claims; penalty "
+            "bond: seller posts, buyer claims."
+        ),
+    )
+    amount: int | None = Field(
+        default=None,
+        description=(
+            "Obligation value in the asset's base units (uint256-domain; "
+            "decimal-digit string on the wire, Python int internally). "
+            "None when the mechanism's value isn't a single scalar."
+        ),
+    )
+    asset: str | None = Field(
+        default=None,
+        description=(
+            "Mechanism-scoped asset identifier — ERC-20 contract address "
+            "for alkahest token escrows, a currency code for fiat. None "
+            "when not applicable (e.g. bundle escrows)."
+        ),
+    )
+    expiration_unix: int = Field(
+        gt=0,
+        description=(
+            "Absolute UTC unix-time collect-vs-reclaim boundary. Absolute "
+            "(not relative-to-creation) so both sides share one agreed "
+            "timestamp with no clock-drift window."
+        ),
+    )
+    conditions: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description=(
+            "Declared condition descriptors gating collection. Opaque to "
+            "core; interpreted by the mechanism codec / domain policy."
+        ),
+    )
+    mechanism: str = Field(
+        description=(
+            "Settlement mechanism codec identifier (e.g. ``alkahest.v1``). "
+            "Selects the kit codec that interprets ``params``."
+        ),
+    )
+    params: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Mechanism-specific materialization/verification params. "
+            "Opaque to market core."
+        ),
+    )
+
+    @field_validator("amount", mode="before")
+    @classmethod
+    def _parse_obligation_amount(cls, v: Any) -> int | None:
+        return _parse_uint256_str(v, "amount")
+
+    @field_serializer("amount")
+    def _serialize_obligation_amount(self, v: int | None) -> str | None:
+        return _serialize_uint256_str(v)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_legacy_escrow_terms(cls, value: Any) -> Any:
+        """LEGACY wire compatibility — not part of the carrier contract.
+
+        Pre-plan artifacts (run logs, negotiation threads, the current
+        client wheels) carry flat ``EscrowTerms`` dicts: ``{maker,
+        chain_name?, escrow_contract, obligation_data, expiration_unix}``.
+        Normalize that shape into the mechanism envelope here so old
+        artifacts keep parsing. Remove once no deployed client sends the
+        flat shape (leaves with the client-wheel wire bump).
+        """
+        if not isinstance(value, dict):
+            return value
+        if "mechanism" in value or "escrow_contract" not in value:
+            return value
+
+        data = dict(value)
+        maker = data.pop("maker", "buyer")
+        obligation_data = data.pop("obligation_data", {}) or {}
+        params: dict[str, Any] = {
+            "escrow_contract": data.pop("escrow_contract"),
+            "obligation_data": obligation_data,
+        }
+        if data.get("chain_name") is not None:
+            params["chain_name"] = data.pop("chain_name")
+        else:
+            data.pop("chain_name", None)
+
+        amount = obligation_data.get("amount")
+        return {
+            "payer": maker,
+            "claimant": "seller" if maker == "buyer" else "buyer",
+            "amount": amount if isinstance(amount, (int, str)) else None,
+            "asset": obligation_data.get("token"),
+            "expiration_unix": data.pop("expiration_unix", None),
+            "mechanism": _ALKAHEST_MECHANISM,
+            "params": params,
+            **data,
+        }
+
+
+class SettlementPlan(BaseModel):
+    """The negotiated settlement plan both sides derive identically.
+
+    Generalizes the single accepted-escrow handoff: a plan is N
+    obligations (payment escrows, interval escrows, penalty bonds —
+    possibly under different mechanisms) plus the off-chain duties each
+    party takes on while servicing the deal. The determinism contract
+    extends unchanged in kind: both sides must derive the same plan from
+    the shared message history; for mechanisms whose materialization is
+    not independently derivable (fiat), determinism covers the agreed
+    terms and the codec verifies the materialized object against them.
+
+    ``service_terms`` is the attachment point for heartbeat cadence and
+    schema, oracle identity, evidence format, and interval boundaries
+    (lifecycle doc work items I.4/I.5). Opaque to core; empty for plans
+    with no off-chain duties beyond the mechanism defaults.
+    """
+
+    obligations: list[SettlementObligation] = Field(
+        description="Every obligation the deal materializes.",
+    )
+    service_terms: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Off-chain servicing duties (heartbeat cadence/schema, oracle "
+            "identity, interval boundaries). Opaque to market core."
+        ),
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_legacy_terms_list(cls, value: Any) -> Any:
+        """LEGACY wire compatibility — not part of the carrier contract.
+
+        Pre-plan artifacts carry a bare ``list[EscrowTerms]`` where the
+        plan now travels. Wrap it; the per-obligation legacy coercion
+        handles each entry. Remove with the client-wheel wire bump.
+        """
+        if isinstance(value, list):
+            return {"obligations": value}
+        return value
+
+
+# ---------------------------------------------------------------------------
+# Rate slots: per-unit-time (or per-unit-anything) rates on obligation fields.
+# A rate carries the field path on the obligation data plus the unit it
+# scales by; the value is in the payment token's base units (uint256 domain).
+# At settlement time both sides compute the final field value as
+# ``value * duration_quantum // PER_UNIT_QUANTUM[per]`` (integer division;
+# sub-unit fractions truncate, matching the prior single-rate semantics).
+# ---------------------------------------------------------------------------
+
+# Allowed values for ``RateValue.per`` and the seconds-per-unit divisor used
+# at settlement. ``hour`` is the only one wired end-to-end today;
+# ``request`` / ``kWh`` etc. are reserved for the design's "non-time rate
+# units" open question — adding one is a single dict entry plus negotiated
+# quantity (request_count, energy_kwh) carried on the deal.
+PER_UNIT_SECONDS: dict[str, int] = {
+    "hour": 3600,
+}
+
+
+class RateValue(BaseModel):
+    """One rate-bearing slot on an accepted escrow / proposal.
+
+    ``field`` is the dotted/indexed path into the obligation data
+    (``"amount"`` for ERC-20 escrows; ``"erc20Amounts[0]"``,
+    ``"nativeAmount"`` etc. for TokenBundle). ``per`` is the unit the
+    rate scales by — ``"hour"`` for the time-rate case. ``value`` is
+    the rate itself in base units, uint256-domain (decimal-digit string
+    on the wire, Python int internally).
+
+    Negotiation pressure points at ``value``; ``field`` and ``per``
+    come from the seller's escrow template and are non-negotiable.
+    """
+
+    field: str = Field(description="Obligation-data field path the rate populates.")
+    per: str = Field(default="hour", description="Unit the rate scales by.")
+    value: int = Field(description="Rate amount in payment-token base units (uint256).")
+
+    @field_validator("value", mode="before")
+    @classmethod
+    def _parse_value(cls, v: Any) -> int:
+        parsed = _parse_uint256_str(v, "value")
+        if parsed is None:
+            raise ValueError("RateValue.value must not be null")
+        return parsed
+
+    @field_serializer("value")
+    def _serialize_value(self, v: int) -> str:
+        return _serialize_uint256_str(v) or "0"
+
+
+def compute_rate_total(rate: RateValue, duration_seconds: int) -> int:
+    """Multiply a rate by the negotiated duration.
+
+    Returns the final on-chain field value for ``rate.field``. Uses
+    integer division so sub-unit fractions truncate (i.e. for ERC20:
+    ``rate × duration_seconds // 3600``).
+    """
+    divisor = PER_UNIT_SECONDS.get(rate.per)
+    if divisor is None:
+        raise ValueError(f"unknown rate.per unit: {rate.per!r}")
+    return rate.value * duration_seconds // divisor
+
+
+# ---------------------------------------------------------------------------
+# AcceptedEscrow / EscrowProposal accessors
+# ---------------------------------------------------------------------------
+# Most consumers treat an accepted_escrows entry as a JSON dict (after a
+# round-trip through SQLite or the wire); these accessors operate on
+# either a Pydantic model OR a dict so the only change at the call site
+# is the accessor name.
+
+
+def primary_rate_value(accepted_or_proposal: Any) -> int | None:
+    """Return the headline rate's value for negotiation/display.
+
+    Today's negotiation engine treats every escrow as having a single
+    rate — that's true for ERC-20 (the ``amount`` rate) and ``None`` for
+    pure-attestation escrows. Multi-rate templates (TokenBundle) return
+    the *first* rate; vector negotiation is a deferred extension.
+
+    Returns ``None`` when the escrow advertises no rates (hidden-reserve
+    listings, attestation one-shots). Callers translate ``None`` into
+    either a hidden-reserve fallback (negotiation strategies) or a
+    "no scaling" path (settlement of pure-literal escrows).
+    """
+    rates = _rates_of(accepted_or_proposal)
+    if not rates:
+        return None
+    first = rates[0]
+    if isinstance(first, dict):
+        v = first.get("value")
+        if isinstance(v, str) and v.strip().isdigit():
+            return int(v.strip())
+        if isinstance(v, int) and not isinstance(v, bool):
+            return v
+        return None
+    v = getattr(first, "value", None)
+    if isinstance(v, int) and not isinstance(v, bool):
+        return v
+    return None
+
+
+def accepted_token_address(accepted_or_proposal: Any) -> str | None:
+    """Return the payment-token address from an ERC-20-style entry.
+
+    Reads ``literal_fields["token"]`` — the canonical place ERC-20 and
+    ERC-1155 escrows pin their payment-token. Returns ``None`` for
+    escrow kinds (NativeToken, TokenBundle, attestation) that don't
+    have a single ``token`` literal.
+    """
+    literals = _literal_fields_of(accepted_or_proposal)
+    val = literals.get("token") if isinstance(literals, dict) else None
+    return val if isinstance(val, str) and val else None
+
+
+def accepted_recipient_address(accepted_or_proposal: Any) -> str | None:
+    """Return the escrow demand recipient from an accepted/proposed escrow.
+
+    Preferred source is ``demands[].demand_data.recipient`` on the
+    RecipientArbiter demand. ``literal_fields["recipient"]`` remains a
+    legacy fallback for transitional data.
+    """
+    for demand in accepted_demands(accepted_or_proposal):
+        data = demand.get("demand_data")
+        if isinstance(data, dict):
+            val = data.get("recipient")
+            if isinstance(val, str) and val:
+                return val
+    literals = _literal_fields_of(accepted_or_proposal)
+    val = literals.get("recipient") if isinstance(literals, dict) else None
+    return val if isinstance(val, str) and val else None
+
+
+def accepted_demands(accepted_or_proposal: Any) -> list[dict[str, Any]]:
+    """Return arbiter demands advertised/negotiated for this escrow shape."""
+    if isinstance(accepted_or_proposal, dict):
+        raw = accepted_or_proposal.get("demands")
+    else:
+        raw = getattr(accepted_or_proposal, "demands", None)
+    if not isinstance(raw, list):
+        return []
+    out: list[dict[str, Any]] = []
+    for item in raw:
+        if isinstance(item, dict):
+            out.append(dict(item))
+        else:
+            dumped = item.model_dump() if hasattr(item, "model_dump") else None
+            if isinstance(dumped, dict):
+                out.append(dumped)
+    return out
+
+
+def _rates_of(entry: Any) -> list[Any]:
+    if isinstance(entry, dict):
+        out = entry.get("rates")
+        return out if isinstance(out, list) else []
+    return list(getattr(entry, "rates", []) or [])
+
+
+def _literal_fields_of(entry: Any) -> dict[str, Any]:
+    if isinstance(entry, dict):
+        out = entry.get("literal_fields")
+        return out if isinstance(out, dict) else {}
+    return dict(getattr(entry, "literal_fields", {}) or {})
+
+
+class EscrowDemand(BaseModel):
+    """One arbiter demand paired with an escrow obligation.
+
+    ``arbiter`` is the deployed arbiter contract address. ``demand_data``
+    is the JSON-shaped input for that arbiter's codec; settlement codecs
+    own encoding it into on-chain demand bytes.
+    """
+
+    chain_name: str | None = Field(
+        default=None,
+        description=(
+            "Optional chain identifier for listings that advertise demands "
+            "across multiple chains."
+        ),
+    )
+    arbiter: str = Field(
+        description="Deployed arbiter contract address for this demand.",
+    )
+    demand_data: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Codec-specific arbiter demand data.",
+    )
+
+
+class AcceptedEscrow(BaseModel):
+    """One escrow shape the seller will accept for this listing.
+
+    Each entry pins the (chain, escrow contract) tuple plus the
+    obligation literals + rates the seller has fixed. The buyer's
+    proposal references one of these entries by
+    ``(chain_name, escrow_address)`` and inherits its ``literal_fields``.
+
+    ``literal_fields`` is escrow-data-only: keys present advertise a seller-
+    preferred value; keys absent are open. Never includes a rate-bearing
+    field directly — those live in ``rates`` so duration scaling stays
+    explicit. Arbiter release criteria live in the listing/proposal-level
+    ``demands`` list.
+
+    ``rates`` carries every rate-bearing field on the obligation. For
+    ERC20 escrows that's a single ``{"field": "amount", "per": "hour",
+    "value": …}`` entry; multi-rate templates (TokenBundle) carry one
+    per rate-bearing field. Empty list = hidden reserve (seller did not
+    publish a rate; negotiation establishes one via the strategy's
+    ``default_min_price``). Readers use the ``primary_rate_value`` /
+    ``accepted_token_address`` helpers in this module.
+    """
+
+    chain_name: str = Field(
+        description=(
+            "Alkahest chain identifier (e.g. ``base_sepolia``, ``anvil``). "
+            "Combined with ``escrow_address`` to look up the SDK codec via "
+            "``market_alkahest.alkahest.get_escrow_codec_for``."
+        ),
+    )
+    escrow_address: str = Field(
+        description=(
+            "Deployed escrow obligation contract address on ``chain_name``. "
+            "The (chain, address) pair determines the EscrowData ABI."
+        ),
+    )
+    literal_fields: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Literal obligation-data keys the seller has fixed (e.g. "
+            "``token``). Keys present = seller-preferred "
+            "value; keys absent = open. Never includes a rate-bearing "
+            "field — those live in ``rates``. Arbiter demand criteria "
+            "live in ``demands``."
+        ),
+    )
+    rates: list[RateValue] = Field(
+        default_factory=list,
+        description=(
+            "Rate-bearing obligation fields. Each entry pins one field "
+            "(``amount`` for ERC20, ``erc20Amounts[i]`` / ``nativeAmount`` "
+            "for TokenBundle, …) plus its ``per`` unit and the rate "
+            "``value`` in base units. Empty list = hidden reserve. "
+            "Readers use ``primary_rate_value`` for the headline rate."
+        ),
+    )
+
+
+class EscrowProposal(BaseModel):
+    """Buyer's escrow proposal at negotiation round 0.
+
+    References one of the listing's ``accepted_escrows`` entries by
+    ``(chain_name, escrow_address)`` and supplies the buyer-committable
+    EscrowData fields. ``amount`` is intentionally not on the proposal —
+    it's derived at settlement from the agreed price + duration. The
+    seller echoes back the accepted proposal verbatim on the negotiation
+    outcome so settlement code reconstructs the same on-chain
+    obligation_data on both sides.
+    """
+
+    chain_name: str = Field(
+        description=(
+            "Chain identifier; must match the picked accepted_escrows entry."
+        ),
+    )
+    escrow_address: str = Field(
+        description=(
+            "Escrow contract address; must match the picked "
+            "accepted_escrows entry."
+        ),
+    )
+    fields: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Complete buyer-committable EscrowData fields (arbiter, "
+            "token, …). Excludes ``amount`` and arbiter demand bytes, "
+            "which are derived at settlement."
+        ),
+    )
+    literal_fields: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Forward-looking sibling of ``fields`` for the generic-escrow "
+            "migration. When set, mirrors ``fields`` (literal obligation-"
+            "data keys the buyer commits to). Readers should prefer the "
+            "canonical accessor ``accepted_token_address`` which handles "
+            "either shape."
+        ),
+    )
+    rates: list[RateValue] | None = Field(
+        default=None,
+        description=(
+            "Forward-looking sibling for multi-rate templates. Today "
+            "negotiation produces a single scalar amount that becomes the "
+            "primary rate-bearing field at settlement; future TokenBundle "
+            "proposals carry one ``RateValue`` per rate-bearing field."
+        ),
+    )
+    demands: list[EscrowDemand] | None = Field(
+        default=None,
+        description=(
+            "Arbiter demand criteria inherited from the accepted escrow "
+            "entry and committed during negotiation."
+        ),
+    )
+    expiration_unix: int = Field(
+        gt=0,
+        description=(
+            "Absolute UTC unix-time the on-chain escrow attestation "
+            "expires. Both sides commit to this single timestamp; no "
+            "clock-drift tolerance window."
+        ),
+    )