Skip to main content

Timelines

What are Timelines?​

A timeline is a hash-chained sequence of authenticated events that serves as a verifiable record of actions. Timelines provide the cryptographically secure foundation for interactions within Blue documents, allowing processors to verify exactly who performed which actions.

Each timeline entry is linked to previous entries, creating an immutable chain that cannot be retroactively modified without detection.

Timelines as Event Sources​

Documents in Blue receive events through channels, with timelines being the most common channel type:

name: Purchase Agreement
contracts:
  buyerChannel:
    type: Timeline Channel
    timelineId: buyer-timeline-123
    
  sellerChannel:
    type: Timeline Channel
    timelineId: seller-timeline-456

  purchaseWorkflow:
    type: Sequential Workflow
    channel: buyerChannel
    event:
      type: Confirm Purchase
    steps:
      - type: Update Document
        changeset:
          - op: add
            path: /status
            val: "confirmed"

When an event appears on the buyer's timeline, the document processes it according to defined workflows. The timeline provides cryptographic verification that the event genuinely came from the claimed source, creating a foundation of trust for all document operations. When multiple timelines interact with the same document, proper coordination mechanisms are needed to determine the order of processing events from different sources, as explained in detail in the Events from Multiple Sources section.

Timeline Types and Trust Models​

The Blue language accommodates multiple timeline implementations, each offering different trust characteristics:

Managed Timelines​

MyOS Timelines provide a convenient managed implementation with email-based authentication and extensive features:

userTimeline:
  type: MyOS Timeline
  account: user@example.com

These timelines are straightforward to set up and use. While they rely on MyOS as a service provider, the nature of timelines limits this trust requirement in important ways:

  • Timeline services like MyOS only record ordered messages; they don't execute arbitrary operations
  • Timeline entries are chained, making any tampering immediately detectable
  • Any timeline manipulation would be cryptographically verifiable, undermining the provider's reputation
  • The contents of timeline messages may be encrypted, limiting what the provider can see

For most use cases, managed timelines offer an excellent balance of convenience and security. Learn more in the MyOS Timelines section.

Self-Hosted Timelines​

For organizations with specific compliance requirements, self-hosted implementations are available:

personalTimeline:
  type: AWS Basic Timeline with Secp256k1 Schnorr Signature
  name: MyTimeline
  sqs: arn:aws:sqs:eu-west-1:000000000000:SimpleBlueTimeline-TimelineEntriesSQS-xxx
  publicKey: 03a1b2c3d4e5f6098a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f40

These implementations require more technical setup and maintenance but provide additional control.

Institutional Timelines​

Organizations, governments, and institutions can provide timeline implementations with stronger identity verification:

citizenTimeline:
  type: USDS Citizen Timeline
  signature: f2b1a3c5d7e9f0e1d3c2b4a6987f5e4d2c1b3a59687766554433221
  api: https://api.usds.gov/v1/timelines/public/entries
  publicKey: 03a1b2c3d4e5f6098a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f40

For example, a professor can issue academic records associated with their institutional timeline and the student's timeline:

  1. The resulting document is persistent and student-owned, not just a record in a university database
  2. Students can embed their verified academic records into other documents like job applications or loan agreements
  3. As a living document, the professor can update grades if necessary (for corrections or academic integrity issues)

This creates persistent digital credentials with clear provenance and update capabilities.

Blockchain-Based Timelines​

For maximum decentralization, timelines can be built on top of blockchain systems:

ethTimeline:
  type: ETH Standard Timeline
  address: 0x1234567890abcdef1234567890abcdef12345678

These timelines inherit the security and decentralization properties of the underlying blockchain.

Timeline Privacy Models​

Timelines support different privacy models:

  • Public timelines: Entries visible to anyone who knows the timeline ID
  • Private timelines: Entries only visible to authorized participants
  • Mixed privacy: Individual entries can be encrypted, allowing selective sharing

It's generally recommended to create a unique timeline for each interaction or relationship rather than using a single timeline for all activities. This improves privacy and limits the scope of information sharing.

Anatomy of a Timeline Entry​

The base definition of a timeline entry includes:

name: Timeline Entry
timeline:
  type: Timeline
entryPrev: 
  type: Timeline Entry
message:
  # Any message content

Different timeline implementations extend this with additional fields. For example, a MyOS Timeline Entry:

timeline: 
  type: MyOS Timeline
  timelineId: 554d7714-5c18-4a8b-9ffd-edba24b067f0
  accountId: 15543223
entryPrev:
  blueId: 8BqE4SiVtoJsYKDgHLmzCdWqVN2r5fup7wV
timestamp: 2023-11-10T14:27:19Z
message:
  type: Purchase Request
  itemId: ITEM-12345
  quantity: 3
signature: 6tM3RwnJpLvKgHZ9yb2kLw5EdXCSfPjmXyJ2

This structure ensures:

  • Integrity: Entries cannot be modified once added (hash chain integrity)
  • Authentication: Each entry is verifiably from the claimed author
  • Ordering: The sequence of events is preserved through previous entry references

Timeline Owners Beyond Humans​

Timelines can represent various actors in a system:

  • Human users: The most common timeline owners
  • AI agents: Creating accountability for automated systems
  • IoT devices: Establishing trusted device identity
  • Organizations: Representing collective entities through authorized signers
  • Services: Creating verifiable service identities

This flexibility allows Blue documents to model complex multi-party interactions where both human and non-human actors need to be represented with clear identity and action verification.