Registry Program

The Registry program manages Light Protocol’s configuration, coordinates forester operations, and wraps Account Compression instructions with access control for decentralized tree maintenance.

Program ID

Lighton6oQpVkeewmo2mcPTQQp7kYHr4fWpAgJyEmDX

Overview

The Registry program serves three primary functions:

Protocol Configuration: Stores network parameters, epoch settings, and fees
Forester Coordination: Manages forester registration, work tracking, and rewards
Access Control: Wraps Account Compression instructions with eligibility checks

Key Features

Protocol Config

Network-wide settings and parameters

Forester Epochs

Time-based registration and work tracking

Wrapper Instructions

Access-controlled tree operations

Rent Management

Compressible config accounts

Account Types

Protocol Config PDA

Stores global protocol configuration.

authority

Pubkey

required

Protocol authority that can update config

bump

required

PDA bump seed

config

ProtocolConfig

required

Configuration parameters:

genesis_slot: Protocol start slot
active_phase_length: Slots per active phase
registration_phase_length: Slots for forester registration
report_work_phase_length: Slots for work reporting
network_fee: Base network fee in lamports
slot_length: Seconds per slot

Derivation: Seeds [b"protocol_config_pda_v1", authority] Source: programs/registry/src/protocol_config/state.rs

Forester Epoch PDA

Tracks forester registration and work for an epoch.

authority

Pubkey

required

Forester authority

epoch

u64

required

Epoch number

total_work

u64

required

Work units completed this epoch

work_by_tree

HashMap<Pubkey, u64>

Work breakdown per tree

registration_slot

u64

required

Slot when forester registered

finalized

bool

required

Whether epoch is finalized

Derivation: Seeds [b"forester_epoch_pda", authority, epoch.to_le_bytes()] Source: programs/registry/src/epoch/state.rs

Compressible Config

Configuration for compressible token accounts (rent management).

Address that sponsored the rent

config_state

CompressibleConfigState

required

State: Active, Deprecated, or Inactive

rent_authority

Option<Pubkey>

Authority that can claim rent back

compression_incentive

u64

required

Incentive paid for compression (in lamports)

decompression_incentive

u64

required

Incentive paid for decompression

slot_length

u64

required

Duration accounts must stay decompressed (in slots)

counter

u64

required

Counter for deriving unique config addresses

Derivation: Seeds [b"compressible_config", rent_sponsor, counter.to_le_bytes()] Source: program-libs/compressible/src/config.rs

Core Instructions

Protocol Configuration

initialize_protocol_config

Initializes the protocol config PDA. Can only be called once.Accounts:

authority (signer): Protocol authority
protocol_config_pda (writable): PDA to initialize
system_program

Parameters:

bump: PDA bump seed
protocol_config: Configuration parameters

Requirements:

Must be signed by program account keypair during deployment
Can only be initialized once

Source: programs/registry/src/protocol_config/initialize.rs

update_protocol_config

Updates protocol configuration.Accounts:

authority (signer): Current protocol authority
protocol_config_pda (writable): Config to update
new_authority: Optional new authority

Parameters:

protocol_config: New configuration (optional)

Restrictions:

Cannot change genesis_slot
Cannot change active_phase_length (would break epoch calculations)

Source: programs/registry/src/protocol_config/update.rs

Forester Management

register_epoch

Registers a forester for the current epoch.Accounts:

authority (signer): Forester authority
forester_epoch_pda (writable): PDA to create
protocol_config_pda: Protocol config
system_program

Process:

Calculates current epoch from slot and config
Checks registration is during registration phase
Creates forester epoch PDA for this epoch

Requirements:

Must be called during registration phase
One registration per epoch per forester

Source: programs/registry/src/epoch/register_epoch.rs

report_work

Reports work completed by a forester (called by wrapper instructions).Accounts:

forester_epoch_pda (writable): Forester’s epoch PDA
tree_account: Tree work was performed on

Parameters:

work_units: Amount of work to record

Process:

Validates epoch is active
Increments total_work
Updates work_by_tree for the specific tree

Source: programs/registry/src/epoch/report_work.rs

finalize_registration

Finalizes a forester’s epoch registration for rewards.Accounts:

authority (signer): Forester authority
forester_epoch_pda (writable): Epoch PDA to finalize
protocol_config_pda: Protocol config

Requirements:

Must be called during report work phase
Can only finalize once per epoch

Effect: Marks epoch as finalized, enabling reward distributionSource: programs/registry/src/epoch/finalize_registration.rs

Compressible Config Management

create_compressible_config_counter

Creates a counter account for generating unique config addresses.Accounts:

rent_sponsor (signer): Sponsor who will own configs
counter_account (writable): Counter PDA to create
system_program

