XRPL 핵심 기능별 샘플 코드(Typescript)

📦 주요 기능(폴더)별 README

MPtokensV1

About XRPL

XRPL Dev Source

Program Q&A

MPtokensV1

주요 내용

발행자 승인형 토큰 발행/전송

폴더명

MPtokensV1

스크립트 실행 명령어

#1) 사전 발행 정의 생성(Admin)
$npx ts-node xrpl/MPTokensV1/createIssuance.ts
# 실행 후 IssuanceID(created): 006419063CEBEB49FC20032206CE0F203138BFC59F1A#### 기록해두기, 이후 2~5번 스크립트에 쓰임

#2) 홀더 권한 부여 : 1번에서 트랜잭션을 (tfMPTRequireAuth: true)로 보냈을 때만!
  -아닐 때에도 옵트인 해야 함.
$npx ts-node xrpl/MPTokensV1/authorizeHolder.tsi

#3) MPT 전송
$npx ts-node xrpl/MPTokensV1/sendMPT.ts

#4) 발행정의 삭제 (모든 홀더들의 해당 토큰 잔액이 0이어야 가능)
$npx ts-node xrpl/MPTokensV1/destroyIssuance.ts

#5) 발행된 토큰 락/언락 (Optional)
$npx ts-node xrpl/MPTokensV1/setIssuance.ts
Bash
복사

1. MPT(Multi-Purpose Token)이란?

MPT는 XRPL의 새로운 펀저블 토큰 타입으로, 기존 IOU(양방향 트러스트라인)보다 단순한 발행·보유 모델을 제공한다.

토큰은 두 가지 원장 객체로 다뤄진다:

•

MPTokenIssuance: 발행 정의(스케일, 최대발행량, 전송/락/클로백/권한필요 등의 정책)

•

MPToken: 개별 계정이 특정 발행본을 얼마나 보유하는지

v1의 특징: 직접 결제만 지원(계정→계정). DEX 거래는 불가.

2. 왜 필요한가?

•

간결한 운영 모델

Trustline 없이 발행·전송 중심의 단방향 모델.

•

정책 일원화

전송 가능 여부, 권한 필요(RequireAuth), 락/언락, 클로백 등의 발행본 단위 정책을 한 곳에서 관리.

•

명확한 식별자

결제에 MPTokenIssuanceID(고유 ID)를 사용 → 토큰 정의를 명확히 구분.

•

스케일(소수점) 내장

AssetScale로 최소단위를 정의 → 금액 처리가 예측 가능.

3. 시나리오: createIssuance → authorizeHolder → sendMPT (+ setIssuance, destroyIssuance )

Step 1. 발행 정의 생성 (createIssuance.ts)

•

주체: ADMIN(발행자)

•

행동: MPTokenIssuanceCreate  트랜잭션 전송

•

내용:

◦

AssetScale(소수 자리수), MaximumAmount(선택), Flags( tfMPTCanTransfer, tfMPTRequireAuth 등) 지정

◦

•

tfMPTRequireAuth: true – 발행자가 사전 승인(MPTokenAuthorize)한 계정만 해당 MPT를 보유·수령 가능하게 하는 화이트리스트 모드. KYC/AML 등 규제 준수형 토큰에 활용.

import { Client, Wallet, Transaction } from "xrpl"
import path from "path"
import dotenv from "dotenv"
dotenv.config({ path: path.join(__dirname, "..", ".env") })

