Ctrlk

SAM Resources

Dashboards, repositories, APIs, and technical reference for SAM participants.

TL;DR: One-stop reference page. Dashboards, repositories, audits, key contract addresses, the parameters at a glance for production config, and the glossary of SAM terms.

Overview

A single landing page for the tools, dashboards, repositories, and reference data validators and stakers use to interact with the Stake Auction Marketplace. Bookmark this page for quick navigation.

Dashboards

Web interfaces for monitoring SAM and validator activity.

CLI and SDKs

Tools for programmatic interaction with the validator bonds program and Marinade APIs.

Repositories

Source code for the SAM pipeline and supporting infrastructure.

  • validator-bonds: Monorepository for the on-chain bonds program, CLI, SDK, and supporting tools.

  • ds-sam: PSR and SAM scoring logic.

  • ds-sam-pipeline: Pipeline orchestration for PSR and SAM scoring runs. Each epoch's auction inputs and outputs are committed under auctions/<epoch>/.

  • psr-dashboard: Source for the PSR dashboard.

APIs

Data endpoints for monitoring and integration.

  • Delegation Strategy API: Public API for validator metadata, geolocation, scoring, and SAM-relevant performance data.

  • Snapshots API: Per-epoch snapshots of stake, MNDE Enhanced Stake support, and validator state.

  • Marinade Stats API: Aggregate protocol statistics.

  • Bonds API: Current state of bond accounts. Updated once per hour.

Data Sources

Raw data published per epoch.

Technical Reference

Addresses, identifiers, and operational parameters.

  • Validator Bonds program address: vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4

  • Marinade Validator Bonds config account: vbMaRfmTCg92HWGzmd53APkMNpPnGVGZTUHwUJQkXAU

  • Bonds Select config address: VbinSTyUEC8JXtzFteC4ruKSfs6dkQUUcY6wB1oJyjE

  • Validator Bonds Stake Account Withdrawer authority: 8CsAFqTh75jtiYGjTXxCUbWEurQcupNknuYTiaZPhzz3

  • Native Staking Select Staker authority: STNi1NHDUi6Hvibvonawgze8fM83PFLeJhuGMEXyGps

  • Geolocation provider: ipwhois. Validator data center identification refreshed every 24 hours.

  • Pipeline scoring cadence: Once per epoch. Stake rebalancing actions are dispatched at epoch boundary.

  • Solana epoch duration: Approximately 2 days.

Audits

Third-party security reviews.

Parameters at a Glance

Operational parameters governing SAM auction mechanics, bond requirements, eligibility, and notifications. Values reflect production configuration at the time of writing.

Source of truth: Live values are maintained in the following sources. If the values below appear stale, check the source files directly.

Auction and Decentralization

Parameter
Value
Description

Per-validator TVL cap

15%

Maximum portion of Marinade TVL any single validator can hold. Introduced in MIP-19, live from epoch 946. See Stake Distribution.

ASO concentration cap

30%

Maximum portion of Solana's total network stake that can be allocated to validators in a single ASO.

Country concentration cap

40%

Maximum portion of Solana's total network stake that can be allocated to validators in a single country.

Rebalance baseline

~1% per epoch

Approximate share of Marinade's total TVL rebalanced under normal conditions. Configurable in the pipeline; subject to adjustment.

Effective inflation commission limit

7%

Maximum effective commission to Marinade stakers before eligibility is lost. See Eligibility Criteria.

Stake Matching

Parameter
Value
Description

unprotectedDelegatedStakeDec

0.1 (10%)

Match rate on non-SFDP external stake.

unprotectedFoundationStakeDec

0.3 (30%)

Match rate on SFDP / Solana Foundation stake.

minUnprotectedStakeToDelegateSol

1,000 SOL

Minimum calculated match. Matches below this collapse to zero.

Per-validator matching cap

0.4% of Marinade TVL

Maximum matched stake per validator. Separate from the 15% per-validator direct SAM cap. See Stake Matching.

maxStakeWanted

