[PROPOSAL] Scroll Bridge Reliability & Finality (SBRF)

Ecosystem Growth
1

Overview

Project: Scroll Bridge Reliability & Finality (SBRF)

What: An open-source, Scroll-native SDK + tiny UI that turns canonical L1↔L2 bridging into observable and repair-oriented flows for any Scroll dapp. It wraps Gateway / Messenger / MessageQueue semantics to deliver: (1) signed finality receipts, (2) automatic retries for failed L1→L2 executions, (3) a one-click enforced-inclusion action (capability-gated by Euclid/Stage-1), and (4) ready-to-prove/finalize helpers for L2→L1 exits. Targets Scroll Mainnet (chainId 534352) and **Scroll Sepolia (534351)

##** Summary

  • Problem: Canonical deposits/withdrawals on Scroll span multiple phases (Confirmed → Committed → Finalized) and cross-domain messages. When gas is mis-estimated, batches stall, or UIs lose track of status, users get stuck and teams get support load. Dapps lack a Scroll-canonical reliability layer exposing finality, retries, and enforced-inclusion.

  • Solution (SBRF): A TypeScript SDK + small React panel that:

    1. emits finality receipts keyed by queueIndex + L1/L2 tx hashes,

    2. wraps L1ScrollMessenger.replayMessage for auto-retry with a bounded gas-bump policy,

    3. exposes a one-click enforced-inclusion action (shown only when supported by network), and

    4. signals when withdrawals are ready to prove/finalize, including calldata helpers.

Motivation

Moving money between Ethereum and Scroll isn’t a single step. One user action crosses layers and several checkpoints. If your app doesn’t guide that journey, people think funds are stuck, support tickets pile up, and usage drops.

  • Finality has three steps, not one. On Scroll a bridge/tx becomes Confirmed, then Committed, and only after the proof is verified on L1 is it Finalized. Unlock too early and balances look wrong; wait too long and users feel blocked. This lifecycle is explicitly documented by Scroll. For more context

  • Withdrawals need a last-mile action on L1. For Scroll → Ethereum exits you must call relayMessageWithProof on L1 using parameters from Scroll’s bridge API. If you don’t surface that clearly in-app, users assume assets disappeared. Scroll Docs for more context

  • Some L1 → L2 messages fail quietly for gas. If the L2 gas limit is too low, the L2 execution fails and you must replayMessage with a higher limit. This retry flow is part of Scroll’s design; without it, deposits sit in limbo. More context

  • There are safety valves, but most apps don’t expose them. After the Euclid upgrade, Scroll is Stage-1: users can force-include a tx from L1 (censorship resistance) and anyone can permissionlessly post/finalize batches if the sequencer stalls. These guarantees exist today; typical frontends don’t give users a clear recovery button. For more context

  • Real transactions take messy routes. Scroll’s own “Transaction Journey” guide shows statuses like queued, pending, executed, dropped, replaced. If your app doesn’t present reliable status, people lose trust fast. For more context

  • Generic bridge widgets are about cross-chain routing, not Scroll’s internals. Tools like LI.FI or Bungee/Socket optimize multi-chain routes and provide pluggable UIs, but their docs focus on routing and widget setup; not on Scroll-specific signals like queue indices, replayMessage, or force-include controls your app needs for canonical reliability. For more context

  • The stakes are high. L2BEAT shows Scroll is Stage-1 with hundreds of millions secured and a large canonically-bridged share. When deposits or withdrawals feel uncertain at that scale, every stalled transfer becomes lost usage and support large. For more context

These exact pain points are what SBRF turns into a simple, product-grade flow inside your dapp; finality made visible, retries automatic, and recovery one click away.

Execution Plan & Use Case

1536×1024 193 KB

A. SBRF Core (TypeScript SDK, Node 20)

  • Finality & status engine: Subscribe to L1/L2 events/receipts and emit confirmed | committed | finalized, attaching queueIndex, L1/L2 tx hashes, and timestamps.

  • Auto-retry wrapper: On L2 execution failure, call L1ScrollMessenger.replayMessage with a bounded gas bump; surface a single “deposit completed” outcome to the app.

  • Enforced-inclusion helper: If Stage-1 capability is present, expose a force-include action that enqueues the transaction from L1; otherwise hide the action.

  • Withdrawal helper: Detect when an exit is ready to prove/finalize and assemble calldata for the finalize step; return a signed JSON receipt for app storage.

B. SBRF UI (tiny, optional React 18 panel)

  • Plug-in “Bridge Status Panel” showing lifecycle, tx hashes, and actions (retry / force-include / finalize).

C. Example app (Next.js)

  • End-to-end demos: ETH & ERC-20 deposit via GatewayRouter, withdraw to L1, failed-then-auto-retried flow, and enforced-inclusion showcase.

Tech: TypeScript, Node 20, viem/wagmi or ethers v6, React 18. Networks: Scroll Mainnet 534352 & Sepolia 534351.

Primary use case (day-1 value):
A DEX embeds SBRF. A user deposits USDC from L1. The panel shows Confirmed → Committed → Finalized; on Committed, the DEX can enable a light UI; on Finalized, balances unlock. If L2 execution fails for gas, SBRF auto-retries via replayMessage. If a stall/censorship is detected, the user can force-include (if the Scroll network supports enforced inclusion)

