@nexus-cross/pop 1.3.10-beta.2 → 1.4.0-beta.2

package/dist/{createSafeDrop-qoNG59jB.d.ts → createSafeDrop-CayUX4w_.d.ts}

@@ -1,6 +1,6 @@
 /** 0x-prefixed 주소. viem Address에 의존하지 않는 도메인 표현. */
 type Address = string;
-/** 0x-prefixed hex 문자열 (서명/salt/digest/해시 등). */
+/** 0x-prefixed hex 문자열 (서명/digest/drop key/해시 등). */
 type Hex = string;
 /** 소셜 식별자 string (컨트랙트 `id`). 예: 'theo_13303'. */
 type Id = string;
@@ -28,7 +28,7 @@ interface DepositParams {
     token: Address;
     /** raw 토큰 수량 (wei-scale). BigInt 유지. */
     amount: bigint;
-    /** 비밀 문구. 미지정 시 CryptoPort.randomSecret()로 생성. (expiry는 계약이 결정.) */
+    /** 비밀 문구. 미지정 시 CryptoPort.randomSecret()로 생성. */
     secret?: Secret;
     /**
      * 수령인에게 보여줄 메시지 (최대 140 runes). 컨트랙트에는 필드가 없고
@@ -38,7 +38,8 @@ interface DepositParams {
     /** 카드 디자인 id. 목록은 `listEnvelopes()` (GET /envelopes). */
     envelopeId?: string;
 }
