feat: return groupId when adding groups (CPL-145) (#202)

* feat: return group_id from addGroup across contract and API (CPL-145)

Modify the Solidity addGroup function to return the on-chain group ID
(uint256). Update ABI, generated Rust bindings, and make send_transaction
generic over Detokenize. The Rust add_group function simulates the call
first to capture the group ID, then sends the real transaction. Adds
AddGroupResponse with success + group_id fields.

Includes a fix for signer pool leak if the simulation call fails.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: surface group_id in SDK and dashboard (CPL-145)

Update core_sdk.js addGroup to document the new AddGroupResponse type.
Dashboard now shows the created group ID in the success toast.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: use returned group_id in K6 tests (CPL-145)

Add AddGroupResponse type to K6 client. Integration and security tests
now extract group_id directly from the addGroup response instead of
calling listGroups, simplifying setup and removing race conditions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: update API examples with addGroup response format (CPL-145)

Show the new {"success":true,"group_id":"1"} response in API docs.
Remove the now-unnecessary listGroups step from quickstart examples.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: GTC6244

docs/api_direct.mdx

@@ -156,11 +156,8 @@ Create a group (with optional permitted actions and PKPs). Then add an action (I
       -H "Content-Type: application/json" \
       -H "X-Api-Key: KEY" \
       -d '{"group_name":"My Group","group_description":"","pkp_ids_permitted":[],"cid_hashes_permitted":[]}'
-    
-    # List groups to get group_id (use the "id" from the response)
-    curl -s "http://localhost:8000/core/v1/list_groups?page_number=0&page_size=10" \
-      -H "X-Api-Key: KEY"
-    
+    # Response: {"success":true,"group_id":"1"}
+
     # Register action metadata (replace IPFS_CID)
     curl -s -X POST "http://localhost:8000/core/v1/add_action" \
       -H "Content-Type: application/json" \

docs/management/api_direct.mdx

@@ -175,12 +175,9 @@ Create a group, then add an action (IPFS CID) to scope which keys can run it.
         "pkp_ids_permitted": [],
         "cid_hashes_permitted": []
       }'
+    # Response: {"success":true,"group_id":"1"}
 
-    # List groups to get group_id
-    curl -s "http://localhost:8000/core/v1/list_groups?page_number=0&page_size=10" \
-      -H "X-Api-Key: KEY"
-
-    # Add action to group (replace GROUP_ID and IPFS_CID)
+    # Add action to group (use group_id from the response above)
     curl -s -X POST "http://localhost:8000/core/v1/add_action_to_group" \
       -H "Content-Type: application/json" \
       -H "X-Api-Key: KEY" \

k6/correctness/api-key-security.spec.ts

@@ -130,23 +130,15 @@ export function setup(): SecuritySetupData {
     adminA,
   );
   if (!assertOk("setup/addGroupX", "POST /add_group", addGroupXRes)) throw new Error("setup failed: addGroupX");
+  const groupIdX = parseInt((addGroupXRes.data as { group_id: string }).group_id);
 
   // Create group Y
   const addGroupYRes = client.addGroup(
     { group_name: `k6-sec-groupY-${K6_RUN_ID}`, group_description: "Security test group Y", pkp_ids_permitted: [], cid_hashes_permitted: [] },
     adminA,
   );
   if (!assertOk("setup/addGroupY", "POST /add_group", addGroupYRes)) throw new Error("setup failed: addGroupY");
-
-  // List groups to extract IDs
-  const listGroupsRes = client.listGroups({ page_number: 0, page_size: 100 }, adminA);
-  if (!assertOk("setup/listGroups", "GET /list_groups", listGroupsRes)) throw new Error("setup failed: listGroups");
-  const groups = listGroupsRes.data as Array<{ id: string; name: string }>;
-  const groupX = groups.find((g) => g.name === `k6-sec-groupX-${K6_RUN_ID}`);
-  const groupY = groups.find((g) => g.name === `k6-sec-groupY-${K6_RUN_ID}`);
-  if (!groupX || !groupY) throw new Error("setup failed: could not find created groups");
-  const groupIdX = parseInt(groupX.id);
-  const groupIdY = parseInt(groupY.id);
+  const groupIdY = parseInt((addGroupYRes.data as { group_id: string }).group_id);
 
   // Get IPFS CID for hello-world action
   const ipfsRes = client.getLitActionIpfsId(HELLO_WORLD_CODE);
@@ -218,13 +210,7 @@ export function setup(): SecuritySetupData {
     adminB,
   );
   if (!assertOk("setup/addGroupB", "POST /add_group", addGroupBRes)) throw new Error("setup failed: addGroupB");
-
-  const listGroupsBRes = client.listGroups({ page_number: 0, page_size: 100 }, adminB);
-  if (!assertOk("setup/listGroupsB", "GET /list_groups", listGroupsBRes)) throw new Error("setup failed: listGroupsB");
-  const groupsB = listGroupsBRes.data as Array<{ id: string; name: string }>;
-  const groupB = groupsB.find((g) => g.name === `k6-sec-groupB-${K6_RUN_ID}`);
-  if (!groupB) throw new Error("setup failed: could not find Account B group");
-  const groupIdB = parseInt(groupB.id);
+  const groupIdB = parseInt((addGroupBRes.data as { group_id: string }).group_id);
 
   // Add action to Account B's group
   const addActionBRes = client.addAction(
@@ -290,13 +276,9 @@ export default function (data: SecuritySetupData) {
     assertOk("2-createGroup-positive", "POST /add_group", posRes);
 
     // Clean up: delete the created group with admin key
-    const listRes = client.listGroups({ page_number: 0, page_size: 100 }, adminA);
-    if (assertOk("2-listGroups-cleanup", "GET /list_groups", listRes)) {
-      const gs = listRes.data as Array<{ id: string; name: string }>;
-      const created = gs.find((g) => g.name === `k6-sec-t2-pos-${K6_RUN_ID}`);
-      if (created) {
-        client.removeGroup({ group_id: created.id }, adminA);
-      }
+    const createdGroupId = (posRes.data as { group_id: string }).group_id;
+    if (createdGroupId) {
+      client.removeGroup({ group_id: createdGroupId }, adminA);
     }
 
     // Negative: key with can_create_groups=false
@@ -315,15 +297,11 @@ export default function (data: SecuritySetupData) {
       adminA,
     );
     assertOk("3-createTempGroup", "POST /add_group", tempRes);
-    const listRes = client.listGroups({ page_number: 0, page_size: 100 }, adminA);
-    assertOk("3-listGroups", "GET /list_groups", listRes);
-    const gs = listRes.data as Array<{ id: string; name: string }>;
-    const temp = gs.find((g) => g.name === `k6-sec-t3-temp-${K6_RUN_ID}`);
-    if (!temp) { console.error("3-deleteGroup: temp group not found"); return; }
+    const tempGroupId = (tempRes.data as { group_id: string }).group_id;
 
     // Positive: key with can_delete_groups=true
     const posRes = client.removeGroup(
-      { group_id: temp.id },
+      { group_id: tempGroupId },
       authHeaders(data.usageKey_deleteGroups),
     );
     assertOk("3-deleteGroup-positive", "POST /remove_group", posRes);

k6/correctness/integration.spec.ts

@@ -130,14 +130,16 @@ export default function (data: IntegrationSetupData) {
   checkAndLog(addGroupRes.response, {
     "addGroup success": (r) => {
       try {
-        return JSON.parse(r.body as string).success === true;
+        const body = JSON.parse(r.body as string);
+        return body.success === true && typeof body.group_id === "string";
       } catch {
         return false;
       }
     },
   }, "addGroup");
+  const groupId = (addGroupRes.data as { success: boolean; group_id: string }).group_id;
 
-  // ── 7. listGroups — extract groupId for subsequent tests ──────────────────
+  // ── 7. listGroups — verify group appears ──────────────────────────────────
   const listGroupsRes = client.listGroups(
     { page_number: 0, page_size: 10 },
     authHeaders,
@@ -152,12 +154,6 @@ export default function (data: IntegrationSetupData) {
       }
     },
   }, "listGroups");
-  const groups = listGroupsRes.data as Array<{ id: string; name: string; description: string }>;
-  if (!groups || groups.length === 0) {
-    console.error("listGroups returned empty array after addGroup");
-    return;
-  }
-  const groupId = groups[groups.length - 1].id; // use the most recently created group
 
   // ── 8. updateGroup — called while group is empty so the full-replace is safe ───
   const updateGroupRes = client.updateGroup(

k6/litApiServer.ts

@@ -72,12 +72,20 @@ export interface LitActionRequest {
 }
 
 /**
- * Response for account config operations (add_group, add_pkp_to_group, remove_pkp_from_group, add_usage_api_key, remove_usage_api_key).
+ * Response for account config operations (add_pkp_to_group, remove_pkp_from_group, add_usage_api_key, remove_usage_api_key).
  */
 export interface AccountOpResponse {
   success: boolean;
 }
 
+/**
+ * Response for add_group, includes the on-chain group ID.
+ */
+export interface AddGroupResponse {
+  success: boolean;
+  group_id: string;
+}
+
 /**
  * Request for add_group. permitted_actions and pkps are keccak256 hashes as hex strings (with or without 0x). API key via header.
  */
@@ -398,7 +406,7 @@ export type AddGroupHeaders = {
   "X-Api-Key": string;
 };
 
-export type AddGroupDefault = AccountOpResponse | ErrMessage;
+export type AddGroupDefault = AddGroupResponse | ErrMessage;
 
 export type RemoveGroupHeaders = {
   /**

lit-api-server/blockchain/lit_node_express/contracts/AccountConfigFacets/WritesFacet.sol

@@ -107,7 +107,7 @@ contract WritesFacet {
         string memory description,
         uint256[] memory cidHashes,
         address[] memory pkpIds
-    ) public {
+    ) public returns (uint256) {
         SecurityLib.revertIfNoAccountAccess(accountApiKeyHash, msg.sender);
         SecurityLib.revertIfNotMasterAccount(accountApiKeyHash);
         AppStorage.AccountConfigStorage storage s = AppStorage.getStorage();
@@ -124,6 +124,7 @@ contract WritesFacet {
         for (uint256 i = 0; i < pkpIds.length; i++) {
             group.pkpId.add(pkpIds[i]);
         }
+        return account.groupCount;
     }
 
     function updateGroup(

lit-api-server/src/accounts/contracts/AccountConfig.json

@@ -215,7 +215,13 @@
         }
       ],
       "name": "addGroup",
-      "outputs": [],
+      "outputs": [
+        {
+          "internalType": "uint256",
+          "name": "",
+          "type": "uint256"
+        }
+      ],
       "stateMutability": "nonpayable",
       "type": "function"
     },

lit-api-server/src/accounts/contracts/account_config_contract.rs

@@ -2230,7 +2230,7 @@ pub mod account_config {
             description: ::std::string::String,
             cid_hashes: ::std::vec::Vec<::ethers::core::types::U256>,
             pkp_ids: ::std::vec::Vec<::ethers::core::types::Address>,
-        ) -> ::ethers::contract::builders::ContractCall<M, ()> {
+        ) -> ::ethers::contract::builders::ContractCall<M, ::ethers::core::types::U256> {
             self.0
                 .method_hash(
                     [43, 18, 222, 230],

lit-api-server/src/accounts/mod.rs

@@ -73,18 +73,37 @@ pub async fn add_group(
     description: &str,
     cid_hashes: Vec<U256>,
     pkp_ids: Vec<Address>,
-) -> Result<bool> {
+) -> Result<U256> {
     let (contract, signer_address, client) =
         get_signable_account_config_contract(signer_pool.clone()).await?;
     let account_api_key_hash = api_key_hash(api_key);
+
+    // Simulate the call first to obtain the returned group ID.
+    let sim_call = contract.add_group(
+        account_api_key_hash,
+        name.to_string(),
+        description.to_string(),
+        cid_hashes.clone(),
+        pkp_ids.clone(),
+    );
+    let group_id = match sim_call.call().await {
+        Ok(id) => id,
+        Err(e) => {
+            // Release the signer back to the pool before propagating.
+            signer_pool.release(signer_address).await?;
+            return Err(e.into());
+        }
+    };
+
     let function_call = contract.add_group(
         account_api_key_hash,
         name.to_string(),
         description.to_string(),
         cid_hashes,
         pkp_ids,
     );
-    send_transaction(function_call, signer_pool, signer_address, client).await
+    send_transaction(function_call, signer_pool, signer_address, client).await?;
+    Ok(group_id)
 }
 
 /// Create a new action entry with name, description, and IPFS CID hash in the account's actionMetadata mapping.

lit-api-server/src/accounts/signable_contract.rs

@@ -108,8 +108,8 @@ pub(crate) async fn get_read_only_account_config_contract()
     Ok(contract)
 }
 
-pub async fn send_transaction(
-    mut function_call: ContractCall<SigningClient, ()>,
+pub async fn send_transaction<T: ethers::abi::Detokenize>(
+    mut function_call: ContractCall<SigningClient, T>,
     signer_pool: Arc<SignerPool>,
     signer_address: H160,
     client: Arc<SigningClient>,