Proto: Admin v1

Source: proto/fora/admin/v1/admin.proto

fora.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 fora.v1 idempotency convention scopes a key to the agent an RFC 9421 signature authenticates, 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 FORA 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.

All three SDKs ship a client for this service and the two domain-verification RPCs of ExchangeService: connect.NewAdminClient (Go), createAdminClient (TypeScript) and AdminClient (Python). It stamps ver, checks each request against its generated model and sends it to the configured base URL; see Testing a FORA Service Through the SDK.

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, reporting window). Full replace: omitted optional fields clear their value so the receiving Exchange's defaults apply. The deprecated quantity_tolerance is accepted and ignored: a usage report is never refused for its quantity.

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	FORA protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in fora.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	FORA protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in fora.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, and the reporting window in seconds (capped at one year). quantity_tolerance is deprecated and ignored: a usage report is never refused for its quantity, so an Exchange MUST NOT refuse a report on this setting. The field and its 0–1 bounds stay only for wire compatibility. 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	DEPRECATED, ignored. This used to set the accepted relative deviation between the estimated and the reported quantity, and a report outside it was refused. A usage report is never refused for its quantity: the reported quantity is unrestricted, and monitoring how far reports fall from estimates is the Exchange operator's own business, not part of the protocol. An Exchange MUST NOT refuse a report on this setting. The field and its bounds are retained because removing them would break the wire contract.
`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	FORA protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in fora.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	FORA protocol version — "1.0". Stamped by the sender from a single constant; advisory on receive. See "Protocol version" in fora.proto.
`policy`	ReportingPolicy	2	The reporting policy as persisted.