Guide to Migrate Programs from v1 to v2 Merkle trees

V2 Improvements

	v1	v2
Merkle tree type	Concurrent	Batched
State tree depth	26 (~67M leaves)	32 (~4B leaves)
Address tree depth	26	40
Address tree accounts	Separate tree + queue	Single batch tree

TypeScript
Rust
Pinocchio

Update imports

// v1
import {
    deriveAddress,
    deriveAddressSeed,
    defaultTestStateTreeAccounts,
    PackedAccounts,
} from "@lightprotocol/stateless.js";

// v2
import {
    deriveAddressV2,
    deriveAddressSeedV2,
    batchAddressTree,
    PackedAccounts,
    featureFlags,
    VERSION,
} from "@lightprotocol/stateless.js";

Enable v2 mode

Set the feature flag before making any calls:

import { featureFlags, VERSION } from "@lightprotocol/stateless.js";

(featureFlags as any).version = VERSION.V2;

Update address derivation

The seed and address derivation functions have different signatures in v2:

// v1 - Program ID passed to seed derivation
const seed = deriveAddressSeed(
    [counterSeed, signer.publicKey.toBytes()],
    new PublicKey(program.idl.address)
);
const address = deriveAddress(seed, addressTree);

// v2 - Program ID passed to address derivation
const seed = deriveAddressSeedV2([counterSeed, signer.publicKey.toBytes()]);
const address = deriveAddressV2(
    seed,
    addressTree,
    new PublicKey(program.idl.address)
);

Update address tree references

Use batchAddressTree instead of defaultTestStateTreeAccounts().addressTree:

// v1
const addressTree = defaultTestStateTreeAccounts().addressTree;
const addressQueue = defaultTestStateTreeAccounts().addressQueue;

// In proof request
{
    tree: addressTree,
    queue: addressQueue,
    address: bn(address.toBytes()),
}

// v2 - queue equals tree for batch trees
const addressTree = new PublicKey(batchAddressTree);

// In proof request
{
    tree: addressTree,
    queue: addressTree,
    address: bn(address.toBytes()),
}

Update PackedAccounts

Use the v2 variant when building remaining accounts:

// v1
const remainingAccounts = PackedAccounts.newWithSystemAccounts(systemAccountConfig);

// v2
const remainingAccounts = PackedAccounts.newWithSystemAccountsV2(systemAccountConfig);

Update Cargo.toml

Add the v2 feature flag to your dependencies:

[dependencies]
light-sdk = { version = "0.16", features = ["v2"] }
light-sdk-types = { version = "0.3", features = ["v2"] }

Update imports

// v1
use light_sdk::{
    address::v1::derive_address,
    constants::ADDRESS_TREE_V1,
    cpi::v1::{CpiAccounts, LightSystemProgramCpi},
};

// v2
use light_sdk::{
    address::v2::derive_address,
    cpi::v2::{CpiAccounts, LightSystemProgramCpi},
};
use light_sdk_types::ADDRESS_TREE_V2;

Update address derivation

The derive_address function signature remains the same, but the internal derivation logic differs. No code changes needed beyond updating the import path.

Update address params

Replace into_new_address_params_packed() with into_new_address_params_assigned_packed():

// v1
let new_address_params = instruction_data
    .address_tree_info
    .into_new_address_params_packed(address_seed);

// v2
let new_address_params = instruction_data
    .address_tree_info
    .into_new_address_params_assigned_packed(address_seed, Some(0));

The second parameter specifies the output queue index. Use Some(0) to assign the address to the first available queue.

Update tree validation

If your program validates the address tree pubkey, update the constant:

// v1
if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V1 {
    return Err(ProgramError::InvalidAccountData);
}

// v2
if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
    return Err(ProgramError::InvalidAccountData);
}

The Pinocchio SDK follows the same import changes as the Rust SDK, plus one additional API change.

Update imports

// v1
use light_sdk_pinocchio::{
    address::v1::derive_address,
    constants::ADDRESS_TREE_V1,
    cpi::v1::{CpiAccounts, LightSystemProgramCpi},
};

// v2
use light_sdk_pinocchio::{
    address::v2::derive_address,
    cpi::v2::{CpiAccounts, LightSystemProgramCpi},
};
use light_sdk_types::ADDRESS_TREE_V2;

Update CpiAccounts

CpiAccounts::try_new_with_config() becomes CpiAccounts::new_with_config() (infallible):

// v1
let cpi_accounts = CpiAccounts::try_new_with_config(signer, &accounts[1..], config)
    .map_err(to_custom_error_u32)?;

// v2
let cpi_accounts = CpiAccounts::new_with_config(signer, &accounts[1..], config);

Update address params

Same as the Rust SDK:

// v1
let new_address_params = instruction_data
    .address_tree_info
    .into_new_address_params_packed(address_seed);

// v2
let new_address_params = instruction_data
    .address_tree_info
    .into_new_address_params_assigned_packed(address_seed, Some(0));

Get Started

Compressed Tokens

Compressed PDAs

JSON RPC Methods

Learn

Resources

References

SDK Reference

Guide to Migrate Programs from v1 to v2 Merkle trees

V2 Improvements

Update imports

Enable v2 mode

Update address derivation

Update address tree references

Update PackedAccounts

Update Cargo.toml

Update imports

Update address derivation

Update address params

Update tree validation

Update imports

Update CpiAccounts

Update address params

View Program Examples

Program examples

Get Started

Compressed Tokens

Compressed PDAs

JSON RPC Methods

Learn

Resources

References

SDK Reference

​V2 Improvements

​Update imports

​Enable v2 mode

​Update address derivation

​Update address tree references

​Update PackedAccounts

​Update Cargo.toml

​Update imports

​Update address derivation

​Update address params

​Update tree validation

​Update imports

​Update CpiAccounts

​Update address params

​View Program Examples

Program examples

V2 Improvements

Update imports

Enable v2 mode

Update address derivation

Update address tree references

Update PackedAccounts

Update Cargo.toml

Update imports

Update address derivation

Update address params

Update tree validation

Update imports

Update CpiAccounts

Update address params

View Program Examples