Derivation: Seeds [b"compressible_config_counter", rent_sponsor]Source: programs/registry/src/compressible/create_config_counter.rs

create_compressible_config

Creates a new compressible config.Accounts:

rent_sponsor (signer): Config owner
counter_account (writable): Counter to increment
compressible_config (writable): Config to create
system_program

Parameters:

config_data: Configuration (rent authority, incentives, slot length)

Process:

Increments counter
Derives config PDA with new counter value
Initializes config with provided data

Source: programs/registry/src/compressible/create_config.rs

update_compressible_config

Updates an existing compressible config.Accounts:

rent_sponsor (signer): Config owner
compressible_config (writable): Config to update

Parameters:

config_state: New state (Active, Deprecated, Inactive)
rent_authority: Optional new rent authority
compression_incentive: Optional new compression incentive
decompression_incentive: Optional new decompression incentive
slot_length: Optional new slot length

Source: programs/registry/src/compressible/update_config.rs

Wrapper Instructions (Access Control)

These instructions wrap Account Compression operations with forester eligibility checks.

Wrapper Pattern

All wrapper instructions follow the same pattern:

Load account - Deserialize target account metadata
Check forester - Validate authority and track work
Execute CPI - Call Account Compression with PDA signer

pub fn wrapper_instruction(
    ctx: Context<WrapperContext>,
    bump: u8,
    data: Vec<u8>,
) -> Result<()> {
    // 1. Load account
    let account = load_account(&ctx.accounts.target_account)?;
    
    // 2. Check forester eligibility
    check_forester(
        &account.metadata,
        ctx.accounts.authority.key(),
        &mut ctx.accounts.registered_forester_pda,
        work_units,
    )?;
    
    // 3. Execute CPI
    process_wrapper_cpi(&ctx, bump, data)
}

batch_append

Wraps Account Compression’s batch_append with access control.Work Units: Based on batch size from queue metadataSource: programs/registry/src/account_compression_cpi/batch_append.rs

batch_nullify

Wraps batch_nullify with forester eligibility check.Work Units: Based on batch sizeSource: programs/registry/src/account_compression_cpi/batch_nullify.rs

batch_update_address_tree

Wraps batched address tree updates.Source: programs/registry/src/account_compression_cpi/batch_update_address_tree.rs

nullify

Wraps single leaf nullification.Work Units: DEFAULT_WORK_V1 constantSource: programs/registry/src/account_compression_cpi/nullify.rs

update_address_merkle_tree

Wraps single address insertion.Work Units: DEFAULT_WORK_V1 constantSource: programs/registry/src/account_compression_cpi/update_address_tree.rs

rollover_state_merkle_tree_and_queue

Wraps state tree rollover.Source: programs/registry/src/account_compression_cpi/rollover_state_tree.rs

rollover_batched_state_merkle_tree

Wraps batched state tree rollover.Source: programs/registry/src/account_compression_cpi/rollover_batched_state_tree.rs

rollover_batched_address_merkle_tree

Wraps batched address tree rollover.Source: programs/registry/src/account_compression_cpi/rollover_batched_address_tree.rs

initialize_batched_state_merkle_tree

Wraps batched state tree initialization.Source: programs/registry/src/account_compression_cpi/initialize_batched_state_tree.rs

initialize_batched_address_merkle_tree

Wraps batched address tree initialization.Source: programs/registry/src/account_compression_cpi/initialize_batched_address_tree.rs

migrate_state

Wraps state migration between trees.Source: programs/registry/src/account_compression_cpi/migrate_state.rs

Compressible Token Operations

compress_and_close

Wraps Compressed Token’s compress and close operation.Process:

Validates compressible config is not inactive
Executes compression via CPI
Handles rent distribution

Source: programs/registry/src/compressible/compress_and_close.rs

claim

Wraps Compressed Token’s claim instruction.Requirements:

Config must not be inactive
Account must be compressible

Source: programs/registry/src/compressible/claim.rs

withdraw_funding_pool

Wraps Compressed Token’s withdraw funding pool instruction.Source: programs/registry/src/compressible/withdraw_funding_pool.rs

Forester Eligibility System

Epoch Phases

Each epoch consists of three phases:

Registration Phase: Foresters register for the epoch
Active Phase: Foresters perform work on trees
Report Work Phase: Foresters finalize registration and receive rewards

Work Tracking

Work is tracked per operation:

Operation	Work Units
Batch append	Batch size
Batch nullify	Batch size
Batch address update	Batch size
Single nullify	DEFAULT_WORK_V1 (1)
Single address update	DEFAULT_WORK_V1 (1)
Tree rollover	DEFAULT_WORK_V1 (1)

Eligibility Check

The check_forester function validates operations: With Forester PDA:

Validates epoch registration
Checks authority matches registered forester
Tracks work units
Requires network fee payment

Without Forester PDA (Private Trees):

