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

packages/interfaces/src/distribution.cairo

@@ -1,7 +1,92 @@
+/// How a pool is split across paid places.
+///
+/// ## This enum is closed — do not add variants
+///
+/// The shape space is covered: flat (`Uniform`), linear, polynomial
+/// (`Exponential`), scale-free decay (`Geometric`), headline-plus-tail
+/// (`Tiered`), and arbitrary (`Custom`). Before reaching for variant #7:
+///
+/// - **A shape these can't express, with a fixed field?** Use `Custom` — it
+///   encodes any curve exactly, up to its packed-storage ceiling. That is the
+///   escape hatch; it removes the need for the enum to grow.
+/// - **Anything involving external state** — dynamic payouts, oracle-driven
+///   amounts, streaming, vesting? That is an integration, not a curve: use a
+///   prize/entry-fee *extension*, which exists precisely for logic the host
+///   cannot know about.
+///
+/// Every variant added here ripples through Serde (events, calldata,
+/// indexers, SDKs, clients) and two packed-storage layouts, and costs
+/// consumer-contract bytecode against Starknet's 81,920-felt class limit —
+/// adding `Geometric` + `Tiered` cost Budokan ~3,000 felts, leaving it ~95%
+/// full. Curves are core; integrations are extensions.
+///
+/// ## Choosing a variant
+///
+/// | you want | use | notes |
+/// | --- | --- | --- |
+/// | everyone equal | `Uniform` | cheapest |
+/// | gentle gradient | `Linear(w)` | any weight |
+/// | steeper gradient, small field | `Exponential(10*k)` | k in 1..=5; 1st ≈ (k+1)/n |
+/// | "each place gets X% of the one above" | `Geometric(a, b)` | 1st ≈ 1 - b/a at any field size;
+/// reach bounded by ratio |
+/// | headline 1st prize AND thousands of paid places | `Tiered` | the only variant that serves a
+/// very large field |
+/// | exact hand-authored percentages | `Custom(shares)` | fixed field only |
 #[derive(Drop, Copy, Serde, PartialEq)]
 pub enum Distribution {
     Linear: u16,
     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,32 @@ 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,
+                )) => {
+                    // The two ratio terms share one u16 param slot as
+                    // a*256 + b. Values past 255 would either panic on the
+                    // u16 multiply or unpack as a silently different ratio,
+                    // so the bound is owned here, not left to the host.
+                    assert!(
+                        *a <= 255 && *b <= 255, "EntryFee: geometric ratio terms must fit 8 bits",
+                    );
+                    (DIST_TYPE_GEOMETRIC, *a * 256 + *b, 0_u16, 0_u16)
+                },
+                Distribution::Tiered(cfg) => {
+                    let (a, b) = *cfg.head_ratio;
+                    assert!(
+                        a <= 255 && b <= 255, "EntryFee: geometric ratio terms must fit 8 bits",
+                    );
+                    (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 +278,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();