CDCP Core Lib #9

MatheusFranco99 · 2025-11-16T15:36:38Z

Overview

This PR introduces the CDCP protocol for composing with external rollups.
It includes a markdown for explaining the protocol in prose, and a minimal spec implementation along with unit tests.

- Simulation returns written messages. - sbcp/sequencer sealed block var renaming. - Proof timeout config logic - Proof timeout resets seq number to 0

This reverts commit c064476.

Copilot

Pull request overview

This PR introduces the Cross-Domain Composability Protocol (CDCP) for coordinating atomic execution between Compose native rollups and external rollups. The implementation provides three main components: Publisher (orchestrates consensus), Native Sequencer (wraps existing SCP sequencer), and Wrapped Sequencer (handles external rollup interactions with mailbox-aware simulations).

Key Changes

Implements CDCP protocol with Publisher, Native Sequencer, and Wrapped Sequencer roles
Adds comprehensive unit tests covering state machine transitions, error handling, and edge cases
Includes detailed documentation with sequence diagrams and interface specifications

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
compose/cdcp/README.md	Protocol documentation with interface descriptions and sequence diagrams
compose/cdcp/publisher.go	Publisher implementation managing votes from native chains and decisions from wrapped sequencer
compose/cdcp/publisher_test.go	Comprehensive test suite for publisher state machine and edge cases
compose/cdcp/wrapped_sequencer.go	Wrapped sequencer implementation handling mailbox-aware simulations and ER client interaction
compose/cdcp/wrapped_sequencer_test.go	Test suite covering simulation flows, mailbox message handling, and timeout behavior
compose/cdcp/native_sequencer.go	Thin wrapper delegating to SCP sequencer for native chain behavior
compose/cdcp/helpers_test.go	Test utilities including fake implementations and data cloning helpers
compose/README.md	Updated module listing to include CDCP

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-28T15:22:48Z

compose/cdcp/wrapped_sequencer_test.go

+		compose.StateRoot{},
+		testLogger(),
+	)
+	// Ensure an error is returned chain has no transaction.


Comment says "Ensure an error is returned chain has no transaction" but should say "Ensure an error is returned when chain has no transaction". The word "when" is missing.

Suggested change

// Ensure an error is returned chain has no transaction.

// Ensure an error is returned when chain has no transaction.

Copilot · 2025-11-28T15:22:48Z

compose/cdcp/publisher_test.go

+		chainReq(2, []byte("b")),
+	)
+	_, err = NewPublisherInstance(instance, &fakePublisherNetwork{}, compose.ChainID(3), testLogger())
+	// creation errors if the ER chain has no transaction.


Comment says "creation errors if the ER chain has no transaction" but should say "creation errors if the ER chain has no transactions" (plural) to match the error name ErrERNotFound and the validation logic context.

Suggested change

// creation errors if the ER chain has no transaction.

// creation errors if the ER chain has no transactions.

Copilot · 2025-11-28T15:22:48Z

compose/cdcp/wrapped_sequencer.go

+	}
+
+	// Else, sends successful decision, and terminates
+	ws.logger.Info().Err(err).Msg("ER call succeeded. Sending WSDecided as true.")


The log message "ER call succeeded. Sending WSDecided as true." logs the error with .Err(err), but at this point err is nil (the success case). This will log a nil error unnecessarily. The .Err(err) should be removed from line 305.

Suggested change

ws.logger.Info().Err(err).Msg("ER call succeeded. Sending WSDecided as true.")

ws.logger.Info().Msg("ER call succeeded. Sending WSDecided as true.")

Copilot · 2025-11-28T15:22:49Z

compose/cdcp/README.md