export async function createIssuance() {
  const client = new Client("wss://s.devnet.rippletest.net:51233")
  await client.connect()

  const ADMIN_SEED = process.env.ADMIN_SEED
  if (!ADMIN_SEED) throw new Error("Missing env: ADMIN_SEED")
  const admin = Wallet.fromSeed(ADMIN_SEED)

  /**
   * MPTokenIssuanceCreate 트랜잭션
   * - AssetScale: 소수 자릿수 (0 → 정수만)
   * - MaximumAmount: 총 발행 상한 (옵션)
   * - Flags: 정책 지정 (전송 가능, 에스크로 가능, 권한 필요 여부 등)
   */
  const tx: Transaction = {
    TransactionType: "MPTokenIssuanceCreate",
    Account: admin.address,
    AssetScale: 0,                            // 소수점 없음
    MaximumAmount: "1000000000",              // 최대 발행량 (옵션)
    Flags: {                                  // 정책 예시
      tfMPTCanTransfer: true,                 // 전송 가능
      tfMPTCanEscrow: true,                   // 에스크로 가능
      tfMPTRequireAuth: false                 // 권한 필요 X
    },
    // MPTokenMetadata: "<hex-encoded string>" // 필요시 hex 메타데이터 추가
  }

  try {
    // 트랜잭션 준비 → 서명 → 제출
    const prepared = await client.autofill(tx)
    const signed   = admin.sign(prepared)
    const result   = await client.submitAndWait(signed.tx_blob)

    // 전체 응답 로그 출력
    console.log(JSON.stringify(result, null, 2))

    // 결과 로그에서 발행본의 IssuanceID 추출 (일부 노드 구현체는 meta에 저장됨)
    const issuanceId48 = (result.result.meta as any)?.mpt_issuance_id
    if (issuanceId48) {
      console.log(`IssuanceID(created): ${issuanceId48}`)
    } else {
      console.log("⚠️ IssuanceID를 meta에서 찾지 못했습니다. 응답 로그 확인 필요.")
    }

    return result
  } finally {
    await client.disconnect()
    console.log("🔄 연결 종료")
  }
}

// 직접 실행
if (require.main === module) {
  createIssuance().catch(e => { console.error(e); process.exit(1) })
}
TypeScript
복사

•

출력 예시

IssuanceID(created): 006419063CEBEB49FC20032206CE0F203138BFC59F1A####
PowerShell
복사

•

결과 로그에서 IssuanceID를 복사 → 이후 모든 단계에 사용

Step 2. 홀더 권한 부여 (authorizeHolder.ts)

•

주체: ADMIN

•

행동: MPTokenAuthorize 트랜잭션 전송

•

내용:

◦

발행본이 tfMPTRequireAuth=true면 전송 전에 홀더(USER)를 허가해야 함

◦

MPTokenIssuanceID: <복사한 ID>, Holder: USER.address

◦

(해제는 Flags.tfMPTUnauthorize)

1단계 : User가 Issuance에 옵트인

•

Account : User 주소

•

트랜잭션 서명 주체 : User

import { Client, Wallet, Transaction } from "xrpl"
import path from "path"
import dotenv from "dotenv"
dotenv.config({ path: path.join(__dirname, "..", ".env") })

// ⚠️ createIssuance 실행 로그에서 복사한 IssuanceID 사용
const ISSUANCE_ID = "0049CE349E4215DD8AC6196A0A5027DF489AEC3B17BD6211"

export async function authorizeHolder() {
  const client = new Client("wss://s.devnet.rippletest.net:51233")
  await client.connect()

  const ADMIN_SEED = process.env.ADMIN_SEED
  const USER_SEED  = process.env.USER2_SEED
  if (!ADMIN_SEED || !USER_SEED) throw new Error("Missing env: ADMIN_SEED, USER2_SEED")

  // 발행자(Admin)와 피발급자(User) 지갑 로드
  const admin = Wallet.fromSeed(ADMIN_SEED)
  const user  = Wallet.fromSeed(USER_SEED)

  /**
   * Step 1. User가 Issuance에 옵트인
   *  - Account: user.address
   *  - 서명자: User (스스로 "참여 의사" 제출)
   */
  const tx: Transaction = {
    TransactionType: "MPTokenAuthorize",
    Account: user.address,                 // User가 서명/전송
    MPTokenIssuanceID: ISSUANCE_ID,        // MPT 발행 정의 ID
    // Holder: user.address                // User 단계에서는 불필요
    // Flags: { tfMPTUnauthorize: true }   // 해제할 때만 사용
  }

  try {
    // 트랜잭션 준비 → 서명 → 제출
    const prepared = await client.autofill(tx)
    const signed   = user.sign(prepared)
    const result   = await client.submitAndWait(signed.tx_blob)

    // 전체 응답 로그 출력
    console.log(JSON.stringify(result, null, 2))
    return result
  } finally {
    await client.disconnect()
    console.log("🔄 연결 종료")
  }
}

