Subnet services

A validator (a hotkey with a validator permit on a subnet) or the subnet owner, for its owner hotkey, can publish a service with set-service, so that apps and agents can find what the subnet serves and how it is paid for. A service is a url to a document of its services and the spender its customers name on gamma deposits. The coldkey that owns the hotkey signs it, names the spender, and pays a normal fee. Publishing an empty url removes the service.

btcli tx set-service --netuid 1 --url https://example.com/services.json -w my_coldkey -H my_hotkey
btcli query services --netuid 1

await client.execute(bt.SetService(netuid=1, url="https://example.com/services.json"), wallet)
services = await client.subnets.services(netuid=1)  # {hotkey: {url, spender, owner}}

The permit is checked when the service is published. A service follows a hotkey swap and is removed when its neuron is deregistered. A coldkey swap leaves its spender, and changing the spender leaves deposits that name the old one until their coldkeys re-point them. owner marks the service of the subnet owner's hotkey while the owner owns it, whose spender new deposits name by default. A leased subnet's beneficiary publishes it through its SubnetLeaseBeneficiary proxy. Customers name a service's spender by minting with --service-hotkey (see Gamma).

The document

The chain stores the url and the spender. The document says what the services are, how to reach them, and how they are paid for:

{
  "version": 1,
  "name": "Example Inference",
  "description": "Pay-per-call inference for open models over an OpenAI-compatible API.",
  "publishers": [{ "netuid": 1, "hotkey": "5…" }],
  "services": [
    { "type": "openapi", "endpoint": "https://…", "spec": "https://…/openapi.json" },
    { "type": "mcp", "endpoint": "https://…/mcp" }
  ],
  "payments": [
    { "type": "gamma", "max_spend": "2", "signature": "btauth/1" },
    { "type": "x402" }
  ]
}

• name and description say what is sold. Who sells it is the subnet's or the coldkey's on-chain identity.
• publishers lists, by netuid and hotkey, the published services whose url may point to the document. Readers ignore one that is not listed. Without publishers, any may point to it.
• A gamma payment accepts the subnet's gamma, from deposits that name the service's spender. max_spend, a decimal string in gamma, is the most the service spends at once, so a customer keeps at least that much spendable in its deposit.
• An x402 payment states its price and payee in each HTTP 402 response.
• Readers skip service and payment types they do not know.
• name, description, publishers, max_spend and signature are optional, and readers skip fields they do not know.

Serve the document with Access-Control-Allow-Origin: *, so that web apps can read it.

A gamma payment with "signature": "btauth/1" accepts signed requests. The deposit's hotkey signs each request, with the service's hotkey as the receiver, and the service charges that deposit. Without signature, the service's own interface says how a request names its deposit.

A service can name any spender, and that spender can spend the deposits that name it without serving, so prefer the service marked owner.

While a spender's coldkey swap is announced, it cannot spend. A service that must never pause names a spender that never needs a swap, such as a multisig of several keys, and spends through a separate GammaSpend key, which the spender itself replaces by changing the proxy. A pure proxy is not such a spender, as the coldkey that controls it keeps that control through its own coldkey swap, so a leaked coldkey would keep spending.