Updated the Signer API docs

jclapis · jclapis · commit ff716a0ed7b1 · 2025-07-29T01:06:31.000-04:00
diff --git a/api/signer-api.yml b/api/signer-api.yml
@@ -60,7 +60,7 @@ paths:
 
   /signer/v1/request_signature:
     post:
-      summary: Send a signature request
+      summary: Request a signature for a 32-byte blob of data (typically a hash), signed by the requested BLS or ECDSA key.
       tags:
         - Signer
       security:
@@ -81,15 +81,15 @@ paths:
                   type: string
                   enum: [consensus, proxy_bls, proxy_ecdsa]
                 pubkey:
-                  description: Public key of the validator for consensus signatures
+                  description: The 48-byte BLS public key, with optional `0x` prefix, of the proposer key that you want to request a signature from.
                   $ref: "#/components/schemas/BlsPubkey"
                 proxy:
-                  description: BLS proxy pubkey or ECDSA address for proxy signatures
+                  description: The 48-byte BLS public key (for `proxy_bls` mode) or the 20-byte Ethereum address (for `proxy_ecdsa` mode), with optional `0x` prefix, of the proxy key that you want to request a signature from.
                   oneOf:
                     - $ref: "#/components/schemas/BlsPubkey"
                     - $ref: "#/components/schemas/EcdsaAddress"
                 object_root:
-                  description: The root of the object to be signed
+                  description: The 32-byte data you want to sign, with optional `0x` prefix.
                   type: string
                   format: hex
                   pattern: "^0x[a-fA-F0-9]{64}$"
@@ -112,7 +112,7 @@ paths:
                   object_root: "0x3e9f4a78b5c21d64f0b8e3d9a7f5c02b4d1e67a3c8f29b5d6e4a3b1c8f72e6d9"
       responses:
         "200":
-          description: Success
+          description: A successful signature response. The returned signature is the Merkle root hash of the provided `object_root` field and the requesting module's Signing ID as specified in the Commit-Boost configuration. For details on this signature, see the [signature structure documentation](https://commit-boost.github.io/commit-boost-client/developing/prop-commit-signing.md#structure-of-a-signature).
           content:
             application/json:
               schema:
@@ -126,8 +126,45 @@ paths:
                   value: "0xa3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989a3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989"
                 ProxyEcdsa:
                   value: "0x985b495f49d1b96db3bba3f6c5dd1810950317c10d4c2042bd316f338cdbe74359072e209b85e56ac492092d7860063dd096ca31b4e164ef27e3f8d508e656801c"
+        "400":
+          description: |
+            This can occur in several scenarios:
+            
+            - You requested an operation while using the Dirk signer mode instead of locally-managed signer mode, but Dirk doesn't support that operation.
+            - Something went wrong while preparing your request; the error text will provide more information.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - code
+                  - message
+                properties:
+                  code:
+                    type: number
+                    example: 400
+                  message:
+                    type: string
+                    example: "Bad request: Invalid pubkey format"
+        "401":
+          description: The requesting module did not provide a JWT string in the request's authorization header, or the JWT string was not configured in the signer service's configuration file as belonging to the module.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - code
+                  - message
+                properties:
+                  code:
+                    type: number
+                    example: 401
+                  message:
+                    type: string
+                    example: "Unauthorized"
+        
         "404":
-          description: Unknown value (pubkey, etc.)
+          description: You either requested a route that doesn't exist, or you requested a signature from a key that does not exist.
           content:
             application/json:
               schema:
@@ -142,8 +179,24 @@ paths:
                   message:
                     type: string
                     example: "Unknown pubkey"
+        "429":
+          description: Your module attempted and failed JWT authentication too many times recently, and is currently timed out. It cannot make any more requests until the timeout ends.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - code
+                  - message
+                properties:
+                  code:
+                    type: number
+                    example: 429
+                  message:
+                    type: string
+                    example: "Too many requests"
         "500":
-          description: Internal error
+          description: Your request was valid, but something went wrong internally that prevented it from being fulfilled.
           content:
             application/json:
               schema:
@@ -158,6 +211,22 @@ paths:
                   message:
                     type: string
                     example: "Internal error"
+        "502":
+          description: The signer service is running in Dirk signer mode, but Dirk could not be reached.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - code
+                  - message
+                properties:
+                  code:
+                    type: number
+                    example: 502
+                  message:
+                    type: string
+                    example: "Bad gateway: Dirk signer service is unreachable"
 
   /signer/v1/generate_proxy_key:
     post:
