Skip to main content

Programs on SphereNet

SphereNet uses a whitelist-based approach to control which programs can execute on the network. The BPF loader has been modified to only execute programs that are listed in the governance-maintained whitelist. To be added to this whitelist, programs must have their upgrade authority set to the governance program's PDA.

This ensures that all program code running on the network has been reviewed and approved by governance, and that only governance can authorize program upgrades.

Program Mutability​

All programs on SphereNet must be upgradeable through governance. This requirement ensures the network can deploy security patches when vulnerabilities are discovered, implement protocol upgrades as the network evolves, adapt to changing regulatory requirements, and fix bugs that may be discovered in even thoroughly audited programs.

For this reason, immutable programs or programs with non-governance upgrade authorities will not be approved for the whitelist.

Deployment Process​

The program deployment process consists of several steps:

  1. Initial Deployment

    Developer deploys their program to the network, transfers program upgrade authority to governance PDA, and submits governance proposal containing:

    • Program ID
    • Source code repository link
    • Technical documentation
    • Security audit reports (if available)
    • Source code (must be open source)
    • Intended functionality and use cases
    • Build instructions and verification steps

  2. Community Review Period

    CORE holders review the program in context of:

    • Source code quality and correctness
    • Security considerations
    • Compliance implications
    • Technical architecture
    • Integration requirements

    The review period typically lasts 7 days.

  3. Voting Phase

    If the proposal reaches quorum, CORE holders vote to add or reject the program from the whitelist.

  4. Whitelist Addition

    If approved, the governance program will add the program ID to the whitelist, which allows it to be executed on the network.

Program Updates​

Program updates on SphereNet follow a structured governance process to ensure all modifications are properly reviewed and approved:

  1. Buffer Deployment

    Developer deploys new program code to a buffer account, transfers buffer authority to governance PDA, and submits governance proposal containing:

    • Program ID to upgrade
    • Buffer account address
    • Source code changes with detailed diff
    • Change description and rationale
    • Updated technical documentation
    • Security implications

  2. Review Period

    CORE holders review the proposed changes. Standard review period is 7 days. Emergency patches may have expedited review. Changes are reviewed in context of:

    • Source code modifications and quality
    • Code modifications
    • Security impact
    • Backwards compatibility
    • Integration effects

  3. Voting Phase

    If proposal reaches quorum, CORE holders vote to approve or reject the upgrade from buffer.

  4. Upgrade Execution

    If approved, the governance PDA will immediately apply the upgrade from the buffer. Upgraded program is immediately executable with no interuptions.

Emergency Updates​

For critical security fixes, an expedited process exists with shorter review and voting periods. Lower quorum requirements and immediate execution upon approval.

In cases of critical vulnerabilities, governance can immediately remove the program from the whitelist to prevent execution, keep the program deployed but non-executable while fixes are developed, or re-add to whitelist once patched version is approved.

Program Removal​

Programs can be removed from the whitelist through governance if they:

  • Contain critical vulnerabilities
  • No longer meet network requirements
  • Have been superseded by newer versions

Technical Implementation​

The governance program maintains a simple whitelist of approved program IDs:

pub struct ProgramWhitelist {
    pub last_update_slot: u64,    // Slot when whitelist was last updated
    pub programs: Vec<Pubkey>,    // List of approved program IDs
}

Before executing any program, the BPF loader checks if the program's ID exists in this whitelist. This simple membership check ensures that only approved programs can run on the network.

BPF Loader Enforcement​

The BPF loader has only one modification - checking the whitelist before program execution. It checks the program ID against the whitelist before any execution and rejects transactions that attempt to call non-whitelisted programs.

All other program operations (deployment, upgrades, closure) use standard SVM authority checks. The requirement for governance control comes from the whitelist policy that programs must have the governance PDA as their upgrade authority to be approved.