From 3701ed2c90d794e3b8fc47437a78af2cb8685402 Mon Sep 17 00:00:00 2001
From: Olivier Desenfans <desenfans.olivier@gmail.com>
Date: Tue, 25 Aug 2026 15:21:04 +0200
Subject: [PATCH] feat: add V-PROGRAM to address stats sort keys and counts

SortByMessageType gains V_PROGRAM and AddressStats a v_program counter
(defaulting to 0 so responses from nodes that do not report it still
parse, given extra="forbid").
---
 src/aleph/sdk/query/filters.py      |  3 ++-
 src/aleph/sdk/query/responses.py    |  1 +
 tests/unit/test_asynchronous_get.py | 14 ++++++++++++++
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/aleph/sdk/query/filters.py b/src/aleph/sdk/query/filters.py
index 4ed7f15d..9e5c9a0e 100644
--- a/src/aleph/sdk/query/filters.py
+++ b/src/aleph/sdk/query/filters.py
@@ -30,6 +30,7 @@ class SortByMessageType(str, Enum):
     POST = "post"
     PROGRAM = "program"
     STORE = "store"
+    V_PROGRAM = "v_program"
     TOTAL = "total"
 
 
@@ -252,7 +253,7 @@ class AddressesFilter:
     A collection of query parameters for address stats queries.
 
     :param address_contains: Case-insensitive substring to filter addresses
-    :param sort_by: Message type to sort by (aggregate, forget, instance, post, program, store, total)
+    :param sort_by: Message type to sort by (aggregate, forget, instance, post, program, store, v_program, total)
     :param sort_order: Sort order (ascending or descending)
     """
 
diff --git a/src/aleph/sdk/query/responses.py b/src/aleph/sdk/query/responses.py
index 5204d08a..46d6f77c 100644
--- a/src/aleph/sdk/query/responses.py
+++ b/src/aleph/sdk/query/responses.py
@@ -160,6 +160,7 @@ class AddressStats(BaseModel):
     forget: int = Field(description="Number of FORGET messages")
     program: int = Field(description="Number of PROGRAM messages")
     instance: int = Field(description="Number of INSTANCE messages")
+    v_program: int = Field(default=0, description="Number of V-PROGRAM messages")
 
     model_config = ConfigDict(extra="forbid")
 
diff --git a/tests/unit/test_asynchronous_get.py b/tests/unit/test_asynchronous_get.py
index 1514bfcd..f7d37623 100644
--- a/tests/unit/test_asynchronous_get.py
+++ b/tests/unit/test_asynchronous_get.py
@@ -16,6 +16,7 @@
 )
 from aleph.sdk.query.responses import (
     AccountFilesResponse,
+    AddressStats,
     AddressStatsResponse,
     ChainBalancesResponse,
     PostsResponse,
@@ -393,3 +394,16 @@ async def test_get_account_files_rejects_empty_address():
 
 if __name__ == "__main __":
     unittest.main()
+
+
+def test_addresses_filter_sort_by_v_program():
+    f = AddressesFilter(sort_by=SortByMessageType.V_PROGRAM)
+    assert f.as_http_params() == {"sortBy": "v_program"}
+
+
+def test_address_stats_v_program_defaults_to_zero():
+    stats = AddressStats(
+        messages=1, post=1, aggregate=0, store=0, forget=0, program=0, instance=0
+    )
+    assert stats.v_program == 0
+    assert AddressStats(**{**stats.model_dump(), "v_program": 3}).v_program == 3