feat(transactions): add multi-safe queued transactions endpoint by clovisdasilvaneto · Pull Request #2985 · safe-global/safe-client-gateway

clovisdasilvaneto · 2026-03-23T08:40:57Z

Summary

Implement an endpoint to retrieve pending queued transactions across multiple Safe addresses in a single request. This enables efficient monitoring of transaction queues for multiple Safes without making separate requests. We're gonna use this endpoint in the spaces dashboard while queue-service doesn't support mainnet.

Changes

SafeQueuedTransaction entity: New entity wrapping a transaction with the associated Safe address and chain ID
GET /multi-safe/transactions/queued endpoint: Accepts CAIP-10 formatted Safe addresses and returns queued transactions sorted by timestamp
TransactionsService.getMultiSafeTransactionQueue(): Fetches transactions in batches (size: 3), handles errors gracefully, and returns top N results
Integration tests: Added comprehensive tests for the multi-safe queued transactions endpoint
Query parameters:
- safes (required): Comma-separated CAIP-10 addresses (e.g., 1:0x1234...,5:0xabcd...)
- trusted (optional): Filter by trust status (default: true)
- limit (optional): Max transactions per result (default: 10)

🤖 Generated with Claude Code

Implement endpoint to retrieve queued transactions across multiple Safes in a single request. Transactions are fetched in batches, merged, and sorted by timestamp. Returns top N transactions for each Safe address. - Add SafeQueuedTransaction entity wrapping transaction with safe address and chain ID - Add GET /multi-safe/transactions/queued endpoint accepting CAIP-10 formatted addresses - Implement getMultiSafeTransactionQueue service with configurable batch size - Add integration tests for multi-safe transaction queue endpoint - Support filtering by trust status and limiting results Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

- Remove queueService property that doesn't exist in actual configuration - Simplify failing multi-safe test to avoid complex mock setup

LucieFaire

its not the most performant method (and for a large set it can grow exponentialy) and it could be improved, but if its a temp solution it is a solid one. I left some comments.
It would also be great to have unit tests for service-level method as there is a lot of logic going on

LucieFaire · 2026-03-23T10:32:27Z

src/modules/transactions/routes/transactions.service.ts

    return new TXSCreationTransaction(tx);
  }

+  private static readonly MULTI_SAFE_QUEUE_BATCH_SIZE = 3;


not: that would usually go to the top of the file, before the constructor

LucieFaire · 2026-03-23T10:47:11Z

src/modules/transactions/routes/entities/safe-queued-transaction.entity.ts

+  readonly safeAddress: string;
+  @ApiProperty()
+  readonly chainId: string;
+  @ApiProperty()


@ApiProperty({ type: Transaction })
so that Swagger can infer the type fully

LucieFaire · 2026-03-23T10:52:21Z

src/modules/transactions/routes/entities/safe-queued-transaction.entity.ts

+export class SafeQueuedTransaction {
+  @ApiProperty()
+  readonly safeAddress: string;
+  @ApiProperty()
+  readonly chainId: string;
+  @ApiProperty()
+  readonly transaction: Transaction;
+
+  constructor(safeAddress: string, chainId: string, transaction: Transaction) {
+    this.safeAddress = safeAddress;
+    this.chainId = chainId;
+    this.transaction = transaction;
+  }


you can also write it in a short form:

export class SafeQueuedTransaction { @ApiProperty() readonly safeAddress!: string; @ApiProperty() readonly chainId!: string; @ApiProperty({ type: Transaction }) readonly transaction!: Transaction; }

! means the definite assignment assertion (!) which tells TypeScript the properties will be assigned in the constructor.

LucieFaire · 2026-03-23T10:53:03Z

src/modules/transactions/routes/transactions.service.ts

+                  safe,
+                  dataDecoded,
+                );
+              return new SafeQueuedTransaction(address, chainId, transaction);


if you update the DTO definition, you can just return plain object w/o contructor

