API Evangelist enhancements for the Kusama Substrate API Sidecar

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Kusama Substrate API Sidecar
  version: 1.0.0
  x-generated: '2026-07-19'
  x-method: generated
  x-source: openapi/kusama-sidecar-openapi.yaml
  x-notes: >-
    Non-destructive enhancements over Parity's published specification. The original spec is never
    mutated. Every statement here is grounded in the published document or in live probes of
    https://kusama-public-sidecar.parity-chains.parity.io/ on 2026-07-19. Applying this overlay narrows
    the spec to the Kusama server, records the deprecation state Parity announced in prose, and attaches
    the operating semantics (idempotency, historical-state pinning, numeric encoding) that the spec
    itself does not carry.
extends: openapi/kusama-sidecar-openapi.yaml
actions:
- target: $.info
  description: Record enrichment provenance and the Kusama-specific framing.
  update:
    x-apis-io-provider: kusama
    x-apis-io-enriched: '2026-07-19'
    x-chain: kusama
    x-native-token: KSM
    x-token-decimals: 12
    x-ss58-prefix: 2
    x-observed-spec-version: 2003000
    x-observed-transaction-version: 26
    x-observed-node-version: 1.24.0-660acefe665
    x-observed-at: '2026-07-19'
- target: $.info
  description: Flag the API-level deprecation Parity announced in prose so tooling can detect it.
  update:
    x-lifecycle-status: deprecated
    x-superseded-by: https://github.com/paritytech/polkadot-rest-api
    x-migration-guide: https://github.com/paritytech/polkadot-rest-api/blob/main/docs/guides/MIGRATION.md
    x-successor-path-prefix: /v1/
    x-support-commitment: Final feature release; only critical-security fixes backported.
- target: $.servers
  description: Narrow the server list to the Kusama relay-chain instance verified live, and annotate the
    others rather than silently carrying them.
  update:
  - url: https://kusama-public-sidecar.parity-chains.parity.io/
    description: Kusama relay chain — Parity public sidecar. Verified live 2026-07-19 (GET /node/version
      returned chain "Kusama", clientImplName "parity-kusama").
    x-verified: true
    x-verified-at: '2026-07-19'
  - url: https://kusama-asset-hub-public-sidecar.parity-chains.parity.io/
    description: Kusama Asset Hub — Parity public sidecar.
    x-verified: false
    x-verified-at: '2026-07-19'
    x-probe-result: 'HTTP 500 "WebSocket is not connected" — not serving at probe time.'
