Skip to main content

Source Binding

Blue documents can interact with events from the external world - from cryptocurrency transactions to weather conditions. This creates a powerful connection between digital documents and physical reality, but introduces an important question: how do we establish a shared understanding of external events?

Individual Interpretation: A Starting Point​

Let's explore a document that tracks two different types of external events:

name: External Reality Counter
btcBlockCount: 0
sunnyDayCount: 0
contracts:
  btcChannel:
    type: BTC Ledger Channel
    network: mainnet

  weatherChannel:
    type: Channel
    description: 'Incoming events represent sunny days in New York'

  btcBlockWorkflow:
    type: Sequential Workflow
    channel: btcChannel
    steps:
      - name: Increment BTC Block Counter
        type: Update Document
        changeset:
          - op: replace
            path: /btcBlockCount
            val: ${document('/btcBlockCount') + 1}

  weatherWorkflow:
    type: Sequential Workflow
    channel: weatherChannel
    steps:
      - name: Increment Sunny Day Counter
        type: Update Document
        changeset:
          - op: replace
            path: /sunnyDayCount
            val: ${document('/sunnyDayCount') + 1}

This document increments counters when Bitcoin blocks are confirmed or when there's a sunny day in New York. By default, each processor can decide for itself:

  • How to connect to the Bitcoin network
  • What constitutes a "sunny" day in New York

This approach works in scenarios where:

  • The document is processed by a single entity making its own determinations
  • Participants have a shared understanding of how to interpret external events
  • Precise agreement isn't critical to the document's purpose

This mirrors everyday casual agreements like "If it's sunny tomorrow, let's go to the park" - we don't typically specify the exact definition of "sunny" or which weather service to consult.

However, if Alice and Bob both process this document independently, they'll likely reach different counts based on their individual interpretations of "sunny" or which Bitcoin node they connect to.

Establishing Shared Sources: Channel Bindings​

For most practical Blue documents, we need to ensure all processors work with the same events. This is where channel bindings come in - they establish authoritative sources for events.

Let's modify our counter to use shared event sources:

name: Shared Reality Counter
type: External Reality Counter
contracts:
  mainBtcLedgerChannel:
    type: MyOS Timeline Channel
    account: main-btc-channel@myos.blue
    event:
      type: Block Confirmation

  weatherObservationChannel:
    type: MyOS Timeline Channel
    account: new-york-weather-channel@myos.blue
    event:
      type: Weather Observation
      condition: sunny

  channelBindings:
    type: Channel Source Binding
    btcChannel: mainBtcLedgerChannel
    weatherChannel: weatherObservationChannel

With this configuration:

  1. The abstract btcChannel now receives events from the concrete mainBtcLedgerChannel
  2. The abstract weatherChannel receives events from the concrete weatherObservationChannel
  3. All processors using this document will work with identical events

The Channel Source Binding preserves the document's logical structure while ensuring all processors share the same understanding of external events.

Why Channel Bindings Matter​

Channel bindings solve a fundamental challenge in distributed systems: establishing agreement about external reality. By explicitly defining authoritative sources, Blue documents can:

  1. Create consistency across processors: Everyone works with the same inputs
  2. Maintain document simplicity: Keep the core logic focused on what happens, not where events come from
  3. Enable verification: Observers can check the authoritative sources
  4. Preserve logical structure: Abstract channels define what the document responds to, concrete channels define where events come from

This pattern is essential for practically any Blue document that needs to function across multiple processors or participants.

Next Steps​

Now that you understand how Blue handles external events through channel bindings, let's explore how documents process these events using Sequential Workflows.