// 직접 실행
if (require.main === module) {
  authorizeHolder().catch(e => { console.error(e); process.exit(1) })
}
TypeScript
복사

2단계 : Admin(발행자)가 허용

•

Account : Admin 주소

•

Holder : User 주소

•

트랜잭션 서명 주체 : Admin

// createIssuance 실행 로그에서 복사한 IssuanceID
const ISSUANCE_ID = "006419063CEBEB49FC20032206CE0F203138BFC59F1A####"

const tx: Transaction = {
   TransactionType: "MPTokenAuthorize",
   Account: admin.address,
   MPTokenIssuanceID: ISSUANCE_ID,
   Holder: user.address
   // Flags: { tfMPTUnauthorize: true } // 해제하고 싶을 때만 사용
}
TypeScript
복사

Step 3. MPT 전송 (sendMPT.ts)

•

주체: ADMIN(보내는 쪽)

•

행동: Payment 트랜잭션 전송

•

내용:

◦

Amount는 MPTAmount 형식:

{ mpt_issuance_id: "<복사한 ID>", value: "<정수 문자열>" }

◦

v1은 직접 결제만 지원(DEX/경로탐색 없음)

import { Client, Wallet, Transaction } from "xrpl"
import path from "path"
import dotenv from "dotenv"
dotenv.config({ path: path.join(__dirname, "..", ".env") })

// ⚠️ createIssuance 실행 로그에서 복사한 IssuanceID 입력
const ISSUANCE_ID = "0049CE349E4215DD8AC6196A0A5027DF489AEC3B17BD6211"

export async function sendMPT() {
  const client = new Client("wss://s.devnet.rippletest.net:51233")
  await client.connect()

  const ADMIN_SEED = process.env.ADMIN_SEED
  const USER_SEED  = process.env.USER_SEED
  if (!ADMIN_SEED || !USER_SEED) throw new Error("Missing env: ADMIN_SEED, USER_SEED")

  const admin = Wallet.fromSeed(ADMIN_SEED)  // 발행자 (송신자)
  const user  = Wallet.fromSeed(USER_SEED)   // 수신자

  /**
   * MPT 전송 트랜잭션
   * - TransactionType: Payment
   * - Amount: { mpt_issuance_id, value }
   *   * mpt_issuance_id: 발행 정의 고유 ID
   *   * value: 전송 수량 (정수 문자열)
   * - DeliverMax / SendMax 도 같은 구조로 지정 가능
   */
  const tx: Transaction = {
    TransactionType: "Payment",
    Account: admin.address,
    Destination: user.address,
    Amount: {
      mpt_issuance_id: ISSUANCE_ID,  // 발행본 ID
      value: "100"                   // 전송 수량
    }
  }

  try {
    // 트랜잭션 준비 → 서명 → 제출
    const prepared = await client.autofill(tx)
    const signed   = admin.sign(prepared)
    const result   = await client.submitAndWait(signed.tx_blob)

    console.log(JSON.stringify(result, null, 2))
    return result
  } finally {
    await client.disconnect()
    console.log("🔄 연결 종료")
  }
}

// 직접 실행
if (require.main === module) {
  sendMPT().catch(e => { console.error(e); process.exit(1) })
}
TypeScript
복사

(수정필요) Step 4. 발행본 락/언락 (setIssuance.ts) + Clawback

•

주체: ADMIN

•

행동: MPTokenIssuanceSet 트랜잭션 전송

•

내용:

◦

글로벌 잠금/해제: Flags.tfMPTLock / Flags.tfMPTUnlock

◦

특정 홀더만 잠금/해제: Holder에 대상 주소 지정 + 같은 플래그 사용

◦

효과: 잠금 중에는 해당 범위 전송/사용 제한(정책에 따름)

// createIssuance 실행 로그에서 복사한 IssuanceID
const ISSUANCE_ID = "006419063CEBEB49FC20032206CE0F203138BFC59F1A####"

// ===== CLI 인자 파싱 =====
// 사용법: ts-node setIssuance.ts <lock|unlock> [holderAddress]
// - 첫 번째 인자(mode): "lock" 이면 잠금, "unlock" 이면 잠금 해제
// - 두 번째 인자(holder): 선택값. 특정 홀더만 잠그거나 풀 때 그 XRPL 주소를 넣음.
//   * holder를 생략하면 "글로벌" 적용(발행본 전체를 잠그거나 풂).
const mode = (process.argv[2] || "").toLowerCase()
const holder = process.argv[3]