Parameter
Value
Description

minMaxStakeWanted

10,000 SOL

Floor on the effective cap. Setting maxStakeWanted below this has no effect. See maxStakeWanted Parameter.

Bid Reduction Penalty

Parameter
Value
Description

historyEpochs

3

Lookback window in epochs used to compute the historical floor.

permittedBidDeviation

0.01 (1%)

Buffer below the floor in which bid reductions do not incur a penalty. See Bid Reduction Penalty.

Bond Risk Reduction Mechanism

Parameter
Value
Description

minBondEpochs

4 future epochs

Minimum bond coverage required to avoid the fee (5 epochs total including the current epoch).

idealBondEpochs

12 future epochs

Target bond coverage to remain eligible for new stake (13 epochs total).

bondObligationSafetyMult

1.1

Safety multiplier (10% margin) applied to all bond obligation calculations.

minBondBalanceSol

7 SOL

Minimum bond balance before complete undelegation occurs.

bondRiskFeeMult

Governance-adjustable

Multiplier on the fee calculation. Subject to change by governance. See Bond Risk Reduction Mechanism.

Bonds Settlements

Parameter
Value
Description

epochsToClaimSettlement

3 epochs

Claim window for validators to dispute or claim a settlement before it finalizes.

Bond Notifications

Parameter
Value
Description

Underfunding critical threshold

< 2 epochs of coverage

Triggers a critical alert.

Underfunding warning threshold

< 10 epochs of coverage

Triggers a warning alert.

Minimum deficit to notify

0.5 SOL

Deficits below this threshold do not trigger a notification.

Re-alert cadence

Max once per 24 hours

Notifications for persistent conditions only refire if the condition changes significantly. See Bond Notifications.

Eligibility and Blacklist

Parameter
Value
Description

Uptime threshold

80% of expected blocks produced

Validators below this threshold lose eligibility.

MEV sandwich attack threshold

30% of blocks produced

Validators above this threshold are blacklisted. See Blacklist Policy.

Bond minimum (for downtime)

1 SOL per 10,000 SOL of stake

Covers one epoch of PSR-style downtime.

Timing and Cadence

Parameter
Value
Description

Solana epoch duration

~2 days

Native time unit on Solana. All SAM mechanisms operate on per-epoch cycles.

ASO data refresh cadence

24 hours

Geolocation data is refreshed daily via the ipwhois provider.

Bonds API update cadence

1 hour

The Bonds API refreshes once per hour. Use the CLI for real-time bond state.

PSR dashboard refresh

Every few hours

Web dashboards refresh on a delay. Always cross-check with the CLI for real-time values.

Pipeline scoring cadence

Once per epoch

Stake rebalancing actions are dispatched at the epoch boundary.

Glossary

Definitions for terms used across SAM documentation. Includes acronyms, units, code-name synonyms, and shorthand. Alphabetical.

Units at a Glance

A quick reference for the unit conventions used across the CLI, dashboards, and configuration files. Mixing these up is the most common cause of misconfiguration.

Concept
Unit
Example

Bond balance and settlement amounts

SOL

25 SOL

Lamports (Solana base unit)

1 SOL = 1,000,000,000 lamports

25 SOL = 25,000,000,000 lamports

CPMPE (--cpmpe)

lamports

100,000,000 lamports = 0.1 SOL per 1,000 SOL per epoch

--max-stake-wanted

lamports

25,000 SOL = 25,000,000,000,000 lamports

Dynamic commission (--inflation-commission, --mev-commission, --block-commission)

basis points (bps)

10,000 bps = 100%

PMPE and CPMPE display on dashboards

SOL per 1,000 SOL per epoch

0.1

