@glowlabs-org/utils 0.2.99 → 0.2.101

package/src/browser.ts

@@ -8,6 +8,7 @@ export * from "./lib/control-api/farms-router";
 export * from "./lib/types";
 export * from "./lib/region-metadata";
 export * from "./lib/abis/forwarderABI";
+export * from "./lib/abis/offchainFractions";
 export * from "./constants/addresses";
 export * from "./constants/weights";
 export * from "./constants/urls";

package/src/constants/addresses.ts

@@ -42,7 +42,7 @@ const sepoliaAddresses: Record<ContractKeys, `0x${string}`> = {
   USDG_UNISWAP: "0x2a085A3aEA8982396533327c854753Ce521B666d",
   GLW_UNISWAP: "0x8e27016D0B866a56CE74A1a280c749dD679bb0Fa",
   FORWARDER: "0xDaC24F18171224eeaf6a9B38f5C5081aDbDff969",
-  OFFCHAIN_FRACTIONS: "0x1Eca5C4391f10097C3232a0672e83c60A7dab7cD",
+  OFFCHAIN_FRACTIONS: "0x0095F2F0C7bbEEd97eCF058D28a8b768Ece32Ac3",
   COUNTERFACTUAL_HOLDER_FACTORY: "0x2c3AB887746F6f4a8a4b9Db6aC800eb71945509A",
   FOUNDATION_WALLET: "0x5e230FED487c86B90f6508104149F087d9B1B0A7",
   UNISWAP_V2_ROUTER: "0xeE567Fe1712Faf6149d80dA1E6934E354124CfE3",

package/src/lib/abis/offchainFractions.ts

@@ -41,6 +41,7 @@ export const OFFCHAIN_FRACTIONS_ABI = [
   { inputs: [], name: "MinSharesCannotBeGreaterThanTotalSteps", type: "error" },
   { inputs: [], name: "NoStepsPurchased", type: "error" },
   { inputs: [], name: "NotAllOrNothing", type: "error" },
+  { inputs: [], name: "NotFractionsCloser", type: "error" },
   { inputs: [], name: "NotFractionsOwner", type: "error" },
   { inputs: [], name: "RecipientCannotBeSelf", type: "error" },
   { inputs: [], name: "ReentrancyGuardReentrantCall", type: "error" },
@@ -120,6 +121,12 @@ export const OFFCHAIN_FRACTIONS_ABI = [
         name: "minSharesToRaise",
         type: "uint256",
       },
+      {
+        indexed: false,
+        internalType: "address",
+        name: "closer",
+        type: "address",
+      },
     ],
     name: "FractionCreated",
     type: "event",
@@ -240,7 +247,10 @@ export const OFFCHAIN_FRACTIONS_ABI = [
     type: "function",
   },
   {
-    inputs: [{ internalType: "bytes32", name: "id", type: "bytes32" }],
+    inputs: [
+      { internalType: "address", name: "creator", type: "address" },
+      { internalType: "bytes32", name: "id", type: "bytes32" },
+    ],
     name: "closeFraction",
     outputs: [],
     stateMutability: "nonpayable",
@@ -256,6 +266,7 @@ export const OFFCHAIN_FRACTIONS_ABI = [
       { internalType: "address", name: "to", type: "address" },
       { internalType: "bool", name: "useCounterfactualAddress", type: "bool" },
       { internalType: "uint256", name: "minSharesToRaise", type: "uint256" },
+      { internalType: "address", name: "closer", type: "address" },
     ],
     name: "createFraction",
     outputs: [],
@@ -294,6 +305,7 @@ export const OFFCHAIN_FRACTIONS_ABI = [
           { internalType: "address", name: "to", type: "address" },
           { internalType: "uint256", name: "soldSteps", type: "uint256" },
           { internalType: "uint256", name: "totalSteps", type: "uint256" },
+          { internalType: "address", name: "closer", type: "address" },
         ],
         internalType: "struct OffchainFractions.FractionData",
         name: "",

package/src/lib/hooks/README.md

@@ -0,0 +1,286 @@
+# Hooks Documentation
+
+This directory contains React-like hooks for interacting with Glow protocol smart contracts. These hooks provide a clean, type-safe interface for blockchain operations.
+
+## useOffchainFractions
+
+The `useOffchainFractions` hook provides functionality for creating and managing fractional token sales with optional minimum raise requirements.
+
+### Setup
+
+```typescript
+import { useOffchainFractions } from "./use-offchain-fractions";
+import { ethers } from "ethers";
+
+// Initialize with signer and chain ID
+const signer = new ethers.Wallet(privateKey, provider);
+const CHAIN_ID = 1; // Ethereum mainnet
+const fractions = useOffchainFractions(signer, CHAIN_ID);
+```
+
+### Core Features
+
+#### 1. Creating Fraction Sales
+
+```typescript
+import { CreateFractionParams } from "./use-offchain-fractions";
+
+const params: CreateFractionParams = {
+  id: "0x1234567890abcdef...", // bytes32 hex string
+  token: "0xTokenAddress...", // ERC20 token being sold
+  step: BigInt("1000000"), // Price per step in wei
+  totalSteps: BigInt("1000"), // Total steps available
+  expiration: Math.floor(Date.now() / 1000) + 86400, // Unix timestamp (24h from now)
+  to: "0xRecipientAddress...", // Where funds go
+  useCounterfactualAddress: false, // Use counterfactual holder?
+  minSharesToRaise: BigInt("500"), // Minimum steps needed (0 = no minimum)
+  closer: "0xCloserAddress...", // Address allowed to manually close
+};
+
+try {
+  const txHash = await fractions.createFraction(params);
+  console.log("Fraction created:", txHash);
+} catch (error) {
+  console.error("Creation failed:", error.message);
+}
+```
+
+#### 2. Buying Fractions
+
+```typescript
+import { BuyFractionsParams } from "./use-offchain-fractions";
+
+const buyParams: BuyFractionsParams = {
+  creator: "0xCreatorAddress...", // Original fraction creator
+  id: "0x1234567890abcdef...", // Same ID used in creation
+  stepsToBuy: BigInt("10"), // How many steps to buy
+  minStepsToBuy: BigInt("5"), // Minimum steps that must be available
+};
+
+try {
+  const txHash = await fractions.buyFractions(buyParams);
+  console.log("Purchase successful:", txHash);
+} catch (error) {
+  console.error("Purchase failed:", error.message);
+}
+```
+
+#### 3. Managing Sales
+
+```typescript
+// Close a fraction sale manually (only by closer address)
+const closeTxHash = await fractions.closeFraction(creator, id);
+
+// Claim refund from unfilled sale
+const refundTxHash = await fractions.claimRefund(creator, id);
+```
+
+### Data Retrieval
+
+#### Get Fraction Details
+
+```typescript
+const fractionData = await fractions.getFraction(creator, id);
+console.log({
+  token: fractionData.token,
+  totalSteps: fractionData.totalSteps,
+  soldSteps: fractionData.soldSteps,
+  step: fractionData.step, // Price per step
+  expiration: fractionData.expiration,
+  minSharesToRaise: fractionData.minSharesToRaise,
+  owner: fractionData.owner,
+  to: fractionData.to,
+  closer: fractionData.closer,
+  manuallyClosed: fractionData.manuallyClosed,
+  useCounterfactualAddress: fractionData.useCounterfactualAddress,
+  claimedFromMinSharesToRaise: fractionData.claimedFromMinSharesToRaise,
+});
+```
+
+#### Check User Purchases
+
+```typescript
+const userSteps = await fractions.getStepsPurchased(userAddress, creator, id);
+console.log(`User owns ${userSteps} steps`);
+```
+
+### Token Operations
+
+#### Check Balances and Allowances
+
+```typescript
+const userAddress = await signer.getAddress();
+const tokenAddress = "0xTokenAddress...";
+
+// Check token balance
+const balance = await fractions.checkTokenBalance(userAddress, tokenAddress);
+console.log(`Balance: ${balance}`);
+
+// Check allowance for the contract
+const allowance = await fractions.checkTokenAllowance(
+  userAddress,
+  tokenAddress
+);
+console.log(`Allowance: ${allowance}`);
+```
+
+#### Approve Tokens
+
+```typescript
+const amount = BigInt("1000000"); // Amount to approve
+const success = await fractions.approveToken(tokenAddress, amount);
+console.log("Approval successful:", success);
+```
+
+### Utility Functions
+
+#### Status Checks
+
+```typescript
+// Check if fraction is expired
+const isExpired = await fractions.isFractionExpired(creator, id);
+
+// Check if minimum shares reached
+const reachedMinimum = await fractions.hasReachedMinimumShares(creator, id);
+
+// Check if completely filled
+const isFilled = await fractions.isFractionCompletelyFilled(creator, id);
+```
+
+#### Financial Calculations
+
+```typescript
+// Get total amount raised
+const totalRaised = await fractions.getTotalAmountRaised(creator, id);
+
+// Get remaining steps available
+const remaining = await fractions.getRemainingSteps(creator, id);
+```
+
+### Gas Estimation
+
+```typescript
+const ethPrice = 2000; // Current ETH price in USD
+
+// Estimate gas for creating fraction
+const createCost = await fractions.estimateGasForCreateFraction(
+  params,
+  ethPrice
+);
+console.log(`Creation cost: $${createCost}`);
+
+// Estimate gas for buying fractions
+const buyCost = await fractions.estimateGasForBuyFractions(buyParams, ethPrice);
+console.log(`Purchase cost: $${buyCost}`);
+```
+
+### State Management
+
+```typescript
+// Check if any operation is in progress
+console.log("Processing:", fractions.isProcessing);
+
+// Access contract addresses for current chain
+console.log("Contract address:", fractions.addresses.OFFCHAIN_FRACTIONS);
+
+// Check signer availability
+console.log("Signer available:", fractions.isSignerAvailable);
+```
+
+### Error Handling
+
+The hook provides typed error enums for better error handling:
+
+```typescript
+import { OffchainFractionsError } from "./use-offchain-fractions";
+
+try {
+  await fractions.createFraction(params);
+} catch (error) {
+  if (error.message === OffchainFractionsError.INSUFFICIENT_BALANCE) {
+    // Handle insufficient balance
+  } else if (error.message === OffchainFractionsError.FRACTION_NOT_FOUND) {
+    // Handle fraction not found
+  }
+  // ... handle other errors
+}
+```
+
+Available error types:
+
+- `CONTRACT_NOT_AVAILABLE`
+- `SIGNER_NOT_AVAILABLE`
+- `UNKNOWN_ERROR`
+- `INVALID_PARAMETERS`
+- `FRACTION_NOT_FOUND`
+- `INSUFFICIENT_BALANCE`
+- `INSUFFICIENT_ALLOWANCE`
+
+### Best Practices
+
+1. **Always check balances and allowances** before attempting purchases
+2. **Validate parameters** before calling functions
+3. **Handle errors gracefully** with proper user feedback
+4. **Use gas estimation** for better UX
+5. **Check processing state** to prevent double-submissions
+
+### Example: Complete Fraction Sale Flow
+
+```typescript
+async function createAndBuyFraction() {
+  const fractions = useOffchainFractions(signer, CHAIN_ID);
+
+  try {
+    // 1. Create fraction sale
+    const createParams: CreateFractionParams = {
+      id: ethers.id("my-fraction-sale"),
+      token: "0xTokenAddress...",
+      step: BigInt("1000000"), // 1 token per step
+      totalSteps: BigInt("1000"),
+      expiration: Math.floor(Date.now() / 1000) + 86400,
+      to: await signer.getAddress(),
+      useCounterfactualAddress: false,
+      minSharesToRaise: BigInt("100"),
+      closer: await signer.getAddress(),
+    };
+
+    const createTx = await fractions.createFraction(createParams);
+    console.log("Created fraction:", createTx);
+
+    // 2. Buy some fractions (as different user)
+    const buyParams: BuyFractionsParams = {
+      creator: await signer.getAddress(),
+      id: createParams.id,
+      stepsToBuy: BigInt("50"),
+      minStepsToBuy: BigInt("1"),
+    };
+
+    // Check balance first
+    const balance = await fractions.checkTokenBalance(
+      await signer.getAddress(),
+      createParams.token
+    );
+
+    const requiredAmount = buyParams.stepsToBuy * createParams.step;
+    if (balance < requiredAmount) {
+      throw new Error("Insufficient balance");
+    }
+
+    const buyTx = await fractions.buyFractions(buyParams);
+    console.log("Purchased fractions:", buyTx);
+
+    // 3. Check status
+    const fractionData = await fractions.getFraction(
+      createParams.id,
+      await signer.getAddress()
+    );
+    console.log(
+      `Sold ${fractionData.soldSteps}/${fractionData.totalSteps} steps`
+    );
+  } catch (error) {
+    console.error("Flow failed:", error.message);
+  }
+}
+```
+
+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.

package/src/lib/hooks/use-offchain-fractions.ts

@@ -27,6 +27,7 @@ export interface FractionData {
   to: string;
   soldSteps: bigint;
   totalSteps: bigint;
+  closer: string;
 }
 
 // Parameters for creating a new fraction
@@ -39,6 +40,7 @@ export interface CreateFractionParams {
   to: string; // Recipient address
   useCounterfactualAddress: boolean;
   minSharesToRaise: bigint; // 0 for no minimum
+  closer: string; // Address allowed to manually close the sale
 }
 
 // Parameters for buying fractions
@@ -219,6 +221,7 @@ export function useOffchainFractions(
         to,
         useCounterfactualAddress,
         minSharesToRaise,
+        closer,
       } = params;
 
       // Validate parameters
@@ -246,7 +249,8 @@ export function useOffchainFractions(
             expiration,
             to,
             useCounterfactualAddress,
-            minSharesToRaise
+            minSharesToRaise,
+            closer
           );
       } catch (staticError) {
         throw new Error(parseEthersError(staticError));
@@ -261,7 +265,8 @@ export function useOffchainFractions(
         expiration,
         to,
         useCounterfactualAddress,
-        minSharesToRaise
+        minSharesToRaise,
+        closer
       );
       await tx.wait();
 
@@ -399,10 +404,11 @@ export function useOffchainFractions(
   }
 
   /**
-   * Close a fraction sale manually (only by owner)
+   * Close a fraction sale manually (only by closer)
+   * @param creator The address that created the fraction sale
    * @param id The unique identifier of the fraction sale to close
    */
-  async function closeFraction(id: string): Promise<string> {
+  async function closeFraction(creator: string, id: string): Promise<string> {
     assertSigner(signer);
 
     try {
@@ -413,7 +419,7 @@ export function useOffchainFractions(
       setIsProcessing(true);
 
       // Validate parameters
-      if (!id) {
+      if (!creator || !id) {
         throw new Error(OffchainFractionsError.INVALID_PARAMETERS);
       }
 
@@ -421,7 +427,7 @@ export function useOffchainFractions(
 
       // Run a static call first to surface any revert reason
       try {
-        await contract.getFunction("closeFraction").staticCall(id, {
+        await contract.getFunction("closeFraction").staticCall(creator, id, {
           from: owner,
         });
       } catch (staticError) {
@@ -429,7 +435,7 @@ export function useOffchainFractions(
       }
 
       // Execute the transaction
-      const tx = await contract.getFunction("closeFraction")(id);
+      const tx = await contract.getFunction("closeFraction")(creator, id);
       await tx.wait();
 
       return tx.hash;
@@ -470,6 +476,7 @@ export function useOffchainFractions(
         to: result.to,
         soldSteps: result.soldSteps,
         totalSteps: result.totalSteps,
+        closer: result.closer,
       };
     } catch (error) {
       throw new Error(parseEthersError(error));
@@ -611,6 +618,7 @@ export function useOffchainFractions(
         to,
         useCounterfactualAddress,
         minSharesToRaise,
+        closer,
       } = params;
 
       const feeData = await signer.provider?.getFeeData();
@@ -630,7 +638,8 @@ export function useOffchainFractions(
           expiration,
           to,
           useCounterfactualAddress,
-          minSharesToRaise
+          minSharesToRaise,
+          closer
         );
 
       const estimatedCost: bigint = estimatedGas * gasPrice;