hypay-adapter/README.md

Provides an XRPL payment adapter.

# hypay-adapter

XRPL 결제용 지갑 연동 모듈

## Description

XRPL 네트워크에서 Xaman, Gem 등의 지갑과 연동하여 사용자가 간편하게 결제를 진행할 수 있도록 지원하는 모듈입니다. 다양한 지갑을 감지하고 연결하며, 트랜잭션 서명을 요청할 수 있습니다.

## Xaman으로 시작하기

### 1. Xumm 개발자 계정 생성

[Xaman Developer Console](https://apps.xaman.dev/)에서 Application을 생성해주세요.

[Xaman](https://xaman.app/) 지갑을 생성하여 지갑 주소를 발급받아 주세요.

1. **Xumm 개발자 계정 생성**
   - [Xumm Dev Portal](https://apps.xumm.dev/)에 가입하여 앱 등록
   - API Key / Secret을 발급받아 `.env` 파일에 저장

## 🧪 사용 예시

## constructor

| 파라미터 이름  | 타입                                         | 설명                                |
| -------------- | -------------------------------------------- | ----------------------------------- |
| destination    | `string`                                     | 결제 트랜잭션 목적지 XRP 주소       |
| network        | `NETWORK_TYPES` (default: TESTNET)           | 네트워크 타입 (TESTNET, MAINNET 등) |
| apiCredentials | `{ key: string; secret: string }` (optional) | Xumm API 키와 시크릿 직접 전달 가능 |

**return**: 없음 (클래스 인스턴스 생성자)

---

## connect

| 파라미터 이름 | 타입 | 설명 |
| ------------- | ---- | ---- |
| 없음          | 없음 | 없음 |

**return**: `WalletTypes.WalletConnectionResult`  
지갑 주소(`address`)와 provider 이름(`providerName: 'XAMAN'`)을 반환합니다.

---

## createPaymentTx

| 파라미터 이름 | 타입     | 설명                                                        |
| ------------- | -------- | ----------------------------------------------------------- |
| amount        | `string` | 결제할 XRP 금액                                             |
| meta_data     | `object` | 사용자 정의 메타데이터 (identifier, instruction, blob 포함) |

**return**: `Promise<string>`
생성된 트랜잭션의 UUID를 반환합니다.

---

## `signAndSubmit`

| 파라미터 이름 | 타입     | 설명                   |
| ------------- | -------- | ---------------------- |
| payloadUuid   | `string` | 서명할 트랜잭션의 UUID |

**return**: `Promise<string>`  
서명 요청이 열렸는지를 나타내는 문자열 (`"Sign request opened"` 등)을 반환합니다.

---

## `getSubmittedTxResult`

| 파라미터 이름 | 타입     | 설명          |
| ------------- | -------- | ------------- |
| payloadUuid   | `string` | 트랜잭션 UUID |

**return**: `Promise<TransactionResult>`  
제출 결과 및 상태 정보를 포함한 객체 반환:

- `success`: 서명 성공 여부
- `submitted`: 제출되었는지 여부
- `resolved`: 처리 완료 여부
- `validated`: 검증 완료 여부
- `txid`: XRPL 트랜잭션 ID
- `createdAt`: 생성 시간
- `expiresAt`: 만료 시간
- `raw`: 원시 응답 데이터

---

## `request`

| 파라미터 이름 | 타입                       | 설명                                  |
| ------------- | -------------------------- | ------------------------------------- |
| _(미구현)_    | `WalletTypes.RequestParas` | 추후 구현 예정 (현재는 사용되지 않음) |

**return**: `Promise<void>`  
현재 기능 없음

---

## `respond`

| 파라미터 이름 | 타입                        | 설명                                  |
| ------------- | --------------------------- | ------------------------------------- |
| _(미구현)_    | `WalletTypes.RespondParams` | 추후 구현 예정 (현재는 사용되지 않음) |

**return**: `Promise<void>`  
현재 기능 없음

---

## `ping`

| 파라미터 이름 | 타입 | 설명 |
| ------------- | ---- | ---- |
| 없음          | 없음 | 없음 |

**return**: `Promise<{ pong: boolean }>`  
Xaman SDK와 연결 확인용 ping 결과 반환

```json
{ "pong": true } 또는 { "pong": false }
```

2. **Gem 연동**
   지원 예정