update signal service documentation

[nikeshnazareth]

The existing documentation is a mixture of Taiko's design and previous versions of the signal service.
This PR simplifies it so it matches the current code base

Summary by CodeRabbit

• Documentation
  • Overhauled cross-chain signaling docs to center on SignalService with a contract‑centric model.
  • Introduced a clear workflow: preparation, importing commitments, verification via Merkle proofs, and bridge integration.
  • Consolidated slow/fast paths into a single commitments-based model; clarified non-deletable signals and proof location requirements.
  • Expanded bridge coverage to ETH and token standards (ERC‑20/721/1155) aligned with the new flow.
  • Streamlined narrative by removing outdated flows while preserving consistency with ETH bridge behavior.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

The documentation for SignalService is rewritten to present a contract-centric cross-chain signaling model based on immutable commitments and Merkle proofs, detailing deployment across chains, proof sourcing via providers, and integration with ETH and token bridges. Prior fast/slow pathways are removed in favor of a consolidated verification flow.

Changes

Cohort / File(s)	Summary
Docs: SignalService cross-chain model refresh documentation/signal-service.md	Replaces conceptual signaling with a contract-based model using stored commitments (bytes32) and Merkle proofs; reorganizes into preparation, importing commitments, verification, and bridge integration; updates ETH/token bridge sections (ERC-20/721/1155); removes fast/slow paths; adds explicit proof and slot-verification requirements.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant SrcApp as Source App
    participant SrcSig as SignalService (Source)
    participant Provider as Provider (CheckpointTracker/Anchor)
    participant DstSig as SignalService (Destination)
    participant DstApp as Destination App

    rect rgb(235, 245, 255)
    note over SrcApp,SrCSig: Emit signal as immutable commitment
    SrcApp->>SrcSig: signal(bytes32 payload)
    SrcSig-->>SrcSig: store commitment slot = true
    end

    rect rgb(245, 235, 255)
    note over Provider: Publish source state root / block commitment
    SrcSig-->>Provider: included in stateRoot
    end

    rect rgb(235, 255, 245)
    note over DstApp,DstSig: Verify cross-chain signal via proof
    DstApp->>DstSig: verifySignal(srcChainId, srcSigAddr, slot, proof, stateRoot)
    Provider-->>DstSig: stateRoot (imported/available)
    DstSig-->>DstApp: true/false (Merkle proof of slot==true)
    end

Loading

sequenceDiagram
    autonumber
    participant User as User
    participant Bridge as ETH/Token Bridge (Dst)
    participant DstSig as SignalService (Destination)
    participant SrcSig as SignalService (Source)
    participant Provider as Provider

    rect rgb(250, 250, 230)
    note over SrcSig,Provider: Bridge wraps SignalService flow
    User->>SrcSig: lock/mint triggers signal(commitment)
    SrcSig-->>Provider: commitment included in stateRoot
    end

    User->>Bridge: claim/redeem(params, proof)
    Bridge->>DstSig: verifySignal(..., proof, stateRoot)
    DstSig-->>Bridge: verification result
    alt verified
        Bridge-->>User: release/mint assets
    else failed
        Bridge-->>User: revert/error
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I thump my paws: new signals sing,
Commitments bloom in Merkle ring.
No fast nor slow—just roots that prove,
Across the chains, our bytes now move.
Bridges hop with tidy grace—
A rabbit nods: one solid place. 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title “update signal service documentation” succinctly and accurately conveys that the primary change is to refresh and align the SignalService documentation with the current codebase, matching the PR’s focus.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

documentation/signal-service.md (1)

34-34: Align sub-list indentation with Markdown style.

Line 34’s sub-bullet is indented with four spaces; markdownlint (MD007) expects two. Please dedent by two spaces to satisfy the style check.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 11148b8 and 4968b16.

⛔ Files ignored due to path filters (3)

• documentation/Fast.png is excluded by !**/*.png
• documentation/Taiko Messaging.png is excluded by !**/*.png
• documentation/fast_signaling.svg is excluded by !**/*.svg

📒 Files selected for processing (1)

• documentation/signal-service.md (1 hunks)

🧰 Additional context used

🪛 GitHub Actions: check

documentation/signal-service.md

[error] 27-27: typos: identifer should be identifier

---

[warning] 27-27: typos: identifer should be identifier

🪛 GitHub Check: typos

documentation/signal-service.md

[warning] 27-27:
"identifer" should be "identifier".

🪛 markdownlint-cli2 (0.18.1)

documentation/signal-service.md

34-34: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

[github-actions]

Changes to gas cost

Generated at commit: 12e415cdf4a92f340c00bf3494b49eb3f89b0ce6, compared to commit: 11148b8f68a578f6f7be6d5b9f578ae211384aeb

🧾 Summary (10% most significant diffs)

Contract	Method	Avg (+/-)	%
BlobRefRegistry	getRef	+977 ❌	+70.64%

---

Full diff report 👇

Contract	Deployment Cost (+/-)	Method	Min (+/-)	%	Avg (+/-)	%	Median (+/-)	%	Max (+/-)	%	# Calls (+/-)
TaikoInbox	1,972,875 (+12)	publish	0 (-28,175)	-100.00%	0 (-28,175)	-100.00%	0 (-28,175)	-100.00%	0 (-28,175)	-100.00%	1 (0)
BlobRefRegistry	468,450 (0)	getRef	2,104 (+723)	+52.35%	2,360 (+977)	+70.64%	2,360 (+979)	+70.89%	2,617 (+1,230)	+88.68%	2 (-1)
ERC20Bridge	3,346,015 (+12)
MockReceiver	156,747 (-12)