diff --git a/docs/docs/developing/prop-commit-signing.md b/docs/docs/developing/prop-commit-signing.md
@@ -58,118 +58,3 @@ where:
 The data signed in a proposer commitment is the 32-byte root of this tree (the green `Root` box). Note that calculating this will involve calculating the Merkle Root of two separate trees: first the blue data subtree (with the original request data and the signing ID) to establish the blue `Root` value, and then again with a tree created from that value and the `Domain`. 
 
 Many languages provide libraries for computing the root of an SSZ Merkle tree, such as [fastssz for Go](https://github.com/ferranbt/fastssz) or [tree_hash for Rust](https://docs.rs/tree_hash/latest/tree_hash/). When verifying proposer commitment signatures, use a library that supports Merkle tree root hashing, the `compute_domain()` operation, and validation for signatures generated by your key of choice.
-
-
-## Requesting a Proposer Commitment from the Signer
-
-Prior to requesting a signature from the signer service, first ensure that Commit Boost has been [configured](#configuring-a-module-for-proposer-commitments) with your module's signing ID and JWT secret.
-
-The signer service can be accessed by an HTTP API. In Docker mode, this will be within the `cb_signer` container at the `/signer/v1/request_signature` route (for example, using the default port of `20000`, the endpoint will be `http://cb_signer:20000/signer/v1/request_signature`). Submitting a request must be done via the `POST` method.
-
-
-### Headers
-
-- Set `Content-Type` set to `application/json`.
-- Set `Accept` to `application/json`, as responses are quoted strings. Other formats are not currently supported.
-- Set `Authorization` to a standard JWT string representing your module's JWT authentication information. For the claims, you can add a `module` claim indicating the human-readable name of your module.
-
-
-### BLS Proposer Keys
-
-If requesting a signature directly from a proposer pubkey, use the following body specification:
-
-```json
-{
-    "type": "consensus",
-    "pubkey": "0x1234abcd...",
-    "object_root": "0x01020304..."
-}
-```
-
-where:
-
-- `pubkey` is the 48-byte BLS public key, with optional `0x` prefix, of the proposer key that you want to request a signature from.
-- `object_root` is the 32-byte data you want to sign, with optional `0x` prefix.
-
-
-### BLS Proxy Keys
-
-If requesting a signature indirectly from a proposer key via a [proxy key](./commit-module.md#with-a-proxy-key), use the following body specification:
-
-```json
-{
-    "type": "proxy_bls",
-    "proxy": "0x1234abcd...",
-    "object_root": "0x01020304..."
-}
-```
-
-where:
-
-- `proxy` is the 48-byte BLS public key, with optional `0x` prefix, of the proxy key that you want to request a signature from.
-- `object_root` is the 32-byte data you want to sign, with optional `0x` prefix.
-
-
-### ECDSA Proxy Keys
-
-**NOTE:** ECDSA proxy key support is not available when using Dirk.
-
-If requesting a signature indirectly from an Ethereum private key via a [proxy key](./commit-module.md#with-a-proxy-key), use the following body specification:
-
-```json
-{
-    "type": "proxy_ecdsa",
-    "proxy": "0x1234abcd...",
-    "object_root": "0x01020304..."
-}
-```
-
-where:
-
-- `proxy` is the 20-byte Ethereum address of the proxy key, with optional `0x` prefix, of the ECDSA private key that you want to request a signature from.
-- `object_root` is the 32-byte data you want to sign, with optional `0x` prefix.
-
-
-### Response
-
-The response for any of the above will be one of the following, provided in plaintext format (not JSON).
-
-
-#### `200 OK`
-
-A successful signing request, with the signature provided as a plaintext quoted hex-encoded string, with a `0x` prefix. For example, the response body would look like:
-```
-"0xa43e623f009e615faa3987368f64d6286a4103de70e9a81d82562c50c91eae2d5d6fb9db9fe943aa8ee42fd92d8210c1149f25ed6aa72a557d74a0ed5646fdd0e8255ec58e3e2931695fe913863ba0cdf90d29f651bce0a34169a6f6ce5b3115"
-```
-
-#### `401 Unauthorized`
-
-Your module did not provide a JWT string in the request's authorization header, or the JWT string was not configured in the signer service's configuration file as belonging to your module.
-
-
-#### `400 Bad Request`
-
-This can occur in several scenarios:
-
-- You requested an operation while using the Dirk signer mode instead of locally-managed signer mode, but Dirk doesn't support that operation.
-- Something went wrong while preparing your request; the error text will provide more information.
-
-
-#### `502 Bad Gateway`
-
-The signer service is running in Dirk signer mode, but Dirk could not be reached.
-
-
-#### `404 Not Found`
-
-You either requested a route that doesn't exist, or you requested a signature from a key that does not exist.
-
-
-#### `429 Too Many Requests`
-
-Your module attempted and failed JWT authentication too many times recently, and is currently timed out. It cannot make any more requests until the timeout ends.
-
-
-#### `500 Internal Server Error`
-
-Your request was valid, but something went wrong internally that prevented it from being fulfilled.
