pyth-network_pyth-crosschain/lazer/publisher_sdk/proto/state.proto

syntax = "proto3";
package pyth_lazer;

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

import "dynamic_value.proto";


// All optional fields should always be set unless documented otherwise.

message Channel {
    oneof kind {
        google.protobuf.Duration rate = 1;
        google.protobuf.Empty real_time = 2;
    }
}

// State of a Pyth Lazer shard.
//
// The state is shared across all Pyth Lazer aggregators that process this shard.
// All aggregators should observe the same state at any `last_sequence_no`.
// The state contains all the information necessary for processing the updates.
// The aggregators cannot rely on any external data, except the state and the update sequence.
// A snapshot of the state includes the serialized `State` value as the payload.
message State {
    // [required] ID of this shard. Each state value only accounts for data of a particular shard.
    optional uint32 shard_id = 1;
    // [required] sequence_no of the last update applied to the state.
    optional uint64 last_sequence_no = 2;
    // [required] Timestamp of the last update provided by Kafka/Nats.
    // If no updates were applied, contains the timestamp of genesis snapshot creation time.
    optional google.protobuf.Timestamp last_timestamp = 3;
    // [required] Shard name. Must be unique. Used for governance instruction targeting and
    // for logs, metrics, etc. Example: "shard1.tokyo.staging.pyth-lazer"
    optional string shard_name = 4;
    // [required] Shard group name. Used for governance instruction targeting.
    // Example: "tokyo.staging.pyth-lazer"
    optional string shard_group = 5;
    // [required] Minimal aggregation rate allowed in this shard.
    optional google.protobuf.Duration min_rate = 6;
    // List of feeds.
    repeated Feed feeds = 7;
    // List of publishers.
    repeated Publisher publishers = 8;
    // List of governance sources.
    repeated GovernanceSourceState governance_sources = 9;
    // Currently active feature flags. Feature flags influence the aggregator's behavior.
    repeated string feature_flags = 10;
}

// An item of the state describing a publisher.
message Publisher {
    // [required] Publisher ID. Restricted to uint16.
    optional uint32 publisher_id = 1;
    // [required] Publisher name (only for debug/monitoring/management purposes). Must be unique.
    optional string name = 2;
    // Public keys used to sign publisher update transactions.
    repeated bytes public_keys = 3;
    // [required] If true, the publisher is active, i.e. it's allowed to publish updates.
    optional bool is_active = 4;
    // IDs of the feeds for which the publisher's price will be included in the aggregate.
    repeated uint32 allowed_feed_ids = 5;
}

enum FeedState {
    // Default value. Feeds in this state are not available to consumers.
    // `COMING_SOON` feeds are expected to become stable in the future.
    COMING_SOON = 0;
    // A fully available feed.
    STABLE = 1;
    // Inactive feeds are not available to consumers.
    // `INACTIVE` feeds are not expected to become stable again.
    INACTIVE = 2;
}

// Feed kind determines the set of data fields available in the feed.
// It also determines the kind of data accepted from publishers for this feed
// (`PriceUpdate` or `FundingRateUpdate`).
enum FeedKind {
    // Fields: price, best_bid_price, best_ask_price
    PRICE = 0;
    // Fields: price, rate.
    FUNDING_RATE = 1;
}

