Updates

The current MPL-Distro authority can change selected distribution fields without creating a new PDA or invalidating existing claim receipts.

Summary

updateDistribution applies authority-approved configuration changes to an existing distribution.

• Change the full allocation configuration only outside the active claim window.
• Change operational fields such as authority and permissioned distributor during claims.
• Treat an authority change as immediate and security-sensitive.
• Publish replacement Merkle proofs atomically with any root update.

Quick Start

Updating an MPL-Distro distribution is a signed configuration change on the existing account.

1. Confirm whether the cluster time is inside the inclusive startTime–endTime window.
2. Pass only the fields that should change to updateDistribution.
3. If the Merkle root changes, replace every off-chain proof at the same time.
4. Verify the stored authority and permissioned distributor after confirmation.

MPL-Distro Update Permissions

The current authority must sign every distribution update.

The active window includes both boundary timestamps. The protected allocation fields are locked when startTime <= clusterTime <= endTime.

Update MPL-Distro Configuration

Pass only the fields that should change to updateDistribution.

1import { mplDistro, updateDistribution } from '@metaplex-foundation/mpl-distro'
2import { publicKey } from '@metaplex-foundation/umi'
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
4
5const umi = createUmi(
6  process.env.RPC_URL ?? 'https://api.devnet.solana.com'
7).use(mplDistro())
8
9const distributionAddress = process.env.DISTRIBUTION_ADDRESS!
10const newEndTimestamp = Math.floor(Date.now() / 1000) + 14 * 24 * 60 * 60
11const newDistributorAddress = process.env.PERMISSIONED_DISTRIBUTOR!
12
13await updateDistribution(umi, {
14  distribution: publicKey(distributionAddress),
15  endTime: BigInt(newEndTimestamp),
16  name: 'Extended community distribution',
17  newPermissionedDistributor: publicKey(newDistributorAddress),
18}).sendAndConfirm(umi)
19
20// The distribution end time, name, and permissioned distributor are updated.

When totalClaimants changes without an explicit treeHeight, the program infers a minimum height. Passing the treeHeight returned by the newly prepared tree is clearer and avoids coupling the update to claimant-count inference.

Change the Distribution Authority

updateDistribution replaces the signer that can update, deposit, withdraw tokens, and withdraw subsidy.

1import { mplDistro, updateDistribution } from '@metaplex-foundation/mpl-distro'
2import { publicKey } from '@metaplex-foundation/umi'
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
4
5const umi = createUmi(
6  process.env.RPC_URL ?? 'https://api.devnet.solana.com'
7).use(mplDistro())
8
9const distribution = publicKey(process.env.DISTRIBUTION_ADDRESS!)
10const currentAuthority = umi.identity
11const nextAuthority = publicKey(process.env.NEXT_AUTHORITY!)
12
13await updateDistribution(umi, {
14  distribution,
15  authority: currentAuthority,
16  newAuthority: nextAuthority,
17}).sendAndConfirm(umi)
18
19// Subsequent deposits, withdrawals, and updates require the new authority.

The new authority does not need to sign the update. Verify the destination public key and make sure its signing infrastructure is operational before submitting the change.

Change the Permissioned Distributor

updateDistribution changes the signer accepted for distributions configured with AllowedDistributor.Permissioned. Pass newPermissionedDistributor on updateDistribution.

The change does not alter the Merkle tree or existing receipts. In-flight transactions signed by the previous distributor fail after the update lands.

Update Errors

Update errors protect authority and timing constraints.

Notes

Configuration changes affect proof validity and operational authority immediately after confirmation.

• Changing endTime during an active window can extend or shorten the claim period.
• A post-window root update does not remove existing claim receipts.
• Existing receipts remain keyed to the distribution PDA after an update.

FAQ

Can the authority change the Merkle root during the active window?

No. The root, tree height, start time, and claimant count are locked throughout the active window but can be changed before it starts or after it ends.

Can the claim end time be extended during an active distribution?

Yes. The authority may update endTime while the distribution is active.

Does the new authority need to sign an authority change?

No. Only the current authority signs updateDistribution. Verify the destination key before submitting.