code.vegaprotocol.io/vega@v0.79.0/protos/sources/vega/data_source.proto

syntax = "proto3";

package vega;

import "google/protobuf/struct.proto";
import "vega/data/v1/data.proto";
import "vega/data/v1/spec.proto";

option go_package = "code.vegaprotocol.io/vega/protos/vega";

// Represents the top level object that handles data sources.
// Data source definition can be external or internal, with whatever
// number of data sources are defined for each type in the child objects below.
message DataSourceDefinition {
  oneof source_type {
    DataSourceDefinitionInternal internal = 1;
    DataSourceDefinitionExternal external = 2;
  }
}

// Describes which property of the data source data is to be
// used for price source.
message SpecBindingForCompositePrice {
  // The property name of price.
  string price_source_property = 1;
}

// Internal data source used for emitting timestamps.
message DataSourceSpecConfigurationTime {
  // Conditions that the timestamps should meet in order to be considered.
  repeated vega.data.v1.Condition conditions = 1;
}

// Internal data source used for emitting timestamps automatically using predefined intervals and conditions.
message DataSourceSpecConfigurationTimeTrigger {
  // Conditions that the timestamps need to meet in order to be considered.
  repeated vega.data.v1.Condition conditions = 1;
  // An internal time trigger
  repeated vega.data.v1.InternalTimeTrigger triggers = 2;
}

// Top level object used for all internal data sources.
// It contains one of any of the defined source type variants.
message DataSourceDefinitionInternal {
  // Types of internal data sources
  oneof source_type {
    DataSourceSpecConfigurationTime time = 1;
    DataSourceSpecConfigurationTimeTrigger time_trigger = 2;
  }
}

// DataSourceDefinitionExternal is the top level object used for all external
// data sources. It contains one of any of the defined `SourceType` variants.
message DataSourceDefinitionExternal {
  // Types of External data sources
  oneof source_type {
    DataSourceSpecConfiguration oracle = 1;
    // Contains the data specification that is received from Ethereum sources.
    EthCallSpec eth_oracle = 2;
  }
}

// All types of external data sources use the same configuration set for meeting
// requirements in order for the data to be useful for Vega - valid signatures
// and matching filters.
message DataSourceSpecConfiguration {
  // Signers is the list of authorized signatures that signed the data for this
  // source. All the signatures in the data source data should be contained in
  // this external source. All the signatures in the data should be contained in
  // this list.
  repeated vega.data.v1.Signer signers = 1;

  // Filters describes which source data are considered of interest or not for
  // the product (or the risk model).
  repeated vega.data.v1.Filter filters = 2;
}

// Specifies a data source that derives its content from calling a read method
// on an Ethereum contract.
message EthCallSpec {
  // Ethereum address of the contract to call.
  string address = 1;
  // The ABI of that contract.
  string abi = 2;
  // Name of the method on the contract to call.
  string method = 3;
  // List of arguments to pass to method call.
  // Protobuf 'Value' wraps an arbitrary JSON type that is mapped to an Ethereum
  // type according to the ABI.
  repeated google.protobuf.Value args = 4;
  // Conditions for determining when to call the contract method.
  EthCallTrigger trigger = 5;
  // Number of confirmations required before the query is considered verified
  uint64 required_confirmations = 6;
  // Filters the data returned from the contract method
  repeated vega.data.v1.Filter filters = 7;
  // Normalisers are used to convert the data returned from the contract method
  // into a standard format. The key of the map is the name of the property,
  // which identifies the specific piece of data to other parts of the data
  // sourcing framework, for example filters. The value is a JSONPath expression
  // for expressing where in the contract call result the required data is
  // located, for example $[0] indicates the first result. $[1].price would look
  // in the second result returned from the contract for a structure with a key
  // called 'price' and use that if it exists.
  repeated Normaliser normalisers = 8;

  // The ID of the EVM based chain which is to be used to source the oracle data.
  uint64 source_chain_id = 9;
}

message Normaliser {
  string name = 1;
  string expression = 2;
}

// Determines when the contract method should be called.
message EthCallTrigger {
  oneof trigger {
    EthTimeTrigger time_trigger = 1;
  }
}

// Trigger for an Ethereum call based on the Ethereum block timestamp. Can be
// one-off or repeating.
message EthTimeTrigger {
  // Trigger when the Ethereum time is greater or equal to this time, in Unix
  // seconds.
  optional uint64 initial = 1;
  // Repeat the call every n seconds after the initial call. If no time for
  // initial call was specified, begin repeating immediately.
  optional uint64 every = 2;
  // If repeating, stop once Ethereum time is greater than this time, in Unix
  // seconds. If not set, then repeat indefinitely.
  optional uint64 until = 3;
}

// Data source spec describes the data source base that a product or a risk
// model wants to get from the data source engine. This message contains
// additional information used by the API.
message DataSourceSpec {
  // Hash generated from the DataSpec data.
  string id = 1;
  // Creation date and time
  int64 created_at = 2;
  // Last Updated timestamp
  int64 updated_at = 3;

  DataSourceDefinition data = 4;

  // Status describes the status of the data source spec
  Status status = 5;

  // Status describe the status of the data source spec
  enum Status {
    // Default value.
    STATUS_UNSPECIFIED = 0;
    // STATUS_ACTIVE describes an active data source spec.
    STATUS_ACTIVE = 1;
    // STATUS_DEACTIVATED describes a data source spec that is not listening to
    // data anymore.
    STATUS_DEACTIVATED = 2;
  }
}

message ExternalDataSourceSpec {
  DataSourceSpec spec = 1;
}