+- `Simulate(args)`: simulates `safe_execute` against the given snapshot and returns the result.
+  - `ReadMiss`: tracks the required mailbox header and keeps waiting for native messages, re-simulating once satisfied.
+  - `WriteMiss`: stages the missing outbox message into `PutOutboxMessages` and re-simulates.
+  - Error: sends `WSDecided(false)` and terminates.
+- `ProcessMailboxMessage(msg)`: buffers incoming mailbox messages for simulation; when a pending read is satisfied it moves the message into `PutInboxMessages` and re-runs the simulation.
+- `ProcessNativeDecidedMessage(decided)`: deduplicates the publisher’s native decision and, if `true`, triggers the external rollup submission; `false` cancels execution.
+- `Timeout()`: while not already waiting for the ER response, aborts and reports `WSDecided(false)`.
+


The documentation describes a Simulate(args) method for the WrappedSequencerInstance interface (line 76), but this method doesn't exist in the actual interface. The Simulate method is part of the WSExecutionEngine interface, not WrappedSequencerInstance. The documentation should remove this method description or clarify that it refers to the execution engine, not the sequencer instance itself.

Suggested change

- `Simulate(args)`: simulates `safe_execute` against the given snapshot and returns the result.

- `ReadMiss`: tracks the required mailbox header and keeps waiting for native messages, re-simulating once satisfied.

- `WriteMiss`: stages the missing outbox message into `PutOutboxMessages` and re-simulates.

- Error: sends `WSDecided(false)` and terminates.

- `ProcessMailboxMessage(msg)`: buffers incoming mailbox messages for simulation; when a pending read is satisfied it moves the message into `PutInboxMessages` and re-runs the simulation.

- `ProcessNativeDecidedMessage(decided)`: deduplicates the publisher’s native decision and, if `true`, triggers the external rollup submission; `false` cancels execution.

- `Timeout()`: while not already waiting for the ER response, aborts and reports `WSDecided(false)`.

- `ProcessMailboxMessage(msg)`: buffers incoming mailbox messages for simulation; when a pending read is satisfied it moves the message into `PutInboxMessages` and re-runs the simulation.

- `ProcessNativeDecidedMessage(decided)`: deduplicates the publisher’s native decision and, if `true`, triggers the external rollup submission; `false` cancels execution.

- `Timeout()`: while not already waiting for the ER response, aborts and reports `WSDecided(false)`.

> **Note:** Simulation of `safe_execute` is performed by the `WSExecutionEngine` dependency, not directly by the `WrappedSequencerInstance` interface.

Copilot · 2025-11-28T15:22:49Z

compose/cdcp/wrapped_sequencer.go

+		// Look if it exists in received messages
+		for receivedMsgIdx, receivedMsg := range ws.pendingMessages {
+			if receivedMsg.MailboxMessageHeader.Equal(expectedMsg) {
+				// If found, add to mailboxOps


Comment says "add to mailboxOps" but the code adds to putInboxMessages, not mailboxOps. The comment should be updated to say "add to putInboxMessages" to match the actual code.

Suggested change

// If found, add to mailboxOps

// If found, add to putInboxMessages

Copilot · 2025-11-28T15:22:49Z

compose/cdcp/native_sequencer.go

+}
+
+// NewNativeSequencerInstance returns a new native-sequencer CDCP instance.
+// It has the exact same behaviour as in SCP, and thus its constructor can used.


Comment says "its constructor can used" but should say "its constructor can be used". The word "be" is missing.

Suggested change

// It has the exact same behaviour as in SCP, and thus its constructor can used.

// It has the exact same behaviour as in SCP, and thus its constructor can be used.

Copilot · 2025-11-28T15:22:50Z

compose/cdcp/publisher_test.go

+	// Processed votes
+	require.NoError(t, pub.ProcessVote(compose.ChainID(1), true))
+	require.NoError(t, pub.ProcessVote(compose.ChainID(2), true))
+	// NativeDecided shoudl be sent with result true


Typo in comment: "shoudl" should be "should".

Suggested change

// NativeDecided shoudl be sent with result true

// NativeDecided should be sent with result true

Copilot · 2025-11-28T15:22:50Z

compose/cdcp/wrapped_sequencer_test.go

+	require.Equal(t, 1, len(exec.requests))
+
+	msg := makeMailboxMsg(1, 4, "late", []byte("payload"))
+	// ProcessMailboxMessage don't trigger any simulation requests.


Comment says "ProcessMailboxMessage don't trigger" but should say "ProcessMailboxMessage doesn't trigger". The verb should agree with the singular subject.

Suggested change

// ProcessMailboxMessage don't trigger any simulation requests.

// ProcessMailboxMessage doesn't trigger any simulation requests.

Copilot · 2025-11-28T15:22:50Z

compose/cdcp/publisher.go

+	return r.instance
+}
+
+// Run performs launches the instance by sending a message to all participants.


