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

📦 주요 기능(폴더)별 README

TokenEscrow

About XRPL

XRPL Dev Source

Program Q&A

TokenEscrow

주요 내용

토큰 예치·해제

폴더명

TokenEscrow

스크립트 실행 명령어

#1) MPT로 에스크로 생성하기
$npx ts-node xrpl/TokenEscrow/escrowCreateMPT.ts
#createIssuance 실행 결과에서 복사한 MPT IssuanceID(48hex)를 넣어줘야 함.
#const ISSUANCE_ID = "0049CE349E4215DD8AC6196A0A5027DF489AEC3B17BD6211"

#2) IOU로 에스크로 생성하기 (Admin 계정에 17번 플래그로 AccountSet 필수)
$npx ts-node xrpl/TokenEscrow/escrowCreateIOU.ts

생성이 되면, EscrowCreate(MPT User→User2) -> Owner=<User주소>, OfferSequence=123456 라고 뜨는데, 
여기서 OfferSequence를 기록해 3,4번 스크립트에 사용

#3) 에스크로 끝내기 (조건 끝나기 전에는 안됨)
$npx ts-node xrpl/TokenEscrow/escrowFinish.ts

#4) 에스크로 취소하기 (조건 끝나기 전에는 안됨)
$npx ts-node xrpl/TokenEscrow/escrowCancel.ts
Bash
복사

1. TokenEscrow란?

TokenEscrow는 XRPL의 기존 XRP 전용 Escrow 기능을 확장해,

IOU 토큰과 MPT(Multi-Purpose Token)도 에스크로에 걸 수 있게 하는 기능이다.

토큰 타입별 특징:

•

IOU

◦

발행자와 보유자 간 Trustline 필요

◦

발행자 정책: RequireAuth, Freeze, TransferRate

◦

Escrow 허용 플래그: lsfAllowTrustLineLocking : 17

•

MPT

◦

Trustline 없음

◦

발행자 정책: RequireAuth, Lock, TransferFee

◦

Escrow 허용 플래그: tfMPTCanEscrow (MPTokenIssuance 트랜잭션에 명시해야 Escrow 가능)

◦

전송 가능 플래그: tfMPTCanTransfer (MPTokenIssuance 트랜잭션에 명시, 없으면 발행자에게만 전송 가능)

2. 왜 필요한가?

•

자산 잠금 지원 확대

◦

XRP뿐 아니라, 발행 토큰(스테이블코인·포인트·권리증서 등)도 에스크로 가능.

•

정산 예측성 보장

◦

Escrow 생성 시점의 TransferRate/TransferFee를 고정, 이후 변경에도 영향을 받지 않음.

•

발행자 정책 준수

◦

RequireAuth·Freeze·Lock 등의 제어가 Escrow에도 동일하게 적용.

•

다양한 시나리오 지원

◦

계약금, 지급 보류, 조건부 지급, 베스팅(vesting) 등에 IOU/MPT 사용 가능.

3. 시나리오: escrowCreate → escrowFinish → (옵션) escrowCancel

Step 1. 에스크로 생성 (escrowCreate.ts)

•

주체: 송금자(Source) : User

•

행동: EscrowCreate 트랜잭션 전송

•

Amount 형식:

◦

XRP: drops 문자열

◦

IOU/MPT: CurrencyAmount 객체

•

필수 조건:

◦

IOU/MPT → CancelAfter 필수

◦

발행자가 Source이면 불가

◦

발행자 Escrow 허용 플래그 설정 필요

◦

Source가 RequireAuth 토큰이면 사전 승인 필요

◦

Source 잔액·Trustline·Authorize 상태 정상

+주의할 점 : IOU의 경우 Escrow 생성하기 전에 Admin 계정에 17번 플래그(asfAllowTrustLineLocking)로 accountSet을 해 줘야 함!

잘 안되면 : https://xspence.co.uk/devnet 에서 AccountSet 하면 됨.

import { Client, Wallet, Transaction } from "xrpl"
import { encodeForSigning, encode } from "ripple-binary-codec"
import { sign as kpSign, deriveKeypair } from "ripple-keypairs"
import path from "path"
import dotenv from "dotenv"
dotenv.config({ path: path.join(__dirname, "..", ".env") })

