hip-1195

HIP-1195: Market — Rate Oracles and Exchange Pools. Status Final. Hanzo architectural specification.

HIP-1195: Market — Rate Oracles and Exchange Pools

Abstract

/v1/market is the canonical capability for market within the Hanzo Cloud platform. Package market is what trades on each chain, and how far the read of it got. The implementation is hanzoai/cloud apps/market and plugin/market (HIP-0106, HIP-0139). All operations are native, composable, and authenticated against Hanzo IAM (HIP-0026).

Motivation

Before this specification, market operations lacked a unified canonical surface or were scattered across disparate endpoints. Under HIP-0139 (§1), every cloud capability maps 1:1 with exactly one plugin binary, one address prefix, one client class, and one authoritative specification. This eliminates duplicate implementations and ensures strict physical isolation, predictable billing, and orthogonal composability across the estate.

Specification

The key words MUST, MUST NOT, and SHOULD are to be interpreted as in RFC 2119.

§1 Addresses and Operations

The market capability answers exclusively under its assigned route prefixes:

| Method | Path | Summary | |---|---|---| | GET | /v1/market/chains | Answers every chain this deployment can read, what is deployed on each, and what its au... | | GET | /v1/market/pools | Answers the automated market makers on one chain: their two tokens, their fee tier, and... | | GET | /v1/market/survey | Answers which of the four settlement precompiles carry code on one chain. | | GET | /v1/market/token | Answers one token's daily history — open, high, low, close, price and volume per UTC da... | | GET | /v1/market/tokens | Answers the tokens one chain's indexer has seen, with the decimals a caller needs to re... |

§2 Storage and Physical Isolation

Data is isolated physically per organization using cloud.OrgDB: {DataDir}/orgs/{org}/market.db. Isolation is strictly enforced at the filesystem and OS level; no cross-tenant queries are permitted. Where temporal or timeseries data is captured, postings are signed and immutably appended.

§3 Authentication and Principal

Every request reaching /v1/market MUST present a valid Hanzo IAM bearer token (HIP-0026, HIP-0111). Anonymous requests are rejected at the edge gateway before invoking the plugin. The executing principal is extracted from the token and bound to the request context.

Security Considerations

  1. Physical Separation: Each tenant retains an isolated SQLite database file.
  2. Replay & Channel Binding: Direct dials and internal RPCs enforce channel binding over ZAP native transport.
  3. Audit Trails: All state-modifying actions emit immutable audit events to the centralized event plane (HIP-1190).

References