Bridge Indexing: Multichain support L1<>L2 sync data

[Douglasacost]

No description provided.

[github-actions]

LCOV of commit 38a8776 during checks #739

Summary coverage rate:
  lines......: 27.9% (939 of 3362 lines)
  functions..: 28.1% (150 of 533 functions)
  branches...: 29.4% (164 of 558 branches)

Files changed coverage rate:
                                                    |Lines       |Functions  |Branches    
  Filename                                          |Rate     Num|Rate    Num|Rate     Num
  ========================================================================================
  script/DeployBatchMintNFT.s.sol                   | 0.0%     27| 0.0%     2|    -      0
  script/UpgradeBatchMintNFT.s.sol                  | 0.0%     21| 0.0%     2|    -      0
  src/contentsign/BatchMintNFT.sol                  | 0.0%     58| 0.0%     9| 0.0%      9

[aliXsed]

Reviewed after merging latest main into the branch (conflicts in .cspell.json, foundry.toml, remappings.txt resolved in favor of main's newer state, and main's OpenZeppelin v5.3.0 submodule pointer restored — the branch had pinned it back to v5.1.0).

Summary

The PR adds a multichain SubQuery project indexing L1↔L2 bridge sync state, L2 bridge handlers for the existing single-chain subquery/ project, and an unrelated BatchMintNFT UUPS contract with deploy/upgrade scripts and tests. Every finding below was independently verified against the code (the build break was reproduced end-to-end).

Findings (most severe first)

#	Where	Issue
1	subquery/src/mappings/bridge.ts:86	Package no longer builds: TS2554 (missing required finalized constructor arg) + TS2344 (hand-rolled event-arg interfaces vs generated BridgeL2Abi types)
2	subquery-multichain/src/mappings/bridge.ts:31	Missing-entity throw = permanent poison block; L2-first startup (the documented workflow) guarantees it fires. Mirror throw at :208
3	subquery-multichain/src/mappings/bridge.ts:109	L1 handler unconditionally overwrites the deposit row, wiping L2 finalization data
4	subquery-multichain/src/mappings/bridge.ts:147	Dead getByFields query (results unused) whose empty-result throw halts the indexer on legitimate inputs; type-unsafe receiver_id cast misses the store cache
5	subquery-multichain/docker-compose.yml:31	ZKSYNC_MAINNET_RPC never reaches the container; export:env npm script is a no-op → always falls back to the rate-limited public RPC
6	subquery-multichain/project-ethereum.yaml:23	startBlock drifted from project-ethereum.ts (23635689 vs 23635846) — regeneration silently skips 157 blocks
7	subquery-multichain/src/test/bridge.test.ts:17	Test expectations (deposit- ID prefix) can never match the handlers; subqlTest cases pass vacuously under plain jest
8	src/contentsign/BatchMintNFT.sol:32	Dead MINTER_ROLE, no-op burn() override; sole contract importing OZ v4 via era-contracts' nested vendored copy

Suggestions (not blocking)

• The same L2 bridge events (contract 0x2c1B...529E, same topics, same startBlock) are now indexed by both subquery/ and subquery-multichain/ with incompatible ID schemes (hash-logIndex vs raw hash) and different schemas. If intentional (per-network dashboard vs cross-chain tracker), a README note would help; otherwise one of the two should be dropped.
• subquery-multichain/docker/ (pg.conf, pg-Dockerfile, load-extensions.sh) is a byte-for-byte copy of subquery/docker/ — a shared dir would avoid drift.
• zksync-rpc.ts duplicates rate-limit/fallback logic between makeRpcRequest and getBlockTransactionCountsByNumbers; per-batch results (block range, tx counts) could be cached and chunks early-exited once the cumulative count covers txIndex — currently every WithdrawalFinalized from the same batch repeats the full RPC sweep.
• subquery/mainnet-complete.ts:500 ships startBlock: 65260492 with a TODO: Replace with actual L2Bridge deployment block — if the real deployment block is earlier, those events are permanently missing.
• BatchMintNFT + its scripts/tests are unrelated to bridge indexing and would be cleaner as a separate PR.

I'll push fixes for findings 1-8 (except the OZ v4→v5 port, which isn't mechanical) to this branch shortly.

[aliXsed]

Build break: this package no longer compiles. subql codegen && subql build fails with:

src/mappings/bridge.ts(86,22): error TS2554: Expected 8 arguments, but got 7.