Checks authority matches tree’s designated forester
No work tracking
No network fee required

Usage Examples

Registering as a Forester

use light_registry::cpi::accounts::RegisterEpoch;
use anchor_lang::prelude::*;

#[derive(Accounts)]
pub struct RegisterForester<'info> {
    #[account(mut)]
    pub authority: Signer<'info>,
    
    #[account(mut)]
    /// CHECK: Will be created
    pub forester_epoch_pda: AccountInfo<'info>,
    
    pub protocol_config_pda: Account<'info, ProtocolConfigPda>,
    
    pub light_registry_program: Program<'info, LightRegistry>,
    pub system_program: Program<'info, System>,
}

pub fn register_as_forester(
    ctx: Context<RegisterForester>,
) -> Result<()> {
    let cpi_accounts = RegisterEpoch {
        authority: ctx.accounts.authority.to_account_info(),
        forester_epoch_pda: ctx.accounts.forester_epoch_pda.to_account_info(),
        protocol_config_pda: ctx.accounts.protocol_config_pda.to_account_info(),
        system_program: ctx.accounts.system_program.to_account_info(),
    };
    
    let cpi_ctx = CpiContext::new(
        ctx.accounts.light_registry_program.to_account_info(),
        cpi_accounts,
    );
    
    light_registry::cpi::register_epoch(cpi_ctx)
}

Creating a Compressible Config

import { 
  createCompressibleConfig,
  CompressibleConfigState 
} from '@lightprotocol/compressed-token';
import { PublicKey } from '@solana/web3.js';

const rentSponsor = wallet.publicKey;
const rentAuthority = new PublicKey('...');

const { config, signature } = await createCompressibleConfig(
  rpc,
  payer,
  rentSponsor,
  {
    configState: CompressibleConfigState.Active,
    rentAuthority: rentAuthority,
    compressionIncentive: 1_000_000, // 0.001 SOL
    decompressionIncentive: 500_000,  // 0.0005 SOL
    slotLength: 1000,                 // 1000 slots (~400 seconds)
  }
);

console.log(`Config created: ${config}`);

Error Codes

Code	Name	Description
5000	InvalidEpoch	Epoch number invalid for current slot
5001	InvalidPhase	Operation not allowed in current phase
5002	ForesterNotRegistered	Forester not registered for epoch
5003	InvalidSigner	Signer doesn’t match expected authority
5004	AlreadyFinalized	Epoch already finalized
5005	InvalidNetworkFee	Network fee payment incorrect
5006	InvalidConfigUpdate	Config update violates constraints
5007	ForesterDefined	Tree has forester but none provided
5008	ForesterUndefined	Tree has no forester but one provided
5009	CompressibleConfigInactive	Config state is inactive

Source: programs/registry/src/errors.rs

Source Code

View the full source code on GitHub:

Next Steps

Run a Forester

Learn how to run a forester node

Programs Overview

Back to programs overview

On-Chain Programs

ZK Prover

Forester Service

Indexer

Program ID

Overview

Key Features

Protocol Config

Forester Epochs

Wrapper Instructions

Rent Management

Account Types

Protocol Config PDA

Forester Epoch PDA

Compressible Config

Core Instructions

Protocol Configuration

Forester Management

Compressible Config Management

Wrapper Instructions (Access Control)

Compressible Token Operations

Forester Eligibility System

Epoch Phases

Work Tracking

Eligibility Check

Usage Examples

Registering as a Forester

Creating a Compressible Config

Error Codes

Source Code

Next Steps

Run a Forester

Programs Overview

Build docs developers (and LLMs) love

On-Chain Programs

ZK Prover

Forester Service

Indexer

​Program ID

​Overview

​Key Features

Protocol Config

Forester Epochs

Wrapper Instructions

Rent Management

​Account Types

​Protocol Config PDA

​Forester Epoch PDA

​Compressible Config

​Core Instructions

​Protocol Configuration

​Forester Management

​Compressible Config Management

​Wrapper Instructions (Access Control)

​Compressible Token Operations

​Forester Eligibility System

​Epoch Phases

​Work Tracking

​Eligibility Check

​Usage Examples

​Registering as a Forester

​Creating a Compressible Config

​Error Codes

​Source Code

​Next Steps

Run a Forester

Programs Overview

Build docs developers (and LLMs) love

Program ID

Overview

Key Features

Account Types

Protocol Config PDA

Forester Epoch PDA

Compressible Config

Core Instructions

Protocol Configuration

Forester Management

Compressible Config Management

Wrapper Instructions (Access Control)

Compressible Token Operations

Forester Eligibility System

Epoch Phases

Work Tracking

Eligibility Check

Usage Examples

Registering as a Forester

Creating a Compressible Config

Error Codes

Source Code

Next Steps