@nexus-cross/pop 1.3.10-beta.2

package/AGENTS.md

@@ -0,0 +1,268 @@
+---
+name: nexus-cross-pop
+description: Integrate @nexus-cross/pop (SafeDrop / One Pop) — send ERC20 tokens to an X (Twitter) handle and let the recipient claim them with a link + X login. Use when the user asks about @nexus-cross/pop, SafeDrop, One Pop, claim links, drop inbox, or X-handle token transfers.
+---
+
+# @nexus-cross/pop — Agent Integration Guide
+
+This file ships inside the published package (`node_modules/@nexus-cross/pop/AGENTS.md`).
+It is the machine-readable contract for wiring this SDK. Follow it literally; the
+rules in **Hard rules** are correctness/security requirements, not style.
+
+Human docs: `README.md` (same directory). Backend contract: One Pop API (Swagger 2.0),
+mirrored at `src/infrastructure/openapi.json` in the source repo.
+
+## 1. What this package does
+
+Sponsor deposits ERC20 into a SafeDrop escrow addressed to a **social handle** (X).
+A per-drop **temporary claim wallet** holds custody; the recipient proves handle
+ownership via X OAuth, gets that wallet's private key from the backend, and withdraws
+with gas sponsored by the contract. The plaintext `secret` lives **only** in the claim
+link's `#fragment` — the backend never sees it, so backend + link are each insufficient alone.
+
+## 2. Entry points — pick one, don't mix
+
+| Import | Contents | Requires |
+|---|---|---|
+| `@nexus-cross/pop` | domain types, use cases, pure utils, `createSafeDrop` | nothing |
+| `@nexus-cross/pop/adapters` | `createSafeDropClient`, viem/HTTP adapters, X OAuth, cross-auth | `viem`, `fetch` |
+| `@nexus-cross/pop/react` | `SafeDropProvider`, `useSafeDrop` | `react` |
+
+Default for an app: `createSafeDropClient` (adapters) + `SafeDropProvider` (react).
+`viem` and `react` are **optional peers** — install only what the chosen entry point needs.
+
+```sh
+pnpm add @nexus-cross/pop viem        # + react if using ./react
+```
+
+## 3. Required configuration
+
+| What | Where it goes | Notes |
+|---|---|---|
+| SafeDrop contract address | `createSafeDropClient({ contractAddress })` | per-chain deployment |
+| viem `publicClient` / `walletClient` / `chain` | same | walletClient = connected sponsor wallet |
+| claim page base URL | `createSafeDropClient({ claimBaseUrl })` | the route that handles the claim link |
+| SIWE JWT provider | `createSafeDropClient({ api: { getJwt } })` | **required** for deposit and all authed reads |
+| X OAuth2 client id + redirect URI | `new XAuthClient({ clientId, redirectUri })` | redirect URI must equal the claim route and be registered on the X app |
+| X OAuth2 client secret | **server route only** | never ship to the client bundle |
+
+Environment variables the package reads itself (`adapters/endpoints.ts`) — pick the
+prefix matching the framework, Vite `VITE_` or Next.js `NEXT_PUBLIC_`:
+
+| Variable | Purpose |
+|---|---|
+| `VITE_ONE_POP_ENVIRONMENT` / `NEXT_PUBLIC_ONE_POP_ENVIRONMENT` / `ONE_POP_ENVIRONMENT` | `dev` \| `stage` \| `production` (default `production`) → picks the default API base URL |
+| `VITE_ONE_POP_API_BASE_URL` / `NEXT_PUBLIC_ONE_POP_API_BASE_URL` | override the One Pop API base URL |
+| `VITE_CROSS_AUTH_URL` / `NEXT_PUBLIC_CROSS_AUTH_URL` | override the cross-auth (SIWE) base URL |
+
+Base URLs must be `https` (or `http://localhost` for local dev) or construction throws.
+Everything else (contract address, claim base URL, X client id) is passed as options —
+the package does not read it from the environment.
+
+## 4. Wiring
+
+```ts
+import { createSafeDropClient, CrossAuthClient } from '@nexus-cross/pop/adapters';
+import { createPublicClient, createWalletClient, custom, http } from 'viem';
+
+const publicClient = createPublicClient({ chain, transport: http() });
+const walletClient = createWalletClient({ chain, transport: custom(window.ethereum) });
+
+// SIWE login → JWT (needed by deposit + every authed read)
+const auth = new CrossAuthClient();
+const { message } = await auth.unsignedHash(chain.id, address);
+const signature = await walletClient.signMessage({ account: address, message });
+const { token } = await auth.siweToken(address, signature);
+
+const safeDrop = createSafeDropClient({
+  contractAddress: SAFEDROP_ADDRESS,
+  publicClient,
+  walletClient,
+  chain,
+  claimBaseUrl: 'https://app.example/claim',
+  permit: false,            // true only if BOTH the deployment and the token support EIP-2612
+  api: { getJwt: () => token },
+});
+```
+
+React: wrap once with `<SafeDropProvider client={safeDrop}>`, read with `useSafeDrop()`.
+The provider only carries the client through context — no connection logic lives there.
+
+## 5. Flows
+
+### Send (sponsor)
+
+```ts
+const envelopes = await safeDrop.listEnvelopes();          // optional card designs
+const { withdrawLink, claimAddress } = await safeDrop.deposit({
+  sender: address,
+  recipient: { provider: 'x', handle: 'theo_13303' },
+  token: ERC20_ADDRESS,
+  amount: 1_000_000_000_000_000_000n,                      // BigInt, raw wei-scale
+  message: 'Happy birthday!',                              // optional, <= 140 runes
+  envelopeId: envelopes[0]?.id,                            // optional
+});
+```
+
+Then hand the link to the recipient (X DM compose):
+`location.assign(buildComposeUrl(buildDmText(withdrawLink), recipientId))`.
+
+### Claim (recipient, on the claim route)
+
+```ts
+const { sender, secret } = parseWithdrawLink(location.href);
+const { oauth } = await xauth.complete(location.href);      // X OAuth2 PKCE callback
+const { claimKey, claimAddress } = await safeDrop.retrieveClaimKey({ senderAddress: sender!, oauth });
+await safeDrop.withdraw({ recipient: myAddress, claimAddress, secret: secret!, claimKey });
+```
+
+`retrieveClaimKey` is the point of no return — after it resolves, key custody is the client's.
+It returns **only the latest pending drop** for that `(sender, handle)` pair and takes no
+`claimAddress` selector; multiple drops from the same sender are claimed one link at a time.
+
+### Inbox / social surfaces
+
+```ts
+await safeDrop.connectX({ oauth });          // required once before listDrops
+const conn = await safeDrop.getXConnection();  // null when not connected
+const inbox = await safeDrop.listDrops();      // { items, count, totalAmount, hasClaimedBefore }
+const top = await safeDrop.getLeaderboard({ token: ERC20_ADDRESS });
+const page = await safeDrop.listHistories({ event: 'Withdrawn', page: 1, pageSize: 20 });
+await safeDrop.disconnectX();
+```
+
+`inbox.hasClaimedBefore === false` ⇒ the first claim must be an individual claim; gate any
+batch-claim CTA on it.
+
+### Refund
+
+```ts
+await safeDrop.refund({ claimAddress });   // sponsor only, after expiry
+```
+
+### Batch claim — drain every drop for a handle in one flow
+
+```ts
+const { txHashes, recipient } = await safeDrop.batchClaim({
+  id: myHandle,            // normalized internally
+  oauth,                   // X OAuth proof (handle ownership)
+  maxCount: 30,            // optional page size, default 30
+});
+```
+
+`batchClaim` does the whole sequence in the order the contract enforces:
+read `validatorNonceById(keccak256(utf8(id)))` → request the backend signature →
+read `validatorClaimDigest(recipient, id, nonce, deadline)` on-chain → **verify the signature
+recovers to `validator()` before spending gas** → call `withdrawByValidator` repeatedly until
+`liveDropCountById(id)` is 0, reusing the one signature.
+
+Rules specific to this path:
+
+- **The recipient is the SIWE-authenticated address**, not a parameter you choose. Passing a
+  different `recipient` fails with `SIGN_FAILED`. To claim to another wallet, do SIWE with it.
+- **The transaction must be sent by the recipient wallet** — the contract compares `msg.sender`
+  against the signed recipient. Unlike individual `withdraw`, the temporary claim wallet cannot
+  send this, and there is no gas sponsorship: the recipient needs gas.
+- **No `secret` is involved.** The validator signature is the gate for this path.
+- `maxCount` is a page size and is **not** covered by the signature — that is why one signature
+  survives every page. Do not re-request a signature per page.
+- `hasClaimedBefore === false` (from `listDrops`) means the first claim must be an individual
+  claim; do not offer batch claim yet. The SDK also enforces this on-chain: batch claim aborts
+  with `DROP_NOT_FOUND` when `claimedRecipientOf(id)` is zero.
+- The SDK cross-checks the signed recipient against `claimedRecipientOf(id)` and refuses to send
+  when they differ (`SIGN_FAILED`). This is a client-side guard — whether the contract enforces
+  it is **not verified** (the source is unverified and the signature check runs first), so do not
+  weaken or bypass it.
+- On `SIGN_FAILED` the backend signed something the contract will reject — a different EIP-712
+  domain/type, a stale nonce, or a `personal_sign` prefix. Do not retry; report it.
+
+The on-chain contract (verified against deployed bytecode, CROSS testnet 612044):
+
+```
+domain  { name: 'ONEpop', version: '1', chainId, verifyingContract: <SafeDrop> }
+type    ValidatorClaim(address recipient,string id,uint256 nonce,uint256 deadline)
+nonce   validatorNonceById(bytes32 keccak256(utf8(id)))     // hashed key, NOT the raw string
+submit  withdrawByValidator(address recipient, string id, uint256 nonce,
+                            uint256 deadline, uint256 maxCount, bytes signature)
+errors  ValidatorSigExpired() → deadline passed | InvalidValidatorNonce() → stale nonce
+        ECDSAInvalidSignature() → signer is not validator()
+```
+
+These functions are absent from the bundled `safedrop_abi.json` (a Foundry artifact that does not
+match the deployment); the SDK carries its own bytecode-verified ABI in `adapters/validatorAbi.ts`.
+
+### Live notifications
+
+`GET /events/subscribe` is a plain SSE endpoint (`event: withdrawn` frames, `: ping` keepalives).
+The SDK does not wrap it — use `EventSource` directly. Delivery is best-effort; reconcile with
+`listHistories()`.
+
+## 6. Hard rules
+
+1. **BigInt end-to-end for wei-scale values.** `amount`, `balance`, `totalAmount`,
+   `lastDepositAmount`, gas, fees. Never `Number()`/`parseInt()`/`parseFloat()` them, never feed a
+   formatted display string back into arithmetic, and floor (never round up) when formatting.
+   The API sends wei as decimal strings; the adapters already convert them to BigInt.
+2. **Never send `secret` anywhere.** It belongs in the link `#fragment` only — no query string, no
+   logs, no analytics, no backend call. Sending it collapses the trust split.
+3. **`getJwt` is mandatory** for `deposit`, `listDrops`, `listHistories`, and all `x-connections`
+   calls. Without it those reject with `UNAUTHORIZED` before any request is sent.
+4. **`permit: true` only when the deployment and the token both support EIP-2612.** Enabling it
+   against a non-permit deployment reverts (missing selector).
+5. **Do not change `withdrawFees` away from type-2 dynamic fees with tip ≥ 1 gwei** — gas
+   abstraction (sponsor pays) depends on it, and the claim wallet has a zero balance.
+6. **`message` ≤ 140 runes** (code points) and `envelopeId` must come from `listEnvelopes()`;
+   otherwise the backend rejects with `INVALID_PARAM` / `ENVELOPE_NOT_FOUND`.
+7. **Handles are normalized** by the SDK (`normalizeHandle`); pass the same handle to deposit and
+   to the API — do not hand-roll a second normalization.
+8. **`DropState.token` and `DropState.expiry` are optional.** Deployments differ in what `drops`
+   returns (the permit deployment returns five fields, no expiry). `expiry === undefined` means
+   *unknown*, not *not expired* — never drive refund/expiry UI off a missing value.
+
+## 7. API surface
+
+| `safeDrop` method | Endpoint / chain call | Auth |
+|---|---|---|
+| `deposit` | `POST /wallets` + `approve`/`deposit` (or permit deposit) | JWT |
+| `retrieveClaimKey` | `POST /wallets/private-key` | X OAuth token (body) |
+| `withdraw` | `withdraw(...)` from the claim wallet | claim key |
+| `refund` | `refund(claimAddr)` | sponsor wallet |
+| `getDrop` | `drops(claimAddr)` | — |
+| `listDrops` | `GET /drops` | JWT + active X connection |
+| `listEnvelopes` | `GET /envelopes` | public |
+| `getLeaderboard` | `GET /leaderboards?token=` | public |
+| `listHistories` | `GET /histories` | JWT |
+| `getXConnection` / `connectX` / `disconnectX` | `GET`/`POST`/`DELETE /x-connections` | JWT |
+| `batchClaim` | `POST /batch-claim-signature` + `validatorNonceById`/`validatorClaimDigest`/`validator`/`withdrawByValidator` | JWT + X OAuth token + recipient wallet |
+| `requestBatchClaimSignature` | `POST /batch-claim-signature` (low-level; prefer `batchClaim`) | JWT + X OAuth token |
+
+## 8. Errors
+
+Everything rejects with `SafeDropError` — branch on `err.code`, never on the message.
+
+| `code` | Meaning / action |
+|---|---|
+| `UNAUTHORIZED` | no/expired SIWE JWT → re-run the SIWE login |
+| `INVALID_OAUTH_TOKEN` | X token missing `tweet.read`+`users.read`, or app-only → re-auth the user |
+| `X_CONNECTION_NOT_FOUND` | call `connectX()` first (also returned by `listDrops`) |
+| `WALLET_NOT_FOUND` | no pending claim wallet for that (sender, handle) — already claimed or refunded |
+| `PENDING_LIMIT_EXCEEDED` | too many pending drops for this pair → ask the user to wait/claim |
+| `SEND_BLOCKED` | sender blocked by the backend → surface, do not retry |
+| `ENVELOPE_NOT_FOUND` | stale `envelopeId` → refresh `listEnvelopes()` |
+| `INVALID_PARAM` | bad request body/query (e.g. message > 140 runes) |
+| `RATE_LIMITED` | back off and retry later |
+| `INVALID_AMOUNT` / `INVALID_TOKEN` / `MISSING_*` | client-side validation before any network/chain call |
+| `SIGN_FAILED` | validator signature does not match the contract (see Batch claim) — report, don't retry |
+| `CHAIN_ERROR` | tx reverted or RPC failed; `details.revertName` carries the decoded custom error |
+| `API_ERROR` | unmapped backend failure (5xx, malformed body) or an unimplemented optional port method |
+
+## 9. Common mistakes
+
+- Converting `amount` to `Number` for display math → silent precision loss above ~0.009 ETH in wei.
+- Calling `listDrops()` before `connectX()` → `X_CONNECTION_NOT_FOUND`.
+- Passing the claim `secret` through a query parameter or logging it.
+- Building the claim link by hand instead of using the returned `withdrawLink` /
+  `buildWithdrawLink` (the `#fragment` placement is load-bearing).
+- Injecting a partial `SafeDropApiPort` mock and calling the query methods → `API_ERROR`
+  ("not implemented"); implement the methods your test path touches.
+- Enabling `permit: true` on a deployment whose `deposit` has no permit signature.