Milestone 1 - Core SDK and Tests

Timeline: ~3 weeks
Budget: $12,000

Deliverables

  • TypeScript SDK (Node 20) that emits Confirmed | Committed | Finalized with queueIndex, L1/L2 tx hashes, timestamps, and a signed JSON receipt (plus a verifyReceipt helper).

  • Auto-retry wrapper for L1→L2 failures using L1ScrollMessenger.replayMessage with a bounded gas-bump policy.

  • Withdrawal helper that detects “ready to prove/finalize” and builds calldata for the L1 finalize step.

  • Capability detection for enforced-inclusion (feature is shown only when the network reports it as available).

  • Tests and CI for core modules; target high coverage for reliability-critical paths.

Acceptance Criteria

  • Using sample txs on Scroll Sepolia (and a small mainnet check where safe), the SDK emits expected phases and produces receipts that pass verifyReceipt.

  • A scripted scenario demonstrates an L1→L2 execution failing on first attempt and completing via replayMessage through the SDK wrapper.

  • CI passes; package builds and publishes a pre-release on npm (v0.1.x).

Milestone 2 - UI, Example App, and Developer Docs

Timeline: ~1.5 weeks
Budget: $6,500

Deliverables

  • React 18 “Bridge Status Panel” showing lifecycle, tx hashes, and actions (Retry, Force include when available).

  • Next.js example demonstrating: ETH and ERC-20 deposit via GatewayRouter, L2→L1 withdrawal finalize, a simulated fail-then-auto-retry path, and the enforced-inclusion flow (when supported on network).

  • Docs: quickstart, API reference, integration guide, and notes on using Committed vs Finalized phases.

Acceptance Criteria

  • On Sepolia, the example demonstrates deposit→finalize and withdraw→finalize flows; the fail-then-auto-retry path is reproducible via the provided script.

  • A fresh developer (not the primary author) follows the docs to integrate the SDK and panel into a minimal test app and reports any gaps; resulting edits are applied.

Milestone 3 - Hardening, Optional Webhooks, Release and Maintenance

Timeline: ~1.5 weeks
Budget: $6,500

Deliverables

  • Optional micro-service (Node 20) for webhooks and durable storage of finality receipts, with Dockerfile and a short deploy guide.

  • Production release on npm (v1.0.0) with SemVer, changelog, example env files, and upgrade notes.

  • Post-launch maintenance window of ~30–45 days covering bug fixes and reasonable compatibility updates discovered in early integrations.

Acceptance Criteria

  • The micro-service runs locally via Docker and can emit webhooks on phase changes; the example app receives and logs these events.

  • v1.0.0 is published; release notes and upgrade guidance are available in the repo.

TEAM

Dapps over Apps is a collective advancing Web3 through developer tooling and education. We create tools that enhance the developer experience and lead initiatives that onboard new builders into blockchain ecosystems.

Some of our notable contributions include:

Abdulkareem Oyeneye** – Project Lead
Experienced developer tool engineer and project manager with a strong background in Web3 growth and technical product execution. He has led multiple ecosystem tooling initiatives and is skilled at identifying developer pain points and protocol infrastructure needs.https://www.linkedin.com/in/abdulkareem-oyeneye-82a6aa277

Gospel Ifeadi – Smart Contract Engineer
Proficient in Rust, C++, JavaScript, and Python, Gospel has worked on multiple dApps and developer tooling projects. He brings deep experience in backend development, smart contract automation, and R&D.https://x.com/gospel70800

Emmanuel Charles – Blockchain Developer & QA Engineer
Experienced in Rust, TypeScript, and C++, Emmanuel brings a dual focus on smart contract development and quality assurance for blockchain systems.https://www.linkedin.com/in/emmanuel-charles-0b0023250

Musa Abdulkareem – ZK Engineer
Focused on building robust blockchain toolkits and applications, Musa contributes core engineering support for protocol-level integrations.https://www.linkedin.com/in/wisemrmusa

Bolaji Ahmad – Full Stack Engineer
Bolaji has worked on foundational tooling within the Polkadot ecosystem and contributes full stack and infrastructure expertise across multiple blockchain frameworks.https://linkedin.com/in/bolajahmad

Conclusion

SBRF makes Scroll bridging reliable and clear: finality receipts, safe auto-retries, enforced-inclusion recovery, and ready-to-prove/finalize helpers; inside the canonical flow. It’s Scroll-specific, open-source, non-overlapping with routers, and ships as a drop-in SDK + tiny UI on a modern stack. With a $25k, milestone-based build and a short post-launch window, funding this turns protocol guarantees into production-grade UX and reduces “where are my funds?” tickets across Scroll dapps.

2

Hello! Thanks for your proposal.

I have a question: Did you contact the Foundation & Labs before presenting it here?

Curious to see if it does make sense from a technical and broader roadmap point of view

1 Like
3

Hello @jameskbh , thank you so much for your question.

No we did not contact the foundation. It is an apparent problem we identified and we believe it is crucial for Scroll to implement its solution at this time.

Please let us know w=if you have any more concerns. Thank you.

4

We are tagging @Delegates for feasibility on this proposal. Thank you.