@clawnch/clawncher-sdk 0.1.3 → 0.3.0

package/dist/permit2.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Permit2 — EIP-712 signature-based token approvals for Uniswap V4.
+ *
+ * Permit2 replaces per-contract ERC20 approvals with a two-step model:
+ *   1. Owner approves Permit2 once (ERC20.approve(Permit2, MAX))
+ *   2. For each swap/LP action, owner signs an EIP-712 permit granting
+ *      the router/PositionManager a time-limited, amount-limited allowance
+ *
+ * Two transfer modes:
+ *
+ * **AllowanceTransfer** — used by PositionManager for LP operations
+ *   - On-chain nonce tracking (uint48, auto-incremented per token+spender)
+ *   - Supports amount limits and expiration timestamps
+ *   - sign PermitSingle/PermitBatch → call permit() → router calls transferFrom()
+ *
+ * **SignatureTransfer** — used by UniversalRouter for swaps
+ *   - Off-chain nonce (uint256, bitmap-based, single-use)
+ *   - No on-chain state change for the permit itself
+ *   - sign PermitTransferFrom → router calls permitTransferFrom() in one tx
+ *   - Supports "witness" data for swap parameters
+ *
+ * @see https://docs.uniswap.org/contracts/permit2/overview
+ * @see https://github.com/Uniswap/permit2
+ */
+import { type Address, type Hash, type Hex, type PublicClient, type WalletClient } from 'viem';
+/** Permit2 is deployed at the same address on all chains */
+export declare const PERMIT2_ADDRESS: Address;
+export interface Permit2Config {
+    /** Wallet client for signing and sending transactions */
+    wallet: WalletClient & {
+        account: {
+            address: Address;
+        };
+    };
+    /** Public client for reads */
+    publicClient: PublicClient;
+    /** Chain ID (default: 8453 = Base) */
+    chainId?: number;
+}
+/** Permit2 allowance state for a token/spender pair */
+export interface Permit2Allowance {
+    /** Current approved amount (uint160) */
+    amount: bigint;
+    /** Expiration timestamp (unix seconds) */
+    expiration: number;
+    /** Current nonce (auto-increments on each permit() call) */
+    nonce: number;
+}
+/** Parameters for signing a single AllowanceTransfer permit */
+export interface PermitSingleParams {
+    /** Token to permit */
+    token: Address;
+    /** Spender (e.g. UniversalRouter or PositionManager) */
+    spender: Address;
+    /** Amount to permit (default: max uint160) */
+    amount?: bigint;
+    /** Permit expiration in seconds from now (default: 30 days) */
+    expirationSeconds?: number;
+    /** Signature deadline in seconds from now (default: 30 minutes) */
+    sigDeadlineSeconds?: number;
+}
+/** Parameters for signing a batch AllowanceTransfer permit */
+export interface PermitBatchParams {
+    /** Tokens and amounts to permit */
+    tokens: Array<{
+        token: Address;
+        amount?: bigint;
+        expirationSeconds?: number;
+    }>;
+    /** Spender (e.g. PositionManager) */
+    spender: Address;
+    /** Signature deadline in seconds from now (default: 30 minutes) */
+    sigDeadlineSeconds?: number;
+}
+/** Parameters for signing a SignatureTransfer permit (used by UniversalRouter) */
+export interface PermitTransferFromParams {
+    /** Token to transfer */
+    token: Address;
+    /** Max amount to transfer */
+    amount: bigint;
+    /** Spender (the contract that will call permitTransferFrom) */
+    spender: Address;
+    /** Nonce (caller-chosen, must be unused) */
+    nonce: bigint;
+    /** Deadline in seconds from now (default: 30 minutes) */
+    deadlineSeconds?: number;
+}
+/** Signed permit ready for submission */
+export interface SignedPermitSingle {
+    permit: {
+        details: {
+            token: Address;
+            amount: bigint;
+            expiration: number;
+            nonce: number;
+        };
+        spender: Address;
+        sigDeadline: bigint;
+    };
+    signature: Hex;
+    owner: Address;
+}
+/** Signed batch permit */
+export interface SignedPermitBatch {
+    permit: {
+        details: Array<{
+            token: Address;
+            amount: bigint;
+            expiration: number;
+            nonce: number;
+        }>;
+        spender: Address;
+        sigDeadline: bigint;
+    };
+    signature: Hex;
+    owner: Address;
+}
+/** Signed SignatureTransfer permit */
+export interface SignedPermitTransferFrom {
+    permit: {
+        permitted: {
+            token: Address;
+            amount: bigint;
+        };
+        nonce: bigint;
+        deadline: bigint;
+    };
+    signature: Hex;
+    owner: Address;
+    /** Transfer recipient and amount (filled in by the caller/router) */
+    transferDetails?: {
+        to: Address;
+        requestedAmount: bigint;
+    };
+}
+export declare class Permit2Client {
+    private readonly wallet;
+    private readonly publicClient;
+    private readonly chainId;
+    constructor(config: Permit2Config);
+    /** Owner address */
+    get owner(): Address;
+    /**
+     * Ensure a token has approved the Permit2 contract for max spending.
+     *
+     * This is a one-time operation per token. After this, all future
+     * permits are gas-free (off-chain signatures).
+     *
+     * @returns Transaction hash if approval was needed, null if already approved
+     */
+    ensureTokenApproval(token: Address): Promise<Hash | null>;
+    /**
+     * Batch-approve multiple tokens for Permit2.
+     * Only sends transactions for tokens that need approval.
+     *
+     * @returns Map of token → txHash (only tokens that needed approval)
+     */
+    ensureTokenApprovals(tokens: Address[]): Promise<Map<Address, Hash>>;
+    /**
+     * Read the current Permit2 allowance for a token/spender pair.
+     */
+    getAllowance(token: Address, spender: Address): Promise<Permit2Allowance>;
+    /**
+     * Check if a Permit2 allowance is sufficient and not expired.
+     */
+    isAllowanceSufficient(token: Address, spender: Address, requiredAmount: bigint): Promise<boolean>;
+    /**
+     * Sign a PermitSingle for a single token → spender allowance.
+     *
+     * This is an off-chain operation (no gas). The returned signature
+     * can be submitted by the spender to claim the allowance.
+     *
+     * Used by: PositionManager (LP operations), UniversalRouter (some flows)
+     */
+    signPermitSingle(params: PermitSingleParams): Promise<SignedPermitSingle>;
+    /**
+     * Sign a PermitBatch for multiple tokens → single spender.
+     *
+     * Used by PositionManager when minting LP with two tokens.
+     */
+    signPermitBatch(params: PermitBatchParams): Promise<SignedPermitBatch>;
+    /**
+     * Submit a signed PermitSingle to the Permit2 contract.
+     *
+     * After this, the spender can call transferFrom() on Permit2.
+     * In practice, this is often bundled in the same tx as the router call
+     * via multicall, so you may not need to call this separately.
+     */
+    submitPermitSingle(signed: SignedPermitSingle): Promise<Hash>;
+    /**
+     * Directly approve a spender on Permit2 (no signature, costs gas).
+     *
+     * Simpler but requires an on-chain tx. For agent wallets that control
+     * their own private key, this is often easier than signing a permit.
+     */
+    directApprove(token: Address, spender: Address, amount?: bigint, expirationSeconds?: number): Promise<Hash>;
+    /**
+     * Direct-approve multiple tokens for a spender in sequence.
+     */
+    directApproveBatch(tokens: Address[], spender: Address, amount?: bigint, expirationSeconds?: number): Promise<Hash[]>;
+    /**
+     * Sign a PermitTransferFrom for the UniversalRouter.
+     *
+     * This creates a single-use, nonce-specific permit. The router
+     * calls `permitTransferFrom()` which atomically verifies the sig
+     * and transfers the tokens.
+     *
+     * @param params.nonce - Must be an unused nonce. Use `findUnusedNonce()` to find one.
+     */
+    signPermitTransferFrom(params: PermitTransferFromParams): Promise<SignedPermitTransferFrom>;
+    /**
+     * Check if a specific nonce has been used (SignatureTransfer).
+     *
+     * Permit2 uses a bitmap: nonce N is stored in word N/256, bit N%256.
+     */
+    isNonceUsed(nonce: bigint): Promise<boolean>;
+    /**
+     * Find an unused nonce for SignatureTransfer.
+     *
+     * Scans from `startNonce` forward until an unused one is found.
+     * Uses bitmap reads for efficiency (checks 256 nonces per read).
+     */
+    findUnusedNonce(startNonce?: bigint): Promise<bigint>;
+    /**
+     * Revoke all Permit2 allowances for specific token/spender pairs.
+     *
+     * Sets amount=0 and expiration=0 for each pair. This is the
+     * emergency kill switch if you need to revoke access immediately.
+     */
+    lockdown(pairs: Array<{
+        token: Address;
+        spender: Address;
+    }>): Promise<Hash>;
+    /**
+     * Complete AllowanceTransfer flow for a single token:
+     *   1. Ensure ERC20 → Permit2 approval
+     *   2. Check if Permit2 allowance is sufficient for the spender
+     *   3. If not, sign a PermitSingle and submit it
+     *
+     * Returns the current nonce after the flow completes.
+     */
+    ensurePermit2Allowance(token: Address, spender: Address, amount: bigint): Promise<{
+        approvalTxHash: Hash | null;
+        permitTxHash: Hash | null;
+    }>;
+    /**
+     * Complete flow for two tokens (LP operations):
+     *   1. Ensure ERC20 → Permit2 for both
+     *   2. Direct-approve both on Permit2 for the spender
+     */
+    ensurePermit2AllowancePair(token0: Address, token1: Address, spender: Address, amount0: bigint, amount1: bigint): Promise<{
+        token0ApprovalTx: Hash | null;
+        token1ApprovalTx: Hash | null;
+        permit0Tx: Hash | null;
+        permit1Tx: Hash | null;
+    }>;
+}
+//# sourceMappingURL=permit2.d.ts.map

