@glowlabs-org/utils 0.2.154 → 0.2.156

package/src/lib/hooks/use-rewards-kernel.ts

@@ -0,0 +1,547 @@
+import {
+  type WalletClient,
+  type PublicClient,
+  type Address,
+  formatEther,
+} from "viem";
+import { REWARDS_KERNEL_ABI } from "../abis/rewardKernelABI";
+import { getAddresses } from "../../constants/addresses";
+import {
+  parseViemError,
+  waitForViemTransactionWithRetry,
+} from "../../utils/transaction-utils";
+import {
+  sentryAddBreadcrumb,
+  sentryCaptureException,
+} from "../../utils/sentry";
+
+export enum RewardsKernelError {
+  CONTRACT_NOT_AVAILABLE = "Contract not available",
+  SIGNER_NOT_AVAILABLE = "Signer not available",
+  UNKNOWN_ERROR = "Unknown error",
+  INVALID_PARAMETERS = "Invalid parameters",
+  ALREADY_CLAIMED = "Already claimed from this nonce",
+  NOT_FINALIZED = "Nonce not yet finalized",
+  NONCE_REJECTED = "Cannot claim from rejected nonce",
+}
+
+// Token and amount structure matching the contract
+export interface TokenAndAmount {
+  token: `0x${string}`;
+  amount: bigint;
+}
+
+// Reward metadata structure
+export interface RewardMeta {
+  merkleRoot: string;
+  pushTimestamp: number;
+  rejected: boolean;
+}
+
+// Parameters for claiming a payout
+export interface ClaimPayoutParams {
+  nonce: bigint;
+  proof: `0x${string}`[]; // bytes32[] as hex strings
+  tokensAndAmounts: TokenAndAmount[];
+  from: `0x${string}`; // Address providing the tokens
+  to: `0x${string}`; // Address receiving the tokens
+  isGuardedToken: boolean[]; // Which tokens are guarded
+  toCounterfactual: boolean[]; // Whether to send to counterfactual wallet
+}
+
+// Type-guard style helper to ensure a wallet client exists
+function assertWalletClient(
+  maybeWalletClient: WalletClient | undefined
+): asserts maybeWalletClient is WalletClient {
+  if (!maybeWalletClient) {
+    throw new Error(RewardsKernelError.SIGNER_NOT_AVAILABLE);
+  }
+  if (!maybeWalletClient.account) {
+    throw new Error("Wallet client must have an account");
+  }
+}
+
+export function useRewardsKernel(
+  walletClient: WalletClient | undefined,
+  publicClient: PublicClient | undefined,
+  CHAIN_ID: number
+) {
+  // Use dynamic addresses based on chain configuration
+  const ADDRESSES = getAddresses(CHAIN_ID);
+
+  // Framework-agnostic processing flag
+  let isProcessing = false;
+  const setIsProcessing = (value: boolean) => {
+    isProcessing = value;
+  };
+
+  // Helper to assert public client is available
+  function assertPublicClient(
+    maybePublicClient: PublicClient | undefined
+  ): asserts maybePublicClient is PublicClient {
+    if (!maybePublicClient) {
+      throw new Error("Public client not available");
+    }
+  }
+
+  /**
+   * Claim payout from a finalized nonce
+   * @param params Parameters for claiming the payout
+   */
+  async function claimPayout(params: ClaimPayoutParams): Promise<string> {
+    assertWalletClient(walletClient);
+    assertPublicClient(publicClient);
+
+    try {
+      setIsProcessing(true);
+
+      sentryAddBreadcrumb({
+        category: "rewards-kernel",
+        message: "claimPayout.start",
+        level: "info",
+        data: {
+          chainId: walletClient?.chain?.id,
+          contract: ADDRESSES.REWARDS_KERNEL,
+          nonce: params.nonce.toString(),
+          to: params.to,
+          from: params.from,
+          tokensCount: params.tokensAndAmounts.length,
+        },
+      });
+
+      const {
+        nonce,
+        proof,
+        tokensAndAmounts,
+        from,
+        to,
+        isGuardedToken,
+        toCounterfactual,
+      } = params;
+
+      // Validate parameters
+      if (!proof || proof.length === 0) {
+        throw new Error("Merkle proof is required");
+      }
+
+      if (!tokensAndAmounts || tokensAndAmounts.length === 0) {
+        throw new Error("Tokens and amounts are required");
+      }
+
+      if (isGuardedToken.length !== tokensAndAmounts.length) {
+        throw new Error(
+          "isGuardedToken array length must match tokensAndAmounts"
+        );
+      }
+
+      if (toCounterfactual.length !== tokensAndAmounts.length) {
+        throw new Error(
+          "toCounterfactual array length must match tokensAndAmounts"
+        );
+      }
+
+      if (!from || !to) {
+        throw new Error(RewardsKernelError.INVALID_PARAMETERS);
+      }
+
+      // Check if already claimed
+      const owner = walletClient.account?.address;
+      if (!owner) {
+        throw new Error("No account found in wallet client");
+      }
+
+      const alreadyClaimed = await isClaimed(owner, nonce);
+      if (alreadyClaimed) {
+        throw new Error(RewardsKernelError.ALREADY_CLAIMED);
+      }
+
+      // Check if finalized
+      const finalized = await isFinalized(nonce);
+      if (!finalized) {
+        throw new Error(RewardsKernelError.NOT_FINALIZED);
+      }
+
+      // Run a simulation first to surface any revert reason
+      try {
+        await publicClient.simulateContract({
+          address: ADDRESSES.REWARDS_KERNEL as Address,
+          abi: REWARDS_KERNEL_ABI,
+          functionName: "claimPayout",
+          args: [
+            nonce,
+            proof as `0x${string}`[],
+            tokensAndAmounts as readonly {
+              token: `0x${string}`;
+              amount: bigint;
+            }[],
+            from as Address,
+            to as Address,
+            isGuardedToken,
+            toCounterfactual,
+          ],
+          account: walletClient.account!,
+        });
+      } catch (simulationError) {
+        sentryCaptureException(simulationError, {
+          action: "claimPayout.simulate",
+          chainId: walletClient?.chain?.id,
+          contract: ADDRESSES.REWARDS_KERNEL,
+          nonce: nonce.toString(),
+        });
+        throw new Error(parseViemError(simulationError));
+      }
+
+      // Execute the transaction
+      const hash = await walletClient.writeContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "claimPayout",
+        args: [
+          nonce,
+          proof as `0x${string}`[],
+          tokensAndAmounts as readonly {
+            token: `0x${string}`;
+            amount: bigint;
+          }[],
+          from as Address,
+          to as Address,
+          isGuardedToken,
+          toCounterfactual,
+        ],
+        chain: walletClient.chain,
+        account: walletClient.account!,
+      });
+
+      await waitForViemTransactionWithRetry(publicClient, hash);
+
+      return hash;
+    } catch (error) {
+      sentryCaptureException(error, {
+        action: "claimPayout",
+        chainId: walletClient?.chain?.id,
+        contract: ADDRESSES.REWARDS_KERNEL,
+        nonce: params.nonce.toString(),
+        from: params.from,
+        to: params.to,
+      });
+      throw new Error(parseViemError(error));
+    } finally {
+      setIsProcessing(false);
+    }
+  }
+
+  /**
+   * Get reward metadata for a specific nonce
+   * @param nonce The nonce to query
+   */
+  async function getRewardMeta(nonce: bigint): Promise<RewardMeta> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "getRewardMeta",
+        args: [nonce],
+      })) as any;
+
+      return {
+        merkleRoot: result[0],
+        pushTimestamp: Number(result[1]),
+        rejected: result[2],
+      };
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Get the maximum claimable amount for a token at a specific nonce
+   * @param nonce The nonce to query
+   * @param token The token address
+   */
+  async function getMaxReward(
+    nonce: bigint,
+    token: `0x${string}`
+  ): Promise<bigint> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "getMaxReward",
+        args: [nonce, token as Address],
+      })) as bigint;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Get the amount already claimed for a token at a specific nonce
+   * @param nonce The nonce to query
+   * @param token The token address
+   */
+  async function getAmountClaimed(
+    nonce: bigint,
+    token: `0x${string}`
+  ): Promise<bigint> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "getAmountClaimed",
+        args: [nonce, token as Address],
+      })) as bigint;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Check if a nonce is finalized and claimable
+   * @param nonce The nonce to check
+   */
+  async function isFinalized(nonce: bigint): Promise<boolean> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "isFinalized",
+        args: [nonce],
+      })) as boolean;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Check if a user has already claimed from a specific nonce
+   * @param user The user address
+   * @param nonce The nonce to check
+   */
+  async function isClaimed(
+    user: `0x${string}`,
+    nonce: bigint
+  ): Promise<boolean> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "isClaimed",
+        args: [user as Address, nonce],
+      })) as boolean;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Get the next nonce that will be used for posting
+   */
+  async function getNextPostNonce(): Promise<bigint> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "$nextPostNonce",
+        args: [],
+      })) as bigint;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Get the finality period in seconds
+   */
+  async function getFinality(): Promise<bigint> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "FINALITY",
+        args: [],
+      })) as bigint;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Get the foundation multisig address
+   */
+  async function getFoundationMultisig(): Promise<string> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "FOUNDATION_MULTISIG",
+        args: [],
+      })) as string;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Get the rejection multisig address
+   */
+  async function getRejectionMultisig(): Promise<string> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "REJECTION_MULTISIG",
+        args: [],
+      })) as string;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Get the counterfactual holder factory address
+   */
+  async function getCFHFactory(): Promise<string> {
+    assertPublicClient(publicClient);
+
+    try {
+      const result = (await publicClient.readContract({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "CFH_FACTORY",
+        args: [],
+      })) as string;
+
+      return result;
+    } catch (error) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  /**
+   * Estimate gas for claiming a payout
+   * @param params Parameters for claiming the payout
+   * @param ethPriceInUSD Current ETH price in USD (for cost estimation)
+   */
+  async function estimateGasForClaimPayout(
+    params: ClaimPayoutParams,
+    ethPriceInUSD: number | null
+  ): Promise<string> {
+    assertWalletClient(walletClient);
+    assertPublicClient(publicClient);
+
+    try {
+      const {
+        nonce,
+        proof,
+        tokensAndAmounts,
+        from,
+        to,
+        isGuardedToken,
+        toCounterfactual,
+      } = params;
+
+      const gasPrice = await publicClient.getGasPrice();
+      if (!gasPrice) {
+        throw new Error("Could not fetch gas price to estimate cost.");
+      }
+
+      const estimatedGas = await publicClient.estimateContractGas({
+        address: ADDRESSES.REWARDS_KERNEL as Address,
+        abi: REWARDS_KERNEL_ABI,
+        functionName: "claimPayout",
+        args: [
+          nonce,
+          proof as `0x${string}`[],
+          tokensAndAmounts as readonly {
+            token: `0x${string}`;
+            amount: bigint;
+          }[],
+          from as Address,
+          to as Address,
+          isGuardedToken,
+          toCounterfactual,
+        ],
+        account: walletClient.account!,
+      });
+
+      const estimatedCost: bigint = estimatedGas * gasPrice;
+
+      if (ethPriceInUSD) {
+        const estimatedCostInEth = formatEther(estimatedCost);
+        const estimatedCostInUSD = (
+          parseFloat(estimatedCostInEth) * ethPriceInUSD
+        ).toFixed(2);
+        return estimatedCostInUSD;
+      } else {
+        throw new Error(
+          "Could not fetch the ETH price to calculate cost in USD."
+        );
+      }
+    } catch (error: any) {
+      throw new Error(parseViemError(error));
+    }
+  }
+
+  return {
+    // Core contract functions
+    claimPayout,
+
+    // View functions
+    getRewardMeta,
+    getMaxReward,
+    getAmountClaimed,
+    isFinalized,
+    isClaimed,
+    getNextPostNonce,
+    getFinality,
+    getFoundationMultisig,
+    getRejectionMultisig,
+    getCFHFactory,
+
+    // Gas estimation
+    estimateGasForClaimPayout,
+
+    // State
+    get isProcessing() {
+      return isProcessing;
+    },
+    addresses: ADDRESSES,
+
+    // Wallet client availability
+    isSignerAvailable: !!walletClient,
+  };
+}

