feat: Add exclude_function_args parameter to reduce transaction response sizes #2312

alexthuth · 2025-07-02T23:29:41Z

Description

As an API client developer, I want to control the size of transaction responses by excluding function arguments when they are not needed. This is necessary because transaction responses can vary dramatically in size (5KB to 50KB+) due to complex contract function arguments, forcing clients to use conservative pagination and resulting in 3-5x more API calls than optimal.

This pull request adds the exclude_function_args query parameter to transaction endpoints. When set to true, the API omits the function_args array from contract call transactions, significantly reducing response size while maintaining all other data.

What was changed:

Added ExcludeFunctionArgsParamSchema parameter schema
Modified parseContractCallMetadata to conditionally exclude function args
Threaded parameter through all transaction parsing functions
Updated transaction endpoints: GET /extended/v1/tx, GET /extended/v1/tx/:tx_id
Updated address transaction endpoints
Added comprehensive test coverage

How this impacts application developers:

Enables predictable response sizes for better pagination planning
Reduces bandwidth usage and improves response times
100% backward compatible (defaults to false)
Allows more efficient bulk transaction processing

Example usage:

# Standard response with function_args (larger)
GET /extended/v1/tx/0x123

# Optimized response without function_args (smaller, predictable)
GET /extended/v1/tx/0x123?exclude_function_args=true

For implementation details refer to issue #2310

Type of Change

New feature
Bug fix
API reference/documentation update
Other

Does this introduce a breaking change?

No breaking changes. The parameter is optional and defaults to false, preserving existing behavior. All existing API calls continue to work identically.

Are documentation updates required?

Link to documentation updates: OpenAPI schema is automatically updated via TypeBox

Testing information

Testing is required for this change.

Test coverage includes:

Parameter validation (boolean, optional, defaults)
Function args exclusion for contract call transactions
Preservation of function args when parameter is false/omitted
Non-contract transactions unaffected
End-to-end integration tests for both transaction endpoints

Affected code paths:

Transaction parsing pipeline (parseDbTx, parseDbMempoolTx)
Contract call metadata processing (parseContractCallMetadata)
Database controller transaction retrieval
Transaction and address API endpoints

Testing steps:

Run npm run test:api to verify all tests pass
Test transaction endpoints with and without the parameter
Verify response sizes are reduced when parameter is true
Confirm backward compatibility with existing clients

Checklist

Code is commented where needed
Unit test coverage for new or modified code paths
npm run test passes
Changelog is updated
Tag 1 of @rafaelcr or @zone117x for review

…ints - Add ExcludeFunctionArgsParamSchema to params.ts - Update parseContractCallMetadata to conditionally exclude function_args - Thread excludeFunctionArgs parameter through all parsing functions - Add parameter to transaction list, single tx, multiple tx, and mempool endpoints - Add parameter to address transaction endpoints - Add comprehensive unit tests following the testing strategy - Maintain 100% backward compatibility (defaults to false) - All lint and build checks pass Implements FEAT-FunctionArgsExclusion.md specification.

…ssing

github-actions · 2025-07-02T23:31:00Z

Vercel deployment URL: https://stacks-blockchain-8wppw7fla-hirosystems.vercel.app 🚀

codecov · 2025-07-02T23:31:12Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Default token_transfer_memo builders now default to '0x' (valid bytea hex). Set smartContract.clarity_version to null when undefined. Fixes bytea and UNDEFINED_VALUE errors in exclude_function_args tests.

CHANGELOG.md

rafaelcr · 2025-07-03T18:27:14Z

