개요

요약

mplx distro 명령어는 터미널에서 MPL-Distro 배포를 생성, 자금 투입, 조회, 회수합니다.

• 도구: Metaplex CLI(mplx)의 distro 명령어 그룹
• 클라이언트: 현재 프로그램에 대해 @metaplex-foundation/mpl-distro 0.4.x 필요
• 온체인 작업: 배포 PDA 생성, 토큰 입금, 잔여 출금, 계정 데이터 조회
• 오프체인 작업: Merkle 루트, 증명, 클레임은 JavaScript SDK에 남음

바로가기: 사전 요구사항 · 일반 흐름 · 명령어 레퍼런스 · Merkle 루트 인코딩 · 일반적인 오류 · FAQ · 용어집

사전 요구사항

MPL-Distro CLI 명령어에는 자금이 있는 identity, 기존 원본 SPL Token mint, 32바이트 Merkle 루트가 필요합니다.

• @metaplex-foundation/mpl-distro 0.4.x로 빌드되어 PATH에 있는 Metaplex CLI
• mplx config로 설정한 Solana 키페어(배포 권한자)
• 임대료와 트랜잭션 수수료용 SOL
• 기존 SPL 토큰 mint(Token-2022 아님)와 입금용 자금이 있는 associated token account
• mplx config rpcs add 또는 -r로 지정한 RPC 엔드포인트

명령어 그룹을 확인합니다.

mplx distro --help

일반 흐름

권한자 설정은 CLI로 합니다. 수신자는 증명을 저장하는 앱에서 클레임합니다.

1. 할당 — JavaScript SDK의 prepareDistribution으로 수신자 목록을 만들고 Merkle 루트를 생성합니다. 모든 주소, amount, nonce, 증명을 보존합니다.
2. 생성 — mplx distro create가 루트, 클레임 창, mint, 접근 모드를 온체인에 기록합니다.
3. 입금 — mplx distro deposit가 토큰을 배포 볼트로 이동합니다. 입금은 언제든 가능합니다.
4. 클레임 — 수신자(또는 릴레이어)가 저장된 증명으로 distribute / distributeToLegacyNft를 제출합니다. CLI에는 클레임 명령어가 없습니다.
5. 회수 — endTime 이후(또는 startTime 이전)에 mplx distro withdraw가 미클레임 토큰을 반환합니다.

증명 저장과 클레임 페이지는 프로덕션 전달을 참조하세요.

mplx distro create \
  --name "Community Airdrop" \
  --mint <TOKEN_MINT> \
  --totalClaimants 2 \
  --startTime "2026-09-01T00:00:00Z" \
  --endTime "2026-09-08T00:00:00Z" \
  --merkleRoot <BASE58_32_BYTE_ROOT>

mplx distro deposit <DISTRIBUTION> --amount 1.0
mplx distro fetch <DISTRIBUTION>
mplx distro withdraw <DISTRIBUTION> --amount 0.5

명령어 레퍼런스

mplx distro는 네 가지 명령어를 제공합니다. 증명을 생성하거나 클레임을 제출하지 않습니다.

CLI는 AllowedDistributor.Permissioned, updateDistribution, withdrawSubsidy, 클레임 명령을 지원하지 않습니다.

Merkle 루트 인코딩

--merkleRoot는 32바이트 할당 루트의 base58 인코딩이며 16진 문자열이 아닙니다.

prepareDistribution으로 생성한 뒤 root 바이트를 인코딩합니다.

import { prepareDistribution } from '@metaplex-foundation/mpl-distro'
import { publicKey } from '@metaplex-foundation/umi'
import { base58 } from '@metaplex-foundation/umi/serializers'

const { root, proofs, treeHeight } = prepareDistribution([
  { address: publicKey('RecipientWallet111111111111111111111111111'), amount: 100_000n },
  { address: publicKey('RecipientWallet222222222222222222222222222'), amount: 250_000n },
])

const merkleRoot = base58.deserialize(root)[0]
console.log(merkleRoot)

--totalClaimants를 그 목록의 할당 수로 설정하세요. CLI는 computeTreeHeight(totalClaimants)를 온체인에 저장합니다. prepareDistribution 증명은 그 높이보다 길면 안 됩니다.

일반적인 오류

mplx distro에서 가장 자주 보는 실패입니다.

참고사항

CLI는 SDK로 만든 Merkle 할당을 다루는 권한자 도구입니다.

• mint는 원본 SPL Token 프로그램 소유여야 합니다. Token-2022 mint는 거부됩니다.
• --amount 수량은 mint의 decimals를 사용합니다. --basisAmount는 토큰 최소 단위입니다.
• 입금은 시간 제한이 없습니다. startTime <= clusterTime <= endTime이면 출금이 거부됩니다.
• --allowedDistributor는 permissionless 또는 recipient만 받습니다.
• CLI는 무작위 seed 서명자를 생성하고 seed는 출력하지 않습니다. create 출력에서 배포 PDA를 저장하세요.

FAQ

mplx distro는 무엇을 하나요?

mplx distro 명령어 그룹은 MPL-Distro 계정을 생성하고, SPL 토큰을 입금·출금하며, 온체인 배포 정보를 조회합니다. Merkle 증명을 생성하거나 클레임을 제출하지는 않습니다.

현재 MPL-Distro 프로그램과 맞는 CLI 버전은 무엇인가요?

온체인 프로그램에는 @metaplex-foundation/mpl-distro 0.4.x 클라이언트가 필요합니다. 게시된 @metaplex-foundation/cli 0.4.3은 아직 0.3.x에 의존하며 distro create가 BorshIoError로 실패합니다. mpl-distro 0.4.0 이상에 의존하는 CLI 빌드를 사용하세요.

CLI가 수신자 클레임을 제출하나요?

아니요. prepareDistribution으로 증명을 만들고 JavaScript SDK 또는 클레임 페이지에서 distribute 또는 distributeToLegacyNft를 제출하세요.

권한자는 언제 토큰을 출금할 수 있나요?

시작 타임스탬프 이전 또는 종료 타임스탬프 이후입니다. 클레임 창이 활성일 때 출금은 거부됩니다.

용어집