feat: openapi spec cleanup for schemathesis fuzzing and cleaner API error responses

docs/rpc/components/examples/pox-info.example.json

@@ -3,6 +3,7 @@
   "pox_activation_threshold_ustx": 52329761604388,
   "first_burnchain_block_height": 666050,
   "current_burnchain_block_height": 812345,
+  "current_epoch": "Epoch33",
   "prepare_phase_block_length": 100,
   "reward_phase_block_length": 2000,
   "reward_slots": 4000,

docs/rpc/components/parameters/contract-address.yaml

@@ -1,12 +1,9 @@
+# Deployer address for contract endpoints (standard principal format)
 name: contract_address
 in: path
 required: true
 description: |
   Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).
-  Must be 28-41 characters long using Stacks base58check format.
+  Must be 28-41 characters long using Stacks c32check format.
 schema:
-  type: string
-  pattern: "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$"
-  minLength: 28
-  maxLength: 41
-  example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0
+  $ref: '../schemas/standard-principal.schema.yaml'

docs/rpc/components/parameters/principal.yaml

@@ -6,8 +6,4 @@ description: |
   (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).
   Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.
 schema:
-  type: string
-  pattern: "^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$"
-  minLength: 28
-  maxLength: 170
-  example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info
+  $ref: '../schemas/principal.schema.yaml'

docs/rpc/components/parameters/standard-principal.yaml

@@ -0,0 +1,8 @@
+name: principal
+in: path
+required: true
+description: |
+  Standard Stacks address (standard principal, not contract principal).
+  Must be 28-41 characters long using Stacks c32check format.
+schema:
+  $ref: '../schemas/standard-principal.schema.yaml'

docs/rpc/components/schemas/clarity-data.schema.yaml

@@ -9,5 +9,5 @@ properties:
     pattern: "^0x[0-9a-f]+$"
   proof:
     type: string
-    description: Hex-encoded 0x prefixed string of the Merkle proof for the data
-    pattern: "^0x[0-9a-f]+$"
+    description: Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.
+    pattern: "^(0x[0-9a-f]+)?$"

docs/rpc/components/schemas/clarity-name.schema.yaml

@@ -1,4 +1,9 @@
 type: string
-pattern: "^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$"
+description: |
+  A valid Clarity name. Must either:
+  - Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]
+  - Be exactly one of the special characters: - + = * /
+  - Be a comparison operator: < > <= >=
+pattern: "^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$"
 minLength: 1
 maxLength: 128

docs/rpc/components/schemas/pox-info.schema.yaml

@@ -125,7 +125,6 @@ properties:
           Any eligible stacks must be stacked before this block.
       blocks_until_prepare_phase:
         type: integer
-        minimum: 0
         description:
           The number of burn blocks until the prepare phase for this cycle
           starts. If the prepare phase for this cycle already started, this value

docs/rpc/components/schemas/principal.schema.yaml

@@ -0,0 +1,11 @@
+# Standard principal or contract principal (address.contract-name)
+type: string
+pattern: "^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})?$"
+minLength: 28
+maxLength: 170
+examples:
+  - SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0
+  - SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info
+  - ST000000000000000000002AMW42H
+  - SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G
+  - SN2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKP6D2ZK9

docs/rpc/components/schemas/read-only-function-args.schema.yaml

@@ -1,17 +1,22 @@
 description: Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset
 type: object
+additionalProperties: false
 required:
   - sender
   - arguments
 properties:
   sender:
-    type: string
-    description: The simulated tx-sender
+    description: The simulated tx-sender.
+    allOf:
+      - $ref: './standard-principal.schema.yaml'
   sponsor:
-    type: string
-    description: The simulated sponsor address
+    description: The simulated sponsor address.
+    allOf:
+      - $ref: './principal.schema.yaml'
   arguments:
     type: array
     description: An array of hex serialized Clarity values
     items:
       type: string
+      pattern: "^(0x)?([0-9a-fA-F]{2})+$"
+      description: Hex-encoded Clarity value (optionally prefixed with 0x)

docs/rpc/components/schemas/stackerdb-chunk-data.schema.yaml

@@ -8,16 +8,18 @@ properties:
   slot_id:
     type: integer
     minimum: 0
-    description: Slot identifier
+    maximum: 4294967295
+    description: Slot identifier (u32 range)
   slot_version:
     type: integer
     minimum: 0
-    description: Slot version (lamport clock)
+    maximum: 4294967295
+    description: Slot version (lamport clock, u32 range)
   sig:
     type: string
     description: Hex-encoded signature from the stacker
     pattern: "^[0-9a-f]{130}$"
   data:
     type: string
-    description: Hex-encoded chunk data
-    pattern: "^[0-9a-f]*$"
+    description: Hex-encoded chunk data (must be even length)
+    pattern: "^([0-9a-f]{2})*$"

docs/rpc/components/schemas/standard-principal.schema.yaml

@@ -0,0 +1,10 @@
+# Standard principal only, no contract suffix
+type: string
+pattern: "^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$"
+minLength: 28
+maxLength: 41
+examples:
+  - SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0
+  - ST000000000000000000002AMW42H
+  - SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G
+  - SN2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKP6D2ZK9

docs/rpc/components/schemas/transaction-submission-error.schema.yaml

@@ -3,7 +3,6 @@ type: object
 required:
   - error
   - reason
-  - reason_data
   - txid
 properties:
   error: