@nexus-cross/pop 1.4.0-beta.1 → 1.4.0-beta.3

package/AGENTS.md

@@ -39,7 +39,7 @@ pnpm add @nexus-cross/pop viem        # + react if using ./react
 
 | What | Where it goes | Notes |
 |---|---|---|
-| SafeDrop contract address | `createSafeDropClient({ contractAddress })` | per-chain deployment |
+| SafeDrop contract address | selected by `ONE_POP_ENVIRONMENT` | explicit `contractAddress` remains an override |
 | 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 |
@@ -51,13 +51,14 @@ 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_ENVIRONMENT` / `NEXT_PUBLIC_ONE_POP_ENVIRONMENT` / `ONE_POP_ENVIRONMENT` | `dev` \| `stage` \| `production` (default `production`) → picks the API and contract deployment together |
 | `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.
+Dev and stage contract deployments are built in. Production contract addresses are not configured
+yet, so production must pass `contractAddress` explicitly. Claim base URL and X client id remain app options.
+The protocol fee is fixed at 5% (`ONE_POP_FEE_BPS = 500n`).
 
 ## 4. Wiring
 
@@ -75,12 +76,10 @@ 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 },
 });
 ```
@@ -94,7 +93,7 @@ The provider only carries the client through context — no connection logic liv
 
 ```ts
 const envelopes = await safeDrop.listEnvelopes();          // optional card designs
-const { withdrawLink, claimAddress } = await safeDrop.deposit({
+const deposit = await safeDrop.deposit({
   sender: address,
   recipient: { provider: 'x', handle: 'theo_13303' },
   token: ERC20_ADDRESS,
@@ -102,23 +101,25 @@ const { withdrawLink, claimAddress } = await safeDrop.deposit({
   message: 'Happy birthday!',                              // optional, <= 140 runes
   envelopeId: envelopes[0]?.id,                            // optional
 });
+if (!deposit.isMapped) {
+  location.assign(buildComposeUrl(buildDmText(deposit.withdrawLink), recipientId));
+}
 ```
 
-Then hand the link to the recipient (X DM compose):
-`location.assign(buildComposeUrl(buildDmText(withdrawLink), recipientId))`.
+Mapped deposits have no claim link because the mapped recipient receives them directly.
 
 ### Claim (recipient, on the claim route)
 
 ```ts
-const { sender, secret } = parseWithdrawLink(location.href);
+const { sender, claimAddress, 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 });
+const claim = await safeDrop.retrieveClaimKey({ claimAddress: claimAddress!, senderAddress: sender!, oauth });
+if (claim.isMapped) throw new Error('Use the mapped withdrawal flow');
+await safeDrop.withdraw({ recipient: myAddress, sponsor: sender!, claimAddress, secret: secret!, claimKey: claim.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.
+`claimAddress` selects the exact pending drop; OAuth proves entitlement to that drop's handle.
 
 ### Inbox / social surfaces
 
@@ -126,8 +127,8 @@ It returns **only the latest pending drop** for that `(sender, handle)` pair and
 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 });
+const top = await safeDrop.getLeaderboard({ token: ERC20_ADDRESS, page: 1, pageSize: 10 });
+const page = await safeDrop.listHistories({ type: 'received', page: 1, pageSize: 20 });
 await safeDrop.disconnectX();
 ```
 
@@ -137,7 +138,7 @@ batch-claim CTA on it.
 ### Refund
 
 ```ts
-await safeDrop.refund({ claimAddress });   // sponsor only, after expiry
+await safeDrop.refund({ claimAddress, sponsor: address });
 ```
 
 ### Batch claim — drain every drop for a handle in one flow
@@ -146,33 +147,25 @@ await safeDrop.refund({ claimAddress });   // sponsor only, after expiry
 const { txHashes, recipient } = await safeDrop.batchClaim({
   id: myHandle,            // normalized internally
   oauth,                   // X OAuth proof (handle ownership)
-  maxCount: 30,            // optional page size, default 30
+  sponsor: sender,
+  claimAddress,
+  claimKey,
+  secret,
 });
 ```
 
 `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.
+resolve the anchor and pending drop keys → read `validatorNonceById(keccak256(utf8(id)))` →
+request and verify the backend signature → call `withdrawUnmappedBatchByKeys` once.
 
 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.
+- The anchor temporary wallet submits the transaction with the configured sponsored fee path.
+- The anchor drop's `secret` and `claimKey` are required in addition to the validator signature.
+- A successful batch consumes the nonce and signature. Request a fresh signature for another call.
+- Each page gets a fresh nonce and validator signature; `maxCount` defaults to 30.
 - 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.
 
@@ -182,8 +175,8 @@ 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)
+submit  withdrawUnmappedBatchByKeys(recipient, id, anchorDropKey, claimSignature,
+                                    secret, nonce, deadline, dropKeys, validatorSignature)
 errors  ValidatorSigExpired() → deadline passed | InvalidValidatorNonce() → stale nonce
         ECDSAInvalidSignature() → signer is not validator()
 ```
@@ -207,33 +200,31 @@ The SDK does not wrap it — use `EventSource` directly. Delivery is best-effort
    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.
+4. **The current deployment requires EIP-2612 permit.** The token must support EIP-2612.
+5. **Keep `transactionFees` as EIP-1559 with tip ≥ 1 gwei.** Every write supplies an explicit
+   gas limit. Batch gas is `batchBaseGas + batchGasPerDrop * count` and may not exceed
+   `maxBatchGas`; calibrate these values below the chain block gas limit.
 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.
+8. **Drops are keyed by bytes32.** Resolve `activeDropOf(claimAddress)` before `drops(dropKey)`.
 
 ## 7. API surface
 
 | `safeDrop` method | Endpoint / chain call | Auth |
 |---|---|---|
-| `deposit` | `POST /wallets` + `approve`/`deposit` (or permit deposit) | JWT |
+| `deposit` | `POST /wallets` + 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)` | — |
+| `refund` | `activeDropOf(claimAddr)` + `refund(dropKey)` | sponsor wallet |
+| `getDrop` | `activeDropOf(claimAddr)` + `drops(dropKey)` | — |
 | `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 |
+| `batchClaim` | `POST /batch-claim-signature` + `withdrawUnmappedBatchByKeys` | JWT + X OAuth token + anchor claim key |
 | `requestBatchClaimSignature` | `POST /batch-claim-signature` (low-level; prefer `batchClaim`) | JWT + X OAuth token |
 
 ## 8. Errors
@@ -265,4 +256,4 @@ Everything rejects with `SafeDropError` — branch on `err.code`, never on the m
   `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.
+- Using a token without EIP-2612 permit support.

package/README.md

@@ -24,7 +24,7 @@ npm i @nexus-cross/pop viem   # react는 선택
 
 ## 개념
 
-- **claimAddress** — 드롭당 임시 지갑 주소. 온체인 조회 키(`drops(claimAddress)`).
+- **claimAddress** — 드롭당 임시 지갑 주소. `activeDropOf`로 현재 drop key를 찾는 데 사용.
 - **secret** — 평문 비밀 문구. **어떤 서버에도 전송되지 않고** 수령 링크의 `#fragment`에만 담긴다.
 - **withdrawLink** — `…/claim?sender=<addr>#<secret>`. 이 링크를 X DM으로 수령인에게 보낸다.
 - **claimKey** — 임시 claim 지갑의 개인키. 수령인이 X OAuth 검증 후 백엔드에서 받아 가스 대납 withdraw에 쓴다.
@@ -41,12 +41,11 @@ 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와 ONEpop 주소는 VITE_/NEXT_PUBLIC_ONE_POP_ENVIRONMENT로 함께 결정
   api: { getJwt: async () => siweJwt },   // deposit(createClaimWallet)에 SIWE JWT 필요
 });
 ```
@@ -65,7 +64,9 @@ const { token } = await auth.siweToken(address, signature);   // token = getJwt
 ## 1) Deposit — 토큰 보내기
 
 ```ts
-const { withdrawLink, claimAddress } = await safeDrop.deposit({
+import { buildComposeUrl, buildDmText } from '@nexus-cross/pop';
+
+const deposit = await safeDrop.deposit({
   sender: address,                                  // 연결된 지갑 = 스폰서
   recipient: { provider: 'x', handle: 'theo_13303' },
   token: '0x…ERC20',
@@ -74,18 +75,16 @@ const { withdrawLink, claimAddress } = await safeDrop.deposit({
   envelopeId: 'classic-coral',                      // 선택 — listEnvelopes()의 id
   // secret 미지정 시 자동 생성
 });
+if (!deposit.isMapped) {
+  location.assign(buildComposeUrl(buildDmText(deposit.withdrawLink), recipientId));
+}
 ```
 
 `message`·`envelopeId`는 **백엔드에만 저장**되는 메타데이터다(컨트랙트에 필드 없음).
 
-내부 흐름: 임시 claim 지갑 생성(백엔드) → `approve` → `deposit` → 링크 생성. `amount`는 **BigInt로 끝까지** 유지한다 (Number 변환 금지).
-
-수령인에게 링크 전달 (X DM 작성창):
+내부 흐름: 임시 claim 지갑 생성(백엔드) → EIP-2612 permit 서명 → `deposit` → 링크 생성. `amount`는 **BigInt로 끝까지** 유지한다 (Number 변환 금지).
 
-```ts
-import { buildDmText, buildComposeUrl } from '@nexus-cross/pop';
-location.assign(buildComposeUrl(buildDmText(withdrawLink), recipientId));
-```
+`isMapped: true`면 이미 매핑된 수령인으로 즉시 예치되어 claim link가 없다.
 
 ## 2) Withdraw — 수령인이 받기
 
@@ -95,7 +94,7 @@ location.assign(buildComposeUrl(buildDmText(withdrawLink), recipientId));
 import { parseWithdrawLink } from '@nexus-cross/pop';
 import { XAuthClient, HttpXAuthAdapter } from '@nexus-cross/pop/adapters';
 
-const { sender, secret } = parseWithdrawLink(location.href);
+const { sender, claimAddress, secret } = parseWithdrawLink(location.href);
 
 // (a) X OAuth2 PKCE — 리다이렉트는 앱이 담당
 const xauth = new XAuthClient({
@@ -108,37 +107,38 @@ const xauth = new XAuthClient({
 const { oauth } = await xauth.complete(location.href);
 
 // (b) OAuth 검증 → 임시 claim 키/주소 수령 (point of return)
-const { claimKey, claimAddress } = await safeDrop.retrieveClaimKey({
+const claim = await safeDrop.retrieveClaimKey({
+  claimAddress: claimAddress!,
   senderAddress: sender!,
   oauth,
 });
+if (claim.isMapped) throw new Error('Use the mapped withdrawal flow');
 
 // (c) 가스 대납 withdraw — 임시 지갑이 직접 tx 전송
 const { txHash } = await safeDrop.withdraw({
   recipient: myReceivingAddress,   // 수령인이 지정, 서명에 바인딩
+  sponsor: sender!,
   claimAddress,
   secret: secret!,
-  claimKey,
+  claimKey: claim.claimKey,
 });
 ```
 
-## 3) Refund — 만료 후 환불
+## 3) Refund — sponsor 환불
 
 ```ts
-await safeDrop.refund({ claimAddress });   // 만료 후 sponsor(msg.sender)만 가능
+await safeDrop.refund({ claimAddress, sponsor: address });
 ```
 
 ## 조회 — 드롭 상태 (온체인)
 
 ```ts
-const drop = await safeDrop.getDrop(claimAddress);   // 없으면 null
-// drop: DropState { claimAddress, sponsor, amount, secretHash, salt, id, token?, expiry? }
+const drop = await safeDrop.getDrop(claimAddress, sponsor);   // 없으면 null
+// drop: DropState { dropKey, claimAddress, sponsor, recipient, amount, secretHash, id, token }
 ```
 
-⚠️ `token`·`expiry`는 **optional**이다 — 배포본마다 `drops`의 반환 필드가 다르다(permit
-배포본은 5개: sponsor/amount/secretHash/salt/id). 어댑터가 두 형태를 모두 디코딩하고
-`token`은 에스크로 `token()`으로 채우지만, **`expiry`는 5필드 배포본에서 `undefined`** 다.
-만료 판정 전에 존재 여부를 확인하라(`undefined` = 만료 아님이 아니라 *알 수 없음*).
+현재 컨트랙트는 `activeDropOf(claimAddress)`로 key를 찾고 `drops(dropKey)`를 조회한다.
+토큰은 드롭별 필드가 아니라 에스크로의 고정 `token()` 값이다.
 
 ## 4) 백엔드 조회 — 인박스 · X 연결 · 리더보드 · 히스토리
 
@@ -152,15 +152,15 @@ 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 }
+// { items, count, totalAmount, hasClaimedBefore, mappedRecipient, pendingChangeTo }
+//   PendingDrop { id, dropKey, claimAddress, token, amount, message, envelopeId, depositedAt, sender }
 
 // 카드 디자인 · 리더보드 (공개 — JWT 불필요)
 const envelopes = await safeDrop.listEnvelopes({ locale: 'ko' });
-const top = await safeDrop.getLeaderboard({ token: '0x…ERC20' });
+const top = await safeDrop.getLeaderboard({ token: '0x…ERC20', page: 1, pageSize: 10 });
 
-// 내 온체인 이벤트 (Deposited | Withdrawn | Refunded | BatchWithdrawn)
-const page = await safeDrop.listHistories({ event: 'Withdrawn', page: 1, pageSize: 20 });
+// 내 drop 히스토리
+const page = await safeDrop.listHistories({ type: 'received', page: 1, pageSize: 20 });
 ```
 
 `inbox.hasClaimedBefore === false`면 **첫 수령은 개별 claim만** 가능하다 — 일괄 수령 CTA를 이 값으로 게이트한다.
@@ -169,26 +169,25 @@ const page = await safeDrop.listHistories({ event: 'Withdrawn', page: 1, pageSiz
 
 ```ts
 const { txHashes, recipient } = await safeDrop.batchClaim({
-  id: myHandle,        // 내부에서 normalizeHandle
-  oauth,               // 핸들 소유 증명 (X OAuth)
-  maxCount: 30,        // 선택 — tx 1건이 처리할 건수(기본 30)
+  id: myHandle,
+  oauth,
+  sponsor: sender,
+  claimAddress,
+  claimKey,
+  secret,
 });
 ```
 
-컨트랙트가 강제하는 순서대로 진행한다:
-`validatorNonceById(keccak256(utf8(id)))` → 백엔드 서명 발급 → 온체인
-`validatorClaimDigest(recipient, id, nonce, deadline)` 조회 → **서명이 `validator()`로
-복원되는지 가스 쓰기 전에 검증** → `liveDropCountById(id)`가 0이 될 때까지
-`withdrawByValidator` 반복(서명 1건 재사용).
+컨트랙트가 강제하는 순서대로 진행한다: anchor drop key와 pending keys 조회 →
+`validatorNonceById` → 백엔드 서명 → 서명자 검증 →
+`withdrawUnmappedBatchByKeys` 1회 호출. validator 서명은 성공한 호출마다 소비된다.
 
 | 개별 수령과 다른 점 | 내용 |
 |---|---|
-| secret | **불필요** — 게이트는 validator 서명이다 |
+| secret | anchor drop의 secret/claim key가 필요하다 |
 | 수령 주소 | **SIWE 인증 주소로 고정**. 다른 주소를 넘기면 `SIGN_FAILED`(그 주소로 SIWE 재로그인해야 함) |
-| tx 전송자 | **수령인 본인 지갑**(컨트랙트가 `msg.sender` 대조). 임시 claim 지갑 불가 = **가스 대납 없음** |
-| 서명 재사용 | `maxCount`는 서명 대상이 아니라 페이지 크기 → 페이지마다 재발급 금지 |
-| 첫 수령 | 개별 claim이 선행돼야 한다 — 온체인 `claimedRecipientOf(id)`가 zero면 `DROP_NOT_FOUND`로 차단 |
-| 목적지 교차검증 | 서명된 recipient ≠ `claimedRecipientOf(id)`면 서명이 유효해도 전송하지 않음(`SIGN_FAILED`) |
+| tx 전송자 | anchor 임시 claim 지갑 |
+| 서명 재사용 | 불가 — nonce는 성공한 batch 호출마다 소비됨 |
 
 `SIGN_FAILED`가 나면 백엔드 서명이 컨트랙트가 기대하는 값과 다르다(EIP-712 domain/type 불일치,
 낡은 nonce, `personal_sign` 프리픽스). 재시도해도 동일하게 실패하니 그대로 노출한다.
@@ -200,9 +199,8 @@ const { txHashes, recipient } = await safeDrop.batchClaim({
 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)
+submit  withdrawUnmappedBatchByKeys(recipient, id, anchorDropKey, claimSignature,
+                                    secret, nonce, deadline, dropKeys, validatorSignature)
 검증 순서  deadline(ValidatorSigExpired) → nonce(InvalidValidatorNonce) → 서명(ECDSAInvalidSignature)
 ```
 
@@ -211,8 +209,7 @@ submit  withdrawByValidator(address recipient, string id, uint256 nonce,
 두 조건을 클라이언트에서 선제 차단하지만 온체인 강제의 대체물은 아니다 —
 `docs/pop/02-frontend-dependencies.md#검증-한계-중요` 참조.
 
-이 함수들은 `safedrop_abi.json`(Foundry 산출물, 배포본과 불일치)에 없다 — SDK는
-`adapters/validatorAbi.ts`에 바이트코드로 검증한 ABI를 따로 들고 있다.
+전체 현재 ABI는 `safedrop_abi.json`에서 직접 export된다.
 서명만 직접 받아 쓰려면 저수준 `safeDrop.requestBatchClaimSignature({ id, oauth, nonce, deadline })`.
 </details>
 
@@ -245,7 +242,11 @@ Provider는 client를 context로 넣기만 한다 — 연결 로직은 없다.
 | `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`)만 허용.
+environment 하나로 one-pop-api와 ONEpop/Permit ERC20/NFT/Validator/FeeRecipient 주소를 함께 고른다.
+dev/stage 주소는 패키지에 내장되어 있으며 production contract는 아직 미설정이므로 production에서는
+`contractAddress`를 직접 넘겨야 한다. API override 미지정 시 environment의 기본 URL을 사용한다.
+base URL은 https(또는 `http://localhost`)만 허용한다. 프로토콜 수수료는 5% 고정이며
+`ONE_POP_FEE_BPS`(`500n`)와 `ONE_POP_BPS_DENOMINATOR`(`10_000n`)를 제공한다.
 
 ## 에러
 
@@ -279,13 +280,14 @@ override 미지정 시 environment로 기본 URL을 고른다. base URL은 https
 
 | 옵션 | 타입 | 기본 | 설명 |
 |---|---|---|---|
-| `contractAddress` | `Address` | — (필수) | SafeDrop 컨트랙트 주소 |
+| `contractAddress` | `Address` | environment의 ONEpop 주소 | 테스트/별도 배포 시 override. production 주소 미설정 상태에서는 필수 |
 | `publicClient` | viem `PublicClient` | — (필수) | 읽기·getDrop·digest |
-| `walletClient` | viem `WalletClient` | — (필수) | approve/deposit/refund 서명(연결 지갑) |
+| `walletClient` | viem `WalletClient` | — (필수) | 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 |
+| `transactionFees` | `SafeDropTransactionFees` | 아래 gas-abstraction 기본 | 모든 write의 EIP-1559/gas override |
+| `withdrawFees` | `SafeDropTransactionFees` | — | deprecated alias |
 | `api` | `HttpSafeDropApiAdapterOptions` | — | one-pop-api 어댑터 옵션(아래) |
 | `apiPort` | `SafeDropApiPort` | — | 직접 구현/mock 주입(지정 시 `api` 무시) |
 
@@ -298,17 +300,23 @@ override 미지정 시 environment로 기본 URL을 고른다. base URL은 https
 | `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` 기본값
+### `ViemSafeDropChainAdapter.transactionFees` 기본값
 
-가스 대납(sponsor 과금)을 위한 type-2 dynamic-fee 값. 잔고 0 임시 지갑도 통과. `estimateGas`가 잔고 0에서 실패하므로 gas limit은 고정:
+모든 write는 `type: 'eip1559'`와 gas limit을 명시해 wallet/RPC gas estimation을 피한다.
+batch gas는 `batchBaseGas + batchGasPerDrop × count`이며 `maxBatchGas` 초과 시 전송 전에 실패한다.
 
 ```
-gas: 300_000n
+gas: 1_000_000n
+batchBaseGas: 1_000_000n
+batchGasPerDrop: 750_000n
+maxBatchGas: 30_000_000n
 maxFeePerGas: 4_000_000_000n        // 4 gwei
 maxPriorityFeePerGas: 1_000_000_000n // 1 gwei (노드 최소 tip)
 ```
 
-override는 정상 fee(tip ≥ 1 gwei) + type-2를 유지해야 sponsor 과금이 동작한다.
+기본 batch 30건은 `23_500_000` gas다(CROSS testnet block gas limit `105_000_000` 아래).
+실제 배포 환경의 block gas limit과 실행량에 맞춰 네 값을 함께 조정해야 하며,
+tip ≥ 1 gwei의 type-2를 유지해야 sponsor 과금이 동작한다.
 
 ### `CrossAuthClient(options)` — SIWE JWT 발급 (`getJwt`용)