-interface DepositResult {
+interface UnmappedDepositResult {
+    readonly isMapped: false;
     /** 컨트랙트에 커밋된 임시 claim 지갑 주소 = 이 드롭의 키. */
     readonly claimAddress: Address;
     readonly secretHash: SecretHash;
@@ -46,7 +47,14 @@ interface DepositResult {
     readonly withdrawLink: string;
     readonly depositTxHash: Hex;
 }
+interface MappedDepositResult {
+    readonly isMapped: true;
+    readonly depositTxHash: Hex;
+}
+type DepositResult = UnmappedDepositResult | MappedDepositResult;
 interface WithdrawParams {
+    /** 링크의 sender query 값 = 온체인 sponsor. */
+    sponsor: Address;
     /** 수령 주소 — 수령인 본인이 지정. 서명에 바인딩된다. */
     recipient: Address;
     /** X OAuth 검증 후 백엔드에서 받은 임시 claim 지갑 주소. drops() 조회 키. */
@@ -60,7 +68,9 @@ interface WithdrawResult {
     readonly txHash: Hex;
 }
 interface RefundParams {
-    /** 환불할 드롭의 claimAddr. 만료 후 sponsor(msg.sender)만 호출 가능. */
+    /** 드롭 sponsor. */
+    sponsor: Address;
+    /** 환불할 드롭의 claimAddr. sponsor(msg.sender)만 호출 가능. */
     claimAddress: Address;
 }
 interface RefundResult {
@@ -71,6 +81,14 @@ interface BatchClaimParams {
     id: Id;
     /** 핸들 소유 증명용 X OAuth 토큰. 서명 발급의 전제. */
     oauth: OAuthProof;
+    /** anchor drop의 sponsor(링크 sender). */
+    sponsor: Address;
+    /** 첫 unmapped 드롭의 임시 claim 지갑 주소. */
+    claimAddress: Address;
+    /** 첫 드롭 링크 fragment의 secret. */
+    secret: Secret;
+    /** 첫 드롭의 임시 claim 개인키. */
+    claimKey: Hex;
     /**
      * 기대하는 수령 주소. 서명은 **SIWE 인증 주소**에 바인딩되므로, 다르면
      * `SIGN_FAILED`로 끊는다(다른 주소로 받으려면 그 주소로 SIWE 로그인).
@@ -81,11 +99,11 @@ interface BatchClaimParams {
     deadline?: bigint;
     /** deadline 자동 계산용 TTL(초). 기본 1800. */
     deadlineTtlSeconds?: bigint;
-    /** tx 1건이 처리할 드롭 수(서명 대상 아님 — 페이지 크기). 기본 30. */
+    /** tx 한 건에 포함할 drop key 수. 기본 30. 호출마다 새 validator 서명을 받는다. */
     maxCount?: number;
 }
 interface BatchClaimResult {
-    /** 페이지별 tx hash. 드롭이 maxCount 이하면 1건. */
+    /** 현재 batch 호출의 tx hash(호환을 위해 배열 유지). */
     readonly txHashes: readonly Hex[];
     /** 실제로 서명에 바인딩된 수령 주소. */
     readonly recipient: Address;
@@ -93,7 +111,7 @@ interface BatchClaimResult {
     readonly nonce: bigint;
     readonly deadline: bigint;
 }
-type SafeDropErrorCode = 'MISSING_SENDER' | 'MISSING_RECIPIENT' | 'MISSING_SECRET' | 'MISSING_CLAIM_KEY' | 'MISSING_CLAIM_ADDRESS' | 'INVALID_AMOUNT' | 'INVALID_TOKEN' | 'DROP_NOT_FOUND' | 'SECRET_MISMATCH' | 'SIGN_FAILED' | 'CHAIN_ERROR' | 'API_ERROR' | 'INVALID_PARAM' | 'RATE_LIMITED' | 'INVALID_OAUTH_TOKEN' | 'UNAUTHORIZED' | 'WALLET_NOT_FOUND' | 'SEND_BLOCKED' | 'ENVELOPE_NOT_FOUND' | 'PENDING_LIMIT_EXCEEDED' | 'X_CONNECTION_NOT_FOUND';
+type SafeDropErrorCode = 'MISSING_SENDER' | 'MISSING_RECIPIENT' | 'MISSING_SECRET' | 'MISSING_CLAIM_KEY' | 'MISSING_CLAIM_ADDRESS' | 'INVALID_AMOUNT' | 'INVALID_TOKEN' | 'DROP_NOT_FOUND' | 'SECRET_MISMATCH' | 'SIGN_FAILED' | 'CHAIN_ERROR' | 'API_ERROR' | 'INVALID_PARAM' | 'RATE_LIMITED' | 'INVALID_OAUTH_TOKEN' | 'UNAUTHORIZED' | 'WALLET_NOT_FOUND' | 'SEND_BLOCKED' | 'ENVELOPE_NOT_FOUND' | 'PENDING_LIMIT_EXCEEDED' | 'IDENTIFIER_NOT_MAPPED' | 'X_CONNECTION_NOT_FOUND';
 declare class SafeDropError extends Error {
     readonly code: SafeDropErrorCode;
     readonly details?: Record<string, unknown>;
@@ -108,6 +126,9 @@ interface XConnection {
     readonly profileImageUrl: string;
     /** SIWE 인증 주소. 본문으로 고를 수 없다. */
     readonly walletAddress: Address;
+    readonly revealYou: boolean;
+    readonly onchainMapped: boolean;
+    readonly mappedRecipient: Address | null;
 }
 /** 드롭을 보낸 sponsor. X 연결이 없으면 handle/displayName/profileImageUrl은 빈 문자열. */
 interface DropSender {
@@ -118,6 +139,10 @@ interface DropSender {
 }
 /** GET /drops의 개별 항목. claimAddress로 개별 수령(withdraw)을 진행한다. */
 interface PendingDrop {
+    /** 백엔드 drop id. feedback 등록에 사용한다. */
+    readonly id: number;
+    /** 현재 컨트랙트의 bytes32 drop key. */
+    readonly dropKey: Hex;
     readonly claimAddress: Address;
     readonly token: Address;
     /** raw 토큰 수량 (wei-scale). */
@@ -138,6 +163,8 @@ interface DropInbox {
     readonly totalAmount: bigint;
     /** 첫 수령은 개별 claim만 허용 — 일괄 수령 CTA 게이트. */
     readonly hasClaimedBefore: boolean;
+    readonly mappedRecipient: Address | null;
+    readonly pendingChangeTo: Address | null;
 }
 /** GET /envelopes — 카드 디자인. 공개 엔드포인트. */
 interface Envelope {
@@ -147,30 +174,50 @@ interface Envelope {
     readonly badge: string;
     readonly sortOrder: number;
 }
-/** GET /leaderboards — identifier별 pending 잔액 상위(최대 10). 공개 엔드포인트. */
+/** GET /leaderboards — identifier별 pending 잔액. */
 interface LeaderboardEntry {
     readonly identifier: string;
     /** 수령 가능(pending) 합계 (wei-scale). */
     readonly balance: bigint;
     /** 최근 Deposited 금액 (wei-scale). */
     readonly lastDepositAmount: bigint;
+    readonly rank: number;
+    readonly previousRank: number | null;
+    readonly profileImageUrl: string;
+}
+interface LeaderboardPage {
+    readonly items: readonly LeaderboardEntry[];
+    readonly page: number;
+    readonly pageSize: number;
+    readonly total: number;
+}
+interface MyLeaderboardEntry extends Omit<LeaderboardEntry, 'rank'> {
+    readonly rank: number | null;
+}
+type HistoryType = 'sent' | 'received';
+interface HistoryParty {
+    readonly address: Address;
+    readonly handle: string;
+    readonly displayName: string;
+    readonly profileImageUrl: string;
 }
-type PopEventName = 'Deposited' | 'Withdrawn' | 'Refunded' | 'BatchWithdrawn';
-/** GET /histories 항목. 이벤트가 담지 않는 주소는 null. */
+/** GET /histories의 drop 중심 항목. */
 interface HistoryEntry {
-    readonly eventName: PopEventName | (string & {});
-    readonly txHash: Hex;
-    readonly blockNumber: number;
-    readonly logIndex: number;
-    readonly contractAddress: Address;
-    readonly fromAddress: Address | null;
-    readonly toAddress: Address | null;
-    readonly tempTo: Address | null;
-    readonly identifier: string;
-    /** wei-scale. */
+    readonly id: number;
+    readonly type: HistoryType;
+    readonly status: string;
+    readonly token: Address;
     readonly amount: bigint;
-    readonly createdAt: string;
-    readonly payload?: Record<string, unknown>;
+    readonly claimAddress: Address;
+    readonly depositTxHash: Hex;
+    readonly depositedAt: string;
+    readonly resolvedTxHash: Hex | null;
+    readonly resolvedAt: string | null;
+    readonly message: string;
+    readonly feedback: string | null;
+    readonly envelopeId: string;
+    readonly sender: HistoryParty;
+    readonly receiver: HistoryParty;
 }
 interface HistoryPage {
     readonly items: readonly HistoryEntry[];
@@ -182,8 +229,7 @@ interface HistoryPage {
 /**
  * POST /batch-claim-signature 결과 — EIP-712 ValidatorClaim 서명.
  * recipient는 항상 Bearer 토큰의 SIWE 주소다(본문으로 못 고른다).
- * 같은 id의 live 드롭이 모두 빠질 때까지 페이지네이션된 온체인 호출에
- * **재사용**한다 — 페이지마다 다시 발급받지 않는다.
+ * 서명은 성공한 온체인 호출 1건마다 nonce와 함께 소비된다.
  */
 interface BatchClaimSignature {
     readonly id: Id;
@@ -192,6 +238,15 @@ interface BatchClaimSignature {
     readonly deadline: bigint;
     readonly signature: Hex;
 }
+interface RecipientSignature {
+    readonly id: Id;
+    readonly nonce: bigint;
+    readonly deadline: bigint;
+    readonly signature: Hex;
+}
+interface RecipientChangeSignature extends RecipientSignature {
+    readonly newRecipient: Address;
+}
 
 /**
  * 순수 계산이 아니라 외부 구현(해시 라이브러리/CSPRNG)이 필요한 암호 연산.
@@ -229,27 +284,30 @@ interface SafeDropApiPort {
     createClaimWallet(params: {
         sender: Address;
         recipient: SocialIdentifier;
-        /** 수령인에게 보여줄 메시지 (≤140 runes, 백엔드 저장 전용). */
-        message?: string;
-        /** 카드 디자인 id (GET /envelopes). */
-        envelopeId?: string;
     }): Promise<{
         claimAddress: Address;
+        id: Id;
+        isMapped: boolean;
     }>;
+    /** Associate off-chain card metadata after the deposit transaction is broadcast. */
+    recordDropMetadata?(params: {
+        txHash: Hex;
+        message?: string;
+        envelopeId?: string;
+    }): Promise<void>;
     /**
      * Withdraw: X OAuth 검증 후 복호화된 임시 claim 개인키 반환 (point of return).
-     * dropId가 아니라 (sender_address + OAuth 토큰 소유자의 identifier) 조합으로
-     * 해당하는 최신 pending 지갑 키를 찾는다 — one-pop-api /wallets/private-key.
-     *
-     * ⚠️ 한 (sender, identifier)에 pending 드롭이 여러 개 있을 수 있다(백엔드가
-     * 중복 제한을 풀었다). 이 엔드포인트는 그중 **최신 1건**만 돌려주고 특정
-     * claimAddress를 고르는 파라미터가 없다 — 같은 sender가 보낸 여러 드롭은
-     * 링크마다 순차로 수령해야 한다. 전체 목록은 `listDrops()`로 본다.
+     * claimAddress로 특정 pending 지갑을 선택하고 OAuth 토큰으로 handle 소유권을
+     * 증명한다 — one-pop-api /wallets/private-key.
      */
     retrieveClaimKey(params: {
+        claimAddress: Address;
         senderAddress: Address;
         oauth: OAuthProof;
     }): Promise<{
+        isMapped: true;
+    } | {
+        isMapped: false;
         claimKey: Hex;
         claimAddress: Address;
     }>;
@@ -261,13 +319,20 @@ interface SafeDropApiPort {
     listEnvelopes?(params?: {
         locale?: string;
     }): Promise<readonly Envelope[]>;
-    /** GET /leaderboards — 토큰별 pending 잔액 상위. 공개(인증 불필요). */
+    /** GET /leaderboards — 토큰별 pending 잔액. 공개(인증 불필요). */
     getLeaderboard?(params: {
         token: Address;
-    }): Promise<readonly LeaderboardEntry[]>;
+        page?: number;
+        pageSize?: number;
+        identifier?: string;
+    }): Promise<LeaderboardPage>;
+    getMyLeaderboardEntry?(params: {
+        token: Address;
+    }): Promise<MyLeaderboardEntry>;
     /** GET /histories — 내가 sender이거나 최종 수령인인 온체인 이벤트. Bearer JWT. */
-    listHistories?(params?: {
-        event?: PopEventName;
+    listHistories?(params: {
+        type: HistoryType;
+        token?: Address;
         /** 1-based (기본 1). */
         page?: number;
         /** 기본 20, 최대 100. */
@@ -281,6 +346,25 @@ interface SafeDropApiPort {
     }): Promise<XConnection>;
     /** DELETE /x-connections — 연결 해제. 이미 없으면 조용히 성공(idempotent). */
     disconnectX?(): Promise<void>;
+    submitFeedback?(params: {
+        dropId: number;
+        message: string;
+    }): Promise<string>;
+    setRevealYou?(params: {
+        revealYou: boolean;
+    }): Promise<boolean>;
+    requestRecipientChangeSignature?(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientChangeSignature>;
+    requestRecipientResetSignature?(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientSignature>;
     /**
      * POST /batch-claim-signature — 일괄 수령용 EIP-712 ValidatorClaim 서명.
      * nonce/deadline은 호출자가 정한다. nonce는 컨트랙트
@@ -296,25 +380,20 @@ interface SafeDropApiPort {
     }): Promise<BatchClaimSignature>;
 }
 
-/**
- * drops(claimAddr) 결과 매핑.
- *
- * ⚠️ 배포본마다 `drops`의 반환 필드 수가 다르다(permit 배포본은 5개 —
- * sponsor/amount/secretHash/salt/id). 그래서 `token`·`expiry`는 **optional**이다:
- * - `token` — 5필드 배포본에서는 에스크로의 `token()`으로 채운다(단일 토큰 고정).
- * - `expiry` — 5필드 배포본은 노출하지 않는다 → `undefined`. 만료 판정에 쓰기 전에
- *   존재 여부를 확인해야 한다(없다고 만료가 아니라, 알 수 없다는 뜻).
- */
-interface DropState {
-    claimAddress: Address;
+/** Current ONEpop drop record, keyed by bytes32 rather than claim wallet. */
+interface OnePopDrop {
+    dropKey: Hex;
     sponsor: Address;
-    token?: Address;
     amount: bigint;
-    expiry?: number;
+    claimAddress: Address;
+    recipient: Address;
     secretHash: SecretHash;
-    salt: Hex;
     id: Id;
 }
+interface DropState extends OnePopDrop {
+    /** ONEpop escrow is single-token; token() is contract-wide. */
+    token: Address;
+}
 /**
  * SafeDrop 컨트랙트 상호작용. 어댑터는 자신의 컨트랙트 주소를 알고 있으므로
  * approve의 spender 등은 받지 않는다. 쓰기는 receipt 확인 후 tx hash 반환.
@@ -322,101 +401,124 @@ interface DropState {
  * ABI: src/infrastructure/safedrop_abi.json.
  */
 interface SafeDropChainPort {
-    /** drops(claimAddr). 없으면 null. */
-    getDrop(claimAddress: Address): Promise<DropState | null>;
-    /** claimDigest(recipient, id, salt) — 서명 대상 bytes32. */
+    getDropByKey(dropKey: Hex): Promise<OnePopDrop | null>;
+    getDropKeyByClaimAddress(claimAddress: Address, sponsor: Address): Promise<Hex | null>;
+    getClaimedRecipient(params: {
+        id: Id;
+    }): Promise<Address>;
+    getPendingDropsById(params: {
+        id: Id;
+    }): Promise<readonly OnePopDrop[]>;
+    getPendingDropsByRecipient(params: {
+        recipient: Address;
+    }): Promise<readonly OnePopDrop[]>;
+    getPendingDropsBySponsor(params: {
+        sponsor: Address;
+    }): Promise<readonly OnePopDrop[]>;
+    /** activeDropOf(claimAddr) → drops(dropKey). 없으면 null. */
+    getDrop(claimAddress: Address, sponsor: Address): Promise<DropState | null>;
+    /** claimDigest(recipient, id, dropKey) — 서명 대상 bytes32. */
     getClaimDigest(params: {
         recipient: Address;
         id: Id;
-        salt: Hex;
-    }): Promise<Hex>;
-    /** ERC20 approve (spender = SafeDrop 컨트랙트). 연결된 지갑이 서명. */
-    approve(params: {
-        token: Address;
-        amount: bigint;
+        dropKey: Hex;
     }): Promise<Hex>;
-    /** deposit(claimAddr, token, amount, id, secretHash). sponsor = msg.sender. */
-    deposit(params: {
+    /**
+     * EIP-2612 permit 예치 — 현재 ONEpop deposit의 유일한 형태다.
+     * 서명(typed data)·deadline·v/r/s는 전부 어댑터 내부 관심사다.
+     */
+    depositWithPermit(params: {
         claimAddress: Address;
         token: Address;
         amount: bigint;
         id: Id;
         secretHash: SecretHash;
+        onSubmitted?: (txHash: Hex) => void | Promise<void>;
     }): Promise<{
         txHash: Hex;
     }>;
-    /**
-     * EIP-2612 permit 예치 — approve tx 없이 서명 1회 + tx 1회로 끝낸다.
-     * permit 예치를 지원하는 배포본에서만 구현되는 optional 경로: 존재하면
-     * DepositUseCase가 approve+deposit 대신 이걸 쓴다.
-     * 서명(typed data)·deadline·v/r/s는 전부 어댑터 내부 관심사다.
-     */
-    depositWithPermit?(params: {
-        claimAddress: Address;
+    depositMapped(params: {
         token: Address;
         amount: bigint;
         id: Id;
-        secretHash: SecretHash;
+        onSubmitted?: (txHash: Hex) => void | Promise<void>;
     }): Promise<{
         txHash: Hex;
     }>;
-    /**
-     * withdraw(recipient, id, salt, signature, secret). claimAddr는 서명 recover로
-     * 도출. tx는 claimKey 임시 지갑이 직접 전송 — estimateGas 없이 고정 gas +
-     * dynamic fee(type-2)로 보내 컨트랙트 gas-abstraction 대납을 받는다.
-     */
-    withdraw(params: {
+    withdrawUnmapped(params: {
         claimKey: Hex;
         recipient: Address;
         id: Id;
-        salt: Hex;
-        signature: Hex;
+        dropKey: Hex;
         secret: Secret;
+        signature?: Hex;
+        onSubmitted?: (txHash: Hex) => void | Promise<void>;
     }): Promise<Hex>;
-    /** refund(claimAddr). 만료 후 sponsor(msg.sender)만. */
-    refund(params: {
-        claimAddress: Address;
+    withdrawMapped(params: {
+        dropKey: Hex;
+        onSubmitted?: (txHash: Hex) => void | Promise<void>;
     }): Promise<Hex>;
-    /** validatorNonceById(keccak256(utf8(id))). id 해싱은 어댑터 책임. */
-    getValidatorNonce?(params: {
-        id: Id;
-    }): Promise<bigint>;
-    /**
-     * validatorClaimDigest(recipient, id, nonce, deadline) — 온체인 EIP-712 다이제스트.
-     * 로컬 재조립 대신 이 값을 읽어 백엔드 서명을 검증한다.
-     */
-    getValidatorClaimDigest?(params: {
+    batchWithdrawMapped(params: {
+        count: number;
+    }): Promise<Hex>;
+    batchWithdrawMappedByKeys(params: {
+        dropKeys: readonly Hex[];
+    }): Promise<Hex>;
+    withdrawUnmappedBatchByKeys(params: {
+        claimKey: Hex;
         recipient: Address;
         id: Id;
+        anchorDropKey: Hex;
+        secret: Secret;
         nonce: bigint;
         deadline: bigint;
+        dropKeys: readonly Hex[];
+        validatorSignature: Hex;
     }): Promise<Hex>;
-    /** validator() — 서명자여야 하는 주소. 백엔드 서명 검증의 기준값. */
-    getValidator?(): Promise<Address>;
-    /** liveDropCountById(id) — 남은 수령 대기 건수(페이지네이션 종료 조건). */
-    getLiveDropCount?(params: {
+    refundByKey(params: {
+        dropKey: Hex;
+    }): Promise<Hex>;
+    getChangeNonce(params: {
         id: Id;
     }): Promise<bigint>;
-    /**
-     * claimedRecipientOf(id) — 이 id가 **개별 수령(secret+OAuth)으로 확정한** 수령 주소.
-     * 미수령 id는 zero. 일괄 수령의 목적지를 온체인 값으로 교차 검증하는 데 쓴다.
-     */
-    getClaimedRecipient?(params: {
+    getPendingRecipientChange(params: {
         id: Id;
     }): Promise<Address>;
+    requestRecipientChange(params: {
+        id: Id;
+        newRecipient: Address;
+    }): Promise<Hex>;
+    completeRecipientChange(params: {
+        id: Id;
+        nonce: bigint;
+        deadline: bigint;
+        signature: Hex;
+    }): Promise<Hex>;
+    cancelRecipientChange(params: {
+        id: Id;
+    }): Promise<Hex>;
+    resetRecipient(params: {
+        id: Id;
+        nonce: bigint;
+        deadline: bigint;
+        signature: Hex;
+    }): Promise<Hex>;
+    /** validatorNonceById(keccak256(utf8(id))). id 해싱은 어댑터 책임. */
+    getValidatorNonce?(params: {
+        id: Id;
+    }): Promise<bigint>;
     /**
-     * withdrawByValidator(recipient, id, nonce, deadline, maxCount, signature).
-     * tx는 **수령인 본인 지갑**이 보낸다(컨트랙트가 msg.sender와 서명의 recipient를
-     * 대조). `maxCount`는 서명 대상이 아니라 페이지 크기다 — 같은 서명을 재사용한다.
+     * validatorClaimDigest(recipient, id, nonce, deadline) — 온체인 EIP-712 다이제스트.
+     * 로컬 재조립 대신 이 값을 읽어 백엔드 서명을 검증한다.
      */
-    withdrawByValidator?(params: {
+    getValidatorClaimDigest?(params: {
         recipient: Address;
         id: Id;
         nonce: bigint;
         deadline: bigint;
-        maxCount: number;
-        signature: Hex;
     }): Promise<Hex>;
+    /** validator() — 서명자여야 하는 주소. 백엔드 서명 검증의 기준값. */
+    getValidator?(): Promise<Address>;
 }
 
 /**
@@ -438,7 +540,8 @@ interface ClaimSignerPort {
  *     { claimBaseUrl },
  *     { api, chain, signer, crypto },
  *   );
- *   const { withdrawLink, claimAddress } = await safeDrop.deposit({ ... });
+ *   const result = await safeDrop.deposit({ ... });
+ *   if (!result.isMapped) sendLink(result.withdrawLink);
  *
  * viem/HTTP 어댑터를 자동 조립하려면 `@nexus-cross/pop/adapters`의
  * createSafeDropClient를 사용한다. (도메인/컨트랙트 주소는 chain 어댑터가 안다.)
@@ -459,16 +562,37 @@ interface SafeDrop {
     deposit(params: DepositParams): Promise<DepositResult>;
     /** X OAuth 검증 후 (sender_address + 토큰 소유자)로 임시 claim 키/주소를 받는다 (point of return). */
     retrieveClaimKey(params: {
+        claimAddress: Address;
         senderAddress: Address;
         oauth: OAuthProof;
     }): Promise<{
+        isMapped: true;
+    } | {
+        isMapped: false;
         claimKey: Hex;
         claimAddress: Address;
     }>;
     withdraw(params: WithdrawParams): Promise<WithdrawResult>;
     refund(params: RefundParams): Promise<RefundResult>;
-    /** 온체인 드롭 상태 (drops(claimAddr)). 없으면 null. */
-    getDrop(claimAddress: Address): Promise<DropState | null>;
+    /** activeDropOf(claimAddr)로 조회한 현재 온체인 드롭. */
+    getDrop(claimAddress: Address, sponsor: Address): Promise<DropState | null>;
+    getDropByKey(dropKey: Hex): Promise<OnePopDrop | null>;
+    getDropKeyByClaimAddress(claimAddress: Address, sponsor: Address): Promise<Hex | null>;
+    getClaimedRecipient(id: Id): Promise<Address>;
+    getPendingDropsById(id: Id): Promise<readonly OnePopDrop[]>;
+    getPendingDropsByRecipient(recipient: Address): Promise<readonly OnePopDrop[]>;
+    getPendingDropsBySponsor(sponsor: Address): Promise<readonly OnePopDrop[]>;
+    withdrawUnmapped(params: Parameters<SafeDropChainPort['withdrawUnmapped']>[0]): Promise<Hex>;
+    withdrawMapped(params: Parameters<SafeDropChainPort['withdrawMapped']>[0]): Promise<Hex>;
+    batchWithdrawMapped(count: number): Promise<Hex>;
+    batchWithdrawMappedByKeys(dropKeys: readonly Hex[]): Promise<Hex>;
+    refundByKey(dropKey: Hex): Promise<Hex>;
+    getChangeNonce(id: Id): Promise<bigint>;
+    getPendingRecipientChange(id: Id): Promise<Address>;
+    requestRecipientChange(id: Id, newRecipient: Address): Promise<Hex>;
+    completeRecipientChange(params: Parameters<SafeDropChainPort['completeRecipientChange']>[0]): Promise<Hex>;
+    cancelRecipientChange(id: Id): Promise<Hex>;
+    resetRecipient(params: Parameters<SafeDropChainPort['resetRecipient']>[0]): Promise<Hex>;
     /** 내게 온 수령 대기 목록. Bearer JWT + 활성 X 연결 필요. */
     listDrops(params?: {
         token?: Address;
@@ -480,10 +604,17 @@ interface SafeDrop {
     /** 토큰별 pending 잔액 상위 (공개). */
     getLeaderboard(params: {
         token: Address;
-    }): Promise<readonly LeaderboardEntry[]>;
-    /** 내 온체인 이벤트 히스토리. Bearer JWT 필요. */
-    listHistories(params?: {
-        event?: PopEventName;
+        page?: number;
+        pageSize?: number;
+        identifier?: string;
+    }): Promise<LeaderboardPage>;
+    getMyLeaderboardEntry(params: {
+        token: Address;
+    }): Promise<MyLeaderboardEntry>;
+    /** sent/received 드롭 히스토리. Bearer JWT 필요. */
+    listHistories(params: {
+        type: HistoryType;
+        token?: Address;
         page?: number;
         pageSize?: number;
     }): Promise<HistoryPage>;
@@ -495,9 +626,26 @@ interface SafeDrop {
     }): Promise<XConnection>;
     /** X 연결 해제 (idempotent). */
     disconnectX(): Promise<void>;
+    submitFeedback(params: {
+        dropId: number;
+        message: string;
+    }): Promise<string>;
+    setRevealYou(revealYou: boolean): Promise<boolean>;
+    requestRecipientChangeSignature(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientChangeSignature>;
+    requestRecipientResetSignature(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientSignature>;
     /**
-     * 일괄 수령 — nonce 조회 → 백엔드 서명 → **가스 전 서명 검증** → 전량 회수까지
-     * 한 번에. tx는 연결된 수령인 지갑이 보낸다(secret 불필요).
+     * anchor drop의 secret/claim key와 validator 서명을 함께 사용해 현재 pending key를
+     * 한 번에 수령한다.
      */
     batchClaim(params: BatchClaimParams): Promise<BatchClaimResult>;
     /**
@@ -513,4 +661,4 @@ interface SafeDrop {
 }
 declare function createSafeDrop(config: SafeDropConfig, deps: SafeDropDeps): SafeDrop;
 
-export { type Address as A, type BatchClaimParams as B, type CryptoPort as C, type DepositParams as D, type Envelope as E, type Hex as H, type Id as I, type LeaderboardEntry as L, type OAuthProof as O, type PendingDrop as P, type RefundParams as R, type SafeDropChainPort as S, type WithdrawParams as W, type XConnection as X, type SafeDropApiPort as a, type DepositResult as b, type BatchClaimResult as c, type ClaimSignerPort as d, type WithdrawResult as e, type RefundResult as f, type Secret as g, type BatchClaimSignature as h, type DropInbox as i, type DropSender as j, type DropState as k, type HistoryEntry as l, type HistoryPage as m, type PopEventName as n, type SafeDrop as o, type SafeDropConfig as p, type SafeDropDeps as q, SafeDropError as r, type SafeDropErrorCode as s, type SecretHash as t, type SocialIdentifier as u, type SocialProvider as v, createSafeDrop as w };
+export { type Address as A, type BatchClaimParams as B, type CryptoPort as C, type DepositParams as D, type Envelope as E, type SocialIdentifier as F, type SocialProvider as G, type Hex as H, type Id as I, createSafeDrop as J, type LeaderboardEntry as L, type MappedDepositResult as M, type OAuthProof as O, type PendingDrop as P, type RefundParams as R, type SafeDropChainPort as S, type UnmappedDepositResult as U, type WithdrawParams as W, type XConnection as X, type SafeDropApiPort as a, type DepositResult as b, type BatchClaimResult as c, type ClaimSignerPort as d, type WithdrawResult as e, type RefundResult as f, type Secret as g, type BatchClaimSignature as h, type DropInbox as i, type DropSender as j, type DropState as k, type HistoryEntry as l, type HistoryPage as m, type HistoryParty as n, type HistoryType as o, type LeaderboardPage as p, type MyLeaderboardEntry as q, type OnePopDrop as r, type RecipientChangeSignature as s, type RecipientSignature as t, type SafeDrop as u, type SafeDropConfig as v, type SafeDropDeps as w, SafeDropError as x, type SafeDropErrorCode as y, type SecretHash as z };