package/src/lib/types/index.ts

@@ -573,7 +573,9 @@ export interface WalletFarmInfo {
   protocolDepositPaidCurrency: string;
 
   builtEpoch: number;
-  builtAt: string; // ISO 8601
+  builtAt?: string; // ISO 8601
+  glowSplitPercent6Decimals: string; // Wallet's GLW reward split (6 decimals)
+  depositSplitPercent6Decimals: string; // Wallet's deposit reward split (6 decimals)
 }
 
 export interface WalletDetails {
@@ -586,6 +588,94 @@ export interface WalletDetails {
   ownedFarms: WalletFarmInfo[];
 }
 
+export interface WeeklyReward {
+  weekNumber: number;
+  paymentCurrency: PaymentCurrency;
+  protocolDepositRewardsReceived: string; // Protocol deposit rewards received by wallet
+  glowInflationTotal: string; // GLW inflation rewards (18 decimals)
+}
+
+export interface WeeklyRewardsSummary {
+  totalProtocolDepositRewardsReceived: string;
+  totalGlowInflation: string;
+  weeksActive: number;
+}
+
+export interface WalletWeeklyRewardsResponse {
+  wallet: string;
+  summary: WeeklyRewardsSummary;
+  rewards: WeeklyReward[];
+}
+
+export interface WeeklyRewardsQuery {
+  startWeek?: number; // Inclusive lower bound epoch/week
+  endWeek?: number; // Inclusive upper bound epoch/week
+  paymentCurrency?: PaymentCurrency; // Filter by payment currency
+  limit?: number; // Max rows to return (default 52, capped at 520)
+}
+
+// ----------------------------- Farm Weekly Rewards ---------------------------
+export interface FarmWeeklyReward {
+  weekNumber: number;
+  paymentCurrency: PaymentCurrency;
+  protocolDepositPaidTotal: string; // Total amount farm paid as protocol deposit
+  glowInflationTotal: string; // Total GLW inflation rewards allocated to farm (18 decimals)
+  expectedProductionTotal: string; // Farm's weekly carbon credit production in WAD (18 decimals)
+  protocolDepositRewardsDistributed: string; // Portion of protocol deposits distributed to wallets
+}
+
+export interface FarmWeeklyRewardsSummary {
+  totalProtocolDepositPaid: string;
+  totalGlowInflation: string;
+  totalExpectedProduction: string;
+  weeksActive: number;
+}
+
+export interface FarmWeeklyRewardsResponse {
+  farmId: string;
+  summary: FarmWeeklyRewardsSummary;
+  rewards: FarmWeeklyReward[];
+}
+
+export interface FarmWeeklyRewardsQuery {
+  startWeek?: number; // Inclusive lower bound epoch/week
+  endWeek?: number; // Inclusive upper bound epoch/week
+  paymentCurrency?: PaymentCurrency; // Filter by payment currency
+  limit?: number; // Max rows to return (default 52, capped at 520)
+}
+
+// ----------------------------- Region Weekly Rewards -------------------------
+export interface RegionWeeklyReward {
+  weekNumber: number;
+  paymentCurrency: PaymentCurrency;
+  protocolDepositPaidTotal: string; // Total amount paid by all farms in region as protocol deposit
+  glowInflationTotal: string; // Total GLW inflation rewards allocated to region (18 decimals)
+  expectedProductionTotal: string; // Region's total weekly carbon credit production in WAD (18 decimals)
+  protocolDepositRewardsDistributed: string; // Always "0" for regions (tracked at farm level)
+  createdAt?: string; // ISO 8601
+  updatedAt?: string; // ISO 8601
+}
+
+export interface RegionWeeklyRewardsSummary {
+  totalProtocolDepositPaid: string;
+  totalGlowInflation: string;
+  totalExpectedProduction: string;
+  weeksActive: number;
+}
+
+export interface RegionWeeklyRewardsResponse {
+  regionId: number;
+  summary: RegionWeeklyRewardsSummary;
+  rewards: RegionWeeklyReward[];
+}
+
+export interface RegionWeeklyRewardsQuery {
+  startWeek?: number; // Inclusive lower bound epoch/week
+  endWeek?: number; // Inclusive upper bound epoch/week
+  paymentCurrency?: PaymentCurrency; // Filter by payment currency
+  limit?: number; // Max rows to return (default 52, capped at 520)
+}
+
 // ----------------------------- Farms Reward Score ---------------------------
 export interface EstimateRewardScoreParams {
   userId: string;