Skip to content

v0.2.1

Choose a tag to compare

View all tags
@solarpx solarpx released this 08 Feb 05:34
· 2 commits to main since this release
v0.2.1
24cc77f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Stake Program v0.2.1 - SphereNet Mod - Validator Whitelist Integration

Overview

SphereNet-modified stake program with validator whitelist permissioning for Agave 3.1.8. This release implements Patch 0002 from the SphereNet 2.3.10 patchset with security hardening and Agave 3.x compatibility.

Major Changes

1. Validator Whitelist Integration (~109 lines core logic)

Delegate Instruction Enhancement:

  • Added 5th account parameter: whitelist_entry at index 4
  • Validates vote account is whitelisted before allowing delegation
  • Checks validator is active (within epoch range)

Error Codes Added (4 new):

  • 0xb526ed0b - Validator not whitelisted
  • 0x600eaac4 - Invalid whitelist account
  • 0xbede83fc - Whitelist entry not found
  • 0x9ccf307f - Incorrect program ID

2. Dispatcher Pattern Security Hardening (~80 lines)

Critical Security Fix in deactivate_delinquent():

Refactored into secure dispatcher with explicit account owner validation:

// Dispatcher routes by support account owner:
match support_account.owner() {
    vote::id() => deactivate_network_delinquent(...)  // Network delinquency
    whitelist_id | system_id => deactivate_delisted_delinquent(...)  // Removed from whitelist
    _ => Err(IncorrectProgramId)  // Reject unknown accounts
}

Vulnerability Fixed: Original implementation used simple if/else that blindly trusted any non-vote account, allowing attackers to pass arbitrary accounts (EOAs, token accounts, malicious programs).

Solution: Fail-fast validation at dispatcher level - explicitly check account ownership BEFORE processing.

3. Test Suite Updates (~390 lines)

  • All 116 tests passing
  • Test fixtures updated for whitelist entry accounts
  • Error expectations updated due to validation order changes
  • New test: test_deactivate_delisted_delinquent()

Key Change: Whitelist validation now happens BEFORE downstream validation, improving security posture.

4. Agave 3.x Architectural Change

Critical: In Agave 3.x, the stake program is distributed separately (not built into validator).

Distribution Model:

  • Built independently: cargo build-sbf
  • Distributed as .so file
  • Loaded at genesis via --bpf-program flag
--bpf-program Stake11111111111111111111111111111111111111 \
  BPFLoaderUpgradeab1e11111111111111111111111 \
  spherenet-stake-program-0.2.1.so \
  none

5. Helper Functions (Feature-Gated)

New helpers feature with convenience functions:

instruction_builders.rs (93 lines):

  • delegate_stake() - Auto-includes whitelist entry PDA
  • create_account_and_delegate_stake() - One-step delegation

helpers/genesis.rs (84 lines):

  • Genesis config helpers for test infrastructure
  • Automatic whitelist entry creation

Usage:

spherenet-stake-program = { version = "0.2.1", features = ["helpers"] }

Note: Feature-gated to keep production .so lean (no genesis-config/keypair deps in BPF build).

Dependencies Updated

Agave 3.1.8 Compatible:

  • solana-account: 2.x → 3.0.0
  • solana-pubkey: 2.x → 3.0.0
  • solana-instruction: 2.x → 3.0.0
  • solana-vote-program: 2.x → 3.1.8
  • All other Solana/Agave crates → 3.1.8

SphereNet Dependencies:

  • spherenet-validator-whitelist-interface: 0.2.0
  • serde: Added for serialization

Published Crates

Patch Comparison

SPHERENET_MOD.patch - View on GitHub

Comparable to Patch 0002 from SphereNet 2.3.10 iteration. Changes are procedural:

  1. Patch program logic (109 lines)
  2. Patch tests (390 lines)
  3. Align workspace with SphereNet programs
  4. Build binary (.so)
  5. Vendor out crates

Compatibility

Compatible with:

  • Agave 3.1.8+
  • SphereNet validator 3.x series
  • All SphereNet 0.2.x interface crates

Not compatible with:

  • Agave 2.x (use in-tree stake program instead)
  • SphereNet 0.1.x interface crates

Migration Guide

For validator operators:

  • Update fetch-spherenet.sh to download stake program .so
  • Add --bpf-program flag to genesis creation
  • No config changes required (same instruction interface)

For developers:

# Update dependencies
spherenet-stake-interface = "0.2.1"
spherenet-stake-client = "0.2.1"

# Use helpers for testing
spherenet-stake-program = { version = "0.2.1", features = ["helpers"] }

For delegators:

  • No changes - instruction interface unchanged
  • Whitelist validation happens automatically

Testing

All 116 tests passing:

  • ✅ Unit tests (delegate, deactivate, authorization)
  • ✅ Security tests (dispatcher validation, fail-fast behavior)
  • ✅ Integration tests (whitelist entry validation, epoch ranges)
  • ✅ Compatibility tests (with SphereNet 0.2.x components)

Security Considerations

Improved Security Posture:

  • Fail-fast validation prevents malicious account injection
  • Explicit owner checks at dispatcher level
  • Defense in depth: validation at multiple layers
  • Clear error messages for debugging

Audit Notes:

  • Security fix addresses blind-trust vulnerability in dispatcher
  • All edge cases covered by test suite
  • Validation order changes intentional (security improvement)

Release Date: February 2026
Target: Agave 3.1.8
Program ID: Stake11111111111111111111111111111111111111

Assets 3
Loading