XRPL 결제 (Devnet) — Quick Start

대상: 시연/검증을 진행하는 운영자·개발자 전제: tflow-server / tflow-client 실행 중, Devnet 환경

본 문서는 /projects/:id/payment 화면(ProjectPayment)에서 마일스톤 생성 → 입금 → 에스크로 잠금 → 정산까지 e2e 시연 절차를 단계별로 안내합니다. 화면이 비어있거나 막혔을 때 어디를 점검해야 하는지도 함께 정리합니다.

0. 사전 점검 — 운영자 체크리스트

비활성 상태면 → tflow-xrpl-payment/server/scripts/tus-ops.js로 setup, 또는 Phase 1 README 참조.

1. 프로젝트 측 사전 세팅

1-1. ProjectShare에 Buyer / Seller 등록

/projects/:id/share 메뉴에서 두 사용자를 각각 다른 actor_type으로 추가:

• 사용자 A → actor_type = 'buyer'
• 사용자 B → actor_type = 'seller'

⚠️ Buyer/Seller가 등록되지 않으면 seller_user_id는 NULL로 케이스가 생성됩니다. 케이스 자체는 만들어지지만 escrow 진행 시 wallet 주소가 비어있어 lock-funds가 실패합니다. 마일스톤 추가는 가능하지만 실 결제 흐름은 두 역할 등록 후에 가능합니다.

1-2. 각 사용자의 XRPL 지갑 활성화 (Devnet)

각 시연자가 별도 브라우저 / 시크릿 창에서:

1. Crossmark 익스텐션 설치 (crossmark.io)
2. 새 지갑 생성 → 주소 확보 (예: r9uEmgPLHMNZS8AHH62zm5whEVYXRn5vPJ)
3. Devnet faucet으로 활성화:

   curl -X POST https://faucet.devnet.rippletest.net/accounts \
     -H "Content-Type: application/json" \
     -d '{"destination":"<지갑주소>"}'
   

   → 100 XRP 입금 + 계정 활성화

1-3. 호스트 UI에서 지갑 등록

각 시연자가 /projects/:id/payment → 검증(요청) 또는 검증(발급) 탭 → 지갑 연결 버튼:

• Crossmark 팝업에서 sign-in 승인
• 시스템이 자동으로 TUS TrustLine 설정 팝업 띄움 → 서명 (1회)
• "지갑이 등록되었습니다" 토스트

1-4. Buyer에게 TUS 토큰 발행 (운영자)

운영자가 한 줄 명령:

cd tflow-xrpl-payment/server
node scripts/tus-ops.js issue <Buyer-주소> 1000

→ Buyer 지갑에 1000 TUS 발행. 잔고 확인:

node scripts/tus-ops.js balance <Buyer-주소>

⚠️ 1-3 (Buyer가 TrustLine 설정)을 먼저 끝낸 후에 발행해야 함. 안 끝났으면 발행 트랜잭션이 tecPATH_DRY 등으로 거부됨.

2. 결제 시연 흐름

2-1. 마일스톤(케이스) 생성

/projects/:id/payment → 정산 대시보드 탭:

1. 빈 화면 가운데 "마일스톤 추가" 버튼 클릭
2. 모달: 마일스톤 이름 (예: "선급 30%"), 금액 (예: 100), 비율 (30), 일자 입력
3. 생성 → 첫 케이스 등록, status = DRAFT

2-2. Buyer가 입금 (Deposit)

검증(발급) 탭 (Buyer 권한이면 자동) → "토큰 입금" 액션:

1. Crossmark 팝업 → Payment 트랜잭션 서명 (Buyer → TFlow Escrow Agent)
2. 서버: confirm-funding API 호출 → status DRAFT → FUNDED
3. devnet.xrpl.org에서 트랜잭션 확인 (TX hash UI에 표시됨)

2-3. 자동 에스크로 잠금 (Lock)

XrplEscrowJob 워커가 30초 주기로 FUNDED 케이스를 찾아 자동으로 EscrowCreate 실행:

• 30초 이내에 status FUNDED → ESCROW_OPEN
• TFlow Oracle 지갑이 IOU를 escrow에 잠금 (Crypto-Condition 보안)
• DB에 escrow_sequence, escrow_condition, escrow_fulfillment 저장

기다리지 않고 즉시 잠그려면 (옵션):

curl -X POST http://localhost:3000/api/payment/cases/<case-uuid>/lock-funds \
  -H "Authorization: Bearer <token>"

2-4. Seller 문서 업로드 + Buyer 승인 → Release

검증(요청) 탭 (Seller) → 문서 업로드 → AI 검증 → "승인 요청"

검증(발급) 탭 (Buyer) → "Approve" → 서버 EscrowFinish 실행:

• status ESCROW_OPEN → RELEASED
• Seller 지갑에 IOU 입금 (잔고 확인: node scripts/tus-ops.js balance <Seller-주소>)

2-5. (옵션) 환불 시연

기본 cancelAfterSeconds = 7일 이라 즉시 환불 불가. 시연 시:

# tflow-server/.env
XRPL_ESCROW_CANCEL_AFTER_SECONDS=60

재시작 후 새 케이스 생성 → 60초 후 "Refund" 버튼 → EscrowCancel → 자금 TFlow로 회수 → Buyer로 Payment.

3. 시연 종료 후 정리 (운영자)

각 시연자가 보유한 TUS는 Devnet의 임시 토큰이라 폐기해도 무방하지만, 같은 지갑을 다음 시연에 재사용하려면 Issuer로 회수 가능:

node scripts/tus-ops.js return <holder-seed> <amount>

→ holder의 TUS가 Issuer로 송금되어 자동 burn.

4. 자주 막히는 지점 — 트러블슈팅

5. Mainnet 전환은 별도

본 가이드는 Devnet 전용. Mainnet RLUSD escrow는 Ripple이 RLUSD issuer 계정에 asfAllowTrustLineLocking flag를 활성화한 이후에 가능 (현재 미활성). 사전 준비 항목은 260506-xrpl-스타일링/README.md Phase 4 참조.

6. 관련 도구 / 파일

• 운영 스크립트: tflow-xrpl-payment/server/scripts/tus-ops.js
• e2e dry-run: tflow-xrpl-payment/server/scripts/dry-run.js
• 데모 화면 (mock): /demo/payment, /demo/pof (히든 라우트)
• 운영 화면: /projects/:id/payment