feat(distribution): exact O(1) payouts in token units, and fix the O(n^2) basis-point path

packages/interfaces/src/distribution.cairo

@@ -4,4 +4,55 @@ pub enum Distribution {
     Exponential: u16,
     Uniform,
     Custom: Span<u16>,
+    /// Geometric decay as a rational ratio `(a, b)`: each position receives
+    /// `b / a` of the one above it, so `W(p) = a^(n-p) * b^(p-1)`. Requires
+    /// `a > b > 0` — e.g. `(10, 7)` is "each place gets 70% of the previous".
+    ///
+    /// Unlike `Exponential` — which is a power law, and whose winner share
+    /// falls off as roughly `(k+1)/n` — a geometric curve's shape does not
+    /// depend on the size of the field: first place takes about `1 - b/a` of
+    /// the pool whether there are 10 paid places or 100. That is the shape a
+    /// headline first prize actually needs, and no `Exponential` weight
+    /// produces it over a large field.
+    ///
+    /// The trade is reach: the weights span `(a/b)^n`, so the representable
+    /// field size shrinks as the ratio gets finer. See
+    /// `max_geometric_payouts`.
+    ///
+    /// NOTE: appended deliberately. Serde indices are positional, so inserting
+    /// this anywhere earlier would silently reinterpret every stored and
+    /// indexed distribution.
+    Geometric: (u16, u16),
+    /// Two tiers: a geometric head over the first `head_count` places taking
+    /// `head_share_bps` of the pool, and the remaining places splitting the
+    /// rest evenly.
+    ///
+    /// This is the only family here that works for a very large field. A
+    /// single curve cannot: anything steep enough to give first place a real
+    /// share rounds its tail to nothing, and anything flat enough to pay the
+    /// tail gives first place nothing. Over 10,000 places the best a single
+    /// curve can do for first place is ~0.06% (`Exponential` k=5); a
+    /// `Geometric` head of 39 on (10, 7) taking 80% pays first place 24%,
+    /// while every one of the other 9,961 places still receives its slice of
+    /// the remaining 20%.
+    ///
+    /// The geometric reach bound applies to `head_count`, not the field, so
+    /// the head is always well inside it. Requires a fixed paid-places count
+    /// strictly greater than `head_count`.
+    Tiered: TieredConfig,
+}
+
+/// Configuration for `Distribution::Tiered`.
+#[derive(Drop, Copy, Serde, PartialEq)]
+pub struct TieredConfig {
+    /// Geometric decay `(a, b)` for the head: each place gets `b / a` of the
+    /// one above. Same semantics and validity rules as `Geometric`.
+    pub head_ratio: (u16, u16),
+    /// How many places the head covers. Must be under the paid-places count
+    /// and within `max_geometric_payouts(a)`.
+    pub head_count: u16,
+    /// The head's slice of the pool, in basis points. Strictly between 0 and
+    /// 10000 — at either extreme one of the tiers would round to an
+    /// unclaimable zero, and the single-curve variants cover those shapes.
+    pub head_share_bps: u16,
 }

packages/metagame/src/entry_fee/entry_fee_store.cairo

@@ -8,8 +8,8 @@ use game_components_utilities::distribution::packed_shares::{
     calculate_slot_position,
 };
 use game_components_utilities::distribution::structs::{
-    DIST_TYPE_CUSTOM, DIST_TYPE_EXPONENTIAL, DIST_TYPE_LINEAR, DIST_TYPE_UNIFORM,
-    PackedDistribution,
+    DIST_TYPE_CUSTOM, DIST_TYPE_EXPONENTIAL, DIST_TYPE_GEOMETRIC, DIST_TYPE_LINEAR,
+    DIST_TYPE_TIERED, DIST_TYPE_UNIFORM, PackedDistribution, TieredConfig,
 };
 use starknet::ContractAddress;
 use crate::entry_fee::store::Store;
