@nexus-cross/pop 1.3.10-beta.2

package/dist/adapters/index.d.ts

@@ -0,0 +1,1175 @@
+import { C as CryptoPort, g as Secret, t as SecretHash, H as Hex, A as Address, d as ClaimSignerPort, S as SafeDropChainPort, k as DropState, I as Id, a as SafeDropApiPort, u as SocialIdentifier, O as OAuthProof, i as DropInbox, E as Envelope, L as LeaderboardEntry, n as PopEventName, m as HistoryPage, X as XConnection, h as BatchClaimSignature, o as SafeDrop } from '../createSafeDrop-qoNG59jB.js';
+import { PublicClient, WalletClient, Chain, Transport } from 'viem';
+import { X as XAuthPort, a as XTokenResult } from '../XAuthPort-BNJePosj.js';
+
+/**
+ * viem 기반 CryptoPort 구현. 컨트랙트 ABI 불필요 — 순수 암호 연산.
+ *
+ * keccak256는 one-pop-fe와 동일하게 `keccak256(toBytes(secret))`. withdraw의
+ * secret 인자도 `toHex(toBytes(secret))`라 인코딩이 정합한다. (0x로 시작하지 않는
+ * 일반 문자열은 utf8로, randomSecret도 0x 없는 hex라 utf8로 처리됨.)
+ */
+declare class ViemCryptoAdapter implements CryptoPort {
+    keccak256(input: Secret): SecretHash;
+    /** 32바이트 CSPRNG → 0x 없는 hex 64자 (URL-safe). */
+    randomSecret(): Secret;
+    /**
+     * digest(이미 EIP-712 해시)에 대한 서명자 복원. `hashMessage` 같은 추가 프리픽스를
+     * 붙이지 않는다 — 컨트랙트도 `ECDSA.recover(digest, sig)`로 그대로 검증한다.
+     */
+    recoverAddress(params: {
+        digest: Hex;
+        signature: Hex;
+    }): Promise<Address>;
+}
+
+/**
+ * 임시 claim 개인키로 claimDigest에 raw ECDSA 서명 → serialize (브라우저 로컬).
+ * (컨트랙트 withdraw가 서명에서 signer=claimAddr를 recover한다.)
+ */
+declare class ViemClaimSignerAdapter implements ClaimSignerPort {
+    signDigest(params: {
+        claimKey: Hex;
+        digest: Hex;
+    }): Promise<Hex>;
+}
+
+interface ViemSafeDropChainAdapterOptions {
+    address: Address;
+    publicClient: PublicClient;
+    /** approve/deposit/refund 서명용 지갑(연결된 MetaMask 등). */
+    walletClient: WalletClient;
+    chain: Chain;
+    /** withdraw용 임시 지갑 client의 RPC transport. 기본 http()(chain.rpcUrls). */
+    transport?: Transport;
+    /** withdraw gas/fee override. 기본 DEFAULT_WITHDRAW_GAS(gas-abstraction 대응). */
+    withdrawFees?: {
+        gas?: bigint;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    /**
+     * true면 EIP-2612 permit 예치를 쓴다(approve tx 없음, 서명 1회 + tx 1회).
+     * 배포본마다 deposit 시그니처가 다르므로 opt-in이다 — permit deposit이 없는
+     * 컨트랙트에 켜면 셀렉터가 없어 revert한다. 토큰도 permit을 지원해야 한다.
+     */
+    permit?: boolean;
+}
+/**
+ * SafeDrop 컨트랙트 어댑터 (viem). ABI: src/infrastructure/safedrop_abi.json.
+ * 드롭 키는 claimAddr, id는 소셜 식별자 string. 쓰기는 receipt success까지 확인.
+ */
+declare class ViemSafeDropChainAdapter implements SafeDropChainPort {
+    private readonly address;
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly chain;
+    private readonly transport;
+    private readonly withdrawFees;
+    /**
+     * permit 옵션을 켠 경우에만 채워진다. DepositUseCase는 이 프로퍼티의 존재
+     * 여부로 approve tx를 건너뛸지 판단하므로, 미지원 배포본에서는 undefined여야 한다.
+     */
+    readonly depositWithPermit?: SafeDropChainPort['depositWithPermit'];
+    constructor(options: ViemSafeDropChainAdapterOptions);
+    /**
+     * drops(claimAddr). 배포본에 따라 반환 필드가 8개(Foundry ABI) 또는 5개(permit
+     * 배포본)다 — 셀렉터가 같으므로 raw call 1회 후 디코딩만 나눈다. 8필드를 먼저
+     * 시도하는 이유: 짧은 데이터(5필드=192B)를 8필드로 읽으면 **에러가 나서** 안전하게
+     * 폴백되지만, 반대 순서면 8필드 데이터를 5필드로 조용히 오독한다.
+     */
+    getDrop(claimAddress: Address): Promise<DropState | null>;
+    /** 에스크로가 고정한 단일 ERC20. 5필드 배포본에서 drop.token을 채운다. */
+    private escrowToken;
+    getClaimDigest(params: {
+        recipient: Address;
+        id: Id;
+        salt: Hex;
+    }): Promise<Hex>;
+    approve(params: {
+        token: Address;
+        amount: bigint;
+    }): Promise<Hex>;
+    deposit(params: {
+        claimAddress: Address;
+        token: Address;
+        amount: bigint;
+        id: Id;
+        secretHash: SecretHash;
+    }): Promise<{
+        txHash: Hex;
+    }>;
+    /**
+     * permit 예치. approve tx 없이 typed-data 서명 1회 + deposit tx 1회.
+     * 이 배포본의 deposit에는 token 인자가 없다 — 컨트랙트가 token()으로 고정한다.
+     */
+    private permitDeposit;
+    /**
+     * permit 서명 도메인. EIP-5267 eip712Domain()이 있으면 그 값을 쓰고, 없으면
+     * name() + version '1'로 폴백한다. version을 상수로 박으면 다른 버전을 쓰는
+     * 토큰에서 ecrecover가 조용히 실패해 deposit 내부 revert로만 드러난다.
+     */
+    private permitDomain;
+    withdraw(params: {
+        claimKey: Hex;
+        recipient: Address;
+        id: Id;
+        salt: Hex;
+        signature: Hex;
+        secret: Secret;
+    }): Promise<Hex>;
+    /** validatorNonceById는 **bytes32(id 해시)** 로 키잉된다 — 원문 string이 아니다. */
+    getValidatorNonce(params: {
+        id: Id;
+    }): Promise<bigint>;
+    /** 온체인 EIP-712 다이제스트. 로컬 재조립 대신 이 값으로 백엔드 서명을 검증한다. */
+    getValidatorClaimDigest(params: {
+        recipient: Address;
+        id: Id;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<Hex>;
+    getValidator(): Promise<Address>;
+    getClaimedRecipient(params: {
+        id: Id;
+    }): Promise<Address>;
+    getLiveDropCount(params: {
+        id: Id;
+    }): Promise<bigint>;
+    /**
+     * 개별 withdraw와 달리 **연결된 수령인 지갑**이 보낸다 — 컨트랙트가 msg.sender와
+     * 서명의 recipient를 대조하므로 임시 claim 지갑으로는 보낼 수 없다(가스 대납 대상도 아님).
+     * simulate를 먼저 돌려 `ValidatorSigExpired`/`InvalidValidatorNonce`/
+     * `ECDSAInvalidSignature`를 이름으로 드러낸다.
+     */
+    withdrawByValidator(params: {
+        recipient: Address;
+        id: Id;
+        nonce: bigint;
+        deadline: bigint;
+        maxCount: number;
+        signature: Hex;
+    }): Promise<Hex>;
+    refund(params: {
+        claimAddress: Address;
+    }): Promise<Hex>;
+    private sponsorWrite;
+    private confirm;
+    private recoverRevertName;
+    private requireAccount;
+}
+
+/**
+ * one-pop-api 엔드포인트 — 패키지 내부 상수. onramp/adapters/endpoints.ts와
+ * 동일한 컨벤션(Vite import.meta.env + Next literal process.env, override →
+ * 환경 식별 → 기본 URL, https 검증)을 따른다.
+ *
+ * 우선순위 (override):
+ *   1) `VITE_ONE_POP_API_BASE_URL` (Vite 빌드)
+ *   2) `NEXT_PUBLIC_ONE_POP_API_BASE_URL` (Next.js)
+ *   3) 환경 식별(`VITE_ONE_POP_ENVIRONMENT` / `NEXT_PUBLIC_ONE_POP_ENVIRONMENT`
+ *      / `ONE_POP_ENVIRONMENT`)에 따라 DEFAULT_BASE_URL의 dev/stage/production
+ *
+ * 스펙: packages/pop/src/infrastructure/openapi.json (basePath `/api`)
+ */
+type PopEnvironment = 'dev' | 'stage' | 'production';
+interface PopApiPaths {
+    /** POST — 임시 claim 지갑 생성 (Bearer JWT). */
+    createWallet: string;
+    /** POST — pending 지갑 개인키 수령 (X OAuth 토큰). */
+    retrievePrivateKey: string;
+    /** GET — 수령 대기 인박스 (Bearer JWT + 활성 X 연결). */
+    drops: string;
+    /** GET — 카드 디자인 목록 (공개). */
+    envelopes: string;
+    /** GET — 토큰별 pending 잔액 상위 (공개). */
+    leaderboards: string;
+    /** GET — 내 온체인 이벤트 히스토리 (Bearer JWT). */
+    histories: string;
+    /** GET/POST/DELETE — X 연결 (Bearer JWT). */
+    xConnections: string;
+    /** POST — 일괄 수령 validator 서명 (Bearer JWT). */
+    batchClaimSignature: string;
+    /** GET — SSE 알림 스트림. pop은 구독하지 않는다(앱이 EventSource로 직접). */
+    eventsSubscribe: string;
+}
+declare const DEFAULT_POP_API_PATHS: PopApiPaths;
+/** 환경변수(override → 환경 식별)로 one-pop-api base URL을 결정한다. */
+declare function getOnePopApiBaseUrl(): string;
+/** 환경변수(override → 기본)로 cross-auth base URL을 결정한다. */
+declare function getCrossAuthBaseUrl(): string;
+
+/**
+ * one-pop-api HTTP 어댑터. 스키마: packages/pop/src/infrastructure/openapi.json
+ *   POST   /wallets                 (Bearer JWT)      → {address}
+ *   POST   /wallets/private-key      (oauth_token 본문) → {address,private_key}
+ *   GET    /drops                    (Bearer JWT)      → 수령 인박스
+ *   GET    /envelopes                (공개)            → 카드 디자인
+ *   GET    /leaderboards?token=      (공개)            → pending 상위
+ *   GET    /histories                (Bearer JWT)      → 온체인 이벤트
+ *   GET|POST|DELETE /x-connections   (Bearer JWT)      → X 연결
+ *   POST   /batch-claim-signature    (Bearer JWT)      → ValidatorClaim 서명
+ *
+ * base URL은 미지정 시 환경변수로 결정(getOnePopApiBaseUrl).
+ * wei-scale 값은 응답의 10진 문자열 → BigInt로 변환해 내보낸다(CLAUDE.md §4).
+ */
+interface HttpSafeDropApiAdapterOptions {
+    /** 미지정 시 환경변수(VITE_/NEXT_PUBLIC_ONE_POP_*)로 결정. */
+    baseUrl?: string;
+    /** SIWE JWT 공급자. Bearer 인증이 필요한 모든 호출이 사용한다. */
+    getJwt?: () => string | undefined | Promise<string | undefined>;
+    /** 테스트/SSR용 fetch 주입. 기본 globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** 엔드포인트 경로 override. 기본 DEFAULT_POP_API_PATHS. */
+    paths?: Partial<PopApiPaths>;
+}
+declare class HttpSafeDropApiAdapter implements SafeDropApiPort {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly getJwt?;
+    private readonly paths;
+    constructor(options?: HttpSafeDropApiAdapterOptions);
+    createClaimWallet(params: {
+        sender: Address;
+        recipient: SocialIdentifier;
+        message?: string;
+        envelopeId?: string;
+    }): Promise<{
+        claimAddress: Address;
+    }>;
+    retrieveClaimKey(params: {
+        senderAddress: Address;
+        oauth: OAuthProof;
+    }): Promise<{
+        claimKey: Hex;
+        claimAddress: Address;
+    }>;
+    listDrops(params?: {
+        token?: Address;
+    }): Promise<DropInbox>;
+    listEnvelopes(params?: {
+        locale?: string;
+    }): Promise<readonly Envelope[]>;
+    getLeaderboard(params: {
+        token: Address;
+    }): Promise<readonly LeaderboardEntry[]>;
+    listHistories(params?: {
+        event?: PopEventName;
+        page?: number;
+        pageSize?: number;
+    }): Promise<HistoryPage>;
+    getXConnection(): Promise<XConnection | null>;
+    connectX(params: {
+        oauth: OAuthProof;
+    }): Promise<XConnection>;
+    disconnectX(): Promise<void>;
+    requestBatchClaimSignature(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<BatchClaimSignature>;
+    private request;
+}
+
+declare const SAFEDROP_ABI: readonly [{
+    readonly type: "constructor";
+    readonly inputs: readonly [{
+        readonly name: "claimPeriod_";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "claimDigest";
+    readonly inputs: readonly [{
+        readonly name: "recipient";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "claimPeriod";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "claimedRecipientOf";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "deposit";
+    readonly inputs: readonly [{
+        readonly name: "claimAddr";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+        readonly internalType: "contract IERC20";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "secretHash";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "depositCountOf";
+    readonly inputs: readonly [{
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "depositsBySponsor";
+    readonly inputs: readonly [{
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "claimAddr";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+        readonly internalType: "contract IERC20";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+        readonly internalType: "uint128";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
+    }, {
+        readonly name: "secretHash";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "depositsOf";
+    readonly inputs: readonly [{
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "tuple[]";
+        readonly internalType: "struct SafeDrop.DepositRecord[]";
+        readonly components: readonly [{
+            readonly name: "claimAddr";
+            readonly type: "address";
+            readonly internalType: "address";
+        }, {
+            readonly name: "token";
+            readonly type: "address";
+            readonly internalType: "contract IERC20";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint128";
+            readonly internalType: "uint128";
+        }, {
+            readonly name: "expiry";
+            readonly type: "uint64";
+            readonly internalType: "uint64";
+        }, {
+            readonly name: "secretHash";
+            readonly type: "bytes32";
+            readonly internalType: "bytes32";
+        }, {
+            readonly name: "id";
+            readonly type: "string";
+            readonly internalType: "string";
+        }];
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "drops";
+    readonly inputs: readonly [{
+        readonly name: "claimAddr";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "recordIndex";
+        readonly type: "uint96";
+        readonly internalType: "uint96";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+        readonly internalType: "contract IERC20";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+        readonly internalType: "uint128";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
+    }, {
+        readonly name: "secretHash";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "eip712Domain";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "fields";
+        readonly type: "bytes1";
+        readonly internalType: "bytes1";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }, {
+        readonly name: "verifyingContract";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "extensions";
+        readonly type: "uint256[]";
+        readonly internalType: "uint256[]";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "liveClaimAddrsById";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address[]";
+        readonly internalType: "address[]";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "liveDropCountById";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "liveDropsById";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "claimAddrs";
+        readonly type: "address[]";
+        readonly internalType: "address[]";
+    }, {
+        readonly name: "records";
+        readonly type: "tuple[]";
+        readonly internalType: "struct SafeDrop.Drop[]";
+        readonly components: readonly [{
+            readonly name: "sponsor";
+            readonly type: "address";
+            readonly internalType: "address";
+        }, {
+            readonly name: "recordIndex";
+            readonly type: "uint96";
+            readonly internalType: "uint96";
+        }, {
+            readonly name: "token";
+            readonly type: "address";
+            readonly internalType: "contract IERC20";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint128";
+            readonly internalType: "uint128";
+        }, {
+            readonly name: "expiry";
+            readonly type: "uint64";
+            readonly internalType: "uint64";
+        }, {
+            readonly name: "secretHash";
+            readonly type: "bytes32";
+            readonly internalType: "bytes32";
+        }, {
+            readonly name: "salt";
+            readonly type: "bytes32";
+            readonly internalType: "bytes32";
+        }, {
+            readonly name: "id";
+            readonly type: "string";
+            readonly internalType: "string";
+        }];
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "refund";
+    readonly inputs: readonly [{
+        readonly name: "claimAddr";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "unclaimedCountOf";
+    readonly inputs: readonly [{
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "unclaimedDepositsOf";
+    readonly inputs: readonly [{
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "records";
+        readonly type: "tuple[]";
+        readonly internalType: "struct SafeDrop.DepositRecord[]";
+        readonly components: readonly [{
+            readonly name: "claimAddr";
+            readonly type: "address";
+            readonly internalType: "address";
+        }, {
+            readonly name: "token";
+            readonly type: "address";
+            readonly internalType: "contract IERC20";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint128";
+            readonly internalType: "uint128";
+        }, {
+            readonly name: "expiry";
+            readonly type: "uint64";
+            readonly internalType: "uint64";
+        }, {
+            readonly name: "secretHash";
+            readonly type: "bytes32";
+            readonly internalType: "bytes32";
+        }, {
+            readonly name: "id";
+            readonly type: "string";
+            readonly internalType: "string";
+        }];
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "unclaimedIndexesOf";
+    readonly inputs: readonly [{
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256[]";
+        readonly internalType: "uint256[]";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "withdraw";
+    readonly inputs: readonly [{
+        readonly name: "recipient";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+        readonly internalType: "bytes";
+    }, {
+        readonly name: "secret";
+        readonly type: "bytes";
+        readonly internalType: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "event";
+    readonly name: "Deposited";
+    readonly inputs: readonly [{
+        readonly name: "claimAddr";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+        readonly internalType: "uint256";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly indexed: false;
+        readonly internalType: "string";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+        readonly indexed: false;
+        readonly internalType: "uint64";
+    }, {
+        readonly name: "secretHash";
+        readonly type: "bytes32";
+        readonly indexed: false;
+        readonly internalType: "bytes32";
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "EIP712DomainChanged";
+    readonly inputs: readonly [];
+    readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "Refunded";
+    readonly inputs: readonly [{
+        readonly name: "claimAddr";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly indexed: false;
+        readonly internalType: "string";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+        readonly internalType: "uint256";
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "Withdrawn";
+    readonly inputs: readonly [{
+        readonly name: "claimAddr";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "recipient";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "sponsor";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly indexed: false;
+        readonly internalType: "string";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+        readonly internalType: "uint256";
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "error";
+    readonly name: "AmountOverflow";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "DropAlreadyExists";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "DropExpired";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "DropNotExpired";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "DropNotFound";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "DuplicateDropForId";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ECDSAInvalidSignature";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ECDSAInvalidSignatureLength";
+    readonly inputs: readonly [{
+        readonly name: "length";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ECDSAInvalidSignatureS";
+    readonly inputs: readonly [{
+        readonly name: "s";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "EmptyId";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "IdMismatch";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidShortString";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "NotSponsor";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ReentrancyGuardReentrantCall";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "SafeERC20FailedOperation";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "SaltMismatch";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "SecretMismatch";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "StringTooLong";
+    readonly inputs: readonly [{
+        readonly name: "str";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ZeroAmount";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ZeroClaimAddress";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ZeroRecipient";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ZeroToken";
+    readonly inputs: readonly [];
+}];
+
+/**
+ * 일괄 수령(batch claim) ABI — **배포 바이트코드에서 검증한** as-built 기록.
+ *
+ * `src/infrastructure/safedrop_abi.json`(Foundry 산출물)에는 이 함수들이 없다.
+ * 반대로 openapi.json 설명이 말하는 `validatorNonceById`는 **string이 아니라
+ * bytes32(=keccak256(utf8(id)))** 를 받는다. 그래서 자동 생성 ABI를 믿지 않고
+ * 배포본(CROSS testnet 612044 `0x50911242D9EA1554297ad11eb634230C56ae769c`)의
+ * dispatcher 셀렉터로 직접 확인한 시그니처만 여기 둔다 (2026-07-30 검증):
+ *
+ *   3a5381b5 validator()
+ *   aee5b003 validatorClaimDigest(address,string,uint256,uint256)
+ *   dc4d9bff validatorNonceById(bytes32)          ← id는 **해시**로 키잉
+ *   a730b8c5 withdrawByValidator(address,string,uint256,uint256,uint256,bytes)
+ *   0d14a67d ValidatorSigExpired()
+ *   dcf5a899 InvalidValidatorNonce()
+ *
+ * eth_call로 확인한 검증 순서: deadline → nonce → 서명(ECDSA).
+ * `maxCount`는 **서명 대상이 아니다** — 그래서 서명 1건으로 페이지네이션을 계속
+ * 재사용할 수 있다(openapi 설명과 일치). 온체인 상한은 없고 가스가 한계다.
+ *
+ * EIP-712 (배포본 `eip712Domain()`으로 확인):
+ *   domain = { name: 'ONEpop', version: '1', chainId, verifyingContract: SafeDrop }
+ *   type   = ValidatorClaim(address recipient,string id,uint256 nonce,uint256 deadline)
+ *   → digest는 `validatorClaimDigest()`가 온체인에서 그대로 돌려주므로, 로컬에서
+ *     재조립하지 말고 그 값을 읽어 쓴다(백엔드와의 불일치를 가스 전에 잡는다).
+ */
+declare const SAFEDROP_VALIDATOR_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "validator";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "validatorClaimDigest";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "validatorNonceById";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "idHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "withdrawByValidator";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "maxCount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "liveDropCountById";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "claimedRecipientOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ValidatorSigExpired";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidValidatorNonce";
+    readonly inputs: readonly [];
+}];
+
+/**
+ * cross-auth SIWE 로그인 클라이언트. createClaimWallet에 필요한 플랫폼 JWT를 얻는다.
+ *   1) unsignedHash(chainId, address) → { hash, message }
+ *   2) 앱이 지갑으로 message 서명(signMessage)
+ *   3) siweToken(address, signature) → { token, refresh }
+ *
+ * 서명은 앱(wagmi/walletClient)이 수행 — 이 클라이언트는 HTTP만 담당한다.
+ * domain은 cross-auth가 SIWE domain으로 사용(기본 window.location.origin).
+ */
+interface CrossAuthClientOptions {
+    /** 미지정 시 환경변수(VITE_/NEXT_PUBLIC_CROSS_AUTH_URL) 또는 dev 기본값. */
+    baseUrl?: string;
+    /** SIWE domain. 미지정 시 globalThis.location.origin. */
+    domain?: string;
+    fetchImpl?: typeof fetch;
+}
+declare class CrossAuthClient {
+    private readonly baseUrl;
+    private readonly domain;
+    private readonly fetchImpl;
+    constructor(options?: CrossAuthClientOptions);
+    /** SIWE 서명 대상 메시지 발급. cross-auth 필드는 snake_case `chain_id`. */
+    unsignedHash(chainId: number, address: string): Promise<{
+        hash: string;
+        message: string;
+    }>;
+    /** 서명 → 플랫폼 JWT 교환. */
+    siweToken(address: string, signature: string): Promise<{
+        token: string;
+        refresh: string;
+    }>;
+    private post;
+}
+
+interface CreateSafeDropClientOptions {
+    /** SafeDrop 컨트랙트 주소. */
+    contractAddress: Address;
+    publicClient: PublicClient;
+    /** approve/deposit/refund 서명용 연결 지갑. */
+    walletClient: WalletClient;
+    chain: Chain;
+    /** withdraw 임시 지갑 client의 RPC transport. */
+    transport?: Transport;
+    /** withdraw gas/fee override (gas-abstraction). */
+    withdrawFees?: ViemSafeDropChainAdapterOptions['withdrawFees'];
+    /**
+     * true면 EIP-2612 permit 예치 — approve tx가 사라지고 서명 1회 + tx 1회가 된다.
+     * SafeDrop 배포본과 토큰 양쪽이 permit을 지원할 때만 켠다.
+     */
+    permit?: boolean;
+    /** 수령 링크 base URL. */
+    claimBaseUrl: string;
+    /** one-pop-api 어댑터 옵션(baseUrl 미지정 시 환경변수). */
+    api?: HttpSafeDropApiAdapterOptions;
+    /** 직접 만든 SafeDropApiPort를 쓰려면 주입(mock/커스텀). */
+    apiPort?: SafeDropApiPort;
+}
+/** viem + HTTP 어댑터를 조립해 SafeDrop을 반환하는 기본 진입점. */
+declare function createSafeDropClient(options: CreateSafeDropClientOptions): SafeDrop;
+
+interface Pkce {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+/** code_verifier(43자) + S256 code_challenge 생성. */
+declare function generatePkce(): Promise<Pkce>;
+/** CSRF 방지용 state (base64url 22자). */
+declare function generateState(): string;
+
+/**
+ * X OAuth2 프록시 어댑터. 앱의 same-origin Next 라우트를 호출한다(one-pop-fe와 동일 계약).
+ *   POST {tokenPath}  { clientId, redirectUri, code, verifier } → X 토큰 응답(access_token)
+ *   GET  {mePath}     Authorization: Bearer <token>            → GET /2/users/me ({ data: { username } })
+ *
+ * 프록시가 grant_type/Basic auth 조립과 X API 응답 전달을 담당한다. 다르면 옵션으로 경로만 조정.
+ */
+interface HttpXAuthAdapterOptions {
+    /** 프록시 base URL. 기본 '' (same-origin 상대경로). */
+    baseUrl?: string;
+    /** 토큰 교환 프록시 경로. 기본 '/api/x/token'. */
+    tokenPath?: string;
+    /** 핸들 조회 프록시 경로. 기본 '/api/x/me'. */
+    mePath?: string;
+    fetchImpl?: typeof fetch;
+}
+declare class HttpXAuthAdapter implements XAuthPort {
+    private readonly baseUrl;
+    private readonly tokenPath;
+    private readonly mePath;
+    private readonly fetchImpl;
+    constructor(options?: HttpXAuthAdapterOptions);
+    exchangeCode(params: {
+        clientId: string;
+        redirectUri: string;
+        code: string;
+        codeVerifier: string;
+    }): Promise<XTokenResult>;
+    getHandle(accessToken: string): Promise<{
+        handle: string;
+    }>;
+    private call;
+}
+
+/** verifier/state 임시 보관. 기본은 sessionStorage 어댑터. */
+interface SessionStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+interface XAuthClientOptions {
+    clientId: string;
+    redirectUri: string;
+    /** 기본 'tweet.read users.read offline.access' (GET /2/users/me + refresh token). */
+    scope?: string;
+    /** 기본 X authorize 엔드포인트. */
+    authorizeUrl?: string;
+    /** 토큰 교환/핸들 조회 프록시 어댑터. */
+    port: XAuthPort;
+    /** 기본 globalThis.sessionStorage 어댑터. */
+    storage?: SessionStore;
+}
+/**
+ * X OAuth2 PKCE 플로우. UI/리다이렉트는 앱이 담당한다:
+ *   const { authorizeUrl } = await xauth.start(); location.assign(authorizeUrl);
+ *   // 콜백에서:
+ *   const { oauth, handle } = await xauth.complete(location.href);
+ *   await safeDrop.retrieveClaimKey({ senderAddress, oauth });
+ */
+declare class XAuthClient {
+    private readonly opts;
+    constructor(options: XAuthClientOptions);
+    /** PKCE·state 생성·저장 후 X authorize URL 반환. 리다이렉트는 호출자 몫. */
+    start(): Promise<{
+        authorizeUrl: string;
+        state: string;
+    }>;
+    /** 콜백 URL에서 code/state 추출 → state 검증 → 토큰 교환 → 핸들 조회. */
+    complete(callbackUrl: string): Promise<{
+        oauth: OAuthProof;
+        handle: string;
+    }>;
+}
+
+export { type CreateSafeDropClientOptions, CrossAuthClient, type CrossAuthClientOptions, DEFAULT_POP_API_PATHS, HttpSafeDropApiAdapter, type HttpSafeDropApiAdapterOptions, HttpXAuthAdapter, type HttpXAuthAdapterOptions, type Pkce, type PopApiPaths, type PopEnvironment, SAFEDROP_ABI, SAFEDROP_VALIDATOR_ABI, type SessionStore, ViemClaimSignerAdapter, ViemCryptoAdapter, ViemSafeDropChainAdapter, type ViemSafeDropChainAdapterOptions, XAuthClient, type XAuthClientOptions, createSafeDropClient, generatePkce, generateState, getCrossAuthBaseUrl, getOnePopApiBaseUrl };