package/README.md

@@ -0,0 +1,343 @@
+# @nexus-cross/pop
+
+SafeDrop client SDK — 소셜 핸들(X)로 ERC20 토큰을 예치하고, 수령인이 링크 + X 로그인으로 수령하는 흐름을 다룬다. 프레임워크 무관 core + viem/HTTP 어댑터 + 얇은 React Provider.
+
+```
+npm i @nexus-cross/pop viem   # react는 선택
+```
+
+`viem`·`react`는 **optional peer** — `.`(core)만 쓰면 둘 다 불필요. `./adapters`는 `viem`, `./react`는 `react`가 필요하다.
+
+> **AI 에이전트로 통합한다면** `node_modules/@nexus-cross/pop/AGENTS.md`를 읽히면 된다 —
+> 설치·환경변수·와이어링·필수 규칙·에러 분기가 에이전트용으로 정리돼 함께 배포된다.
+> 백엔드 계약 원본은 `@nexus-cross/pop/openapi.json`.
+
+## Entry points
+
+| import | 내용 | 의존 |
+|---|---|---|
+| `@nexus-cross/pop` | 도메인 타입, usecase, 순수 유틸, `createSafeDrop` facade | 없음 |
+| `@nexus-cross/pop/adapters` | viem/HTTP 어댑터, `createSafeDropClient`, X OAuth, cross-auth | viem, fetch |
+| `@nexus-cross/pop/react` | `SafeDropProvider`, `useSafeDrop` | react |
+
+대부분의 앱은 **`createSafeDropClient`(adapters) + `SafeDropProvider`(react)** 만 쓰면 된다.
+
+## 개념
+
+- **claimAddress** — 드롭당 임시 지갑 주소. 온체인 조회 키(`drops(claimAddress)`).
+- **secret** — 평문 비밀 문구. **어떤 서버에도 전송되지 않고** 수령 링크의 `#fragment`에만 담긴다.
+- **withdrawLink** — `…/claim?sender=<addr>#<secret>`. 이 링크를 X DM으로 수령인에게 보낸다.
+- **claimKey** — 임시 claim 지갑의 개인키. 수령인이 X OAuth 검증 후 백엔드에서 받아 가스 대납 withdraw에 쓴다.
+
+신뢰 분리: 백엔드는 claimKey를 갖지만 secret이 없어 자금을 옮길 수 없고, 링크만으로도 OAuth 없이 키를 못 받는다.
+
+## 클라이언트 만들기
+
+```ts
+import { createSafeDropClient } from '@nexus-cross/pop/adapters';
+import { createPublicClient, createWalletClient, custom, http } from 'viem';
+
+const publicClient = createPublicClient({ chain, transport: http() });
+const walletClient = createWalletClient({ chain, transport: custom(window.ethereum) }); // 연결된 지갑
+
+const safeDrop = createSafeDropClient({
+  contractAddress: '0x…SafeDrop',
+  publicClient,
+  walletClient,
+  chain,
+  claimBaseUrl: 'https://one-pop.example/claim',
+  // api.baseUrl 미지정 시 VITE_/NEXT_PUBLIC_ONE_POP_* 환경변수로 결정
+  api: { getJwt: async () => siweJwt },   // deposit(createClaimWallet)에 SIWE JWT 필요
+});
+```
+
+`getJwt`는 cross-auth SIWE 로그인으로 얻는다:
+
+```ts
+import { CrossAuthClient } from '@nexus-cross/pop/adapters';
+
+const auth = new CrossAuthClient();                     // baseUrl 미지정 시 환경변수/기본값
+const { message } = await auth.unsignedHash(chainId, address);
+const signature = await walletClient.signMessage({ account: address, message });
+const { token } = await auth.siweToken(address, signature);   // token = getJwt가 반환할 값
+```
+
+## 1) Deposit — 토큰 보내기
+
+```ts
+const { withdrawLink, claimAddress } = await safeDrop.deposit({
+  sender: address,                                  // 연결된 지갑 = 스폰서
+  recipient: { provider: 'x', handle: 'theo_13303' },
+  token: '0x…ERC20',
+  amount: 1_000000n,                                // raw wei-scale, BigInt 필수
+  message: '생일 축하해!',                          // 선택 — 수령인에게 표시(≤140 runes)
+  envelopeId: 'classic-coral',                      // 선택 — listEnvelopes()의 id
+  // secret 미지정 시 자동 생성
+});
+```
+
+`message`·`envelopeId`는 **백엔드에만 저장**되는 메타데이터다(컨트랙트에 필드 없음).
+
+내부 흐름: 임시 claim 지갑 생성(백엔드) → `approve` → `deposit` → 링크 생성. `amount`는 **BigInt로 끝까지** 유지한다 (Number 변환 금지).
+
+수령인에게 링크 전달 (X DM 작성창):
+
+```ts
+import { buildDmText, buildComposeUrl } from '@nexus-cross/pop';
+location.assign(buildComposeUrl(buildDmText(withdrawLink), recipientId));
+```
+
+## 2) Withdraw — 수령인이 받기
+
+수령 페이지(`claimBaseUrl`)에서:
+
+```ts
+import { parseWithdrawLink } from '@nexus-cross/pop';
+import { XAuthClient, HttpXAuthAdapter } from '@nexus-cross/pop/adapters';
+
+const { sender, secret } = parseWithdrawLink(location.href);
+
+// (a) X OAuth2 PKCE — 리다이렉트는 앱이 담당
+const xauth = new XAuthClient({
+  clientId: X_CLIENT_ID,
+  redirectUri: 'https://one-pop.example/claim',
+  port: new HttpXAuthAdapter({ /* 토큰 교환 프록시 */ }),
+});
+// 시작:   const { authorizeUrl } = await xauth.start(); location.assign(authorizeUrl);
+// 콜백에서:
+const { oauth } = await xauth.complete(location.href);
+
+// (b) OAuth 검증 → 임시 claim 키/주소 수령 (point of return)
+const { claimKey, claimAddress } = await safeDrop.retrieveClaimKey({
+  senderAddress: sender!,
+  oauth,
+});
+
+// (c) 가스 대납 withdraw — 임시 지갑이 직접 tx 전송
+const { txHash } = await safeDrop.withdraw({
+  recipient: myReceivingAddress,   // 수령인이 지정, 서명에 바인딩
+  claimAddress,
+  secret: secret!,
+  claimKey,
+});
+```
+
+## 3) Refund — 만료 후 환불
+
+```ts
+await safeDrop.refund({ claimAddress });   // 만료 후 sponsor(msg.sender)만 가능
+```
+
+## 조회 — 드롭 상태 (온체인)
+
+```ts
+const drop = await safeDrop.getDrop(claimAddress);   // 없으면 null
+// drop: DropState { claimAddress, sponsor, amount, secretHash, salt, id, token?, expiry? }
+```
+
+⚠️ `token`·`expiry`는 **optional**이다 — 배포본마다 `drops`의 반환 필드가 다르다(permit
+배포본은 5개: sponsor/amount/secretHash/salt/id). 어댑터가 두 형태를 모두 디코딩하고
+`token`은 에스크로 `token()`으로 채우지만, **`expiry`는 5필드 배포본에서 `undefined`** 다.
+만료 판정 전에 존재 여부를 확인하라(`undefined` = 만료 아님이 아니라 *알 수 없음*).
+
+## 4) 백엔드 조회 — 인박스 · X 연결 · 리더보드 · 히스토리
+
+`amount`/`balance` 등 wei-scale 값은 **전부 BigInt로 정규화되어** 나온다(API는 10진 문자열).
+
+```ts
+// X 계정 ↔ 지갑 연결 — listDrops의 선행 조건
+await safeDrop.connectX({ oauth });          // XAuthClient.complete()로 얻은 oauth
+const conn = await safeDrop.getXConnection(); // 연결 없으면 null (에러 아님)
+await safeDrop.disconnectX();                 // idempotent
+
+// 내게 온 수령 대기 목록 (Bearer JWT + 활성 X 연결)
+const inbox = await safeDrop.listDrops({ token: '0x…ERC20' });
+// { items: PendingDrop[], count, totalAmount: bigint, hasClaimedBefore }
+//   PendingDrop { claimAddress, token, amount: bigint, message, envelopeId, depositedAt, sender }
+
+// 카드 디자인 · 리더보드 (공개 — JWT 불필요)
+const envelopes = await safeDrop.listEnvelopes({ locale: 'ko' });
+const top = await safeDrop.getLeaderboard({ token: '0x…ERC20' });
+
+// 내 온체인 이벤트 (Deposited | Withdrawn | Refunded | BatchWithdrawn)
+const page = await safeDrop.listHistories({ event: 'Withdrawn', page: 1, pageSize: 20 });
+```
+
+`inbox.hasClaimedBefore === false`면 **첫 수령은 개별 claim만** 가능하다 — 일괄 수령 CTA를 이 값으로 게이트한다.
+
+## 5) 일괄 수령 (batch claim) — 한 핸들에 쌓인 드롭 전량 회수
+
+```ts
+const { txHashes, recipient } = await safeDrop.batchClaim({
+  id: myHandle,        // 내부에서 normalizeHandle
+  oauth,               // 핸들 소유 증명 (X OAuth)
+  maxCount: 30,        // 선택 — tx 1건이 처리할 건수(기본 30)
+});
+```
+
+컨트랙트가 강제하는 순서대로 진행한다:
+`validatorNonceById(keccak256(utf8(id)))` → 백엔드 서명 발급 → 온체인
+`validatorClaimDigest(recipient, id, nonce, deadline)` 조회 → **서명이 `validator()`로
+복원되는지 가스 쓰기 전에 검증** → `liveDropCountById(id)`가 0이 될 때까지
+`withdrawByValidator` 반복(서명 1건 재사용).
+
+| 개별 수령과 다른 점 | 내용 |
+|---|---|
+| secret | **불필요** — 게이트는 validator 서명이다 |
+| 수령 주소 | **SIWE 인증 주소로 고정**. 다른 주소를 넘기면 `SIGN_FAILED`(그 주소로 SIWE 재로그인해야 함) |
+| tx 전송자 | **수령인 본인 지갑**(컨트랙트가 `msg.sender` 대조). 임시 claim 지갑 불가 = **가스 대납 없음** |
+| 서명 재사용 | `maxCount`는 서명 대상이 아니라 페이지 크기 → 페이지마다 재발급 금지 |
+| 첫 수령 | 개별 claim이 선행돼야 한다 — 온체인 `claimedRecipientOf(id)`가 zero면 `DROP_NOT_FOUND`로 차단 |
+| 목적지 교차검증 | 서명된 recipient ≠ `claimedRecipientOf(id)`면 서명이 유효해도 전송하지 않음(`SIGN_FAILED`) |
+
+`SIGN_FAILED`가 나면 백엔드 서명이 컨트랙트가 기대하는 값과 다르다(EIP-712 domain/type 불일치,
+낡은 nonce, `personal_sign` 프리픽스). 재시도해도 동일하게 실패하니 그대로 노출한다.
+
+<details>
+<summary>온체인 계약 (배포 바이트코드 검증 — CROSS testnet 612044)</summary>
+
+```
+domain  { name: 'ONEpop', version: '1', chainId, verifyingContract: <SafeDrop> }
+type    ValidatorClaim(address recipient,string id,uint256 nonce,uint256 deadline)
+nonce   validatorNonceById(bytes32)   ← keccak256(utf8(id)). **원문 string 아님**
+submit  withdrawByValidator(address recipient, string id, uint256 nonce,
+                            uint256 deadline, uint256 maxCount, bytes signature)
+고정     claimedRecipientOf(string id) → 개별 수령으로 확정된 주소(미수령이면 zero)
+검증 순서  deadline(ValidatorSigExpired) → nonce(InvalidValidatorNonce) → 서명(ECDSAInvalidSignature)
+```
+
+**미검증 2건**: 컨트랙트가 `msg.sender == recipient`와 `recipient == claimedRecipientOf(id)`를
+강제하는지는 확인하지 못했다(소스 미공개 + 서명 검증이 먼저라 블랙박스 구분 불가). pop이
+두 조건을 클라이언트에서 선제 차단하지만 온체인 강제의 대체물은 아니다 —
+`docs/pop/02-frontend-dependencies.md#검증-한계-중요` 참조.
+
+이 함수들은 `safedrop_abi.json`(Foundry 산출물, 배포본과 불일치)에 없다 — SDK는
+`adapters/validatorAbi.ts`에 바이트코드로 검증한 ABI를 따로 들고 있다.
+서명만 직접 받아 쓰려면 저수준 `safeDrop.requestBatchClaimSignature({ id, oauth, nonce, deadline })`.
+</details>
+
+## 실시간 알림 (SSE)
+
+`GET /events/subscribe`는 pop이 감싸지 않는다 — `EventSource`로 직접 구독하고(경로는
+`DEFAULT_POP_API_PATHS.eventsSubscribe`), best-effort라 유실분은 `listHistories()`로 보정한다.
+
+## React
+
+```tsx
+import { SafeDropProvider, useSafeDrop } from '@nexus-cross/pop/react';
+
+<SafeDropProvider client={safeDrop}>
+  <App />
+</SafeDropProvider>;
+
+// 어디서든
+const safeDrop = useSafeDrop();
+```
+
+Provider는 client를 context로 넣기만 한다 — 연결 로직은 없다.
+
+## 환경변수
+
+| 변수 | 용도 |
+|---|---|
+| `VITE_ONE_POP_API_BASE_URL` / `NEXT_PUBLIC_ONE_POP_API_BASE_URL` | one-pop-api base URL override |
+| `VITE_ONE_POP_ENVIRONMENT` / `NEXT_PUBLIC_ONE_POP_ENVIRONMENT` | `dev`\|`stage`\|`production` (기본 production) |
+| `ONE_POP_ENVIRONMENT` | 위 environment의 서버 전용(SSR, 접두사 없음) 변형 |
+| `VITE_CROSS_AUTH_URL` / `NEXT_PUBLIC_CROSS_AUTH_URL` | cross-auth base URL override |
+
+override 미지정 시 environment로 기본 URL을 고른다. base URL은 https(또는 `http://localhost`)만 허용.
+
+## 에러
+
+모든 실패는 `SafeDropError`로 던져진다. **`err.code`로 분기**하고 메시지 문자열에 의존하지 말라.
+백엔드 `code_name`은 아래 코드로 매핑된다(미매핑·5xx는 `API_ERROR`, `err.details`에 `status`/`code`/`codeName`).
+
+| `code` | 의미 / 조치 |
+|---|---|
+| `UNAUTHORIZED` | SIWE JWT 없음·만료 → SIWE 재로그인 (`getJwt` 확인) |
+| `INVALID_OAUTH_TOKEN` | X 토큰 scope 부족(`tweet.read`+`users.read`)·app-only → 재인증 |
+| `X_CONNECTION_NOT_FOUND` | `connectX()` 먼저 (`listDrops`도 이 코드로 실패) |
+| `WALLET_NOT_FOUND` | 해당 (sender, handle)의 pending 지갑 없음 — 이미 수령/환불 |
+| `PENDING_LIMIT_EXCEEDED` | pending 드롭 상한 초과 → 수령/만료 대기 안내 |
+| `SEND_BLOCKED` | 백엔드가 차단한 송금자 → 재시도 금지, 노출만 |
+| `ENVELOPE_NOT_FOUND` | `envelopeId`가 낡음 → `listEnvelopes()` 재조회 |
+| `INVALID_PARAM` | 요청 값 오류(예: `message` 140 runes 초과) |
+| `RATE_LIMITED` | 백오프 후 재시도 |
+| `MISSING_*` / `INVALID_AMOUNT` / `INVALID_TOKEN` | 네트워크·체인 호출 전 클라이언트 검증 실패 |
+| `CHAIN_ERROR` | tx revert·RPC 실패. `details.revertName`에 디코드된 custom error |
+| `API_ERROR` | 미매핑 백엔드 실패, 또는 주입한 `apiPort`가 해당 메서드 미구현 |
+
+## Advanced
+
+어댑터를 직접 조립하려면 `createSafeDrop(config, { api, chain, signer, crypto })`에 포트 구현을 주입한다. 테스트에서는 `SafeDropApiPort`를 mock으로 넘겨(`createSafeDropClient({ apiPort })`) 네트워크 없이 검증한다. 설계: `docs/pop/01-architecture.md`, 외부 서비스 통합: `docs/pop/03-integration.md`.
+
+## Appendix — 어댑터 옵션 레퍼런스
+
+`createSafeDropClient`가 조립하는 어댑터들. 개별로 쓰거나 옵션을 세밀 조정할 때 참고.
+
+### `createSafeDropClient(options)` → `SafeDrop`
+
+| 옵션 | 타입 | 기본 | 설명 |
+|---|---|---|---|
+| `contractAddress` | `Address` | — (필수) | SafeDrop 컨트랙트 주소 |
+| `publicClient` | viem `PublicClient` | — (필수) | 읽기·getDrop·digest |
+| `walletClient` | viem `WalletClient` | — (필수) | approve/deposit/refund 서명(연결 지갑) |
+| `chain` | viem `Chain` | — (필수) | 대상 체인 |
+| `claimBaseUrl` | `string` | — (필수) | 수령 링크 base URL |
+| `transport` | viem `Transport` | `http()`(chain.rpcUrls) | withdraw 임시 지갑 client RPC |
+| `withdrawFees` | `{ gas, maxFeePerGas, maxPriorityFeePerGas }` | 아래 gas-abstraction 기본 | withdraw gas/fee override |
+| `api` | `HttpSafeDropApiAdapterOptions` | — | one-pop-api 어댑터 옵션(아래) |
+| `apiPort` | `SafeDropApiPort` | — | 직접 구현/mock 주입(지정 시 `api` 무시) |
+
+### `HttpSafeDropApiAdapter` (`options.api`)
+
+| 옵션 | 타입 | 기본 | 설명 |
+|---|---|---|---|
+| `baseUrl` | `string` | 환경변수(`getOnePopApiBaseUrl`) | one-pop-api base URL |
+| `getJwt` | `() => string \| undefined \| Promise<…>` | — | **SIWE JWT.** deposit·`listDrops`·`listHistories`·`x-connections`·batch 서명에 필요. 미제공 시 요청 전에 `UNAUTHORIZED` |
+| `fetchImpl` | `typeof fetch` | `globalThis.fetch` | 테스트/SSR 주입 |
+| `paths` | `Partial<PopApiPaths>` | `DEFAULT_POP_API_PATHS` (`/wallets`, `/wallets/private-key`, `/drops`, `/envelopes`, `/leaderboards`, `/histories`, `/x-connections`, `/batch-claim-signature`, `/events/subscribe`) | 엔드포인트 경로 override |
+
+### `ViemSafeDropChainAdapter.withdrawFees` 기본값
+
+가스 대납(sponsor 과금)을 위한 type-2 dynamic-fee 값. 잔고 0 임시 지갑도 통과. `estimateGas`가 잔고 0에서 실패하므로 gas limit은 고정:
+
+```
+gas: 300_000n
+maxFeePerGas: 4_000_000_000n        // 4 gwei
+maxPriorityFeePerGas: 1_000_000_000n // 1 gwei (노드 최소 tip)
+```
+
+override는 정상 fee(tip ≥ 1 gwei) + type-2를 유지해야 sponsor 과금이 동작한다.
+
+### `CrossAuthClient(options)` — SIWE JWT 발급 (`getJwt`용)
+
+| 옵션 | 타입 | 기본 | 설명 |
+|---|---|---|---|
+| `baseUrl` | `string` | 환경변수(`getCrossAuthBaseUrl`) | cross-auth base URL |
+| `domain` | `string` | `globalThis.location.origin` | SIWE domain |
+| `fetchImpl` | `typeof fetch` | `globalThis.fetch` | 주입 |
+
+### `XAuthClient(options)` — X OAuth2 PKCE
+
+| 옵션 | 타입 | 기본 | 설명 |
+|---|---|---|---|
+| `clientId` | `string` | — (필수) | X OAuth2 client id |
+| `redirectUri` | `string` | — (필수) | 콜백 URL(수령 라우트) |
+| `port` | `XAuthPort` | — (필수) | 토큰 교환/핸들 조회(`HttpXAuthAdapter`) |
+| `scope` | `string` | `tweet.read users.read offline.access` | OAuth scope |
+| `authorizeUrl` | `string` | `https://x.com/i/oauth2/authorize` | authorize 엔드포인트 |
+| `storage` | `SessionStore` | `globalThis.sessionStorage` | verifier/state 임시 저장 |
+
+### `HttpXAuthAdapter(options)` — X 토큰/핸들 프록시
+
+앱의 same-origin 서버 라우트(토큰 교환 시 X client secret은 서버에서만)를 호출:
+
+| 옵션 | 타입 | 기본 | 설명 |
+|---|---|---|---|
+| `baseUrl` | `string` | `''`(same-origin) | 프록시 base |
+| `tokenPath` | `string` | `/api/x/token` | `POST {clientId,redirectUri,code,verifier}` → X 토큰 응답 |
+| `mePath` | `string` | `/api/x/me` | `GET` (Bearer) → `GET /2/users/me`(`{data:{username}}`) |
+| `fetchImpl` | `typeof fetch` | `globalThis.fetch` | 주입 |
+
+`ViemClaimSignerAdapter`·`ViemCryptoAdapter`는 옵션이 없다(순수 서명/암호 연산).