Comment says "Run performs launches the instance" which is grammatically incorrect. It should either be "Run launches the instance" or "Run performs the instance launch".

Suggested change

// Run performs launches the instance by sending a message to all participants.

// Run launches the instance by sending a message to all participants.

Copilot · 2025-11-28T15:22:50Z

compose/cdcp/wrapped_sequencer.go

+func (ws *wsInstance) sendWriteMessages(messages []scp.MailboxMessage) {
+	for _, msg := range messages {
+		// Check if belongs to cache
+		alreadySent := false
+		for _, cachedMsg := range ws.writtenMessagesCache {
+			if cachedMsg.Equal(msg) {
+				alreadySent = true
+				break
+			}
+		}
+		if alreadySent {
+			continue
+		}
+
+		// Send and add to cache if new message
+		ws.network.SendMailboxMessage(msg.MailboxMessageHeader.DestChainID, msg)
+		ws.writtenMessagesCache = append(ws.writtenMessagesCache, msg)
+	}
+}


The sendWriteMessages method is called while holding the mutex lock in Run() (line 203), but the method itself doesn't acquire or expect the lock to be held. It accesses shared state like ws.writtenMessagesCache without synchronization. Either the method should document that it must be called with the lock held, or it should acquire the lock internally. Given that it's only called from within Run() while the lock is held, adding a comment documenting this requirement would clarify the locking contract.

GalRogozinski · 2025-12-01T10:43:01Z

compose/cdcp/publisher.go