// An item of the state describing a feed.
message Feed {
    // [required] ID of the feed.
    optional uint32 feed_id = 1;
    // Additional state per publisher.
    // If an eligible publisher is not listed here, the corresponding state should be considered empty.
    repeated FeedPublisherState per_publisher = 2;
    // [required] Additional metadata values. These values will be exposed in the APIs, but
    // are not directly used in the aggregator.
    optional DynamicValue.Map metadata = 3;

    // [required] A readable feed name. It must be unique across all feeds in the shard.
    // Used for logs, metrics, feed search API, TradingView API.
    optional string name = 101;
    // [required] Exponent applied to all price and rate values for this feed.
    // Actual value is `mantissa * 10 ^ exponent`.
    // Restricted to int16.
    optional sint32 exponent = 102;
    // [required] Minimal number of publisher prices required to produce an aggregate.
    optional uint32 min_publishers = 103;
    // [required] Minimal channel of aggregation performed by the aggregator for this feed.
    // Cannot be lower than the shard's top level `State.min_rate`.
    optional Channel min_channel = 104;
    // [required] Time after which the publisher update is discarded.
    optional google.protobuf.Duration expiry_time = 105;
    // [required] Market schedule in Pythnet format.
    optional string market_schedule = 106;
    // [required] Feed state.
    optional FeedState state = 107;
    // [required] Feed kind.
    optional FeedKind kind = 108;
    // [required] Current aggregated data of the feed.
    optional FeedDataFields aggregated_data = 109;


    // [required] Feed status in the current shard. Disabled feeds will not be visible in
    // the consumer API for the current shard. This setting should only be used
    // to migrate a feed from one shard to another.
    //
    // If a feed is present in
    // multiple shards, it must only be active in one of them at each time.
    // To enforce this, `enable_in_shard_timestamp` and `disable_in_shard_timestamp` fields
    // can be used to deactivate a feed in one shard and activate it in another shard
    // at the same instant.
    optional bool is_enabled_in_shard = 201;
    // [optional] If present, the aggregator will enable the feed in the current shard
    // at the specified instant.
    optional google.protobuf.Timestamp enable_in_shard_timestamp = 202;
    // [optional] If present, the aggregator will disable the feed in the current shard
    // at the specified instant.
    optional google.protobuf.Timestamp disable_in_shard_timestamp = 203;

    // TODO: list of permissioned publisher IDs.
}

// A part of the feed state related to a particular publisher.
message FeedPublisherState {
    // [required] Publisher ID. Restricted to uint16.
    optional uint32 publisher_id = 1;
    // [optional] Timestamp of the last update received from this publisher to this feed.
    // This timestamp is provided by Nats/Kafka, not by publisher.
    // Can be absent if no update was ever received or if the last update was deemed no longer relevant.
    optional google.protobuf.Timestamp last_update_timestamp = 2;
    // [optional] Publisher timestamp of the last update received from this publisher to this feed.
    // This timestamp is provided by publisher.
    // Can be absent if no update was ever received or if the last update was deemed no longer relevant.
    optional google.protobuf.Timestamp last_publisher_timestamp = 3;
    // [optional] Data of the last update received from this publisher to this feed.
    // Can be absent if no update was ever received or if the last update was deemed no longer relevant.
    optional FeedData last_feed_data = 4;
}

// Data provided by a publisher for a certain feed.
message FeedData {
    // [required] Timestamp provided by the source of data that the publisher uses (e.g. an exchange).
    // If no such timestamp is available, it should be set to the same value as `publisher_timestamp`.
    optional google.protobuf.Timestamp source_timestamp = 1;
    // [required] Timestamp of the publisher.
    optional google.protobuf.Timestamp publisher_timestamp = 2;
    // [required] Values of the data fields.
    optional FeedDataFields fields = 3;
}

message FeedDataFields {
    // [optional] Best executable price. Can be absent if no data is available. Never present for funding rate feeds.
    optional int64 price = 1;
    // [optional] Best bid price. Can be absent if no data is available. Never present for funding rate feeds.
    optional int64 best_bid_price = 2;
    // [optional] Best ask price. Can be absent if no data is available. Never present for funding rate feeds.
    optional int64 best_ask_price = 3;
    // [optional] Funding rate. Can be absent if no data is available. Can only be present for funding rate feeds.
    optional int64 funding_rate = 4;
    // [optional] Funding rate interval. Can be absent if no data is available. Can only be present for funding rate feeds.
    optional google.protobuf.Duration funding_rate_interval = 5;
}

