builder-stake: size the deposit against the committed rate (#4285)

Implements [B2](malbeclabs/edge-builder#9).
Stacked on #4284; review that first, this diff is the six files above
the base.

## Summary

- `ProgramConfig` gains a tier table: three 2Z amounts, one per RFC-28
rate tier, set by the admin through `ConfigureProgram`.
- `InitializeBuilderStake` looks up the amount for the rate the builder
commits to and pins it on the stake as `required_2z_amount`.
- `BuilderStake::is_funded()` answers whether the stake holds what it
owes.
- A malformed table is refused: a zero amount, or a higher tier that
costs less than a lower one.

## Decisions worth arguing with

**A table, not a price feed.** RFC-28 quotes about \$100k / \$200k /
\$500k but says the deposit is "denominated in 2Z, fixed at the price
prevailing when the tier is set". So an admin writes three numbers and
no oracle is involved.

**The rate ceilings are compiled in, not configured.** 1 Gbps and 5 Gbps
have to agree with `StakeTier::max_rate_bits_per_sec` in the
serviceability program on the DZ ledger. If those two drift, a builder
funds one tier here and its feed is checked against a different one
there. Two configurable copies is exactly how that drift happens.

**The requirement is pinned per stake, not read live.** Repricing a tier
does not move what an existing stake owes, so a builder who fully funded
a stake cannot wake up under-funded because the admin changed a number.
This is the stronger reading of "fixed at the price prevailing when the
tier is set", and it is one field. There is a test for it.

**`Deposit` still accepts any positive amount, which is a departure from
how issue #9 was written.** Requiring the full amount in one transfer
would make "a stake exists implies it is funded" true, which is
tempting. Against it: a builder may reasonably fund from more than one
source or split a large transfer, and nothing bad happens with a short
stake, because only a funded stake gets mirrored to the DZ ledger and so
a short one backs no feed. The guard that actually matters is `Withdraw`
in [B3](malbeclabs/edge-builder#10), which
must not drop a stake below its requirement regardless. Over-funding is
allowed too, since RFC-28 lets a builder withdraw the excess after the
hold.

**An unset table sizes nothing rather than sizing everything at zero.**
`required_2z_amount` returns `None` for a zero entry, so a program
unpaused before it was configured takes no stake instead of handing out
free ones.

## Struct change

`BuilderStake` grew `required_2z_amount`, so its size assertion moves
from 136 to 144. Nothing is deployed, so there is no migration. I also
dropped the `ProgramConfig` size assertion: it is allocated at 10kb, so
a new setting grows into slack, which is the same reasoning
`revenue-distribution` gives.

## Testing Verification

`make test-sbf`, 16 tests (3 unit, 12 integration, plus the id check):

- Every tier boundary, at and either side of each ceiling: 1 Gbps and
one unit over, 5 Gbps and one unit over, and `u64::MAX`.
- A stake starts unfunded, two part-deposits reach the requirement with
the last unit tipping it over, and over-funding is accepted.
- An unpaused program with no tier table refuses to take a stake at all.
- Three malformed tables are refused (a hole at the first tier, 5 Gbps
cheaper than 1 Gbps, unmetered cheaper than 5 Gbps), and a well-formed
one lands and reads back.
- Raising every tier tenfold leaves an existing funded stake funded and
its requirement unchanged, while the next stake posted pays the new
price.
- The seven B1 tests still pass unchanged.

## Size

About 90 non-test lines.

Author: bgm-malbeclabs

CHANGELOG.md

@@ -19,6 +19,7 @@ All notable changes to this project will be documented in this file.
   - The TypeScript and Python `Feed` deserializers read the RFC-28 tail and synthesize `Active` for an account that carries no status byte, matching the Rust program. New `feed_legacy` fixture covers that path alongside the updated `feed` fixture.
 - Solana programs (`solana/`)
   - New `builder-stake` program at `dzbschFChpPoWihZFdnYjyzHJicZwPHb6QTntHjhLki`, holding the 2Z bond a builder posts before deploying a feed under RFC-28. A `BuilderStake` PDA, a 2Z token account owned by it, and `InitializeProgram`, `SetAdmin`, `ConfigureProgram`, `InitializeBuilderStake` and `PostBond`. A bond rather than a deposit: it is returnable after the hold and forfeitable by slashing, and `deposit` carries neither. The address is keyed on `(builder, stake_index)` rather than the builder alone, because RFC-28 collateralizes each feed on its own bond and a builder-only address would cap a builder at one stake for life. The program starts paused, so a deployment with no admin and no tier table holds nothing. No slash instruction yet: the burn authority is what makes this its own deployable, and writing it before the verdict signer is settled means writing it twice. Bond sizing and the six-month hold are not here either.
+  - `builder-stake` sizes a bond against the rate its feed commits to. An admin sets three 2Z amounts, one per RFC-28 rate tier; RFC-28 quotes the tiers in dollars but fixes the bond in 2Z at the price prevailing when the tier is set, so this is a table rather than a price feed. The rate ceilings are compiled in, because they have to agree with `StakeTier` in the serviceability program. A stake's requirement follows the tier table while the stake is short and stops moving once it is funded, so repricing cannot under-fund a builder who already paid in full, and cannot be dodged by pre-creating stakes for the cost of rent and funding them after a rise. A table with a hole, or one where more rate costs less, is refused.
 
 ## [v0.39.0](https://github.com/malbeclabs/doublezero/compare/client/v0.38.0...client/v0.39.0) - 2026-09-04
 

solana/programs/builder-stake/src/instruction/mod.rs

@@ -4,6 +4,14 @@ use solana_pubkey::Pubkey;
 #[derive(Debug, BorshDeserialize, BorshSerialize, Clone, PartialEq, Eq)]
 pub enum ProgramConfiguration {
     Flag(ProgramFlagConfiguration),
+
+    /// The 2Z a bond costs at each rate tier. All three must be non-zero and must not decrease
+    /// as the rate rises.
+    TierParameters {
+        up_to_1gbps_2z_amount: u64,
+        up_to_5gbps_2z_amount: u64,
+        unmetered_2z_amount: u64,
+    },
 }
 
 #[derive(Debug, BorshDeserialize, BorshSerialize, Clone, PartialEq, Eq)]
@@ -28,8 +36,8 @@ pub enum BuilderStakeInstructionData {
     ///
     /// `stake_index` distinguishes a builder's stakes from each other and is part of the address,
     /// so creating the same index twice fails. `committed_rate_bits_per_sec` is the rate the feed
-    /// backed by this stake may commit to. It is recorded here and nothing acts on it yet:
-    /// `PostBond` takes any positive amount. Sizing the bond against the rate is B2.
+    /// backed by this stake may commit to. It selects the tier, and the tier sets the bond this
+    /// stake has to hold, pinned on the account as `required_2z_amount`.
     InitializeBuilderStake {
         stake_index: u64,
         committed_rate_bits_per_sec: u64,

solana/programs/builder-stake/src/processor.rs

@@ -21,13 +21,15 @@ use spl_token_interface::instruction as token_instruction;
 
 use crate::{
     instruction::{BuilderStakeInstructionData, ProgramConfiguration, ProgramFlagConfiguration},
-    state::{self, BuilderStake, ProgramConfig},
+    state::{self, BuilderStake, ProgramConfig, TierParameters},
     DOUBLEZERO_MINT_KEY, ID,
 };
 
 // A change to either size means every deployed account of that type has to be migrated, so make
-// the change deliberate rather than incidental.
-const _: () = assert!(size_of::<BuilderStake>() == 136);
+// the change deliberate rather than incidental. The program config is allocated at 10kb and so
+// never needs a realloc, but its check is what catches a new setting that overruns the storage gap
+// instead of coming out of it.
+const _: () = assert!(size_of::<BuilderStake>() == 144);
 const _: () = assert!(size_of::<ProgramConfig>() == 176);
 
 solana_program_entrypoint::entrypoint!(try_process_instruction);
@@ -160,6 +162,37 @@ fn try_configure_program(accounts: &[AccountInfo], setting: ProgramConfiguration
             msg!("is_paused: {}", paused);
             program_config.set_is_paused(paused);
         }
+        ProgramConfiguration::TierParameters {
+            up_to_1gbps_2z_amount,
+            up_to_5gbps_2z_amount,
+            unmetered_2z_amount,
+        } => {
+            let tier_parameters = TierParameters::new(
+                up_to_1gbps_2z_amount,
+                up_to_5gbps_2z_amount,
+                unmetered_2z_amount,
+            );
+
+            // A table with a hole or a cheaper high tier is a mistake that would let a builder
+            // deploy a fast feed against a small bond, so it never reaches the account.
+            if !tier_parameters.is_well_formed() {
+                msg!(
+                    "Tier amounts must be non-zero and must not decrease: {}, {}, {}",
+                    up_to_1gbps_2z_amount,
+                    up_to_5gbps_2z_amount,
+                    unmetered_2z_amount
+                );
+                return Err(ProgramError::InvalidInstructionData);
+            }
+
+            msg!(
+                "tier_parameters: {}, {}, {}",
+                up_to_1gbps_2z_amount,
+                up_to_5gbps_2z_amount,
+                unmetered_2z_amount
+            );
+            program_config.tier_parameters = tier_parameters;
+        }
     }
 
     Ok(())
@@ -193,6 +226,19 @@ fn try_initialize_builder_stake(
         ZeroCopyAccount::<ProgramConfig>::try_next_accounts(&mut accounts_iter, Some(&ID))?;
     program_config.try_require_unpaused()?;
 
+    // Size the bond before creating anything. An unset tier table sizes nothing, so a program
+    // that was unpaused before it was configured takes no stake rather than a free one.
+    let required_2z_amount = program_config
+        .tier_parameters
+        .required_2z_amount(committed_rate_bits_per_sec)
+        .ok_or_else(|| {
+            msg!(
+                "No tier amount configured for {} bits/sec",
+                committed_rate_bits_per_sec
+            );
+            ProgramError::InvalidAccountData
+        })?;
+
     // Account 1 funds both new accounts and is the builder the stake belongs to. The
     // create-account workflow requires it to be a writable signer.
     let (account_index, builder_info) =
@@ -270,14 +316,16 @@ fn try_initialize_builder_stake(
     builder_stake.builder = *builder_info.key;
     builder_stake.stake_index = stake_index;
     builder_stake.committed_rate_bits_per_sec = committed_rate_bits_per_sec;
+    builder_stake.required_2z_amount = required_2z_amount;
     builder_stake.bump_seed = builder_stake_bump;
     builder_stake.token_account_bump_seed = token_account_bump;
 
     msg!(
-        "Builder {} stake {} committed to {} bits/sec",
+        "Builder {} stake {} committed to {} bits/sec, requires {} 2Z",
         builder_info.key,
         stake_index,
-        committed_rate_bits_per_sec
+        committed_rate_bits_per_sec,
+        required_2z_amount
     );
 
     Ok(())
@@ -323,6 +371,25 @@ fn try_post_bond(accounts: &[AccountInfo], amount: u64) -> ProgramResult {
         return Err(ProgramError::IncorrectAuthority);
     }
 
+    // A stake that is still short is held to the current tier table, not the one that was live
+    // when it was created. Creating a stake is permissionless and costs only rent, so pinning the
+    // requirement at creation would let a builder bank today's price in bulk and fund years later
+    // at a price a repricing was meant to replace. Once a stake is funded the requirement stops
+    // moving, so a builder who paid in full cannot be made short by a later change.
+    if !builder_stake.is_funded() {
+        let committed_rate_bits_per_sec = builder_stake.committed_rate_bits_per_sec;
+        builder_stake.required_2z_amount = program_config
+            .tier_parameters
+            .required_2z_amount(committed_rate_bits_per_sec)
+            .ok_or_else(|| {
+                msg!(
+                    "No tier amount configured for {} bits/sec",
+                    committed_rate_bits_per_sec
+                );
+                ProgramError::InvalidAccountData
+            })?;
+    }
+
     // Account 3 must be this stake's 2Z token account. Checked against the cached bump so a
     // caller cannot redirect the bond to another account.
     let (_, stake_token_account_info, _) = try_next_2z_token_pda_info(
@@ -356,10 +423,17 @@ fn try_post_bond(accounts: &[AccountInfo], amount: u64) -> ProgramResult {
     // otherwise leave the two disagreeing forever.
     builder_stake.bonded_2z_amount = try_token_account_amount(stake_token_account_info)?;
 
+    // Bonds accumulate rather than having to arrive in one transfer, so a stake can be short
+    // of its requirement. Nothing here refuses that: `Withdraw` is what must not drop a stake
+    // below its requirement, and only a funded stake is mirrored to the DZ ledger, so a short one
+    // backs no feed.
+
     msg!(
-        "Posted {} 2Z, stake now holds {}",
+        "Posted {} 2Z, stake now holds {} of {} required (funded: {})",
         amount,
-        builder_stake.bonded_2z_amount
+        builder_stake.bonded_2z_amount,
+        builder_stake.required_2z_amount,
+        builder_stake.is_funded()
     );
 
     Ok(())

solana/programs/builder-stake/src/state/builder_stake.rs

@@ -27,6 +27,15 @@ pub struct BuilderStake {
     /// 2Z held in this stake's token account, in the mint's smallest unit.
     pub bonded_2z_amount: u64,
 
+    /// What this stake has to hold for its committed rate.
+    ///
+    /// Follows the tier table while the stake is short, and stops moving once the stake is funded.
+    /// Both halves matter. Freezing it at creation would let a builder pre-create stakes for the
+    /// cost of rent and fund them after a repricing at the old price. Never freezing it would let
+    /// a repricing make a builder short after it had already paid in full, which RFC-28's "fixed
+    /// at the price prevailing when the tier is set" rules out.
+    pub required_2z_amount: u64,
+
     /// The rate the feed backed by this stake may commit to, in bits per second. `u64::MAX` is the
     /// unmetered tier. Bits per second, not basis points: `bps` means basis points elsewhere in
     /// DoubleZero.
@@ -68,6 +77,12 @@ impl BuilderStake {
         )
     }
 
+    /// Whether this stake holds what its committed rate requires. A stake that is not funded backs
+    /// no feed: nothing mirrors it to the DZ ledger, so no feed can be created against it.
+    pub fn is_funded(&self) -> bool {
+        self.bonded_2z_amount >= self.required_2z_amount
+    }
+
     pub fn checked_address(builder: &Pubkey, stake_index: u64, bump_seed: u8) -> Option<Pubkey> {
         Pubkey::create_program_address(
             &[

solana/programs/builder-stake/src/state/mod.rs

@@ -1,8 +1,10 @@
 mod builder_stake;
 mod program_config;
+mod tier_parameters;
 
 pub use builder_stake::*;
 pub use program_config::*;
+pub use tier_parameters::*;
 
 //
 

solana/programs/builder-stake/src/state/program_config.rs

@@ -7,6 +7,8 @@ use solana_msg::msg;
 use solana_program_error::{ProgramError, ProgramResult};
 use solana_pubkey::Pubkey;
 
+use super::TierParameters;
+
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Pod, Zeroable)]
 #[repr(C, align(8))]
 pub struct ProgramConfig {
@@ -19,7 +21,11 @@ pub struct ProgramConfig {
 
     _padding: [u8; 7],
 
-    _storage_gap: StorageGap<4>,
+    /// What a bond costs at each rate tier. Zero until an admin sets it, which is why a fresh
+    /// deployment starts paused: it can size no bond.
+    pub tier_parameters: TierParameters,
+
+    _storage_gap: StorageGap<3>,
 }
 
 impl PrecomputedDiscriminator for ProgramConfig {

solana/programs/builder-stake/src/state/tier_parameters.rs

@@ -0,0 +1,104 @@
+use bytemuck::{Pod, Zeroable};
+
+/// What a bond costs at each RFC-28 rate tier, in the 2Z mint's smallest unit.
+///
+/// RFC-28 quotes the tiers in dollars (about $100k, $200k and $500k) but fixes the bond "in 2Z,
+/// at the price prevailing when the tier is set". So these are 2Z amounts an admin sets, not a
+/// price feed this program reads.
+///
+/// The rate ceilings are compiled in rather than configured, because they have to agree with
+/// `StakeTier::max_rate_bits_per_sec` in the serviceability program on the DZ ledger. If those two
+/// disagree, a builder funds one tier here and a feed is checked against another there.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Pod, Zeroable)]
+#[repr(C, align(8))]
+pub struct TierParameters {
+    pub up_to_1gbps_2z_amount: u64,
+    pub up_to_5gbps_2z_amount: u64,
+    pub unmetered_2z_amount: u64,
+
+    _padding: [u8; 8],
+}
+
+impl TierParameters {
+    /// Decimal Gbps, as everywhere a link rate is quoted.
+    pub const UP_TO_1GBPS_BITS_PER_SEC: u64 = 1_000_000_000;
+    pub const UP_TO_5GBPS_BITS_PER_SEC: u64 = 5_000_000_000;
+
+    pub fn new(
+        up_to_1gbps_2z_amount: u64,
+        up_to_5gbps_2z_amount: u64,
+        unmetered_2z_amount: u64,
+    ) -> Self {
+        Self {
+            up_to_1gbps_2z_amount,
+            up_to_5gbps_2z_amount,
+            unmetered_2z_amount,
+            _padding: Default::default(),
+        }
+    }
+
+    /// The bond a feed committing to `rate_bits_per_sec` must post.
+    ///
+    /// `None` when this table has no amount for that tier. That is an unset table, not a free
+    /// tier: a zero requirement would let a builder deploy a feed against nothing.
+    pub fn required_2z_amount(&self, rate_bits_per_sec: u64) -> Option<u64> {
+        let amount = if rate_bits_per_sec <= Self::UP_TO_1GBPS_BITS_PER_SEC {
+            self.up_to_1gbps_2z_amount
+        } else if rate_bits_per_sec <= Self::UP_TO_5GBPS_BITS_PER_SEC {
+            self.up_to_5gbps_2z_amount
+        } else {
+            self.unmetered_2z_amount
+        };
+
+        (amount != 0).then_some(amount)
+    }
+
+    /// Whether this table can size every tier, and costs more for more rate.
+    ///
+    /// A cheaper higher tier is always a mistake: every builder would buy the cheap tier and
+    /// commit to the higher rate.
+    pub fn is_well_formed(&self) -> bool {
+        self.up_to_1gbps_2z_amount != 0
+            && self.up_to_1gbps_2z_amount <= self.up_to_5gbps_2z_amount
+            && self.up_to_5gbps_2z_amount <= self.unmetered_2z_amount
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The tier a rate falls into, at and either side of each ceiling.
+    #[test]
+    fn test_rate_selects_its_tier() {
+        let tiers = TierParameters::new(100, 200, 500);
+
+        assert_eq!(tiers.required_2z_amount(1), Some(100));
+        assert_eq!(tiers.required_2z_amount(1_000_000_000), Some(100));
+        assert_eq!(tiers.required_2z_amount(1_000_000_001), Some(200));
+        assert_eq!(tiers.required_2z_amount(5_000_000_000), Some(200));
+        assert_eq!(tiers.required_2z_amount(5_000_000_001), Some(500));
+        assert_eq!(tiers.required_2z_amount(u64::MAX), Some(500));
+    }
+
+    /// An unset table sizes nothing, rather than sizing everything at zero.
+    #[test]
+    fn test_unset_table_sizes_nothing() {
+        let tiers = TierParameters::default();
+
+        assert_eq!(tiers.required_2z_amount(1), None);
+        assert_eq!(tiers.required_2z_amount(u64::MAX), None);
+        assert!(!tiers.is_well_formed());
+    }
+
+    #[test]
+    fn test_well_formed_requires_non_decreasing_amounts() {
+        assert!(TierParameters::new(100, 200, 500).is_well_formed());
+        // Equal amounts are odd but not wrong; the tiers just cost the same.
+        assert!(TierParameters::new(100, 100, 100).is_well_formed());
+
+        assert!(!TierParameters::new(0, 200, 500).is_well_formed());
+        assert!(!TierParameters::new(300, 200, 500).is_well_formed());
+        assert!(!TierParameters::new(100, 600, 500).is_well_formed());
+    }
+}