Terms

  • Activating stake: Stake that Marinade has just delegated to a validator in the current epoch but is not yet earning rewards. Appears as activating in one epoch's snapshot, then transitions to active in the next. Triggers the Activating Stake Fee.

  • Active stake (Marinade): The portion of a validator's total stake that originated from Marinade and is currently earning rewards (not activating or deactivating). Bids in SAM are charged against active Marinade stake each epoch.

  • auctionEffectiveBidPmpe: Source-code name for the Effective Bid. Used in auction outputs and pipeline data. See also effBid.

  • ASO (Autonomous System Organization): The data center or hosting provider a validator runs on, identified by ASN. Marinade enforces a 30% cap on ASO concentration in Stake Distribution. ASO data is refreshed every 24 hours via the ipwhois geolocation provider.

  • Activating Stake Fee: One-time fee charged when new stake activates on a validator. Scaled by how far the validator bid above the auction clearing rate. See Activating Stake Fee.

  • Bid Reduction Penalty: Penalty charged when a validator lowers their static bid (bidPmpe) after winning stake. Internal name bidTooLowPenalty. See Bid Reduction Penalty.

  • bidPmpe: The validator's configured static bid in PMPE form. The CLI accepts this value in lamports as --cpmpe.

  • Bond: On-chain account collateralizing a validator's participation in SAM. Funded in SOL. Covers obligations like PSR settlements, auction bid costs, and downtime protection. Managed via the validator bonds CLI.

  • bondGoodForNEpochs: Field exposed in SAM auction output indicating how many epochs of revenue the validator's bond can cover. Shifted so that zero marks the fee threshold for the Bond Risk Reduction Mechanism: positive means headroom, negative means a fee is due this epoch.

  • bondObligationPmpe: Total per-1,000-SOL-per-epoch obligation a validator must pay from their bond. Includes static bid, block rewards, and inflation/MEV commission difference.

  • bondObligationSafetyMult: Multiplier (1.1 in production) applied to all bond obligation calculations as a 10% safety margin before comparison against the actual bond balance.

  • Bond Risk Reduction Mechanism: Mechanism that undelegates stake and charges a fee from the bond when bond coverage falls below the minimum threshold. See Bond Risk Reduction Mechanism.

  • bps (basis points): Unit for dynamic commission parameters. 10,000 bps = 100%. A value of 0 bps = 0%. See Dynamic Bids.

  • Claimable bond: The portion of a validator's bond not committed to pending withdrawals. Only the claimable portion counts toward bond coverage calculations.

  • CPMPE (cost per 1,000 SOL of delegated stake per epoch): A fixed lamport cost a validator commits to pay per 1,000 SOL of delegated stake, per epoch. Set in the CLI as --cpmpe. The static portion of a SAM bid.

  • Dynamic commission: Commission parameters set in the validator bonds CLI (--inflation-commission, --mev-commission, --block-commission) in basis points. Determines how rewards are split between the validator and stakers. See Dynamic Bids.

  • effBid / Effective Bid: The realized yield for an epoch, in lamports per 1,000 SOL, set by the auction's last-price model. Typically lower than the validator's configured bid. Source-code name auctionEffectiveBidPmpe. See Bonds Settlements.

  • effParticipatingBidPmpe: The minimum bid required to remain in the winning set this epoch. Calculated from the auction-winning total pmpe minus the validator's post-commission on-chain rewards (max(0, winningTotalPmpe - onchainDistributedPmpe)). Does not depend on the validator's own static bid. Used as the floor in the Bid Reduction Penalty calculation.

  • expectedMaxEffBidPmpe: The maximum Effective Bid expected for a validator. Used by the Bond Risk Reduction Mechanism to size required bond coverage. Can never exceed the validator's own bid.

  • External stake: Stake delegated to a validator that did not originate from Marinade and does not come from the validator's own self-stake (retail, SFDP, other LSTs, etc.). See Stake Matching.

  • idealBondEpochs: Source-config parameter (12 in production) for the target bond coverage in future epochs. Combined with the current epoch this represents the recommended 13-epoch operational target.

  • Lamports: Base unit of SOL. 1 SOL = 1,000,000,000 lamports. CLI flags such as --cpmpe and --max-stake-wanted take values in lamports.

  • Last-price auction: The auction model used by SAM. Validators are ranked by max_yield and stake is allocated top-down. The Effective Bid for the epoch is set to the max_yield of the last validator on the winning list, and all winners are charged at that lower rate.

  • max_yield: The maximum yield a validator offers to stakers at a given stake level. Combines the validator's commission and any bid placed through SAM. Used as the ranking metric in the auction. Source-code synonym: totalPmpe.

  • maxStakeWanted: Per-validator cap on incoming Marinade stake, configured via the bonds CLI in lamports. Subject to a 10,000 SOL minimum floor (minMaxStakeWanted). See maxStakeWanted Parameter.

  • MEV (Maximal Extractable Value): Value extractable through transaction ordering, inclusion, or exclusion within blocks. One of three reward categories (inflation, MEV, block rewards) configurable in dynamic commission.

  • MIP (Marinade Improvement Proposal): Governance proposals for protocol changes. Discussed and ratified on the Marinade Forum. Notable: MIP-19 introduced the 15% per-validator cap and the Bond Risk Reduction Mechanism.

  • minBondEpochs: Source-config parameter (4 in production) for the minimum bond coverage in future epochs. Combined with the current epoch this represents the 5-epoch fee threshold.

  • minMaxStakeWanted: Source-config parameter (10,000 SOL in production) setting the floor on the per-validator cap parameter. See maxStakeWanted Parameter.

  • onchainDistributedPmpe: The on-chain distributed PMPE for an epoch, used in Bond Risk Reduction Mechanism calculations.

  • On-chain commission: The validator's commission settings recorded directly on the Solana blockchain (separate from Marinade's bond-level commission). Acts as a floor: dynamic commission can share more with stakers than the on-chain commission implies, but cannot share less.

  • Overstaked: A validator whose SAM target (the stake they would win in this epoch's auction) is lower than their current SAM active stake. The excess is redelegated to other validators.

  • PMPE (per 1,000 SOL per epoch): Unit for yield and bid measurements. Smaller values when expressed in lamports; larger values when expressed in SOL.

  • PSR (Protected Staking Rewards): Marinade's framework for protecting staker rewards via validator-funded bonds. The bond covers obligations like downtime, sandwich attacks, and other PSR-triggering events. See PSR documentation.

  • realized_yield: The yield actually delivered to stakers each epoch, equal to the Effective Bid (or auctionEffectiveBidPmpe). All validators on the winning list deliver this rate, regardless of their configured max_yield.

  • SAM (Stake Auction Marketplace): Marinade's auction-based delegation system. Validators bid for Marinade stake; the auction allocates stake based on max_yield rankings subject to eligibility and decentralization constraints.

  • SFDP (Solana Foundation Delegation Program): Solana Foundation program that delegates stake to qualifying validators. Counts as external stake for Stake Matching. PSR bond counts toward the SFDP self-stake requirement.

  • Slashable bond: The portion of a validator's bond exposed to penalties from PSR-triggering events (downtime, sandwich attacks). Required for direct SAM stake. Not required for matched stake.

  • Solana epoch: The native time unit on Solana, approximately 2 days in duration. All SAM mechanisms operate on per-epoch cycles.

  • Static bid: The CPMPE component of a validator's auction bid. Fixed cost per 1,000 SOL of stake per epoch. Configured in lamports via --cpmpe.

  • totalPmpe: Source-code name for max_yield. Used in auction outputs and pipeline data.

  • Unprotected stake: Source-code term for matched stake. The two refer to the same thing: stake matched by Marinade as additional delegation without slashable bond coverage. Field name unprotectedStakeSol. See Stake Matching.

  • unprotectedDelegatedStakeDec / unprotectedFoundationStakeDec: Configuration parameters for Stake Matching. 0.1 (10%) and 0.3 (30%) respectively in production. Set the match rate on non-SFDP and SFDP stake.

Useful Reads

Background and educational content for SAM participants.

PreviousBond NotificationsNextStaking Rewards Report

Last updated

Was this helpful?