src/api/controllers/db-controller.ts

 interface GetTxsArgs {
  txIds: string[];
  includeUnanchored: boolean;
+  excludeFunctionArgs?: boolean;


Make these two new args required instead of optional. Set to false whenever you don't have it

Suggested change

excludeFunctionArgs?: boolean;

excludeFunctionArgs: boolean;

rafaelcr · 2025-07-03T18:28:29Z

src/api/schemas/params.ts

+  Type.Boolean({
+    default: false,
+    description:
+      'Exclude function_args from contract call responses for smaller, predictable sizes. Only explicit true/false values are accepted (same pattern as `unanchored`).',


Suggested change

'Exclude function_args from contract call responses for smaller, predictable sizes. Only explicit true/false values are accepted (same pattern as `unanchored`).',

'Exclude function_args from contract call responses for smaller transaction sizes.',

tests/api/parse-contract-call-metadata.test.ts

- Param now mandatory; all call sites pass false - Restore CHANGELOG, remove 8.11.0 block only - Shorten schema description - Delete obsolete parse-contract-call-metadata test

alexthuth · 2025-07-03T20:20:21Z

With the two most recent commits, we changed:

Require excludeFunctionArgs (boolean, no default) – all call-sites now pass false.
Deleted CHANGELOG.md (removed 8.11.0 stub entirely).
Trimmed description in params.ts.
Removed obsolete parse-contract-call-metadata.test.ts.

Touched files:

src/api/controllers/db-controller.ts, four route files, params.ts, +2 deletions (test & changelog).

@rafaelcr , if there is anything else, please let me know.

rafaelcr

Just one last batch of comments but it's looking good!

rafaelcr · 2025-07-03T20:29:35Z

CHANGELOG.md

Apologies, I should've explained better how this file works. This file is edited by semantic-release automatically whenever a new API release is published. As such, it should stay as part of the repository because we want to keep its (automatic) edit history. In other words, the file was deleted with your latest commit but it should still remain in the repo unchanged.

Can you revert this file to how it was before? You can do that with

git checkout develop -- CHANGELOG.md

Sorry for the confusion on this!

rafaelcr · 2025-07-03T20:30:20Z

src/api/controllers/db-controller.ts

 interface GetTxsArgs {
  txIds: string[];
  includeUnanchored: boolean;
+  excludeFunctionArgs?: boolean;


Suggested change

excludeFunctionArgs?: boolean;

excludeFunctionArgs: boolean;

rafaelcr · 2025-07-03T20:30:25Z

src/api/controllers/db-controller.ts

 interface GetTxArgs {
  txId: string;
  includeUnanchored: boolean;
+  excludeFunctionArgs?: boolean;


Suggested change

excludeFunctionArgs?: boolean;

excludeFunctionArgs: boolean;

- Restore CHANGELOG.md (auto-generated by semantic-release) - Make excludeFunctionArgs required in GetTxArgs and GetTxsArgs interfaces - Shorten description text in ExcludeFunctionArgsParamSchema - Pass excludeFunctionArgs: false at existing internal call sites and tests (per review guidance)

alexthuth · 2025-07-03T21:20:52Z

Hey @rafaelcr - just pushed the final follow-up changes based on your latest review:

Restored CHANGELOG.md - Used git checkout develop -- CHANGELOG.md as you suggested. Makes total sense that semantic-release manages this automatically!
Made excludeFunctionArgs required - Changed both GetTxArgs and GetTxsArgs interfaces from excludeFunctionArgs?: boolean to excludeFunctionArgs: boolean
Simplified the description - Updated to your exact suggestion: 'Exclude function_args from contract call responses for smaller transaction sizes.'
Removed test file - The parse-contract-call-metadata.test.ts was already deleted in an earlier commit

About the internal call site updates: When we made excludeFunctionArgs required, TypeScript flagged 13 existing call sites that weren't passing this parameter (they were relying on it being optional). Your comment "Set to false whenever you don't have it" guided us to update these internal calls - they all now explicitly pass excludeFunctionArgs: false to maintain the existing behavior (function args included by default).

The affected areas were:

Address routes (2 calls)
WebSocket transmitter (3 calls)
Test helpers (8 calls)
DB controller internal logic (removed ?? false fallbacks)

This ensures the new required parameter doesn't break any existing functionality while giving API consumers explicit control over the behavior.

rafaelcr

LGTM! Thanks @alexthuth

## [8.12.0](v8.11.6...v8.12.0) (2025-08-06) ### Features * Add exclude_function_args parameter to reduce transaction response sizes ([#2312](#2312)) ([852a60e](852a60e)) * add replaced_by_tx_id to replaced mempool transactions ([#2271](#2271)) ([a70c3d1](a70c3d1)) * **prometheus:** add chain tip metrics ([#2333](#2333)) ([bde1037](bde1037)) * SNP integration ([#2291](#2291)) ([9a159e1](9a159e1)) ### Bug Fixes * drop redundant db indexes ([#2329](#2329)) ([0ddd6a6](0ddd6a6)) * ensure some ops only run when SNP is not enabled ([fd4717b](fd4717b)) * only ingest snp chain events to avoid db bloat ([287f572](287f572)) * optimize queries to prune and restore mempool rbf txs ([#2327](#2327)) ([0b196f0](0b196f0)) * optimize replace-by-fee mempool calculations ([#2326](#2326)) ([01998bc](01998bc)) * parallelize mempool rbf updates ([#2328](#2328)) ([e7347e5](e7347e5)) * update snp image in tests ([c7c0dbb](c7c0dbb))

hirosystems-release-bot · 2025-08-06T15:08:23Z

🎉 This PR is included in version 8.12.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Alexander Huth and others added 4 commits July 2, 2025 13:48

fix: parseContractCallMetadata function argument processing

6abae65

feat: complete exclude_function_args implementation with all tests pa…

4c26296

…ssing

feat: add exclude_function_args param to reduce response size

985a147

alexthuth temporarily deployed to Preview July 2, 2025 23:29 — with GitHub Actions Inactive

alexthuth requested a review from rafaelcr July 3, 2025 01:17

alexthuth added 4 commits July 3, 2025 05:02

test: add parseContractCallMetadata missing function test

d320d87

test: cover missing ABI function branch in parseContractCallMetadata

2273bf4

test: add focused test for missing ABI function coverage

737b7d9

chore: remove stray documentation files

58014ad

alexthuth temporarily deployed to Preview July 3, 2025 16:28 — with GitHub Actions Inactive

chore: remove workplan file from PR

f7a6b19

alexthuth temporarily deployed to Preview July 3, 2025 16:29 — with GitHub Actions Inactive

docs: update changelog for exclude_function_args feature

14bb7c3

alexthuth temporarily deployed to Preview July 3, 2025 17:53 — with GitHub Actions Inactive

alexthuth force-pushed the feat/function-args-exclusion branch from 1be2649 to 14bb7c3 Compare July 3, 2025 17:59

alexthuth temporarily deployed to Preview July 3, 2025 17:59 — with GitHub Actions Inactive

fix: conform test builders to DB constraints

97aca16

Default token_transfer_memo builders now default to '0x' (valid bytea hex). Set smartContract.clarity_version to null when undefined. Fixes bytea and UNDEFINED_VALUE errors in exclude_function_args tests.

alexthuth temporarily deployed to Preview July 3, 2025 18:06 — with GitHub Actions Inactive

rafaelcr reviewed Jul 3, 2025

View reviewed changes

alexthuth added 2 commits July 3, 2025 13:08

feat: require excludeFunctionArgs param & drop 8.11.0 changelog

4567592

- Param now mandatory; all call sites pass false - Restore CHANGELOG, remove 8.11.0 block only - Shorten schema description - Delete obsolete parse-contract-call-metadata test

chore: remove CHANGELOG.md from repository

b5ac1ac

alexthuth temporarily deployed to Preview July 3, 2025 20:12 — with GitHub Actions Inactive

rafaelcr reviewed Jul 3, 2025

View reviewed changes

alexthuth temporarily deployed to Preview July 3, 2025 21:04 — with GitHub Actions Inactive

chore: fix prettier line length in tx tests (CI lint)

7dd5048

alexthuth temporarily deployed to Preview July 3, 2025 21:09 — with GitHub Actions Inactive

rafaelcr approved these changes Jul 3, 2025

View reviewed changes

rafaelcr merged commit 852a60e into develop Jul 3, 2025
26 checks passed

rafaelcr deleted the feat/function-args-exclusion branch July 3, 2025 22:38

hirosystems-release-bot bot added the released label Aug 6, 2025

	'Exclude function_args from contract call responses for smaller, predictable sizes. Only explicit true/false values are accepted (same pattern as `unanchored`).',
	'Exclude function_args from contract call responses for smaller transaction sizes.',

feat: Add exclude_function_args parameter to reduce transaction response sizes #2312

feat: Add exclude_function_args parameter to reduce transaction response sizes #2312

Uh oh!

Conversation

alexthuth commented Jul 2, 2025

Description

Type of Change

Does this introduce a breaking change?

Are documentation updates required?

Testing information

Checklist

Uh oh!

github-actions bot commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

rafaelcr Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

rafaelcr Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

rafaelcr Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexthuth commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rafaelcr left a comment

Choose a reason for hiding this comment

Uh oh!

rafaelcr Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

rafaelcr Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

rafaelcr Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

alexthuth commented Jul 3, 2025

Uh oh!

rafaelcr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hirosystems-release-bot bot commented Aug 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Jul 2, 2025 •

edited

Loading

codecov bot commented Jul 2, 2025 •

edited

Loading

alexthuth commented Jul 3, 2025 •

edited

Loading