// State associated with a governance source.
message GovernanceSourceState {
    // [required]
    optional GovernanceSource source = 1;
    // [required]
    optional Permissions permissions = 2;
    // [required]
    optional uint64 last_sequence_no = 3;
}

// Permissions granted to a governance source.
// bool fields in this message are optional and default to false (no permission).
message Permissions {
    enum ShardAction {
        // Required by protobuf. Instruction will be rejected if this value is encountered.
        SHARD_ACTION_UNSPECIFIED = 0;
        // All operations, including operations added in the future.
        ALL_ACTIONS = 1;
        CREATE_SHARD = 101;
        ADD_GOVERNANCE_SOURCE = 102;
        // All operations under `UpdateGovernanceSource`,
        // including operations added in the future.
        UPDATE_GOVERNANCE_SOURCE = 103;
        SET_SHARD_NAME = 105;
        SET_SHARD_GROUP = 106;
        RESET_LAST_SEQUENCE_NO = 107;
        ADD_PUBLISHER = 108;
        // All operations under `UpdatePublisher`,
        // including operations added in the future.
        UPDATE_PUBLISHER = 109;
        REMOVE_PUBLISHER = 110;
        ADD_FEED = 111;
        // All operations under `UpdateFeed`,
        // including operations added in the future.
        UPDATE_FEED = 112;
        REMOVE_FEED = 113;
        ADD_FEATURE_FLAG = 114;
        REMOVE_FEATURE_FLAG = 115;
    }

    enum UpdateGovernanceSourceAction {
        // Required by protobuf. Instruction will be rejected if this value is encountered.
        UPDATE_GOVERNANCE_SOURCE_ACTION_UNSPECIFIED = 0;
        SET_GOVERNANCE_SOURCE_PERMISSIONS = 101;
    }

    enum UpdatePublisherAction {
        // Required by protobuf. Instruction will be rejected if this value is encountered.
        UPDATE_PUBLISHER_ACTION_UNSPECIFIED = 0;
        SET_PUBLISHER_NAME = 101;
        ADD_PUBLISHER_PUBLIC_KEYS = 102;
        REMOVE_PUBLISHER_PUBLIC_KEYS = 103;
        SET_PUBLISHER_PUBLIC_KEYS = 104;
        SET_PUBLISHER_ACTIVE = 105;
        ADD_PUBLISHER_ALLOWED_FEED_IDS = 106;
        REMOVE_PUBLISHER_ALLOWED_FEED_IDS = 107;
        SET_PUBLISHER_ALLOWED_FEED_IDS = 108;
    }

    enum UpdateFeedAction {
        // Required by protobuf. Instruction will be rejected if this value is encountered.
        UPDATE_FEED_ACTION_UNSPECIFIED = 0;
        UPDATE_FEED_PROPERTIES = 101;
        UPDATE_FEED_METADATA = 102;
        ENABLE_FEED_IN_SHARD = 103;
        DISABLE_FEED_IN_SHARD = 104;
    }

    repeated ShardAction actions = 1;
    repeated UpdateGovernanceSourceAction update_governance_source_actions = 2;
    repeated UpdatePublisherAction update_publisher_actions = 3;
    repeated UpdateFeedAction update_feed_actions = 4;
}


// Specifies the way governance transactions are signed and verified.
// Note that once added, a governance source cannot be removed.
// The last sequence number associated with this source
// will be retained in the state indefinitely to prevent repeated execution of instructions.
message GovernanceSource {
    // Governance transactions are signed by a single Ed25519 signature.
    // This will generally be used in development and testing groups.
    message SingleEd25519 {
        // [required] Ed25519 public key that signs governance transactions.
        optional bytes public_key = 1;
    }

    message WormholeEmitter {
        // [required] Wormhole emitter address.
        optional bytes address = 1;
        // [required] Wormhole emitter chain ID. Restricted to uint16.
        optional uint32 chain_id = 2;
    }

    // [required]
    oneof source {
        SingleEd25519 single_ed25519 = 1;
        WormholeEmitter wormhole_emitter = 2;
    }
}