// 인자 검증: lock/unlock 외 값이면 사용법 안내 후 종료(비정상 종료 코드 1)
if (mode !== "lock" && mode !== "unlock") {
  console.error('Usage: ts-node setIssuance.ts <lock|unlock> [holderAddress]')
  process.exit(1)
}

// XRPL 트랜잭션 Flags 설정
// - MPTokenIssuanceSet는 boolean 플래그로 설정 가능
//   * { tfMPTLock: true }   -> 잠금
//   * { tfMPTUnlock: true } -> 잠금 해제
const flags = mode === "lock" ? { tfMPTLock: true } : { tfMPTUnlock: true }

// ===== 트랜잭션 구성 =====
const tx: Transaction = {
  TransactionType: "MPTokenIssuanceSet",
  Account: admin.address,            // 발행자(ADMIN) 서명/전송
  MPTokenIssuanceID: ISSUANCE_ID,    // createIssuance 결과로 얻은 발행 정의 ID

  // Holder 필드는 선택값:
  // - 포함하면 "해당 홀더 주소만" 대상(개별 잠금/해제)
  // - 생략하면 발행본 전체 대상(글로벌 잠금/해제)
  ...(holder ? { Holder: holder } : {}),

  Flags: flags                       // 위에서 mode에 따라 lock/unlock 플래그 지정
}
TypeScript
복사

•

사용 방법 : 터미널 명령어 예시

# 글로벌 잠금
$npx ts-node setIssuance.ts lock

# 글로벌 잠금 해제
$npx ts-node setIssuance.ts unlock

# 특정 홀더(User)만 잠금
$npx ts-node setIssuance.ts lock <user 주소>

# 특정 홀더(User)만 잠금 해제
$npx ts-node setIssuance.ts unlock <user주소>
Bash
복사

(옵션) Step 5. 발행 정의 삭제 (destroyIssuance.ts)

•

주체: ADMIN

•

행동: MPTokenIssuanceDestroy 트랜잭션 전송

•

성공 조건: 모든 홀더의 잔액이 0이어야 함(한 명이라도 남아있으면 실패)

•

효과: 발행 정의 제거, 리저브 1 감소(소유 오브젝트 수 감소)

import { Client, Wallet, Transaction } from "xrpl"
import path from "path"
import dotenv from "dotenv"
dotenv.config({ path: path.join(__dirname, "..", ".env") })

// ⚠️ createIssuance 실행 로그에서 발급된 IssuanceID 입력
const ISSUANCE_ID = "0049CE349E4215DD8AC6196A0A5027DF489AEC3B17BD6211"

export async function destroyIssuance() {
  const client = new Client("wss://s.devnet.rippletest.net:51233")
  await client.connect()

  const ADMIN_SEED = process.env.ADMIN_SEED
  if (!ADMIN_SEED) throw new Error("Missing env: ADMIN_SEED")
  const admin = Wallet.fromSeed(ADMIN_SEED)

  /**
   * MPTokenIssuanceDestroy 트랜잭션
   * - 모든 홀더가 해당 Issuance 잔액을 0으로 만들어야 실행 가능
   * - 성공 시 발행 정의 제거 + 리저브 1 감소
   */
  const tx: Transaction = {
    TransactionType: "MPTokenIssuanceDestroy",
    Account: admin.address,           // 발행자(Admin)
    MPTokenIssuanceID: ISSUANCE_ID    // 삭제할 발행본 ID
  }

  try {
    // 트랜잭션 준비 → 서명 → 제출
    const prepared = await client.autofill(tx)
    const signed   = admin.sign(prepared)
    const result   = await client.submitAndWait(signed.tx_blob)

    console.log(JSON.stringify(result, null, 2))
    return result
  } finally {
    await client.disconnect()
    console.log("🔄 연결 종료")
  }
}

// 직접 실행
if (require.main === module) {
  destroyIssuance().catch(e => { console.error(e); process.exit(1) })
}
TypeScript
복사