@glowlabs-org/utils 0.2.154 → 0.2.156

package/src/lib/hooks/README.md

@@ -284,3 +284,298 @@ async function createAndBuyFraction() {
 ```
 
 This hook provides a complete interface for managing fractional token sales on the Glow protocol, with built-in error handling, gas estimation, and type safety.
+
+## useRewardsKernel
+
+The `useRewardsKernel` hook provides functionality for claiming rewards from the Glow Foundation's Merkle-tree based reward distribution system. This contract enables secure, verifiable token distributions with support for both regular and guarded tokens.
+
+### Key Concepts
+
+**1. Merkle-tree Based Distribution**
+
+- Rewards are distributed using Merkle proofs to ensure only eligible users can claim
+- Each distribution has a unique nonce and merkle root
+- Users provide proof of their eligibility when claiming
+
+**2. Finality Period**
+
+- After a reward root is posted, there's a finality period before claims can begin
+- During this period, the rejection multisig can reject problematic distributions
+- Once finalized, rewards become claimable
+
+**3. Guarded Tokens**
+
+- Some tokens have transfer restrictions (only transferable between EOAs and allowlisted contracts)
+- The contract uses a CounterfactualHolderFactory to handle these special tokens
+- Users can choose to receive guarded tokens to a counterfactual wallet
+
+**4. Security Model**
+
+- Foundation multisig posts reward roots (admin function - not included in this hook)
+- Rejection multisig can reject roots within finality period (admin function - not included)
+- Hot wallet holds the actual tokens and must approve the contract
+- No custodied funds - tokens remain with the hot wallet until claimed
+
+### Setup
+
+```typescript
+import { useRewardsKernel } from "@glowlabs-org/utils";
+import { createWalletClient, createPublicClient, http } from "viem";
+import { mainnet } from "viem/chains";
+
+// Initialize clients
+const walletClient = createWalletClient({
+  chain: mainnet,
+  transport: http(),
+});
+
+const publicClient = createPublicClient({
+  chain: mainnet,
+  transport: http(),
+});
+
+const CHAIN_ID = 1; // Ethereum mainnet
+const rewardsKernel = useRewardsKernel(walletClient, publicClient, CHAIN_ID);
+```
+
+### Core Features
+
+#### 1. Claiming Rewards
+
+```typescript
+import { ClaimPayoutParams } from "@glowlabs-org/utils";
+
+const claimParams: ClaimPayoutParams = {
+  nonce: 1n, // The distribution nonce
+  proof: [
+    "0x1234567890abcdef...", // Merkle proof elements
+    "0xabcdef1234567890...",
+  ],
+  tokensAndAmounts: [
+    {
+      token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+      amount: 1000000n, // 1 USDC (6 decimals)
+    },
+    {
+      token: "0xf4fbC617A5733EAAF9af08E1Ab816B103388d8B6", // GLW
+      amount: 1000000000000000000n, // 1 GLW (18 decimals)
+    },
+  ],
+  from: "0xHotWalletAddress...", // Address holding the tokens
+  to: "0xYourAddress...", // Where you want to receive tokens
+  isGuardedToken: [false, true], // USDC is not guarded, GLW is guarded
+  toCounterfactual: [false, false], // Send both to regular address
+};
+
+try {
+  const txHash = await rewardsKernel.claimPayout(claimParams);
+  console.log("Rewards claimed:", txHash);
+} catch (error) {
+  console.error("Claim failed:", error.message);
+}
+```
+
+### Data Retrieval
+
+#### Check Reward Status
+
+```typescript
+// Get reward metadata for a nonce
+const rewardMeta = await rewardsKernel.getRewardMeta(1n);
+console.log({
+  merkleRoot: rewardMeta.merkleRoot,
+  pushTimestamp: rewardMeta.pushTimestamp,
+  rejected: rewardMeta.rejected,
+});
+
+// Check if nonce is finalized and claimable
+const isFinalized = await rewardsKernel.isFinalized(1n);
+console.log("Can claim:", isFinalized);
+
+// Check if user already claimed
+const userAddress = "0xYourAddress...";
+const hasClaimed = await rewardsKernel.isClaimed(userAddress, 1n);
+console.log("Already claimed:", hasClaimed);
+```
+
+#### Check Token Amounts
+
+```typescript
+const nonce = 1n;
+const usdcAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+
+// Get maximum claimable amount for a token
+const maxReward = await rewardsKernel.getMaxReward(nonce, usdcAddress);
+console.log("Max USDC claimable:", maxReward);
+
+// Get amount already claimed
+const amountClaimed = await rewardsKernel.getAmountClaimed(nonce, usdcAddress);
+console.log("USDC already claimed:", amountClaimed);
+
+// Calculate remaining claimable
+const remaining = maxReward - amountClaimed;
+console.log("USDC remaining:", remaining);
+```
+
+### Contract Configuration
+
+```typescript
+// Get finality period (in seconds)
+const finality = await rewardsKernel.getFinality();
+console.log(`Finality period: ${finality} seconds`);
+
+// Get next nonce that will be used
+const nextNonce = await rewardsKernel.getNextPostNonce();
+console.log("Next nonce:", nextNonce);
+
+// Get multisig addresses
+const foundationMultisig = await rewardsKernel.getFoundationMultisig();
+const rejectionMultisig = await rewardsKernel.getRejectionMultisig();
+console.log("Foundation:", foundationMultisig);
+console.log("Rejection:", rejectionMultisig);
+
+// Get counterfactual holder factory
+const cfhFactory = await rewardsKernel.getCFHFactory();
+console.log("CFH Factory:", cfhFactory);
+```
+
+### Gas Estimation
+
+```typescript
+const ethPrice = 2000; // Current ETH price in USD
+
+// Estimate gas for claiming
+const claimCost = await rewardsKernel.estimateGasForClaimPayout(
+  claimParams,
+  ethPrice
+);
+console.log(`Claim cost: $${claimCost}`);
+```
+
+### Understanding the Merkle Proof
+
+The merkle proof verifies your eligibility to claim specific amounts of tokens:
+
+1. **Leaf Construction**: Your claim data is hashed as `keccak256(abi.encode(userAddress, tokensAndAmountsHash))`
+2. **Proof Verification**: The proof elements allow reconstruction of the merkle root
+3. **On-chain Validation**: The contract verifies your proof against the stored root
+
+### Error Handling
+
+```typescript
+import { RewardsKernelError } from "@glowlabs-org/utils";
+
+try {
+  await rewardsKernel.claimPayout(params);
+} catch (error) {
+  if (error.message === RewardsKernelError.ALREADY_CLAIMED) {
+    console.log("You've already claimed from this distribution");
+  } else if (error.message === RewardsKernelError.NOT_FINALIZED) {
+    console.log("Distribution not yet finalized, please wait");
+  } else if (error.message === RewardsKernelError.NONCE_REJECTED) {
+    console.log("This distribution was rejected");
+  }
+  // ... handle other errors
+}
+```
+
+Available error types:
+
+- `CONTRACT_NOT_AVAILABLE`
+- `SIGNER_NOT_AVAILABLE`
+- `UNKNOWN_ERROR`
+- `INVALID_PARAMETERS`
+- `ALREADY_CLAIMED`
+- `NOT_FINALIZED`
+- `NONCE_REJECTED`
+
+### Best Practices
+
+1. **Always check claim status** before attempting to claim
+2. **Verify finalization** to avoid failed transactions
+3. **Handle guarded tokens properly** - understand which tokens need special handling
+4. **Validate merkle proofs** off-chain before submitting transactions
+5. **Monitor gas prices** for optimal claiming times
+
+### Example: Complete Claim Flow
+
+```typescript
+async function claimRewards(nonce: bigint, proof: string[], claimData: any) {
+  const rewardsKernel = useRewardsKernel(walletClient, publicClient, CHAIN_ID);
+
+  try {
+    // 1. Check if nonce exists and is valid
+    const meta = await rewardsKernel.getRewardMeta(nonce);
+    if (meta.rejected) {
+      throw new Error("This distribution was rejected");
+    }
+
+    // 2. Check if finalized
+    const finalized = await rewardsKernel.isFinalized(nonce);
+    if (!finalized) {
+      const finalityPeriod = await rewardsKernel.getFinality();
+      const timeRemaining =
+        Number(meta.pushTimestamp) + Number(finalityPeriod) - Date.now() / 1000;
+      throw new Error(`Not finalized yet. Wait ${timeRemaining} seconds`);
+    }
+
+    // 3. Check if already claimed
+    const userAddress = await walletClient.account.address;
+    const claimed = await rewardsKernel.isClaimed(userAddress, nonce);
+    if (claimed) {
+      throw new Error("Already claimed from this distribution");
+    }
+
+    // 4. Verify amounts are still available
+    for (const tokenAmount of claimData.tokensAndAmounts) {
+      const maxReward = await rewardsKernel.getMaxReward(
+        nonce,
+        tokenAmount.token
+      );
+      const claimed = await rewardsKernel.getAmountClaimed(
+        nonce,
+        tokenAmount.token
+      );
+      const remaining = maxReward - claimed;
+
+      if (remaining < tokenAmount.amount) {
+        throw new Error(`Insufficient ${tokenAmount.token} remaining`);
+      }
+    }
+
+    // 5. Estimate gas
+    const gasEstimate = await rewardsKernel.estimateGasForClaimPayout(
+      claimData,
+      2000 // current ETH price
+    );
+    console.log(`Estimated cost: $${gasEstimate}`);
+
+    // 6. Execute claim
+    const txHash = await rewardsKernel.claimPayout(claimData);
+    console.log("Success! Transaction:", txHash);
+  } catch (error) {
+    console.error("Claim failed:", error.message);
+  }
+}
+```
+
+### Working with Guarded Tokens
+
+Guarded tokens (like GLW) have transfer restrictions. Here's how to handle them:
+
+```typescript
+// Option 1: Receive to counterfactual wallet
+const claimToCounterfactual = {
+  ...claimParams,
+  toCounterfactual: [false, true], // GLW goes to counterfactual
+};
+
+// Option 2: Check if your address can receive guarded tokens
+// (This would require checking with the token contract's allowlist)
+
+// The counterfactual wallet address can be computed:
+const cfhFactory = await rewardsKernel.getCFHFactory();
+// The CFH factory will create/use a deterministic address for your wallet + token
+```
+
+This hook provides a secure interface for claiming rewards from the Glow Foundation's distribution system, with full support for both regular and guarded tokens, comprehensive error handling, and gas estimation.