- target: $
  description: Attach the operating semantics an integrator or agent needs and the spec does not state.
  update:
    x-api-conventions:
      authentication: none — public, unauthenticated. No API keys, no OAuth, no securitySchemes declared.
      idempotency:
        http_header: null
        mechanism: account nonce plus mortal era, enforced on-chain
        description: >-
          Exactly-once execution is a runtime property, not an HTTP one. A signed extrinsic embeds the
          signing account's nonce; the runtime executes a given (account, nonce) pair at most once, and
          the nonce is bound inside the signature. On timeout, re-broadcast the same signed payload —
          re-signing with a fresh nonce is how double-submits occur.
        artifact: conventions/kusama-conventions.yml
      historical_state:
        parameter: at
        applies_to_operations: 70
        description: Block height or hash. Omitted means latest finalized, which moves every ~6 seconds.
          Pin it whenever two reads must be mutually consistent.
      pagination:
        style: none — no limit/offset/cursor/page parameters and no Link headers anywhere in the spec
        bounded_by: [range, depth]
        payload_reduction: [onlyIds, noFees, noMeta, keys]
      numeric_encoding:
        integers_as_strings: true
        description: Balances and heights are JSON strings because u128 values exceed IEEE-754 safe
          integer range. Parse with BigInt or a decimal library.
        balance_unit: Planck (1 KSM = 10^12 Planck)
      addresses:
        format: SS58
        kusama_prefix: 2
        warning: A Polkadot-prefix (0) address is well-formed but a different account. Validate first.
      rate_limiting:
        documented: false
        headers: none observed
      error_format:
        rfc9457: false
        envelope: '{code, message, stack} as application/json'
        warning: The stack field leaks internal server paths to unauthenticated callers.
        artifact: errors/kusama-problem-types.yml
      write_path_semantics:
        warning: >-
          HTTP 200 on POST /transaction means accepted into the transaction pool, NOT executed
          successfully. Inclusion and on-chain success are separate. Inspect the ExtrinsicSuccess or
          ExtrinsicFailed event; failures carry a pallet-specific DispatchError whose catalog is at
          GET /pallets/{palletId}/errors.
      event_surface:
        webhooks: false
        mechanism: WebSocket subscriptions on the JSON-RPC endpoint (wss://kusama-rpc.polkadot.io)
        artifact: asyncapi/kusama-jsonrpc-asyncapi.yml
        finality_warning: Subscribe to chain_subscribeFinalizedHeads rather than newHeads for anything
          financial — best-chain blocks can be reorged away.
- target: $.paths['/transaction'].post
  description: Mark the only state-changing operation in the API so agent tooling can gate it.
  update:
    x-agentic-access:
      action_class: write
      consequence: irreversible
      requires_human_confirmation: true
      requires_signing_key: true
      description: >-
        Submits a signed extrinsic to the network. Spends real KSM and cannot be undone. Must never be
        exposed to an autonomous agent without explicit human confirmation, and the agent must never hold
        the signing key — build the payload, sign out of band, submit only signed bytes.
      safe_alternative: POST /transaction/dry-run
- target: $.paths['/transaction/dry-run'].post
  description: Mark the safe rehearsal path.
  update:
    x-agentic-access:
      action_class: read
      consequence: none
      description: Executes a signed extrinsic against current state without submitting it. The correct
        way for an agent to answer "would this succeed?".
- target: $.paths['/transaction/fee-estimate'].post
  description: Mark fee estimation as read-only despite being a POST.
  update:
    x-agentic-access:
      action_class: read
      consequence: none
- target: $.paths['/contracts/ink/{address}/query'].post
  description: Mark ink! contract query as read-only despite being a POST.
  update:
    x-agentic-access:
      action_class: read
      consequence: none
      note: Executes contract code in a query context; no state is committed, but cost is bounded by
        gasLimit.
- target: $.tags[?(@.name=='paras')]
  description: Record the phase-out that the operation summaries state in prose.
  update:
    x-lifecycle-status: deprecated
    x-superseded-by: coretime
    x-deprecation-note: >-
      The paras/auctions/crowdloans/leases model is being phased out in favor of Agile Coretime. Eight
      operations under /paras carry "DEPRECATION NOTE: PHASED OUT ENDPOINT IN FAVOR OF CORETIME" in their
      summaries. New integrations should model cores, regions, workloads and renewals under the coretime
      tag instead.
- target: $.tags[?(@.name=='trace')]
  description: Flag the trace family as experimental and expensive.
  update:
    x-stability: experimental
    x-cost: high
    x-note: Block tracing is computationally expensive and served under /experimental/ for the relay-chain
      variants. Unsuitable as a default tool in an agent surface.
- target: $.components
  description: Name the schema that anchors the whole data model.
  update:
    x-core-schema: BlockIdentifiers
    x-core-schema-note: >-
      Referenced by 46 of the 156 component schemas — more than ten times any other type. Shape is
      {height, hash}, returned as `at` on nearly every stateful response. It is the version stamp on
      every object in this API; two responses are only mutually consistent if their `at` matches.
    x-data-model-artifact: data-model/kusama-data-model.yml
- target: $
  description: Record the specification-quality gaps found during enrichment, for a follow-up upstream.
  update:
    x-spec-quality-findings:
    - finding: 35 of 119 operations declare no operationId.
      impact: Weakens code generation, MCP tool naming, and agent grounding. Affects the entire
        /pallets/{palletId}/* introspection family and all of /paras and /runtime.
      recommendation: Add stable operationIds to every operation.
    - finding: Only 1 of 119 operations declares a 500 response, yet 500s are trivially reproducible in
        production (captured live on 2026-07-19 from /pallets/staking/progress).
      impact: Generated clients do not model the error path that callers actually hit.
      recommendation: Declare 500 on every operation that touches the upstream node WebSocket.
    - finding: 43 operations declare no 4xx response at all.
      impact: Incomplete error contract.
    - finding: No securitySchemes are declared.
      impact: Correct for the public deployment, but self-hosted operators put auth in front of this and
        the spec offers them no scheme to reference.
    - finding: Errors are not RFC 9457, and the error body includes a server stack trace.
      impact: Callers must string-match on message; the stack field discloses internal paths.
      recommendation: Adopt application/problem+json with stable type URIs, and strip stack in production.