@@ -98,6 +98,30 @@ pub impl EntryFeeStoreImpl<T, +Store<T>, +Drop<T>> of EntryFeeStoreTrait<T> {
             (Option::Some(Distribution::Exponential(packed_dist.dist_param)), packed_dist.positions)
         } else if packed_dist.dist_type == DIST_TYPE_UNIFORM {
             (Option::Some(Distribution::Uniform), packed_dist.positions)
+        } else if packed_dist.dist_type == DIST_TYPE_TIERED {
+            (
+                Option::Some(
+                    Distribution::Tiered(
+                        TieredConfig {
+                            head_ratio: (
+                                packed_dist.dist_param / 256, packed_dist.dist_param % 256,
+                            ),
+                            head_count: packed_dist.dist_param2,
+                            head_share_bps: packed_dist.dist_param3,
+                        },
+                    ),
+                ),
+                packed_dist.positions,
+            )
+        } else if packed_dist.dist_type == DIST_TYPE_GEOMETRIC {
+            (
+                Option::Some(
+                    Distribution::Geometric(
+                        (packed_dist.dist_param / 256, packed_dist.dist_param % 256),
+                    ),
+                ),
+                packed_dist.positions,
+            )
         } else {
             // DIST_TYPE_CUSTOM — return with empty shares span. Loading the
             // full array is O(N/15) storage reads and is only needed for UI
@@ -216,13 +240,20 @@ pub impl EntryFeeStoreImpl<T, +Store<T>, +Drop<T>> of EntryFeeStoreTrait<T> {
 
         // Persist the distribution config (shape + paid-places count), and
         // for Custom, the shares array in packed out-of-band storage.
-        let (dist_type, dist_param) = match config.distribution {
-            Option::None => (DIST_TYPE_LINEAR, 0_u16),
+        let (dist_type, dist_param, dist_param2, dist_param3) = match config.distribution {
+            Option::None => (DIST_TYPE_LINEAR, 0_u16, 0_u16, 0_u16),
             Option::Some(dist) => match dist {
-                Distribution::Linear(w) => (DIST_TYPE_LINEAR, *w),
-                Distribution::Exponential(w) => (DIST_TYPE_EXPONENTIAL, *w),
-                Distribution::Uniform => (DIST_TYPE_UNIFORM, 0_u16),
-                Distribution::Custom(_) => (DIST_TYPE_CUSTOM, 0_u16),
+                Distribution::Linear(w) => (DIST_TYPE_LINEAR, *w, 0_u16, 0_u16),
+                Distribution::Exponential(w) => (DIST_TYPE_EXPONENTIAL, *w, 0_u16, 0_u16),
+                Distribution::Uniform => (DIST_TYPE_UNIFORM, 0_u16, 0_u16, 0_u16),
+                Distribution::Custom(_) => (DIST_TYPE_CUSTOM, 0_u16, 0_u16, 0_u16),
+                Distribution::Geometric((
+                    a, b,
+                )) => (DIST_TYPE_GEOMETRIC, *a * 256 + *b, 0_u16, 0_u16),
+                Distribution::Tiered(cfg) => {
+                    let (a, b) = *cfg.head_ratio;
+                    (DIST_TYPE_TIERED, a * 256 + b, *cfg.head_count, *cfg.head_share_bps)
+                },
             },
         };
         // For Custom, paid places are defined by the shares array length;
@@ -235,7 +266,11 @@ pub impl EntryFeeStoreImpl<T, +Store<T>, +Drop<T>> of EntryFeeStoreTrait<T> {
             Option::None => 0_u32,
         };
 
-        self.set_distribution(context_id, PackedDistribution { dist_type, dist_param, positions });
+        self
+            .set_distribution(
+                context_id,
+                PackedDistribution { dist_type, dist_param, positions, dist_param2, dist_param3 },
+            );
 
         if let Option::Some(dist) = config.distribution {
             if let Distribution::Custom(shares) = dist {

packages/metagame/src/prize/prize_component.cairo

@@ -263,6 +263,17 @@ pub mod PrizeComponent {
             PrizeStoreTrait::get_custom_shares(self, prize_id)
         }
 
+        /// One custom share by 1-indexed position — a single storage read.
+        ///
+        /// `_get_prize` deliberately returns Custom with an empty span, so a
+        /// claim settling one position reads its share through here instead of
+        /// paying to rebuild the whole curve.
+        fn _get_custom_share_at(
+            self: @ComponentState<TContractState>, prize_id: u64, position: u32,
+        ) -> u16 {
+            PrizeStoreTrait::get_custom_share_at(self, prize_id, position)
+        }
+
         /// Store a token-prize record (converts to StoredPrize for storage).
         /// Extension prizes are not persisted via this path.
         fn set_token_record(

packages/metagame/src/prize/prize_store.cairo

@@ -16,8 +16,16 @@ pub trait PrizeStoreTrait<T> {
     /// are routed via the component's `resolve_prize` before this is
     /// called and never reach the store bridge.
     fn get_token_record(self: @T, prize_id: u64) -> PrizeRecord;
-    /// Get custom shares for a prize (reconstructs from packed storage)
+    /// Get custom shares for a prize (reconstructs from packed storage).
+    ///
+    /// O(count/15) storage reads. Only view surfaces need the whole curve —
+    /// a claim wants exactly one share, so it calls `get_custom_share_at`.
     fn get_custom_shares(self: @T, prize_id: u64) -> Array<u16>;
+    /// One share by 1-indexed position, without rebuilding the array.
+    ///
+    /// Mirrors `EntryFeeStoreTrait::get_custom_share_at`. Shares are packed
+    /// 15 to a felt, so this is a single storage read at any position.
+    fn get_custom_share_at(self: @T, prize_id: u64, position: u32) -> u16;
     /// Store a token prize. Takes the host-assigned context + sponsor
     /// alongside the variant payload; converts to StoredPrize for
     /// storage.
@@ -67,10 +75,19 @@ pub impl PrizeStoreImpl<T, +Store<T>, +Drop<T>> of PrizeStoreTrait<T> {
                             Option::Some(dist) => {
                                 match dist {
                                     game_components_utilities::distribution::structs::Distribution::Custom(_) => {
-                                        let shares = self.get_custom_shares(prize_id);
+                                        // Return the shape with an empty span
+                                        // rather than rebuilding the curve.
+                                        // Loading it is O(count/15) storage
+                                        // reads on a path that runs on every
+                                        // claim, and a claim needs exactly one
+                                        // share — `get_custom_share_at`.
+                                        // View surfaces call
+                                        // `get_custom_shares` explicitly.
+                                        // Mirrors the entry-fee store, which
+                                        // has always done this.
                                         Option::Some(
                                             game_components_utilities::distribution::structs::Distribution::Custom(
-                                                shares.span(),
+                                                array![].span(),
                                             ),
                                         )
                                     },
@@ -99,6 +116,13 @@ pub impl PrizeStoreImpl<T, +Store<T>, +Drop<T>> of PrizeStoreTrait<T> {
         record
     }
 
+    fn get_custom_share_at(self: @T, prize_id: u64, position: u32) -> u16 {
+        let index: u32 = position - 1;
+        let slot_index: u8 = (index / CUSTOM_SHARES_PER_SLOT.into()).try_into().unwrap();
+        let index_in_slot: u8 = (index % CUSTOM_SHARES_PER_SLOT.into()).try_into().unwrap();
+        Store::get_custom_shares_packed(self, prize_id, slot_index).get_share(index_in_slot)
+    }
+
     fn get_custom_shares(self: @T, prize_id: u64) -> Array<u16> {
         let count = Store::get_custom_shares_count(self, prize_id);
         let mut shares = ArrayTrait::new();

packages/metagame/src/prize/structs.cairo

@@ -16,6 +16,7 @@ use starknet::storage_access::StorePacking;
 mod nz128 {
     pub const TWO_POW_8: NonZero<u128> = 0x100;
     pub const TWO_POW_16: NonZero<u128> = 0x10000;
+    pub const TWO_POW_32: NonZero<u128> = 0x100000000;
 }
 
 // Payout type constants for storage
@@ -24,16 +25,21 @@ pub const PAYOUT_TYPE_LINEAR: u8 = 1;
 pub const PAYOUT_TYPE_EXPONENTIAL: u8 = 2;
 pub const PAYOUT_TYPE_UNIFORM: u8 = 3;
 pub const PAYOUT_TYPE_CUSTOM: u8 = 4;
+pub const PAYOUT_TYPE_GEOMETRIC: u8 = 5;
+pub const PAYOUT_TYPE_TIERED: u8 = 6;
 
 /// Internal packed representation for ERC20 data storage
-/// Layout: [amount: 128 bits][payout_type: 8 bits][param: 16 bits][count: 32 bits] = 184 bits
+/// Layout: [amount: 128 bits][payout_type: 8][param: 16][count: 32][param2: 16][param3: 16]
+/// = 216 bits. param2/param3 carry Tiered's head_count and head_share_bps; 0 otherwise.
 /// This is used internally by StorePacking and not exposed in the API
 #[derive(Copy, Drop)]
 struct PackedERC20Data {
     amount: u128,
     payout_type: u8,
     param: u16,
     count: u32,
+    param2: u16,
+    param3: u16,
 }
 
 /// u128-aligned StorePacking for PackedERC20Data.
@@ -53,7 +59,9 @@ impl PackedERC20DataPacking of StorePacking<PackedERC20Data, felt252> {
 
         let high: u128 = value.payout_type.into()
             + value.param.into() * 0x100_u128 // shift 8
-            + value.count.into() * 0x1000000_u128; // shift 24
+            + value.count.into() * 0x1000000_u128 // shift 24
+            + value.param2.into() * 0x100000000000000_u128 // shift 56
+            + value.param3.into() * 0x1000000000000000000_u128; // shift 72
 
         let packed = u256 { low, high };
         packed.try_into().unwrap()
@@ -66,13 +74,17 @@ impl PackedERC20DataPacking of StorePacking<PackedERC20Data, felt252> {
 
         let high = packed.high;
         let (hi, payout_type) = DivRem::div_rem(high, nz128::TWO_POW_8);
-        let (count, param) = DivRem::div_rem(hi, nz128::TWO_POW_16);
+        let (hi2, param) = DivRem::div_rem(hi, nz128::TWO_POW_16);
+        let (hi3, count) = DivRem::div_rem(hi2, nz128::TWO_POW_32);
+        let (param3, param2) = DivRem::div_rem(hi3, nz128::TWO_POW_16);
 
         PackedERC20Data {
             amount,
             payout_type: payout_type.try_into().unwrap(),
             param: param.try_into().unwrap(),
             count: count.try_into().unwrap(),
+            param2: param2.try_into().unwrap(),
+            param3: param3.try_into().unwrap(),
         }
     }
 }
@@ -115,30 +127,39 @@ fn pack_token_type(token_type: TokenTypeData) -> PackedTokenTypeData {
     match token_type {
         TokenTypeData::erc20(erc20_data) => {
             // Convert ERC20Data to packed format
-            let (payout_type, param) = match erc20_data.distribution {
-                Option::None => (PAYOUT_TYPE_POSITION, 0_u16),
+            let (payout_type, param, param2, param3) = match erc20_data.distribution {
+                Option::None => (PAYOUT_TYPE_POSITION, 0_u16, 0_u16, 0_u16),
                 Option::Some(dist) => {
                     match dist {
                         game_components_utilities::distribution::structs::Distribution::Linear(w) => (
-                            PAYOUT_TYPE_LINEAR, w,
+                            PAYOUT_TYPE_LINEAR, w, 0_u16, 0_u16,
                         ),
                         game_components_utilities::distribution::structs::Distribution::Exponential(w) => (
-                            PAYOUT_TYPE_EXPONENTIAL, w,
+                            PAYOUT_TYPE_EXPONENTIAL, w, 0_u16, 0_u16,
                         ),
                         game_components_utilities::distribution::structs::Distribution::Uniform => (
-                            PAYOUT_TYPE_UNIFORM, 0_u16,
+                            PAYOUT_TYPE_UNIFORM, 0_u16, 0_u16, 0_u16,
                         ),
                         game_components_utilities::distribution::structs::Distribution::Custom(_) => (
-                            PAYOUT_TYPE_CUSTOM, 0_u16,
+                            PAYOUT_TYPE_CUSTOM, 0_u16, 0_u16, 0_u16,
                         ),
+                        game_components_utilities::distribution::structs::Distribution::Geometric((
+                            a, b,
+                        )) => (PAYOUT_TYPE_GEOMETRIC, a * 256 + b, 0_u16, 0_u16),
+                        game_components_utilities::distribution::structs::Distribution::Tiered(cfg) => {
+                            let (a, b) = cfg.head_ratio;
+                            (PAYOUT_TYPE_TIERED, a * 256 + b, cfg.head_count, cfg.head_share_bps)
+                        },
                     }
                 },
             };
             let count = match erc20_data.distribution_count {
                 Option::Some(c) => c,
                 Option::None => 0_u32,
             };
-            let packed = PackedERC20Data { amount: erc20_data.amount, payout_type, param, count };
+            let packed = PackedERC20Data {
+                amount: erc20_data.amount, payout_type, param, count, param2, param3,
+            };
             PackedTokenTypeData::erc20(PackedERC20DataPacking::pack(packed))
         },
         TokenTypeData::erc721(erc721_data) => PackedTokenTypeData::erc721(erc721_data),
@@ -170,6 +191,22 @@ fn unpack_token_type(packed_token_type: PackedTokenTypeData) -> TokenTypeData {
                 Option::Some(
                     game_components_utilities::distribution::structs::Distribution::Uniform,
                 )
+            } else if packed.payout_type == PAYOUT_TYPE_GEOMETRIC {
+                Option::Some(
+                    game_components_utilities::distribution::structs::Distribution::Geometric(
+                        (packed.param / 256, packed.param % 256),
+                    ),
+                )
+            } else if packed.payout_type == PAYOUT_TYPE_TIERED {
+                Option::Some(
+                    game_components_utilities::distribution::structs::Distribution::Tiered(
+                        game_components_utilities::distribution::structs::TieredConfig {
+                            head_ratio: (packed.param / 256, packed.param % 256),
+                            head_count: packed.param2,
+                            head_share_bps: packed.param3,
+                        },
+                    ),
+                )
             } else {
                 Option::Some(
                     game_components_utilities::distribution::structs::Distribution::Custom(
@@ -240,7 +277,7 @@ mod packed_erc20_data_tests {
     fn build_packed_erc20(
         amount: u128, payout_type: u8, param: u16, count: u32,
     ) -> PackedERC20Data {
-        PackedERC20Data { amount, payout_type, param, count }
+        PackedERC20Data { amount, payout_type, param, count, param2: 0, param3: 0 }
     }
 
     fn assert_roundtrip(data: PackedERC20Data) {
@@ -250,6 +287,21 @@ mod packed_erc20_data_tests {
         assert!(unpacked.payout_type == data.payout_type, "payout_type mismatch");
         assert!(unpacked.param == data.param, "param mismatch");
         assert!(unpacked.count == data.count, "count mismatch");
+        assert!(unpacked.param2 == data.param2, "param2 mismatch");
+        assert!(unpacked.param3 == data.param3, "param3 mismatch");
+    }
+
+    #[test]
+    fn test_tiered_params_roundtrip_in_the_widened_slots() {
+        let data = PackedERC20Data {
+            amount: 0xffffffffffffffffffffffffffffffff, // u128::MAX alongside full params
+            payout_type: 6,
+            param: 10 * 256 + 7,
+            count: 10000,
+            param2: 39,
+            param3: 8000,
+        };
+        assert_roundtrip(data);
     }
 
     // -------------------------------------------------------------------------

packages/metagame/src/prize/tests/mocks/prize_mock.cairo

@@ -131,6 +131,12 @@ pub mod PrizeMock {
         self.prize._get_custom_shares(prize_id)
     }
 
+    /// One custom share by 1-indexed position, without rebuilding the array
+    #[external(v0)]
+    fn get_custom_share_at(self: @ContractState, prize_id: u64, position: u32) -> u16 {
+        self.prize._get_custom_share_at(prize_id, position)
+    }
+
     /// Get extension address for a context and prize
     #[external(v0)]
     fn get_extension_address(