+}
+
+// validateChains validates the instance and returns the set of native chains.
+func validateChains(instance compose.Instance, erChainID compose.ChainID) (nativeChains map[compose.ChainID]struct{}, err error) {


Suggested change

func validateChains(instance compose.Instance, erChainID compose.ChainID) (nativeChains map[compose.ChainID]struct{}, err error) {

func validateNativeChains(instance compose.Instance, erChainID compose.ChainID) (nativeChains map[compose.ChainID]struct{}, err error) {

Also maybe it is nice to to support multiple ERs?
But good enough for now

GalRogozinski

Good job!
For some of my comments you can see what Engineering thinks

GalRogozinski · 2025-12-01T10:47:59Z

compose/cdcp/publisher.go

+)
+
+type publisherInstance struct {
+	mu sync.Mutex


why aren't we using RW mutex from the get go?

GalRogozinski · 2025-12-01T10:50:41Z

compose/cdcp/publisher.go

+		r.logger.Info().
+			Uint64("chain_id", uint64(sender)).
+			Bool("vote", vote).
+			Msg("Ignoring vote because not waiting anymore")
+		return nil
+	}
+
+	// Ensure no duplicates
+	if _, exists := r.votes[sender]; exists {
+		r.logger.Info().
+			Uint64("chain_id", uint64(sender)).
+			Bool("vote", vote).
+			Msg("Ignoring duplicated vote")
+		return ErrDuplicatedVote
+	}
+
+	// Ensure it's a native chain
+	if _, ok := r.nativeChains[sender]; !ok {
+		r.logger.Info().
+			Uint64("chain_id", uint64(sender)).
+			Bool("vote", vote).
+			Msg("Ignoring vote from non-native chain")
+		return ErrVoteSenderNotNativeChain
+	}


just wondering if those shouldn't be WARN level because they are unaccepted behavior

GalRogozinski · 2025-12-01T11:22:52Z

compose/cdcp/wrapped_sequencer.go

+		PutInboxMessages:  append([]scp.MailboxMessage(nil), ws.putInboxMessages...),
+		PutOutboxMessages: append([]scp.MailboxMessage(nil), ws.writePrePopulationMessages...),
+		Transactions:      ws.txs,


shouldn't you do all the reads inside a lock?

GalRogozinski · 2025-12-01T11:26:28Z

compose/cdcp/wrapped_sequencer.go

+func (ws *wsInstance) attemptERCall() {
+	ws.mu.Lock()
+
+	// If not waiting for native decided, return
+	if ws.state != WSStateWaitingNativeDecided {
+		ws.mu.Unlock()
+		return
+	}


why not use defer mu.unlock?

GalRogozinski · 2025-12-01T11:28:33Z

compose/cdcp/wrapped_sequencer.go

+	ws.mu.Unlock()
+	if includedAny {


you don't use defer mu.unlock becuase of the log?

GalRogozinski · 2025-12-01T11:29:59Z

compose/cdcp/wrapped_sequencer.go

+
+// consumeReceivedMailboxMessagesAndSimulate checks if any expected read mailbox messages have been received
+// If so, remove from the lists, and call run to simulate
+func (ws *wsInstance) consumeReceivedMailboxMessagesAndSimulate() error {


I don't see you simulating here...
How will this be used as lib? Maybe pass a simulation function?

GalRogozinski · 2025-12-01T11:30:56Z

compose/cdcp/wrapped_sequencer.go

+		ws.logger.Info().
+			Bool("received_native_decided", decided).
+			Bool("stored_native_decision", *ws.nativeDecided).
+			Msg("Ignoring native decided because already received")
+		ws.mu.Unlock()
+		return ErrDuplicateNativeDecided
+	}
+
+	if ws.state == WSStateDone {
+		ws.logger.Info().
+			Bool("received_native_decided", decided).
+			Str("stored_decision", ws.decisionState.String()).
+			Msg("Ignoring native decided message because already done")
+
+		ws.mu.Unlock()
+		return nil


GalRogozinski

AI review:

Potential deadlocks/back-pressure while holding mutexes during outbound network calls. In several code paths the state lock stays held while invoking network/ER clients: publisher.ProcessVote sends SendDecided/SendNativeDecided under lock (compose/cdcp/publisher.go:174-185), publisher.ProcessWSDecided sends SendDecided under lock (compose/cdcp/publisher.go:245-265), and wsInstance sends mailbox/WSDecided messages while locked (compose/cdcp/wrapped_sequencer.go:194-198, 235-252, 294-309, 422-428). If the transport layer is slow or re-enters callbacks, the state mutex can block progress or deadlock. Consider releasing locks before making external calls or deferring them outside the critical section.

Duplicate native decisions are treated as hard errors even after the instance completes (compose/cdcp/wrapped_sequencer.go:381-388). Networks often retry messages; returning ErrDuplicateNativeDecided after finishing could surface spurious errors upstream instead of being idempotent. Consider ignoring duplicates once a final decision is reached.

MatheusFranco99 added 30 commits October 27, 2025 10:12

Init compose

dc8d553

fix go mod module declaration

9219656

fix go mod renaming

3098e7f

downgrade go to 1.23.0

6596525

refactor Instance.Chains from field to method

b434865

Drop unused err and ERChainID field from publisher

af59b02

Added features, logging, and comments:

b387094

- Simulation returns written messages. - sbcp/sequencer sealed block var renaming. - Proof timeout config logic - Proof timeout resets seq number to 0

Add logging and no limit for proof_window=0 config

05deb09

align tests

1f8c47a

Add proto files and reamde

6bad137

Add publisher interface to scp

96f717a

Add pending dependency

4e6df41

Add periodID to rollback msg

b67e314

Export GenerateInstanceID method

f16afce

Add interface for scp sequencer

b96001e

Add proto with XTRequest with chain id

7c95866

Deprecate Transactions interface for XTRequest explicit structure

397ad85

Use chain id as uint64

4597cc5

rename scp.go to mailbox.go

29572a9

Add non-participant check in scp/publisher

b384351

Rename proto file

6318cbc

participant check refactor

09620b4

Add sbcp-v2 spec file

d180d98

Add proof pipeline logic to sbcp spec code

8fefc57

Add deprecated note to sbcp v1

90d7ea4

Fix lock usage

1480ead

check that proof.superblock has finished

6ea0acb

align unit tests

5814c6f

align scp

2c50d7d

github action for unit tests

9c26848

MatheusFranco99 added 2 commits November 24, 2025 15:41

re-order check and add unit tests

49647f2

add cdcp readme

4998334

MatheusFranco99 requested a review from GalRogozinski November 24, 2025 16:10

MatheusFranco99 added 16 commits November 25, 2025 07:47

clarify hash content

0a5d814

clarify hash content

eafc14b

Merge branch 'compose-lib' into cdcp-md-and-impl

ef208d8

rename network proof to superblock proof

ff18057

add target superblock to publisher constructor

18478c6

remove v1 file

4833bb3

remove v2 mentions

201c4cc

add golangci lint

34aa6e0

fix linter

5e6b18b

improve readability of StartPeriod

c064476

Revert "improve readability of StartPeriod"

d738783

This reverts commit c064476.

clarify input var names

7855cc0

Merge branch 'compose-lib' into cdcp-md-and-impl

84de545

Merge branch 'main' into cdcp-md-and-impl

1f49e15

fix linter issue

89001bd

delete cdcp markdown

84d7483

MatheusFranco99 changed the title ~~CDCP~~ CDCP Spec Nov 27, 2025

fix wrong spaces

8377c9a

MatheusFranco99 changed the title ~~CDCP Spec~~ CDCP Core Lib Nov 27, 2025

MatheusFranco99 marked this pull request as ready for review November 28, 2025 15:18

Copilot AI review requested due to automatic review settings November 28, 2025 15:18

Copilot started reviewing on behalf of MatheusFranco99 November 28, 2025 15:18 View session

Copilot finished reviewing on behalf of MatheusFranco99 November 28, 2025 15:21

Copilot AI reviewed Nov 28, 2025

View reviewed changes

GalRogozinski reviewed Dec 1, 2025

View reviewed changes

	// Ensure an error is returned chain has no transaction.
	// Ensure an error is returned when chain has no transaction.

	// creation errors if the ER chain has no transaction.
	// creation errors if the ER chain has no transactions.

	ws.logger.Info().Err(err).Msg("ER call succeeded. Sending WSDecided as true.")
	ws.logger.Info().Msg("ER call succeeded. Sending WSDecided as true.")

	// If found, add to mailboxOps
	// If found, add to putInboxMessages

	// It has the exact same behaviour as in SCP, and thus its constructor can used.
	// It has the exact same behaviour as in SCP, and thus its constructor can be used.

	// NativeDecided shoudl be sent with result true
	// NativeDecided should be sent with result true

	// ProcessMailboxMessage don't trigger any simulation requests.
	// ProcessMailboxMessage doesn't trigger any simulation requests.

	// Run performs launches the instance by sending a message to all participants.
	// Run launches the instance by sending a message to all participants.

	func validateChains(instance compose.Instance, erChainID compose.ChainID) (nativeChains map[compose.ChainID]struct{}, err error) {
	func validateNativeChains(instance compose.Instance, erChainID compose.ChainID) (nativeChains map[compose.ChainID]struct{}, err error) {

CDCP Core Lib #9

Are you sure you want to change the base?

CDCP Core Lib #9

Uh oh!

Conversation

MatheusFranco99 commented Nov 16, 2025

Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025 • 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!

GalRogozinski left a comment

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

GalRogozinski left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

GalRogozinski Dec 1, 2025 •

edited

Loading