Proto: Admin v1

Source: proto/ramp/admin/v1/admin.proto

ramp.admin.v1 is the Exchange operator/config plane — deliberately a separate package and service from ExchangeService, so the agent-facing contract is untouched. Deployments MUST NOT expose AdminService on the public agent-facing listener: reachability is restricted at the network layer (an internal listener plus a source allowlist), and there is no per-operator identity inside the service in v1.

Both RPCs are full-replace overwrites and therefore idempotent — they carry no idempotency_key (the ramp.v1 idempotency convention dedupes per verified RFC 9421 signer, and the admin plane has no request signing in v1) and no ext/ext_critical extension maps. Each request and response is a thin {ver, payload} envelope (ver is field 1, the RAMP protocol version — value "1.0", stamped by the sender from the SDK’s ProtocolVersion constant and advisory on receive, as on the agent-facing plane; the reason differs, since this plane rests on network-layer reachability rather than on a request signature) wrapping a required payload message — TenantFeeRate or ReportingPolicy — that is shared by the request and its response, so every field rule is stated once and the echoed read-back cannot drift from the write. Responses echo the payload as persisted, giving operator tooling a read-back confirmation.

Every constraint is a field-level protovalidate rule, so it flows into the generated Pydantic/Zod types; this package defines no cross-field (message-level CEL) rules.

Services

AdminService

Exchange operator overrides: the tenant fee rate and the tenant reporting policy. SetOfferPrice and SetDeliveryWitnessMode are planned extensions of this service and are tracked separately.

RPC	Request	Response	Description
`SetTenantFeeRate`	`SetTenantFeeRateRequest`	`SetTenantFeeRateResponse`	Sets the tenant's fee rate (basis points) and optional operator note. Full replace: the previous rate and note are overwritten.
`SetReportingPolicy`	`SetReportingPolicyRequest`	`SetReportingPolicyResponse`	Replaces the tenant's reporting policy (required report fields, quantity tolerance, reporting window). Full replace: omitted optional fields clear their value so the receiving Exchange's defaults apply.

Messages — Tenant Fee Rate

TenantFeeRate

The fee-rate payload shared by the SetTenantFeeRate request and response, so its rules are stated once. The fee is in basis points of gross — floor(gross * bps / 10000), so a value below 10000 keeps it strictly under 100%, and integer basis points avoid float drift when aggregating many charges. 0 is a legitimate explicit value (“no fee”), not an unset sentinel. Omitting notes clears any existing note.

Field	Type	Number	Description
`tenant_id`	string	1	The tenant whose fee rate is being set.
`fee_rate_bps`	int32	2	Fee rate in basis points of gross: fee = floor(gross * bps / 10000). Below 10000 keeps the fee strictly under 100%; integer basis points avoid float drift when aggregating many charges. 0 is a legitimate explicit value ("no fee"), not an unset sentinel.
`notes`	optional string	3	Operator commentary on the rate (why it was set, by whom, ticket link). Omitted clears any existing note.

SetTenantFeeRateRequest

A thin {ver, rate} envelope carrying the required TenantFeeRate to apply.

Field	Type	Number	Description
`ver`	string	1	RAMP protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in ramp.proto.
`rate`	TenantFeeRate	2	The fee rate to apply. Required — an absent payload would otherwise skip validation of its fields.

SetTenantFeeRateResponse

Echoes the TenantFeeRate as persisted.

Field	Type	Number	Description
`ver`	string	1	RAMP protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in ramp.proto.
`rate`	TenantFeeRate	2	The fee rate as persisted.

Messages — Reporting Policy

ReportingPolicy

The reporting-policy payload shared by the SetReportingPolicy request and response, so its rules are stated once: the report field names the usage-report validator requires, the accepted quantity tolerance (a fraction, 0–1, where 0 requires an exact match), and the reporting window in seconds (capped at one year). Omitted optional fields clear their value so the receiving Exchange’s defaults apply. The wire constrains only the token shape of required_fields; which names are meaningful is defined by the receiving Exchange and may change without a contract change, and names are a set (repeats are rejected). The window applies to obligations minted after the call — obligations already issued keep the window they were minted with.

Field	Type	Number	Description
`tenant_id`	string	1	The tenant whose reporting policy is being replaced.
`required_fields`	repeated string	2	Report field names the usage-report validator requires. The wire constrains only the token shape; which names are meaningful is defined by the receiving Exchange and may change without a contract change. Names are a set: repeats are rejected. Empty means no required fields.
`quantity_tolerance`	optional double	3	Accepted relative deviation between estimated and reported quantity, as a fraction: 0 requires an exact match, 1 accepts any deviation. Omitted: the receiving Exchange's default tolerance applies.
`window_seconds`	optional int32	4	Reporting window in seconds. Applies to obligations minted after this call; obligations already issued keep the window they were minted with. Capped at one year. Omitted: the receiving Exchange's default applies.

SetReportingPolicyRequest

A thin {ver, policy} envelope carrying the required ReportingPolicy to apply.

Field	Type	Number	Description
`ver`	string	1	RAMP protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in ramp.proto.
`policy`	ReportingPolicy	2	The reporting policy to apply. Required — an absent payload would otherwise skip validation of its fields.

SetReportingPolicyResponse

Echoes the ReportingPolicy as persisted.

Field	Type	Number	Description
`ver`	string	1	RAMP protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in ramp.proto.
`policy`	ReportingPolicy	2	The reporting policy as persisted.