// XRPL 리플 에폭 시간 변환
function Now() {
  return Math.floor(Date.now() / 1000) - 946_684_800
}

export async function escrowCreateMPT() {
  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!
  const USER2_SEED = process.env.USER2_SEED!
  const admin = Wallet.fromSeed(ADMIN_SEED)  // MPT 발행자(참조용)
  const user  = Wallet.fromSeed(USER_SEED)   // Escrow 소스
  const user2 = Wallet.fromSeed(USER2_SEED)  // Escrow 목적지

  try {
    // ⚠️ createIssuance 실행 결과에서 복사한 MPT IssuanceID(48hex)
    const ISSUANCE_ID = "0049CE349E4215DD8AC6196A0A5027DF489AEC3B17BD6211"

    // 📝 EscrowCreate 트랜잭션 (MPTAmount 사용)
    const tx: Transaction = {
      TransactionType: "EscrowCreate",
      Account: user.address,      // 소스(User)
      Destination: user2.address, // 목적지(User2)
      Amount: {
        mpt_issuance_id: ISSUANCE_ID,
        value: "50"               // 전송 수량
      } as any,                   // XRPL SDK에서 MPTAmount 미지원 → any 처리
      FinishAfter: Now() + 30,    // 최소 완료 시각 (30초 후)
      CancelAfter: Now() + 120    // 취소 가능 시각 (120초 후)
    }

    // 1) autofill → 기본 필드 채움 (Sequence, Fee 등)
    const prepared = await client.autofill(tx)

    // 2) 서명 대상 객체에 SigningPubKey를 넣음
    const toSign = {
      ...prepared,
      SigningPubKey: user.publicKey,
    }

    // 3) seed 기반 keypair 생성
    const { privateKey } = deriveKeypair(USER_SEED)

    // 4) 프리픽스 포함 데이터 서명
    const signingData = encodeForSigning(toSign as any)
    const signature   = kpSign(signingData, privateKey)

    // 5) 최종 트랜잭션에 TxnSignature 추가 후 인코딩
    const signedTx = { ...toSign, TxnSignature: signature }
    const tx_blob  = encode(signedTx)

    // 6) 제출 & 결과 확인
    const result = await client.submitAndWait(tx_blob)

    console.log(JSON.stringify(result, null, 2))
    console.log(`✅ EscrowCreate(MPT) 성공: Owner=${user.address}, OfferSequence=${prepared.Sequence}`)

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

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

•

서명 방식 : xrpl.js가 아직 EscrowCreate의 Amount를 “XRP 문자열”로만 검증/직렬화하려고 해서 IOU/MPT 객체 넣으면 클라이언트에서 막혀 Invalid signature가 남.

•

그래서 raw 서명(encodeForSigning + ripple-keypairs.sign) 으로 검증/직렬화를 우회하면 서버가 그대로 받아서 정상 처리.

//기존 방식
const prepared = await client.autofill(tx)
const signed   = user.sign(prepared)
const result   = await client.submitAndWait(signed.tx_blob)
TypeScript
복사

//TokenEscrow에서 사용해야 하는 서명 방식
import { encodeForSigning, encode } from "ripple-binary-codec"
import { sign as kpSign, deriveKeypair } from "ripple-keypairs"

const prepared = await client.autofill(tx)
// 1) 서명 대상 객체에 SigningPubKey를 "미리" 넣는다
const toSign = {
...prepared,
SigningPubKey: user.publicKey,   // 보통 'ED...' 33바이트(hex)
}   
// 2) seed로 keypair 파생 (★ Wallet.privateKey 대신, seed→derive 사용)
const { privateKey, publicKey } = deriveKeypair(USER_SEED)
// 3) 서명 (프리픽스 자르지 말고 그대로 전달)
const signingData = encodeForSigning(toSign as any)
const signature   = kpSign(signingData, privateKey)
// 4) 최종 인코딩 & 제출
const signedTx = { ...toSign, TxnSignature: signature }
const tx_blob  = encode(signedTx)
const result = await client.submitAndWait(tx_blob)
TypeScript
복사

•

콘솔 출력 예시

EscrowCreate(MPT User→User2) -> Owner=<User주소>, OfferSequence=123456
Bash
복사

Step 2. 에스크로 해제 (escrowFinish.ts)

•

주체: 누구나(조건 충족 시)

•

행동: EscrowFinish 트랜잭션 전송

•

필수 조건:

◦

FinishAfter 시간 경과

◦

Destination이 RequireAuth이면 사전 승인 필요

◦

IOU → Trustline 존재 / MPT → 토큰 보유 또는 자동 생성 가능

◦

Freeze/Lock 상태 체크

•

상태 변화:

◦

잔액 이동: 발행자/수신자 조합에 따라 EscrowedAmount, OutstandingAmount 처리 규칙 다름

◦

Escrow 객체 삭제

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

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

  // 🔑 지갑 로드
  const USER_SEED  = process.env.USER_SEED!   // Escrow 소스(User)
  const USER2_SEED = process.env.USER2_SEED!  // 목적지(User2, Finisher)

  const ownerWallet    = Wallet.fromSeed(USER_SEED)   // Escrow 소스
  const finisherWallet = Wallet.fromSeed(USER2_SEED)  // Finish 실행자

  try {
    // ⚠️ EscrowCreate 실행 후 콘솔에 출력된 Sequence 값으로 교체
    const OFFER_SEQUENCE = 4836805

    // 📝 EscrowFinish 트랜잭션
    const tx: Transaction = {
      TransactionType: "EscrowFinish",
      Account: finisherWallet.address,  // 실행자(보통 수혜자 User2)
      Owner: ownerWallet.address,       // Escrow 원 소스 주소
      OfferSequence: OFFER_SEQUENCE     // EscrowCreate 시퀀스 번호
    }

    // 자동 필드 채움 → 서명 → 제출
    const prepared = await client.autofill(tx)
    const signed   = finisherWallet.sign(prepared)
    const result   = await client.submitAndWait(signed.tx_blob)

    console.log(JSON.stringify(result, null, 2))
    console.log(`✅ EscrowFinish 성공: Owner=${ownerWallet.address}, OfferSequence=${OFFER_SEQUENCE}`)
    return result
  } finally {
    await client.disconnect()
    console.log("🔄 연결 종료")
  }
}

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

Step 3. 에스크로 취소 (escrowCancel.ts)

•

주체: 누구나(조건 충족 시)

•

행동: EscrowCancel 트랜잭션 전송

•

필수 조건:

◦

CancelAfter 경과

◦

Source Authorize·Trustline/MPT 보유 상태 정상

◦

Freeze/Lock 상태는 취소 가능

•

상태 변화:

◦

잔액 반환

◦

Escrow 객체 삭제

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

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

  // 🔑 환경변수에서 시드 로드
  const USER_SEED  = process.env.USER_SEED!   // Escrow 소스(User)
  const USER2_SEED = process.env.USER2_SEED!  // Cancel 실행자(User2)

  // 🪪 Escrow 소스(Owner) / Cancel 실행자 계정 생성
  const ownerWallet     = Wallet.fromSeed(USER_SEED)
  const cancellerWallet = Wallet.fromSeed(USER2_SEED)

  try {
    /**
     * ⚠️ EscrowCreate 실행 후 반환된 "Sequence"를 OFFER_SEQUENCE에 넣어야 함
     * - EscrowCancel은 Escrow를 생성한 원래 트랜잭션(Sequence)와 Owner 주소를 지정해야 유효
     */
    const OFFER_SEQUENCE = 4836805

    const tx: Transaction = {
      TransactionType: "EscrowCancel",
      Account: cancellerWallet.address, // Cancel 실행자(= 트랜잭션 서명 주체)
      Owner: ownerWallet.address,       // Escrow 소스(원래 Escrow 만든 계정)
      OfferSequence: OFFER_SEQUENCE     // EscrowCreate의 Sequence
    }

    // 트랜잭션 준비 → 서명 → 제출
    const prepared = await client.autofill(tx)
    const signed   = cancellerWallet.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) {
  escrowCancel().catch(e => { console.error(e); process.exit(1) })
}
TypeScript
복사