From 366b4334037bc726b3293e7aa8f9e1d504c41cc9 Mon Sep 17 00:00:00 2001
From: Linus Kendall <5172293+linuskendall@users.noreply.github.com>
Date: Mon, 14 Sep 2026 06:22:26 +0000
Subject: [PATCH] feat(spec): add getBlockCommitment specification

---
 methods/http/getBlockCommitment.md     | 11 ++++++++
 methods/http/getBlockCommitment.yaml   | 38 +++++++++++++++++++++++++
 proposals/0036-get-block-commitment.md | 39 ++++++++++++++++++++++++++
 spec-info.yaml                         |  2 +-
 4 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 methods/http/getBlockCommitment.md
 create mode 100644 methods/http/getBlockCommitment.yaml
 create mode 100644 proposals/0036-get-block-commitment.md

diff --git a/methods/http/getBlockCommitment.md b/methods/http/getBlockCommitment.md
new file mode 100644
index 0000000..abeaffa
--- /dev/null
+++ b/methods/http/getBlockCommitment.md
@@ -0,0 +1,11 @@
+# getBlockCommitment
+
+Returns the cluster stake commitment accumulated for slot.
+
+## Semantics
+
+The commitment member is null when the node has no retained commitment record for the slot. Otherwise it is the fixed 32-entry array indexed by confirmation depth; each value is stake, not a percentage. totalStake is reported even when commitment is null.
+
+## Implementation notes
+
+- [**Agave**](../../implementations/agave.md): reference implementation. See the pinned [handler](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc.rs#L3383-L3389).
diff --git a/methods/http/getBlockCommitment.yaml b/methods/http/getBlockCommitment.yaml
new file mode 100644
index 0000000..526dcc3
--- /dev/null
+++ b/methods/http/getBlockCommitment.yaml
@@ -0,0 +1,38 @@
+name: getBlockCommitment
+status: standard
+summary: Returns the stake commitment for a block slot.
+params:
+  - name: slot
+    required: true
+    summary: Slot whose commitment is requested.
+    schema: { $ref: '#/components/schemas/Slot' }
+result:
+  name: blockCommitment
+  summary: Stake commitment array, if retained, and the cluster total stake.
+  schema:
+    type: object
+    required: [commitment, totalStake]
+    properties:
+      commitment:
+        oneOf:
+          - type: array
+            minItems: 32
+            maxItems: 32
+            items: { $ref: '#/components/schemas/U64' }
+          - type: 'null'
+      totalStake: { $ref: '#/components/schemas/U64' }
+errors:
+  - $ref: '#/components/errors/InvalidParams'
+examples:
+  - name: committed-slot
+    summary: Return commitment for a recently rooted slot.
+    params:
+      - name: slot
+        value: 5
+    result:
+      name: blockCommitment
+      value: { commitment: null, totalStake: 10000 }
+implementations:
+  agave: { status: full }
+  cloudbreak: { status: none }
+  superbank: { status: none }
diff --git a/proposals/0036-get-block-commitment.md b/proposals/0036-get-block-commitment.md
new file mode 100644
index 0000000..9a884d9
--- /dev/null
+++ b/proposals/0036-get-block-commitment.md
@@ -0,0 +1,39 @@
+---
+number: 0036
+title: Add getBlockCommitment method specification
+authors: [rpcpool]
+status: draft
+created: 2026-09-14
+reference-implementations:
+  - https://github.com/anza-xyz/agave/tree/6dd9d38771e46103b9680357a855804165612602
+---
+
+# Add getBlockCommitment method specification
+
+## Summary
+
+Add the public ledger commitment query.
+
+## Motivation
+
+Clients need a portable contract for this public Agave RPC method.
+
+## Specification
+
+Add the paired HTTP method files. The method accepts one slot and returns a nullable stake array with the total stake.
+
+## Return-type impact
+
+Adds the result shape defined by the paired method source.
+
+## Compatibility
+
+This is additive. Agave conforms. Cloudbreak and Superbank do not serve the method.
+
+## Reference implementation
+
+- [Agave handler](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc.rs#L3383-L3389)
+
+## Security considerations
+
+The method reads public cluster metadata and has a fixed-size request.
diff --git a/spec-info.yaml b/spec-info.yaml
index 892ea85..bca4391 100644
--- a/spec-info.yaml
+++ b/spec-info.yaml
@@ -1,5 +1,5 @@
 title: Solana JSON-RPC API
-version: 0.1.0
+version: 0.2.0
 license:
   name: MIT
   url: https://opensource.org/license/mit/