cloudevent

DIMO CloudEvent

A Go library for working with CloudEvents in the DIMO ecosystem, with specialized support for Decentralized Identifiers (DIDs).

Overview

DIMO CloudEvent is designed for developers building applications within the DIMO ecosystem who need to:

• Work with standardized event data following the CloudEvents specification
• Process events with blockchain-based identifiers (DIDs)
• Build event-driven applications with persistent, well-structured event data

This library implements a DIMO-specific profile of the CloudEvents specification, extending the standard with additional features for decentralized identifiers and blockchain data structures while maintaining compatibility with the core specification.

CloudEvent Format

CloudEvents Specification

DIMO CloudEvents are a derived standard from the official CloudEvents specification v1.0. While maintaining full compatibility with the base standard, DIMO CloudEvents include additional fields and conventions specific to the DIMO ecosystem.

The core structure is:

type CloudEvent[A any] struct {
    CloudEventHeader
    Data A `json:"data"`
}

Example CloudEvent JSON

When working with DIMO services, your CloudEvent payload should follow this format:

{
  "id": "unique-event-identifier",
  "source": "0xEthereumAddress",
  "producer": "did:erc721:1:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:42",
  "specversion": "1.0",
  "subject": "did:erc721:1:0x123456789abcdef0123456789abcdef012345678:42",
  "time": "2025-03-04T12:00:00Z",
  "type": "dimo.status",
  "datacontenttype": "application/json",
  "dataversion": "default/v1.0",
  "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12",
  "tags": ["telemetry"],
  "data": {
    "signals": [
      {
        "name": "powertrainTransmissionTravelledDistance",
        "timestamp": "2025-03-04T12:00:00Z",
        "value": 12345.67
      },
      {
        "name": "speed",
        "timestamp": "2025-03-04T12:01:00Z",
        "value": 55
      },
      {
        "name": "powertrainType",
        "timestamp": "2025-03-04T12:03:00Z",
        "value": "COMBUSTION"
      }
    ],
    "vin": "1GGCM82633A123456"
  }
}

CloudEvent Headers

Each CloudEvent contains the following header fields:

The DIMO-specific extensions to the CloudEvents specification include:

• Producer: Provides additional context about the specific instance, process, or device that created the event
• DataVersion: A DIMO-specific extension that is unique to each source. This can be used by a source to determine the shape of the data field, enabling version-based data processing
• Signature: An optional cryptographic signature field for verifying the integrity and authenticity of the CloudEvent's data
• RawEventID: An optional identifier pointing from a parsed event to its raw source event
• Tags: An optional list of tags for filtering and categorizing events, useful for event organization and query optimization

Event Uniqueness

A CloudEvent is uniquely identified by the combination of the following fields:

• Subject
• Time
• Type
• Source
• ID

This combination is the event's logical key (see CloudEventHeader.Key()) and is used for deduplication.

Storage keys

These are storage pointers, set server-side by the ingestion pipeline. They are not part of the CloudEvent wire format and must never be set from producer-supplied input.

• index_key: pointer to the backing object holding this event's row. For events grouped into a Parquet bundle, the format is <bundleObjectKey>#<rowOffset> (see parquet.ParseIndexKey). For singleton events, it's the standalone object's key (see clickhouse.CloudEventToObjectKey).
• data_index_key: pointer to the external object holding this event's payload, when the payload is stored out-of-band (e.g. a large image). Empty when the payload is inline in the row's data / data_base64. Carried on cloudevent.StoredEvent.DataIndexKey at write time and stored as a column in both ClickHouse and the Parquet bundle.

DIMO Event Types

The library defines several DIMO-specific event types:

• dimo.status: Used for status updates
• dimo.fingerprint: Used for fingerprint updates
• dimo.verifiablecredential: Used for verifiable credentials
• dimo.unknown: Used for unknown events
• dimo.attestation: Used for attestation events from a vehicle attestation.
• dimo.event: Used for events from a vehicle event.
• dimo.trigger: Used for trigger events from a vehicle trigger.
• dimo.sacd: Used for cloudevents defining a SACD(Service Access Control Definition) agreement.
• dimo.sacd.template: Used for cloudevents defining a template SACD agreement.

DIMO services expect the Type field to be one of these predefined types. Using custom or undefined types may result in events being improperly processed or rejected by DIMO services.

Decentralized Identifier (DID) Formats

The library provides support for two types of DIDs:

ERC721 DID

The ERC721 DID format is used to identify ERC721 tokens on a blockchain:

did:erc721:<chainID>:<contractAddress>:<tokenID>

Example: did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:123

• chainID: The blockchain network ID (e.g., 1 for Ethereum mainnet, 137 for Polygon)
• contractAddress: Ethereum hex address of the NFT contract
• tokenID: The numeric token ID

Ethereum DID

The Ethereum DID format is used to identify Ethereum accounts or contracts:

did:ethr:<chainID>:<address>

Example: did:ethr:1:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF

• chainID: The blockchain network ID
• address: Ethereum hex address

Usage Examples

Creating a CloudEvent

event := cloudevent.CloudEvent[MyDataType]{
    CloudEventHeader: cloudevent.CloudEventHeader{
        ID:             "unique-id",
        Source:         "0xConnectionLicenseAddress",
        Producer:       cloudevent.ERC721DID{
          ChainID: 1,
          ContractAddress: "0x123456789abcdef0123456789abcdef012345678",
          TokenID: big.NewInt(123),
        }.String(),
        Subject:         cloudevent.ERC721DID{
          ChainID: 1,
          ContractAddress: "0x123456789abcdef0123456789abcdef012345678",
          TokenID: big.NewInt(123),
        }.String(),
        Time:           time.Now().UTC(),
        Type:           cloudevent.TypeStatus,
        DataContentType: "application/json",
        DataVersion:    "default/v1.0",
        Signature:      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12",
        Tags:           []string{"telemetry"},
    },
    Data: MyDataType{
        // Your data fields
    },
}

Working with DIDs

// Parse an ERC721 DID
erc721DID, err := cloudevent.DecodeERC721DID("did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:123")
if err != nil {
    // Handle error
}

// Convert back to string
didString := erc721DID.String()

Development

Use make to manage the project building, testing, and linting.

> make help

Specify a subcommand:

  build                Build the code
  clean                Clean the project binaries
  tidy                 tidy the go modules
  test                 Run the all tests
  lint                 Run the linter
  format               Run the linter with fix
  migration            Generate migration file specify name with name=your_migration_name
  tools                Install all tools
  tools-golangci-lint  Install golangci-lint
  tools-migration      Install migration tool

License

Apache 2.0