package/dist/XAuthPort-BNJePosj.d.ts

@@ -0,0 +1,29 @@
+/**
+ * X(Twitter) OAuth2 인증 계약. api.x.com은 CORS를 막으므로 실제 토큰 교환/핸들
+ * 조회는 앱의 same-origin 프록시(Next 라우트 `/api/x/token`, `/api/x/me`)를
+ * 경유한다 — 이 포트는 그 프록시 호출을 추상화한다. one-pop-api 미경유.
+ */
+interface XTokenResult {
+    accessToken: string;
+    scope?: string;
+    expiresIn?: number;
+    refreshToken?: string;
+}
+interface XAuthPort {
+    /**
+     * authorization code + PKCE verifier를 access token으로 교환 (프록시 경유).
+     * 프록시(/api/x/token)가 grant_type/Basic auth 조립을 담당하므로 clientId도 함께 전달.
+     */
+    exchangeCode(params: {
+        clientId: string;
+        redirectUri: string;
+        code: string;
+        codeVerifier: string;
+    }): Promise<XTokenResult>;
+    /** access token 소유자의 X 핸들 조회 (GET /2/users/me 프록시). */
+    getHandle(accessToken: string): Promise<{
+        handle: string;
+    }>;
+}
+
+export type { XAuthPort as X, XTokenResult as a };