Merge pull request #413 from helium/map/subscriber-referral

Add subscriber referral eligibility ingest messages

Cargo.toml

@@ -32,6 +32,8 @@ bytes = { workspace = true }
 prost = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
+strum = { version = "0.26.3", features = ["derive"] }
+strum_macros = "0.26.4"
 
 [build-dependencies]
 tonic-build = { workspace = true, optional = true }

build.rs

@@ -36,6 +36,10 @@ macro_rules! config {
     ($config:expr) => {
         $config
             .type_attribute(".", "#[derive(serde::Serialize, serde::Deserialize)]")
+            .enum_attribute(
+                ".helium.service_provider",
+                "#[derive(strum_macros::EnumIter)]",
+            )
             .field_attribute(
                 ".helium.tagged_spreading.region_spreading",
                 "#[serde(with = \"serde_region_spreading\" )]",

src/lib.rs

@@ -5,6 +5,7 @@ include!(concat!(env!("OUT_DIR"), "/helium.rs"));
 
 pub use blockchain_txn::Txn;
 pub use prost::{DecodeError, EncodeError, Message};
+pub use strum::IntoEnumIterator;
 
 #[cfg(feature = "services")]
 pub mod services {

src/reward_manifest.proto

@@ -3,10 +3,19 @@ syntax = "proto3";
 package helium;
 
 import "decimal.proto";
+import "service_provider.proto";
 
 message mobile_reward_data {
   Decimal poc_bones_per_reward_share = 1;
   Decimal boosted_poc_bones_per_reward_share = 2;
+  repeated service_provider_allocation sp_allocations = 3;
+}
+
+message service_provider_allocation {
+  service_provider service_provider = 1;
+  // The percentage of the SP rewards that are allocated to the incentive fun,
+  // in basis points
+  uint32 incentive_escrow_fund_bps = 2;
 }
 
 message iot_reward_data {

src/service/poc_mobile.proto

@@ -278,6 +278,48 @@ message verified_subscriber_location_ingest_report_v1 {
   uint64 timestamp = 3;
 }
 
+message promotion_reward_req_v1 {
+  // Entity to be rewarded
+  oneof entity {
+    // Subscriber reward
+    bytes subscriber_id = 1;
+    // Gateway reward
+    bytes gateway_key = 2;
+  }
+  // Shares rewarded to the subscriber
+  uint64 shares = 3;
+  // Timestamp in seconds since the unix epoch
+  uint64 timestamp = 4;
+  // Pubkey of the carrier for which the entity is attached
+  bytes carrier_pub_key = 5;
+  // Signed payload of the request
+  bytes signature = 6;
+}
+
+message promotion_reward_resp_v1 { string id = 1; }
+
+message promotion_reward_ingest_report_v1 {
+  // Timestamp in milliseconds since the unix epoch
+  uint64 received_timestamp = 1;
+  promotion_reward_req_v1 report = 2;
+}
+
+enum promotion_reward_status {
+  promotion_reward_status_valid = 0;
+  promotion_reward_status_invalid_subscriber_id = 1;
+  promotion_reward_status_invalid_gateway_key = 2;
+  promotion_reward_status_invalid_carrier_key = 3;
+}
+
+message verified_promotion_reward_v1 {
+  promotion_reward_ingest_report_v1 report = 1;
+  // Status of the report
+  promotion_reward_status status = 2;
+  // Timestamp at which verification was determined, in milliseconds since
+  // the unix epoch
+  uint64 timestamp = 3;
+}
+
 service poc_mobile {
   rpc submit_speedtest(speedtest_req_v1) returns (speedtest_resp_v1);
   rpc submit_cell_heartbeat(cell_heartbeat_req_v1)
@@ -301,6 +343,8 @@ service poc_mobile {
   rpc submit_subscriber_verified_mapping_event(
       subscriber_verified_mapping_event_req_v1)
       returns (subscriber_verified_mapping_event_res_v1);
+  rpc submit_promotion_reward(promotion_reward_req_v1)
+      returns (promotion_reward_resp_v1);
 }
 
 message file_info {
@@ -566,6 +610,20 @@ message subscriber_reward {
   uint64 verification_mapping_amount = 3;
 }
 
+message promotion_reward {
+  // Entity given the reward
+  oneof entity {
+    // Subscriber reward
+    bytes subscriber_id = 1;
+    // Gateway reward
+    bytes gateway_key = 2;
+  }
+  // Amount in bones given by the service provider
+  uint64 service_provider_amount = 3;
+  // Amount in bones matched by the network
+  uint64 matched_amount = 4;
+}
+
 message service_provider_reward {
   // rewardable entity id of the service provider to which the reward will be
   // credited
@@ -604,6 +662,7 @@ message mobile_reward_share {
     service_provider_reward service_provider_reward = 6;
     unallocated_reward unallocated_reward = 7;
     radio_reward_v2 radio_reward_v2 = 8;
+    promotion_reward promotion_reward = 9;
   }
 }
 
@@ -811,4 +870,4 @@ message verified_subscriber_verified_mapping_event_ingest_report_v1 {
   subscriber_verified_mapping_event_verification_status status = 2;
   // Timestamp in milliseconds since unix epoch
   uint64 timestamp = 3;
-}
+}

src/service_provider.proto

@@ -5,3 +5,17 @@ package helium;
 enum service_provider {
   helium_mobile = 0;
 }
+
+message service_provider_promotion_fund_v1 {
+  /// The timestamp for this report in milliseconds since unix epoch
+  uint64 timestamp = 1;
+
+  /// Service Provider that is allocating funds for promotions
+  service_provider service_provider = 2;
+
+  /// Percentage of Rewards allocated for promotions
+  /// stored in Basis Points
+  ///
+  /// https://www.investopedia.com/terms/b/basispoint.asp
+  uint32 bps = 3;
+}