Skip to main content

Events from Multiple Sources

Blue documents often receive events from multiple channels. While each channel maintains its own ordering, a key challenge arises: how should events from different channels be sequenced relative to each other? This page explains how Blue handles this challenge through channel coordination contracts.

The Multi-Channel Counter Problem​

Let's start with a concrete example: a document that counts events from both Alice and Bob:

name: Alice and Bob Counter
counterAlice: 0
counterBob: 0
contracts:
  aliceChannel:
    type: Timeline Channel
    account: alice@example.com

  bobChannel:
    type: Timeline Channel
    account: bob@example.com

  aliceWorkflow:
    type: Sequential Workflow
    channel: aliceChannel
    steps:
      - name: Update Alice Counter
        type: Update Document
        changeset:
          - op: replace
            path: /counterAlice
            val: ${document('/counterAlice') + 1}

  bobWorkflow:
    type: Sequential Workflow
    channel: bobChannel
    steps:
      - name: Update Bob Counter
        type: Update Document
        changeset:
          - op: replace
            path: /counterBob
            val: ${document('/counterBob') + 1}

This document works well when processed by a single processor that receives events in a fixed order. But what happens when multiple processors independently handle the same document? Without coordination, they might process the events in different orders, leading to different final states.

The Coordination Problem​

Consider this sequence of events:

  1. Alice adds event A1 to her timeline
  2. Bob adds event B1 to his timeline
  3. Alice adds event A2 to her timeline

Processor 1 might see: A1 → B1 → A2
Processor 2 might see: A1 → A2 → B1
Processor 3 might see: B1 → A1 → A2

Without coordination, these processors will reach different document states, breaking Blue's deterministic processing guarantee. This is where channel coordination contracts become essential.

Centralized Coordinator​

For scenarios where centralized processing is acceptable, the Centralized Coordinator provides a straightforward solution:

name: Alice and Bob Counter with Central Coordination
counterAlice: 0
counterBob: 0
contracts:
  aliceChannel:
    type: Timeline Channel
    account: alice@example.com

  bobChannel:
    type: Timeline Channel
    account: bob@example.com

  channelCoordinator:
    type: Centralized Coordinator
    authority: myos.blue
    channels: [aliceChannel, bobChannel]

  # Workflows as before

Benefits and Limitations​

Benefits:

  • Simple implementation
  • Immediate ordering decisions
  • No coordination overhead for participants
  • Higher performance

Limitations:

  • Requires trust in the central authority
  • Creates a single point of failure

Vector Clock Coordinator​

The Vector Clock Coordinator enables decentralized coordination between independent timelines by implementing a logical clock system:

name: Alice and Bob Counter with Vector Coordination
counterAlice: 0
counterBob: 0
contracts:
  aliceChannel:
    type: Timeline Channel
    account: alice@example.com

  bobChannel:
    type: Timeline Channel
    account: bob@example.com

  channelCoordinator:
    type: Vector Clock Coordinator
    channels: [aliceChannel, bobChannel]

  # Workflows as before

How Vector Clock Coordination Works​

This coordination mechanism:

  1. Requires each timeline entry to include a vector clock (counters for all participants)
  2. Establishes causal relationships between events based on these vectors
  3. Orders concurrent events deterministically using timeline IDs
  4. Ensures all processors reach the same event ordering

In practice, each timeline entry includes a vector showing what the participant has seen:

# Example entry in Alice's timeline
type: Vector Clock Message
message: 'Increment counter'
vectorClock:
  alice@example.com: 2 # Alice's timeline (incremented)
  bob@example.com: 1 # Last seen event from Bob

The Vector Clock Coordinator enables resilient decentralized coordination even during network partitions, though it requires active participation from all channels.

For a detailed explanation of vector clocks with complex examples, see the Vector Clock Coordination page.

Benefits and Limitations​

Benefits:

  • Works in fully decentralized environments
  • No central authority required
  • Guarantees causal consistency
  • Participants maintain autonomy

Limitations:

  • Requires active participation from all channels
  • Increases timeline entry complexity
  • May delay event processing while waiting for acknowledgments
  • Creates some performance overhead

Ethereum Coordinator​

The Ethereum Coordinator uses an Ethereum smart contract to establish a canonical ordering:

name: Alice and Bob Counter with Blockchain Coordination
counterAlice: 0
counterBob: 0
contracts:
  aliceChannel:
    type: Timeline Channel
    account: alice@example.com

  bobChannel:
    type: Timeline Channel
    account: bob@example.com

  channelCoordinator:
    type: Ethereum Coordinator
    contractAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
    chainId: 1
    channels: [aliceChannel, bobChannel]

  # Workflows as before

How the Ethereum Coordinator Works​

This coordination mechanism:

  1. Requires participants to submit event hashes to an Ethereum smart contract
  2. Uses the blockchain's ordering (block number and transaction index) to sequence events
  3. Ensures all processors can independently verify the same sequence

The Ethereum smart contract typically implements a simple event registry:

// Simple Event Registry Contract
contract EventRegistry {
    event EventRegistered(bytes32 eventId, uint256 timestamp);

    function registerEvent(bytes32 eventId) external {
        emit EventRegistered(eventId, block.timestamp);
    }
}

Processors observe the Ethereum blockchain to determine the canonical order of registered events.

Benefits and Limitations​

Benefits:

  • Decentralized without requiring participant cooperation
  • Provides tamper-resistant ordering
  • Resistant to participant collusion
  • Creates publicly verifiable evidence

Limitations:

  • Higher cost (Ethereum gas fees)
  • Slower confirmation times
  • Requires Ethereum infrastructure
  • Adds blockchain dependency

Choosing a Coordination Strategy​

When designing Blue documents with multiple channels, consider these factors:

  1. Trust Model: Is a central authority acceptable, or is full decentralization required?

  2. Performance Needs: Is immediate processing critical, or can events wait for coordination?

  3. Participant Capabilities: Can all participants implement complex coordination protocols?

  4. Resilience Requirements: How important is operation during infrastructure disruptions?

Next Steps​

Now that you understand how events from multiple channels can be coordinated, let's explore how Blue documents can incorporate external events from systems like cryptocurrency networks and weather services in the Source Binding section.