schema.graphql declares finalized: Boolean! on BridgeWithdrawal, so the generated constructor requires it as the 8th argument — the trailing withdrawal.finalized = false assignment doesn't satisfy it.

There are two more build errors at lines 18-19 (TS2344): the hand-rolled DepositFinalizedEventArgs/WithdrawalInitiatedEventArgs interfaces don't satisfy the EthereumResult constraint. Every other mapping in this package imports the generated log types (e.g. rewards.ts uses ../types/abi-interfaces/RewardsAbi), and BridgeL2.abi.json is already registered in mainnet-complete.ts, so importing DepositFinalizedLog/WithdrawalInitiatedLog from ../types/abi-interfaces/BridgeL2Abi (as subquery-multichain already does) fixes both issues at once.

Related design note: no handler in this single-chain project ever sets finalized = true (finalization is an L1 event this project doesn't index), so finalized/finalizedAt/finalizedTransaction will be permanently false/null — any frontend gating on this flag will show every withdrawal as pending forever.

[aliXsed]

Crash-loop / poison block: the two chain indexers run independently — SubQuery's --multi-chain mode only shares a Postgres schema and gives no cross-chain ordering guarantee — yet this handler throws when the L1-created deposit doesn't exist. An unhandled handler error is fatal for the block: the node exits, restart: unless-stopped re-attempts the same block, and a deterministic error becomes a permanent crash-loop.

The ordering that triggers this is the normal one: docker-compose.yml starts subquery-node-zksync first (subquery-node-ethereum has depends_on: subquery-node-zksync: service_healthy), and start-ethereum-services.sh explicitly documents starting ethereum "after zkSync has finished indexing" — which guarantees every historical DepositFinalized is processed before its L1 DepositInitiated entity exists.

Since L2-first is the expected order, this should upsert: create the BridgeDeposit with status finalized from the L2 event data when missing (requires l1TransactionHash to become nullable in the schema, since it's unknown on the L2 side), and let handleDepositInitiated fill in the L1 fields when it catches up.

The mirror-image throw exists at lines 208-211 (Withdrawal ${withdrawalId} not found) — a withdrawal initiated before the L2 startBlock will never exist, making that a permanent poison block too; it should log and skip instead.

[aliXsed]

Finalization data silently wiped: the BridgeDeposit.get(depositId) result is never used — deposit is unconditionally reassigned to a new BridgeDeposit(..., "initiated") and saved. save() is an upsert keyed on id that replaces the whole row, and both handlers use the same key (l2DepositTxHash here, event.transaction.hash in the L2 handler), so if the L2 side already recorded status: "finalized" / finalizedAt / l2TransactionHash, this overwrite regresses the deposit to "initiated" and nulls the finalization fields — permanently, since the L2 event won't be processed again.

This should branch on the fetched entity: if it exists, update only the L1-side fields (l1TransactionHash, sender/receiver, amount, timestamp) and preserve status/finalizedAt/l2TransactionHash.

Same dead-get-then-overwrite pattern in handleClaimedFailedDeposit (lines 244-246) — harmless there since the constructor repopulates every field identically, but the get is dead code either way.

[aliXsed]

Dead query that can halt the indexer: this store.getByFields result is only used for entities.length (a log line and the throw below) — the actual withdrawal is located later via the RPC-derived l2TransactionHash. Meanwhile the throw at lines 162-164 poisons the L1 indexer for legitimate cases: a receiver whose withdrawal was initiated before the L2 startBlock, or already finalized, has zero "initiated" rows — and that never changes on retry, so the block crash-loops forever.

The "receiver_id" as keyof BridgeWithdrawal cast is also a red flag: the entity field is receiverId; receiver_id is the underlying DB column name. It happens to work against Postgres only because Sequelize passes the unknown key through to the underscored column, but it silently misses SubQuery's in-memory store cache (matchesField reads data["receiver_id"] → undefined), so unflushed same-block entities are never matched.

Since the results aren't used, the whole query + throw can simply be deleted.

Minor, same function: the ternary at lines 170-173 has identical branches (Number(batchNumber) both ways) — it's just Number(batchNumber).

[aliXsed]

ZKSYNC_MAINNET_RPC never reaches the indexer: this environment: block only passes DB_* vars, there's no env_file:, and no ${...} interpolation anywhere in the compose file — so process.env.ZKSYNC_MAINNET_RPC in handleWithdrawalFinalized is always undefined inside the container and every batch→tx-hash lookup falls back to the hardcoded public https://mainnet.era.zksync.io (whose "fallback" RETRY_URL in zksync-rpc.ts:3 is the same endpoint). Combined with the throw-on-null-hash path, indexing correctness ends up depending on a rate-limited public RPC.

The "export:env": "export $(grep -v '^#' .env | xargs)" script in package.json:14 doesn't help — each npm run spawns its own sh -c child shell, so the exports die before the next command in the && chain runs. It's a no-op everywhere it's used (codegen, build, start:docker, dev).

Fix: add ZKSYNC_MAINNET_RPC: ${ZKSYNC_MAINNET_RPC:-https://mainnet.era.zksync.io} to this block (compose reads .env automatically for interpolation) and drop the export:env script.

[aliXsed]

Config drift: this file's header says "Auto-generated, DO NOT EDIT" from project-ethereum.ts, but the two disagree: startBlock: 23635689 here vs 23635846 in project-ethereum.ts:36. Docker runs the yaml (-f=/app/project-ethereum.yaml), so today the earlier block wins — but the next subql codegen regeneration silently moves the L1 start forward 157 blocks, and any DepositInitiated events in 23635689-23635845 would never be indexed (their DepositFinalized counterparts on L2 would then hit the missing-entity throw). The two values should be aligned (the earlier one is the safe choice). project-zksync.yaml/.ts have no drift.

[aliXsed]

Test expectations can never match: the expected entity IDs use a deposit- prefix (here and at line 98), but the handlers use the raw tx hash as the ID (mappings/bridge.ts:25 and :103) — no deposit- prefix exists anywhere in the mappings. The first test also expects handleDepositFinalized to create a BridgeDeposit, but the handler currently throws when the deposit doesn't exist.

This goes unnoticed because these subqlTest cases never actually run: npm test invokes plain jest, and @subql/testing's subqlTest() only pushes specs onto global.subqlTests — no handler execution, no assertions — so the file passes vacuously. Running them for real requires subql-node-ethereum test, which no npm script wires up.

Also worth noting: zksync-rpc.test.ts intentionally hits the live zkSync mainnet RPC (no fetch mock, 30s timeouts), so npm test is network-dependent and flaky.

[aliXsed]

Dead code: MINTER_ROLE is declared but never granted or checked anywhere — contract, deploy/upgrade scripts, or tests. Minting is intentionally public (per the contract NatSpec), so this constant only misleads auditors into looking for role-gated minting that doesn't exist. The burn() override at lines 188-190 is likewise a pure super.burn() pass-through the compiler doesn't require (only _burn has a diamond collision, and that override exists separately) — verified it compiles fine without it. Both can be deleted.

Separate note: this contract is the only file in the repo importing OZ upgradeable v4 via era-contracts' nested vendored copy (openzeppelin-contracts-upgradeable-v4/...), while every other upgradeable contract uses @openzeppelin/contracts-upgradeable/ → the repo's v5 submodule. If era-contracts is ever updated or its nested lib layout changes, this contract's build breaks. A v5 port isn't mechanical (hook/override patterns changed), so flagging rather than asking for it here — but worth a follow-up or at least a comment documenting the v4 pin.

[aliXsed]

Pushed fixes for the review findings in 38a8776 (all except the suggestion-level items and the OZ v4→v5 port):

• subquery/ builds again: generated BridgeL2Abi log types + required finalized constructor arg
• multichain handlers no longer throw on cross-chain ordering: handleDepositFinalized upserts from L2 data (l1TransactionHash now nullable in the schema), handleDepositInitiated merges without wiping finalization state, handleWithdrawalFinalized drops the dead getByFields query and skips (instead of poisoning the block) when the withdrawal predates the L2 startBlock
• ZKSYNC_MAINNET_RPC is passed into the ethereum indexer container via compose interpolation; no-op export:env script removed
• L1 startBlock aligned to 23635689 in project-ethereum.ts (matches the running yaml; earlier value = no skipped events)
• test entity IDs fixed to match the handlers' raw-hash IDs
• BatchMintNFT: unused MINTER_ROLE and no-op burn() override removed

Also merged latest main into the branch (b0d200b) — conflicts resolved keeping main's newer state, and main's OpenZeppelin v5.3.0 submodule pointer restored. All checks are green: Tests ✓ Coverage ✓ Specification-PDF ✓ (verified locally too: 1198 forge tests, spellcheck, lint, and both subquery packages' codegen+build).