proto/pubsub/v1/pubsub.proto

syntax = "proto3";
package pubsub.v1;

import "gogoproto/gogo.proto";

option go_package = "github.com/peggyjv/sommelier/v8/x/pubsub/types";

// represents a publisher, which are added via governance
message Publisher {
  // account address of the publisher
  string address = 1;

  // unique key, FQDN of the publisher, max length of 256
  string domain = 2;

  // the publisher's self-signed CA cert PEM file, expecting TLS 1.3 compatible ECDSA certificates, max length 4096
  string ca_cert = 3;
}

// represents a subscriber, can be set or modified by the owner of the subscriber address
message Subscriber {
  // unique key, account address representation of either an account or a validator
  string address = 1;

  // the below fields are optional, and only required if the subscriber wants to use "push" PublisherIntents

  // the subscriber's self-signed CA cert PEM file, expecting TLS 1.3 compatible ECDSA certificates, max length 4096
  string ca_cert = 2;

  // max length of 512
  string push_url = 3;
}

// for a given PublisherIntent, whether or not it is pulled or pushed
enum PublishMethod {
  // subscribers should pull from the provided URL
  PULL = 0;

  // subscribers must provide a URL to receive push messages
  PUSH = 1;
}

// for a given PublisherIntent, determines what types of subscribers may subscribe
enum AllowedSubscribers {
  // any valid account address
  ANY = 0;

  // account address must map to a validator in the active validator set
  VALIDATORS = 1;

  // a specific list of account addresses
  LIST = 2;
}

// represents a publisher committing to sending messages for a specific subscription ID
message PublisherIntent {
  // unique key is subscription_id and publisher_domain tuple

  // arbitary string representing a subscription, max length of 128
  string subscription_id = 1;

  // FQDN of the publisher, max length of 256
  string publisher_domain = 2;

  // either PULL or PUSH (see enum above for details)
  PublishMethod method = 3;

  // optional, only needs to be set if using the PULL method, max length of 512
  string pull_url = 4;

  // either ANY, VALIDATORS, or LIST (see enum above for details)
  AllowedSubscribers allowed_subscribers = 5;

  // optional, must be provided if allowed_subscribers is LIST, list of account addresses, max length 256
  repeated string allowed_addresses = 6;
}

// represents a subscriber requesting messages for a specific subscription ID and publisher
message SubscriberIntent {
  // unique key is subscription_id and subscriber_address tuple, a given subscriber can only subscribe to one publisher per
  // subscription_id at a time

  // arbitary string representing a subscription, max length of 128
  string subscription_id = 1;

  // account address of the subscriber
  string subscriber_address = 2;

  // FQDN of the publisher, max length of 256
  string publisher_domain = 3;
}

// represents a default subscription voted in by governance that can be overridden by a subscriber
message DefaultSubscription {
  // arbitary string representing a subscription, max length of 128
  string subscription_id = 1;

  // FQDN of the publisher, max length of 256
  string publisher_domain = 2;
}

// governance proposal to add a publisher, with domain, adress, and ca_cert the same as the Publisher type
// proof URL expected in the format: https://<domain>/<address>/cacert.pem and serving cacert.pem matching ca_cert
message AddPublisherProposal {
  string title = 1;
  string description = 2;
  string domain = 3;
  string address = 4;
  string proof_url = 5;
  string ca_cert = 6;
}

message AddPublisherProposalWithDeposit {
  string title = 1;
  string description = 2;
  string domain = 3;
  string address = 4;
  string proof_url = 5;
  string ca_cert = 6;
  string deposit = 7;
}

// governance proposal to remove a publisher (publishers can remove themselves, but this might be necessary in the
// event of a malicious publisher or a key compromise), since Publishers are unique by domain, it's the only
// necessary information to remove one
message RemovePublisherProposal {
  string title = 1;
  string description = 2;
  string domain = 3;
}

message RemovePublisherProposalWithDeposit {
  string title = 1;
  string description = 2;
  string domain = 3;
  string deposit = 4;
}

// set the default publisher for a given subscription ID
// these can be overridden by the client
message AddDefaultSubscriptionProposal {
  string title = 1;
  string description = 2;
  string subscription_id = 3;
  string publisher_domain = 4;
}

message AddDefaultSubscriptionProposalWithDeposit {
  string title = 1;
  string description = 2;
  string subscription_id = 3;
  string publisher_domain = 4;
  string deposit = 5;
}

// remove a default subscription
message RemoveDefaultSubscriptionProposal {
  string title = 1;
  string description = 2;
  string subscription_id = 3;
}

message RemoveDefaultSubscriptionProposalWithDeposit {
  string title = 1;
  string description = 2;
  string subscription_id = 3;
  string deposit = 4;
}