pepay-streams-sdk 0.1.0

package/src/claims/index.ts

@@ -0,0 +1,530 @@
+/**
+ * Claims Module
+ *
+ * Provides methods for claiming tokens from campaigns:
+ * - Single claims (with merkle proof)
+ * - Batch claims
+ * - Meta-transaction (gasless) claims
+ * - Lock releases
+ */
+import {
+  type PublicClient,
+  type WalletClient,
+  type Address,
+  type Hash,
+  type Hex,
+  keccak256,
+  encodePacked,
+} from 'viem';
+import { DIAMOND_ABI } from '@pepay-streams/abi/diamond';
+import type {
+  ClaimParams,
+  BatchClaimParams,
+  MetaClaimParams,
+  RecipientStatus,
+  TransactionResult,
+} from '../types';
+
+/**
+ * EIP-712 domain for meta-transaction signatures
+ */
+interface EIP712Domain {
+  name: string;
+  version: string;
+  chainId: number;
+  verifyingContract: Address;
+}
+
+/**
+ * Claims module for claiming tokens from distribution campaigns
+ */
+export class ClaimsModule {
+  constructor(
+    private readonly publicClient: PublicClient,
+    private readonly walletClient: WalletClient | undefined,
+    private readonly diamondAddress: Address,
+    private readonly chainId: number
+  ) {}
+
+  // ============================================================================
+  // Standard Claims
+  // ============================================================================
+
+  /**
+   * Claim vested tokens from a campaign
+   *
+   * For merkle-tree campaigns, requires allocation and proof.
+   * For direct campaigns, allocation should be 0 and proof empty.
+   *
+   * @example
+   * ```typescript
+   * // Direct campaign claim
+   * const result = await sdk.claims.claim({
+   *   campaignId: 1n,
+   *   allocation: 0n,
+   *   proof: [],
+   * });
+   *
+   * // Merkle campaign claim
+   * const result = await sdk.claims.claim({
+   *   campaignId: 1n,
+   *   allocation: parseEther('100'),
+   *   proof: ['0x...', '0x...'],
+   * });
+   * ```
+   */
+  async claim(params: ClaimParams): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    let hash: Hash;
+
+    if (params.claimTo) {
+      hash = await wallet.writeContract({
+        chain: wallet.chain,
+        account: wallet.account!,
+        address: this.diamondAddress,
+        abi: DIAMOND_ABI,
+        functionName: 'claimTo',
+        args: [
+          params.campaignId,
+          params.claimTo,
+          params.allocation ?? 0n,
+          params.proof ?? [],
+        ],
+      });
+    } else {
+      hash = await wallet.writeContract({
+        chain: wallet.chain,
+        account: wallet.account!,
+        address: this.diamondAddress,
+        abi: DIAMOND_ABI,
+        functionName: 'claim',
+        args: [
+          params.campaignId,
+          params.allocation ?? 0n,
+          params.proof ?? [],
+        ],
+      });
+    }
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Claim from a campaign for multiple recipients in a single transaction
+   *
+   * More gas efficient than multiple individual claims.
+   * For direct allocation campaigns only.
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.claims.claimBatch({
+   *   campaignId: 1n,
+   *   recipients: ['0x...', '0x...', '0x...'],
+   * });
+   * ```
+   */
+  async claimBatch(params: BatchClaimParams): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'claimMany',
+      args: [params.campaignId, params.recipients],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Release locked tokens (for Lock campaigns)
+   *
+   * Can only be called after the unlock time has passed.
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.claims.releaseLock(campaignId, [recipient1, recipient2]);
+   * ```
+   */
+  async releaseLock(
+    campaignId: bigint,
+    recipients: Address[]
+  ): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'releaseLock',
+      args: [campaignId, recipients],
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  // ============================================================================
+  // Meta-Transaction Claims (Gasless)
+  // ============================================================================
+
+  /**
+   * Claim via meta-transaction (gasless for recipient)
+   *
+   * A relayer submits the transaction on behalf of the recipient.
+   * The recipient signs an EIP-712 message off-chain.
+   *
+   * @example
+   * ```typescript
+   * // Recipient signs off-chain
+   * const signedAuth = await sdk.claims.signClaimMessage({
+   *   campaignId,
+   *   allocation: parseEther('100'),
+   *   proof: ['0x...'],
+   *   deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour
+   * });
+   *
+   * // Relayer submits
+   * const result = await sdk.claims.claimWithSig(signedAuth);
+   * ```
+   */
+  async claimWithSig(params: MetaClaimParams): Promise<TransactionResult> {
+    const wallet = this.requireWallet();
+
+    const auth = {
+      id: params.campaignId,
+      claimant: params.claimant,
+      payoutTo: params.payoutTo ?? params.claimant,
+      allocation: params.allocation,
+      proofHash: this.computeProofHash(params.proof),
+      deadline: BigInt(params.deadline),
+      nonce: params.nonce,
+    };
+
+    const hash = await wallet.writeContract({
+      chain: wallet.chain,
+      account: wallet.account!,
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'claimWithSig',
+      args: [auth, params.proof, params.signature] as const,
+    });
+
+    return this.createTransactionResult(hash);
+  }
+
+  /**
+   * Generate the EIP-712 typed data for a claim signature
+   *
+   * The recipient signs this message off-chain.
+   */
+  getClaimTypedData(
+    campaignId: bigint,
+    claimant: Address,
+    payoutTo: Address,
+    allocation: bigint,
+    proofHash: Hex,
+    nonce: bigint,
+    deadline: number
+  ): {
+    domain: EIP712Domain;
+    types: Record<string, { name: string; type: string }[]>;
+    primaryType: string;
+    message: Record<string, unknown>;
+  } {
+    return {
+      domain: {
+        name: 'PepayStreams',
+        version: '1',
+        chainId: this.chainId,
+        verifyingContract: this.diamondAddress,
+      },
+      types: {
+        ClaimAuth: [
+          { name: 'id', type: 'uint256' },
+          { name: 'claimant', type: 'address' },
+          { name: 'payoutTo', type: 'address' },
+          { name: 'allocation', type: 'uint128' },
+          { name: 'proofHash', type: 'bytes32' },
+          { name: 'deadline', type: 'uint64' },
+          { name: 'nonce', type: 'uint256' },
+        ],
+      },
+      primaryType: 'ClaimAuth',
+      message: {
+        id: campaignId,
+        claimant,
+        payoutTo,
+        allocation,
+        proofHash,
+        deadline: BigInt(deadline),
+        nonce,
+      },
+    };
+  }
+
+  /**
+   * Sign a claim message for meta-transaction
+   *
+   * Returns the signature that can be submitted by a relayer.
+   */
+  async signClaimMessage(params: {
+    campaignId: bigint;
+    allocation: bigint;
+    proof: Hex[];
+    deadline: number;
+    payoutTo?: Address;
+  }): Promise<{
+    signature: Hex;
+    nonce: bigint;
+    deadline: number;
+    claimant: Address;
+    payoutTo: Address;
+    allocation: bigint;
+    proof: Hex[];
+    campaignId: bigint;
+  }> {
+    const wallet = this.requireWallet();
+    const claimant = wallet.account!.address;
+    const payoutTo = params.payoutTo ?? claimant;
+
+    // Get current nonce
+    const nonce = await this.getClaimNonce(params.campaignId, claimant);
+    const proofHash = this.computeProofHash(params.proof);
+
+    const typedData = this.getClaimTypedData(
+      params.campaignId,
+      claimant,
+      payoutTo,
+      params.allocation,
+      proofHash,
+      nonce,
+      params.deadline
+    );
+
+    const signature = await wallet.signTypedData({
+      account: wallet.account!,
+      domain: typedData.domain,
+      types: typedData.types,
+      primaryType: typedData.primaryType as 'ClaimAuth',
+      message: typedData.message,
+    });
+
+    return {
+      signature,
+      nonce,
+      deadline: params.deadline,
+      claimant,
+      payoutTo,
+      allocation: params.allocation,
+      proof: params.proof,
+      campaignId: params.campaignId,
+    };
+  }
+
+  /**
+   * Get the current nonce for claim meta-transactions
+   */
+  async getClaimNonce(campaignId: bigint, address: Address): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'noncesClaim',
+      args: [campaignId, address],
+    });
+
+    return result as bigint;
+  }
+
+  // ============================================================================
+  // Claim Status Queries
+  // ============================================================================
+
+  /**
+   * Get the amount currently claimable for a recipient
+   *
+   * @example
+   * ```typescript
+   * const claimable = await sdk.claims.getClaimable(campaignId, recipientAddress);
+   * console.log('Claimable:', formatEther(claimable));
+   * ```
+   */
+  async getClaimable(campaignId: bigint, recipient: Address): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'claimableOf',
+      args: [campaignId, recipient],
+    });
+
+    return result as bigint;
+  }
+
+  /**
+   * Check if a recipient is blocked from claiming
+   */
+  async isBlocked(campaignId: bigint, recipient: Address): Promise<boolean> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'isBlocked',
+      args: [campaignId, recipient],
+    });
+
+    return result as boolean;
+  }
+
+  /**
+   * Get vested amount for a recipient (how much has vested so far)
+   */
+  async getVestedAmount(
+    campaignId: bigint,
+    recipient: Address,
+    allocation: bigint
+  ): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'vestedAmount',
+      args: [campaignId, recipient, allocation],
+    });
+
+    return result as bigint;
+  }
+
+  /**
+   * Get merkle claimed shares for a recipient
+   */
+  async getMerkleClaimedShares(
+    campaignId: bigint,
+    recipient: Address
+  ): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DIAMOND_ABI,
+      functionName: 'merkleClaimedShares',
+      args: [campaignId, recipient],
+    });
+
+    return result as bigint;
+  }
+
+  /**
+   * Get detailed recipient status for a campaign
+   */
+  async getRecipientStatus(
+    campaignId: bigint,
+    recipient: Address,
+    allocation: bigint
+  ): Promise<RecipientStatus> {
+    const [claimable, blocked, vested, claimed] = await Promise.all([
+      this.getClaimable(campaignId, recipient),
+      this.isBlocked(campaignId, recipient),
+      this.getVestedAmount(campaignId, recipient, allocation),
+      this.getMerkleClaimedShares(campaignId, recipient),
+    ]);
+
+    return {
+      allocated: allocation,
+      claimed,
+      due: claimable,
+      blocked,
+      fullyVested: vested >= allocation,
+    };
+  }
+
+  /**
+   * Check if a recipient can claim from a campaign
+   */
+  async canClaim(campaignId: bigint, recipient: Address): Promise<boolean> {
+    try {
+      const [claimable, blocked] = await Promise.all([
+        this.getClaimable(campaignId, recipient),
+        this.isBlocked(campaignId, recipient),
+      ]);
+      return claimable > 0n && !blocked;
+    } catch {
+      return false;
+    }
+  }
+
+  // ============================================================================
+  // Merkle Proof Helpers
+  // ============================================================================
+
+  /**
+   * Verify a Merkle proof locally
+   *
+   * Useful for validating proofs before submitting transactions.
+   */
+  verifyMerkleProof(root: Hex, leaf: Hex, proof: Hex[]): boolean {
+    let computedHash = leaf;
+
+    for (const proofElement of proof) {
+      if (computedHash < proofElement) {
+        computedHash = keccak256(
+          encodePacked(['bytes32', 'bytes32'], [computedHash, proofElement])
+        );
+      } else {
+        computedHash = keccak256(
+          encodePacked(['bytes32', 'bytes32'], [proofElement, computedHash])
+        );
+      }
+    }
+
+    return computedHash === root;
+  }
+
+  /**
+   * Compute Merkle leaf for an allocation
+   */
+  computeMerkleLeaf(address: Address, amount: bigint): Hex {
+    return keccak256(encodePacked(['address', 'uint256'], [address, amount]));
+  }
+
+  /**
+   * Compute proof hash for meta-transaction
+   */
+  computeProofHash(proof: Hex[]): Hex {
+    if (proof.length === 0) {
+      return '0x0000000000000000000000000000000000000000000000000000000000000000';
+    }
+    return keccak256(encodePacked(['bytes32[]'], [proof]));
+  }
+
+  // ============================================================================
+  // Helpers
+  // ============================================================================
+
+  private requireWallet(): WalletClient {
+    if (!this.walletClient) {
+      throw new Error(
+        'Wallet client required for write operations. Initialize SDK with a signer.'
+      );
+    }
+    return this.walletClient;
+  }
+
+  private createTransactionResult(hash: Hash): TransactionResult {
+    return {
+      hash,
+      wait: async () => {
+        const receipt = await this.publicClient.waitForTransactionReceipt({
+          hash,
+        });
+        return {
+          blockNumber: receipt.blockNumber,
+          transactionHash: receipt.transactionHash,
+          gasUsed: receipt.gasUsed,
+          status: receipt.status,
+          logs: receipt.logs,
+        };
+      },
+    };
+  }
+}
+
+export default ClaimsModule;