package/dist/permit2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permit2.d.ts","sourceRoot":"","sources":["../src/permit2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,IAAI,EACT,KAAK,GAAG,EACR,KAAK,YAAY,EACjB,KAAK,YAAY,EAIlB,MAAM,MAAM,CAAC;AASd,4DAA4D;AAC5D,eAAO,MAAM,eAAe,EAAE,OAAsD,CAAC;AAqFrF,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,MAAM,EAAE,YAAY,GAAG;QAAE,OAAO,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC;IACzD,8BAA8B;IAC9B,YAAY,EAAE,YAAY,CAAC;IAC3B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,MAAM,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC,CAAC;IACH,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,kFAAkF;AAClF,MAAM,WAAW,wBAAwB;IACvC,wBAAwB;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE;QACN,OAAO,EAAE;YACP,KAAK,EAAE,OAAO,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;YACnB,KAAK,EAAE,MAAM,CAAC;SACf,CAAC;QACF,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,SAAS,EAAE,GAAG,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,0BAA0B;AAC1B,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE;QACN,OAAO,EAAE,KAAK,CAAC;YACb,KAAK,EAAE,OAAO,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;YACnB,KAAK,EAAE,MAAM,CAAC;SACf,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,SAAS,EAAE,GAAG,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE;QACN,SAAS,EAAE;YAAE,KAAK,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9C,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,SAAS,EAAE,GAAG,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,eAAe,CAAC,EAAE;QAChB,EAAE,EAAE,OAAO,CAAC;QACZ,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAMD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,aAAa;IAYjC,oBAAoB;IACpB,IAAI,KAAK,IAAI,OAAO,CAEnB;IAMD;;;;;;;OAOG;IACG,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IA0B/D;;;;;OAKG;IACG,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAuC1E;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAe/E;;OAEG;IACG,qBAAqB,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,OAAO,CAAC;IAUnB;;;;;;;OAOG;IACG,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyC/E;;;;OAIG;IACG,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0C5E;;;;;;OAMG;IACG,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BnE;;;;;OAKG;IACG,aAAa,CACjB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,MAAmB,EAC3B,iBAAiB,GAAE,MAAkC,GACpD,OAAO,CAAC,IAAI,CAAC;IAgBhB;;OAEG;IACG,kBAAkB,CACtB,MAAM,EAAE,OAAO,EAAE,EACjB,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,MAAmB,EAC3B,iBAAiB,GAAE,MAAkC,GACpD,OAAO,CAAC,IAAI,EAAE,CAAC;IAgBlB;;;;;;;;OAQG;IACG,sBAAsB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAgCjG;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAclD;;;;;OAKG;IACG,eAAe,CAAC,UAAU,GAAE,MAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA0B/D;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjF;;;;;;;OAOG;IACG,sBAAsB,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,cAAc,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE,CAAC;IAetE;;;;OAIG;IACG,0BAA0B,CAC9B,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,gBAAgB,EAAE,IAAI,GAAG,IAAI,CAAC;QAC9B,gBAAgB,EAAE,IAAI,GAAG,IAAI,CAAC;QAC9B,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;QACvB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;KACxB,CAAC;CAyBH"}