return { safeAddress: address, chainId, transaction, }; ```s

LucieFaire · 2026-03-23T10:58:18Z

src/modules/transactions/routes/transactions.service.ts

+          const queue = await this.safeRepository.getTransactionQueue({
+            chainId,
+            safe,
+            limit: args.limit,
+            offset: 0,
+            trusted: args.trusted,
+          });


Each Safe fetches args.limit transactions (defaults to 10), but the final result is also capped to args.limit. With 15 Safes and limit=10, you could fetch up to 150 transactions, decode and map all of them, then throw away 140.
Since results are sorted by timestamp (oldest first), you could:

Fetch a smaller per-Safe limit (like that batch size)
or after each batch, track the current "worst" timestamp and skip further processing if a Safe's transactions can't make the cut

@LucieFaire indeed, I can indeed fetch smaller number of pending tx per safe, but this could also lead to the following scenario:

Suppose we fetch 5 per safe, but the user asked for a limit of 15 txs and he just asked for one safe which has 20 pending tx... In this case e would only have 5 pending txs on the response, which would be wrong in this case.

dont you have control over what is returned? Are you planning to give user control over how much data they want and for what safes?

Yes I do, but I'm just talking in a general scenario, in case it is gonna be used elsewhere, but yeah, maybe it might not even make sense, since this is a temporary approach.

LucieFaire · 2026-03-23T11:01:09Z

src/modules/transactions/routes/transactions.service.ts


+  private static readonly MULTI_SAFE_QUEUE_BATCH_SIZE = 3;
+
+  async getMultiSafeTransactionQueue(args: {


If multiple users in the same Space hit this endpoint simultaneously for the same set of Safes, each request does the full work independently. There is caching on separate methods used (like transactions ,and safe) but maybe worth adding caching for this set of params too

PooyaRaki · 2026-03-23T16:56:07Z

@claude review

claude · 2026-03-23T16:56:24Z

Claude finished @PooyaRaki's task —— View job

Code Review: PR #2985

Read changed files
Analyze code quality, bugs, performance, security, test coverage
Post review feedback

Issues to Address

1. No upper bound on limit query parameter (transactions.controller.ts:709)
The limit param is user-controlled with no max cap. A client can pass limit=100000, causing the service to fetch up to maxOverviews * 100000 transactions from upstream, decode and map all of them, then sort. Add a Math.min(limit, MAX_LIMIT) or validate with a Zod/Pipe max constraint.

2. Over-fetching per Safe (transactions.service.ts:668-674)
Each Safe fetches args.limit transactions (e.g., 10), but only args.limit total results are returned. With 10 Safes and limit=10, you fetch up to 100 transactions, decode/map all, then discard 90. Consider fetching a smaller per-Safe limit (e.g., Math.min(args.limit, MULTI_SAFE_QUEUE_BATCH_SIZE) or a fixed small number) and only fetching more if needed.

3. Sequential batch processing negates concurrency benefits (transactions.service.ts:652-712)
The for loop processes batches of 3 sequentially. With maxOverviews=10, that's 4 serial rounds. Since Promise.allSettled already handles errors gracefully, consider processing all Safes in a single Promise.allSettled with concurrency control (e.g., a semaphore pattern) instead of sequential batches, to reduce total latency.

4. Missing @ApiProperty({ type: Transaction }) on entity (safe-queued-transaction.entity.ts:10)
The transaction property uses @ApiProperty() without specifying the type. Swagger won't be able to infer the nested Transaction schema. Use @ApiProperty({ type: Transaction }).

5. Static constant placement (transactions.service.ts:642)
MULTI_SAFE_QUEUE_BATCH_SIZE is defined mid-file between methods. Move it to the top of the class (before the constructor) to follow the existing code convention.

6. Missing unit tests for service logic
Only integration tests are provided. The getMultiSafeTransactionQueue method has significant logic (batching, error handling, sorting, slicing) that would benefit from unit tests with mocked dependencies - particularly edge cases like partial failures across batches, the maxOverviews cap, and sorting correctness with mixed timestamps.

7. No test for maxOverviews truncation behavior
The service silently truncates the input list to maxOverviews (transactions.service.ts:649). There's no test verifying that excess Safes are ignored, or that the endpoint communicates this limit to callers.

|

PooyaRaki · 2026-03-23T17:02:05Z

src/modules/transactions/routes/transactions.controller.ts

+    description:
+      'Comma-separated list of Safe addresses in CAIP-10 format (chainId:address)',
+    example:
+      '1:0x1234567890123456789012345678901234567890,5:0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',


QQ: Why don't we accept an object with chainId as the key which has safeAddresses as the values?
e.g.

{ "1" : [{{ADDRESS_1}}, {{ADDRESS_2}}], "5": [{{ADDRESS_1}}, {{ADDRESS_2}}], }

@PooyaRaki because I'm following the same standard we have in the safesOverview endpoint (the one we use to get the number of queued transactions and show in the sidebar)

PooyaRaki · 2026-03-23T17:04:44Z

src/modules/transactions/routes/transactions.controller.ts

+    description:
+      'Array of queued transactions enriched with Safe address and chain ID',
+  })
+  @Get('multi-safe/transactions/queued')


What do you think removing multi-safe? then it would be
@Get('transactions/queued')

PooyaRaki · 2026-03-24T08:43:28Z

src/modules/transactions/routes/transactions.service.ts

+    const limitedSafes = args.addresses.slice(0, this.maxOverviews);
+    const transactions: Array<SafeQueuedTransaction> = [];
+
+    for (


Instead of using a for loop and then .slice we could simplify it using lodash which is already a dependency, Something like the following:
for (const batch of chunk(limitedSafes, TransactionsService.MULTI_SAFE_QUEUE_BATCH_SIZE)) {

PooyaRaki · 2026-03-24T08:45:48Z

...s/__tests__/controllers/list-queued-transactions.transactions.controller.integration.spec.ts

+    networkService = moduleFixture.get(NetworkService);
+    loggingService = moduleFixture.get(LoggingService);
+
+    jest.spyOn(loggingService, 'error');


Since the service is mocked we can safely remove the mocks.

PooyaRaki · 2026-03-24T08:46:13Z

.../controllers/list-multi-safe-queued-transactions.transactions.controller.integration.spec.ts

+        ...baseConfiguration.mappings,
+        safe: {
+          ...baseConfiguration.mappings.safe,
+          maxOverviews: 10,


Should use a random number generated by faker

PooyaRaki · 2026-03-24T08:47:06Z

.../controllers/list-multi-safe-queued-transactions.transactions.controller.integration.spec.ts

+    await app.close();
+  });
+
+  async function buildSafeWithTransaction(args: {


Nit: We could extract the builder to another file.

PooyaRaki · 2026-03-24T08:47:47Z

...s/__tests__/controllers/list-queued-transactions.transactions.controller.integration.spec.ts

+      submissionDate: new Date('2024-01-01T00:00:00Z'),
+    });
+    const safe2Data = await buildSafeWithTransaction({
+      nonce: 1,


Nit: We should use faker here.

PooyaRaki · 2026-03-24T08:48:07Z

.../controllers/list-multi-safe-queued-transactions.transactions.controller.integration.spec.ts

+    });
+    const safe2Data = await buildSafeWithTransaction({
+      nonce: 1,
+      submissionDate: new Date('2024-06-01T00:00:00Z'),


We can use faker to generate the dates throughout the test file.

PooyaRaki · 2026-03-24T08:54:11Z

...s/__tests__/controllers/list-queued-transactions.transactions.controller.integration.spec.ts

+    networkService.get.mockImplementation(({ url }) => {
+      for (const data of allMocks) {
+        const chainUrl = `${safeConfigUrl}/api/v1/chains/${data.chain.chainId}`;
+        const safeUrl = `${data.chain.transactionService}/api/v1/safes/${data.safeAddress}`;
+        const txUrl = `${data.chain.transactionService}/api/v2/safes/${data.safeAddress}/multisig-transactions/`;
+
+        if (url === chainUrl) {
+          return Promise.resolve({
+            data: rawify(data.chain),
+            status: 200,
+          });
+        }
+        if (url === safeUrl) {
+          return Promise.resolve({
+            data: rawify(data.safe),
+            status: 200,
+          });
+        }
+        if (url === txUrl) {
+          return Promise.resolve({
+            data: rawify({
+              count: 1,
+              next: null,
+              previous: null,
+              results: [
+                multisigToJson(data.transaction) as MultisigTransaction,
+              ],
+            }),
+            status: 200,
+          });
+        }
+      }
+      if (url.includes('/api/v1/tokens/')) {
+        return Promise.resolve({ data: rawify({}), status: 200 });
+      }
+      if (url.includes('/api/v1/contracts/')) {
+        return Promise.resolve({
+          data: rawify(
+            pageBuilder().with('results', [contractBuilder().build()]).build(),
+          ),
+          status: 200,
+        });
+      }
+      if (url.includes('/api/v1/safe-apps/')) {
+        return Promise.resolve({ data: rawify([]), status: 200 });
+      }
+      return Promise.reject(new Error(`Could not match ${url}`));
+    });


We should extract all the mock within the tests to another method to keep the test itself short and easy to follow.

PooyaRaki · 2026-03-24T08:57:33Z

...s/__tests__/controllers/list-queued-transactions.transactions.controller.integration.spec.ts

+
+    const safesParam = `${chain.chainId}:${safeAddress}`;
+
+    await request(app.getHttpServer())


We should explicitly check trusted and limit in this test as the title suggests.

- Remove 'multi-safe' prefix from queued transactions endpoint - Simplify batch processing using lodash chunk() utility - Extract buildSafeWithTransaction helper to separate builder file - Use faker consistently for test data generation - Update entity class to use property initialization - Add multiSafeQueue configuration for cache expiration

clovisdasilvaneto requested a review from a team as a code owner March 23, 2026 08:40

clovisdasilvaneto force-pushed the feat/spaces-pending-tx branch 2 times, most recently from 0ef85a2 to 20a3951 Compare March 23, 2026 08:55

clovisdasilvaneto added 3 commits March 23, 2026 10:10

chore: add SPDX license headers to modified files

0fed76a

fix: remove queueService from test config and simplify failing test

4b4be24

- Remove queueService property that doesn't exist in actual configuration - Simplify failing multi-safe test to avoid complex mock setup

style: fix prettier formatting

9d3302d

vseehausen approved these changes Mar 23, 2026

View reviewed changes

LucieFaire reviewed Mar 23, 2026

View reviewed changes

PooyaRaki requested changes Mar 24, 2026

View reviewed changes

clovisdasilvaneto force-pushed the feat/spaces-pending-tx branch from 46287cf to 4f99075 Compare March 25, 2026 11:21


		private static readonly MULTI_SAFE_QUEUE_BATCH_SIZE = 3;

		async getMultiSafeTransactionQueue(args: {


		const safesParam = `${chain.chainId}:${safeAddress}`;

		await request(app.getHttpServer())

Conversation

clovisdasilvaneto commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Uh oh!

LucieFaire left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PooyaRaki commented Mar 23, 2026

Uh oh!

claude bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review: PR #2985

Issues to Address

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clovisdasilvaneto Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clovisdasilvaneto commented Mar 23, 2026 •

edited

Loading

claude bot commented Mar 23, 2026 •

edited

Loading

clovisdasilvaneto Mar 25, 2026 •

edited

Loading